版本 0.11 及更早版本中的新增功能

有关数据 API 生成器版本 0.11 及更低版本中所有更新和增强功能的发行说明和信息。

版本 0.11 中的新增功能

数据 API 生成器 0.10 版中的更新和增强功能的发行说明和信息。

对 SQL 数据仓库的 GraphQL 支持

SQL 数据仓库现在支持 GraphQL 终结点。

增强的 Azure Cosmos DB for NoSQL 筛选

Azure Cosmos DB for NoSQL 现在支持使用 contains 运算符进行嵌套筛选器、ID 变量和字符串数组搜索。

使用命令行接口启用应用程序数据收集

现在可以使用 DAB 命令行接口 (CLI) 来启用 Application Insights 的数据收集。

版本 0.10 中的新增功能

数据 API 生成器 0.10 版中的更新和增强功能的发行说明和信息。

随着我们正式发布,我们的重点将转向稳定性。 虽然本文并未详细介绍代码质量和引擎稳定性方面的所有工作,但此列表突出显示了重要更新。

GitHub 发行说明

查看这些发布页面,获取所有更改和改进的完整列表:

内存中缓存

版本 0.10 引入了 REST 和 GraphQL 终结点的内存中缓存。 此功能专为内部缓存而设计,为未来的分布式缓存奠定了基础。 内存中缓存可减少重复查询的数据库负载。

缓存方案

  • 减少数据库负载:缓存存储昂贵查询的结果,无需重复数据库调用。
  • 提高 API 可伸缩性:缓存支持更频繁的 API 调用,而无需增加数据库请求,从而显著扩展 API 的功能。

配置更改

缓存设置在 runtime 部分和每个实体中提供,提供精细控制。

运行时设置

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 6
    }
  }
}
  • 默认情况下,缓存处于禁用状态。
  • (TTL) 的默认生存时间为 5 秒。

实体设置

{
  "Book": {
    "source": {
      "object": "books",
      "type": "table"
    },
    "graphql": {
      "enabled": true,
      "type": {
        "singular": "book",
        "plural": "books"
      }
    },
    "rest": {
      "enabled": true
    },
    "permissions": [
      {
        "role": "anonymous",
        "actions": [
          {
            "action": "*"
          }
        ]
      }
    ],
    "cache": {
      "enabled": true,
      "ttl-seconds": 6
    }
  }
}

CLI 中的配置验证

CLI 现在支持 dab validate 检查配置文件中的错误或不一致,从而增强开发工作流。

验证步骤

  1. 架构验证
  2. 配置属性验证
  3. 配置权限验证
  4. 数据库连接验证
  5. 实体元数据验证

预览功能

  • 初始 DWSQL 支持。 #1864
  • 支持多个数据源。 #1709

版本 0.9 中的新增功能

下面是数据 API 生成器 0.9 中最相关的更改和改进的详细信息。

GitHub 发行说明

查看这些发布页面,获取所有更改和改进的完整列表:

在自承载 DAB 时启用 Application Insights

现在可以将日志流式传输到 Application Insights,以提供更好的监视和调试体验,尤其是在 Azure 中部署数据 API 生成器时。 可将新 telemetry 节添加到配置文件中,以启用和配置与 Application Insights 的集成:

"telemetry": {
    "application-insights": {
    "enabled": true,    // To enable/disable application insights telemetry
    "connection-string": "{APP_INSIGHTS_CONNECTION_STRING}" // Application Insights connection string to send telemetry
    }
}

阅读 使用 Application Insights 文档页中的所有详细信息。

支持忽略 REST 请求正文中的无关字段

使用新 request-body-strict 选项,现在可以确定 REST 有效负载中具有额外字段是否生成错误 (默认行为、向后兼容) 还是以无提示方式忽略额外字段。

"runtime": {
    "rest": {
      "enabled": true,
      "path": "/api",
      "request-body-strict": true
    },
    ...
}

通过将 选项设置为 request-body-strictfalse,将忽略没有映射到相关数据库对象的字段,而不会生成任何错误。

为连接添加应用程序名称mssql

数据 API 生成器现在注入连接字符串( mssql 仅适用于数据库类型)值 dab-<version> 作为 Application Name 属性,从而更轻松地识别数据库服务器中的连接。 如果 Application Name 连接字符串中已存在 ,则会向其追加数据 API 生成器版本。

支持 time 中的数据类型 mssql

time 数据库中现在支持 mssql 数据类型。

具有 触发器的表上的突变 mssql

现在,具有数据库触发器 mssql 的表完全支持突变。

阻止用户更新/插入表中的只读字段

自动检测数据库的只读字段,并阻止用户更新/插入这些字段。

版本 0.8 中的新增功能

下面是数据 API 生成器 0.8 中最相关的更改和改进的详细信息。

GitHub 发行说明

查看这些发布页面,获取所有更改和改进的完整列表:

添加了对 .env 文件的支持

环境变量 可保护机密免受纯文本泄露,并允许在不同设置中交换值。 但是,必须在用户或计算机范围内设置这些变量,如果变量名称重复,这可能会导致跨项目变量“出血”。 更好的替代方法是环境文件。 有关详细信息,请参阅 数据 API 生成器中的环境文件 - 博客

版本 0.7.6 中的新增功能

本文介绍 0.7.6 版本的发行说明。

GitHub 拉取请求

OpenAPI v3-0-1 说明文档创建的初始支持

数据 API 生成器支持 OpenAPI 标准,用于生成和公开包含有关服务的有用信息的说明文档。 这些文档是从运行时配置文件和每个数据库对象的元数据创建的。 这些对象与在同一配置文件中定义的已启用 REST 的实体相关联。 然后,它们通过 UI 公开,并作为序列化文件提供。

有关 OpenAPI 和数据 API 生成器的详细信息,请参阅 OpenAPI

允许合并配置文件

添加了自动合并两个配置文件的功能。

可以维护多对特定于基线和环境的配置文件,以简化特定于环境的设置的管理。 例如,可以维护开发和生产的单独配置。 此步骤涉及创建一个基本配置文件,该文件具有不同环境之间的所有通用设置。 然后, DAB_ENVIRONMENT 通过设置 变量,可以控制要合并哪些配置文件供数据 API 生成器使用。

有关详细信息,请参阅 CLI 参考

在事务中执行 GraphQL 和 REST 突变

数据 API 生成器创建数据库事务来执行某些类型的 GraphQL 和 REST 请求。

有许多请求,这些请求涉及完成多个数据库查询。 例如,若要返回更新的结果,必须先对更新进行查询,然后必须在返回之前读取新值。 当请求需要执行多个数据库查询时,数据 API 生成器现在在单个事务中执行这些数据库查询。

有关此功能的详细信息,请参阅 REST 文档 和 GraphQL 文档中的 GraphQL 上下文

版本 0.6.14 中的新增功能

本文介绍适用于 Azure 数据库的数据 API 生成器 2023 年 3 月版本的修补程序。

Bug 修复

  • 解决 Cosmos 的查询筛选器访问被拒绝问题。
  • Cosmos DB 目前不支持字段级授权,为了避免用户意外传入 field 运行时配置中的权限的情况,我们添加了验证检查。

版本 0.6.13 中的新增功能

GitHub 上提供了此版本发行说明的完整列表: https://github.com/Azure/data-api-builder/releases/tag/v0.6.13

用于导出 GraphQL 架构的新 CLI 命令

添加了用于导出 GraphQL 架构的新选项。 这会启动 DAB 服务器,然后对其进行查询以获取架构,然后再将其写入到提供的位置。

dab export --graphql -c dab-config.development.json -o ./schemas

此命令在 ./schemas 目录中生成 GraphQL 架构文件。 配置文件的路径是可选参数,除非“dab-config”,否则默认为“dab-config.json”。<>存在DAB_ENVIRONMENT.json',其中DAB_ENVIRONMENT是环境变量。

MsSql 的创建操作的数据库策略支持

MsSql 的所有 CRUD (创建、读取、更新、删除) 操作现在都支持数据库策略。 例如:

"entities":{
  "Revenue":{
    "source": "revenues",
    "permissions":[
      "role": "authenticated",
          "actions": [
            {
              "action": "Create",
              "policy": {
                "database": "@item.revenue gt 0"
              }
            },
            "read",
            "update",
            "delete"
          ]
    ]
  }
}

实体的先前配置 Revenue 指示不允许使用角色 Authenticated 执行插入操作的用户创建收入小于或等于零的记录。

能够通过 CLI 全局配置 GraphQL 路径并禁用 REST 和 GraphQL 终结点

现在,我们支持命令的 init 另外三个选项:

  • graphql.path :提供自定义 GraphQL 路径
  • rest.disabled:全局禁用 REST 终结点
  • graphql.disabled:全局禁用 GraphQL 终结点

例如,命令 init 将生成包含运行时部分的配置文件:

dab init --database-type mssql --rest.disabled --graphql.disabled --graphql.path /gql
"runtime": {
    "rest": {
      "enabled": false,
      "path": "/api"
    },
    "graphql": {
      "allow-introspection": true,
      "enabled": false,
      "path": "/gql"
    },
}

在 CLI 中添加和更新视图时必需的关键字段

现在,当用户通过 CLI 将新的数据库视图 dab add () 添加到配置时,必须提供键字段 (,以便通过公开的选项 source.key-fields) 用作主键。 此外,每当通过 dab update CLI 通过配置文件中的) 更新视图 (配置中的任何内容时,如果更新更改了与基础数据库中视图定义相关的任何内容, (例如源类型、键字段) ,则还必须在 update 命令中指定键字段。

但是,我们仍支持没有在配置中指定的显式主键的视图,但此类视图的配置必须直接写入配置文件中。

例如, dab add 命令用于添加视图:

dab add books_view --source books_view --source.type "view" --source.key-fields "id" --permissions "anonymous:*" --rest true --graphql true

此命令为 books_view 实体生成配置,如以下示例所示:

"books_view": {
      "source": {
        "type": "view",
        "object": "books_view",
        "key-fields":[
          "id"
        ]
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            "*"
          ]
        }
      ],
      "rest": true,
      "graphql": true
    }

由于 DAB 现在是开源的,因此无需从存储帐户下载项目。 相反,我们可以直接从 GitHub 下载它们。 因此,链接会相应地更新。

版本 0.5.34 中的新增功能

GitHub 上提供了此版本发行说明的完整列表: https://github.com/Azure/data-api-builder/releases/tag/v0.5.34

在运行时级别遵循已启用 REST 和 GraphQL 的标志

添加了一个新选项,允许在运行时级别为所有实体启用或禁用 REST/GraphQL 请求。 如果全局禁用,则无论单个实体设置如何,都不会通过 REST 或 GraphQL 请求访问任何实体。 如果全局启用,默认情况下可以访问各个实体,除非实体级别设置显式禁用。

"runtime": {
    "rest": {
      "enabled": false,
      "path": "/api"
    },
    "graphql": {
      "allow-introspection": true,
      "enabled": false,
      "path": "/graphql"
    }
  }

请求日志中的关联 ID

为了帮助调试,我们将关联 ID 附加到请求期间生成的任何日志。 由于可能会发出许多请求,因此有一种方法来识别特定请求的日志对于帮助调试过程非常重要。

引擎和 CLI 中存储过程的通配符操作支持

对于存储过程,现在可以使用通配符 * 操作配置角色,但它只会扩展到操作 execute

版本 0.5.32 中的新增功能

GitHub 上提供了此版本发行说明的完整列表: https://github.com/Azure/data-api-builder/releases/tag/v0.5.32-beta

能够通过 CLI 自定义 rest 路径

命令中init引入了一个新选项--rest.path,用于自定义 REST API 的路径。

dab init --database-type mssql --connection-string "Connection-String" --rest.path "rest-api" 

此命令使用 前缀 rest-api配置 REST 终结点。 REST 终结点的完整路径为 https://<dab-server>/rest-api/<entity-name>

不使用 选项时 --rest.path ,REST 终结点将使用默认前缀 api进行配置。 在本例中,完整路径为 https://<dab-server>/api/<entity-name>

MAR 中的数据 API 生成器容器映像

适用于 Azure 数据库的数据 API 生成器的官方 docker 映像现已在 Microsoft Artifact Registry 中提供。

有关使用已发布映像的说明,请参阅 Microsoft 容器注册表 - 数据 API 生成器

支持 GraphQL 片段

片段是 graphQL 查询的可重用部分。 如果必须在不同的查询中查询相同的字段,则可以将重复字段合并到称为 fragment 的单个可重用组件中。

有关片段的详细信息,请参阅 GraphQL 查询

接下来定义类型上Character调用description的片段:

fragment description on Character {
  name
  homePlanet
  primaryFunction
}

可以构造使用已定义片段的 GraphQL 查询,如下所示:

{
  Player1: Player{
    id
    playerDescription{
        ...description
    }
  }
}

对于上一个查询,结果包含以下字段:

{
 Player1: Player{
    id
    playerDescription{
        name
        homePlanet
        primaryFunction
    }
  }   
}

打开 BinSkim 并修复 Policheck 警报

BinSkim 是一种可移植可执行文件 (PE) 轻型扫描程序,用于验证编译器/链接器设置和其他与安全相关的二进制特征。 将添加管道中的 static-tools 管道任务,以便每次运行管道时执行 BinSkim 扫描。 PoliCheck 系统是一组工具和数据,作为总体全局就绪策略的一部分,可帮助保持符合文本和代码评审要求。 Policheck 扫描生成的警报已修复,以符合敏感条款。

版本 0.5.0 中的新增功能

GitHub 上提供了此版本发行说明的完整列表: https://github.com/Azure/data-api-builder/releases/tag/v0.5.0-beta

公共 JSON 架构

如果使用支持 JSON 架构的 IDE(如 Visual Studio Code),则公共 JSON 架构提供对“intellisense”的支持。 basic-empty-dab-config.json文件夹中的文件samples具有手动创建dab-config.json文件时的示例起点。

公共 Microsoft.DataApiBuilder NuGet

Microsoft.DataApiBuilder 现在 在此处 以公共 NuGet 包的形式提供,以便于使用 dotnet 工具进行安装,如下所示:

dotnet tool install --global Microsoft.DataApiBuilder

Azure SQL 中存储过程的新 execute 操作

仅当源类型支持 的实体stored-procedure时,才会在配置文件的 节中permissions引入新execute操作作为唯一允许的操作。 默认情况下,仅POST允许此类实体使用 方法,并且仅使用添加到其名称的前缀execute配置 GraphQL mutation 操作。 在配置文件的 节中rest显式指定允许methods的 将替代此行为。 同样,对于 GraphQL,operationgraphql部分中的 可以替代 为 query 。 有关详细信息,请参阅 视图和存储过程

新建 mappings 分区

mappings在每个 部分中entity,数据库对象字段名称及其相应的公开字段名称之间的映射是为 GraphQL 和 REST 终结点定义的。

格式为:

<database_field>: <entity_field>

例如:

  "mappings":{
    "title": "descriptions",
    "completed": "done"
  }

title相关数据库对象中的 字段映射到 description GraphQL 类型或 REST 请求和响应有效负载中的字段。

支持 Azure SQL 中的会话上下文

为了启用额外的安全 (例如行级别安全性 (RLS) ) ,DAB 现在支持通过 SESSION_CONTEXT 将数据发送到基础 Sql Server 数据库。 有关更多详细信息,请参阅有关SESSION_CONTEXT: 运行时到数据库授权的详细文档。

支持在 PostgreSQL 中对文档中的嵌套对象进行筛选

借助 PostgreSQL,现在可以使用架构中定义的对象或数组关系,从而可以像 Azure SQL 一样对嵌套对象执行筛选操作。

query {
  books(filter: { series: { name: { eq: "Foundation" } } }) {
    items {
      title
      year
      pages
    }
  }
}

在 Cosmos DB NoSQL 中支持标量列表

现已为 Cosmos DB 添加了查询 List 标量的功能。

请考虑此类型定义。

type Planet @model(name:"Planet") {
    id : ID,
    name : String,
    dimension : String,
    stars: [Star]
    tags: [String!]
}

现在可以运行提取列表的查询,例如

query ($id: ID, $partitionKeyValue: String) {
    planet_by_pk (id: $id, _partitionKeyValue: $partitionKeyValue) {
        tags
    }
}

使用日志级别增强的日志记录支持

  • 当 为 ProductionDevelopment 时,引擎host.mode的默认日志级别分别更新为 ErrorDebug
  • 在引擎启动期间,对于实体的每个列,将记录公开的字段名称和主键等信息。 当自动生成字段映射时,甚至类型也会发生此行为。
  • 在本地执行方案中,在引擎启动期间生成和执行的所有查询都按 Debug 级别记录。
  • 对于每个实体,都会记录关系字段,例如 source.fieldstarget.fieldscardinality 。 如果存在多多关系,linking.objectlinking.source.fields则会记录从数据库 (或从配置文件推断) 、 和 linking.target.fields
  • 对于每个传入请求,都会记录请求的角色和身份验证状态。
  • 在 CLI 中,版本 Microsoft.DataAPIBuilder 与与相应命令的执行关联的日志一起记录。

更新的 CLI

  • --no-https-redirect 选项已添加到 start 命令。 使用此选项,可以阻止从 httphttps 的请求自动重定向。

  • 在 MsSql 中,可以使用 命令中的 init 来启用--set-session-context true会话上下文。 此示例中显示了一个示例命令:

    dab init --database-type mssql --connection-string "Connection String" --set-session-context true
    
  • 可以使用 命令中的选项 --auth.provider--auth.audience和 配置身份验证详细信息,例如提供程序、受众和--auth.issuer.颁发者。init 此示例中显示了一个示例命令:

    dab init --database-type mssql --auth.provider AzureAD --auth.audience "audience" --auth.issuer "issuer"
    
  • 未指定实体名称时,用户友好的错误消息。

版本 0.4.11 中的新增功能

GitHub 上提供了此版本的发行说明的完整列表: https://github.com/Azure/data-api-builder/releases/tag/v0.4.11-alpha

更新了节的 data-source JSON 架构

data-source配置文件中的 节将更新为在所有受支持的数据库中保持一致,但仍允许每个数据库具有自定义配置。 引入了一个新部分 options ,用于对特定于数据库的所有属性进行分组。 例如:

{
  "$schema": "https://dataapibuilder.azureedge.net/schemas/v0.4.11-alpha/dab.draft.schema.json",
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "options": {
      "database": "PlaygroundDB",
      "graphql-schema": "schema.gql"
    },
    "connection-string": "AccountEndpoint=https://localhost:8081/;AccountKey=REPLACEME;"
  }
}

节中 options 可用的元素取决于所选 database-type的 。

支持在 Azure SQL 和 SQL Server 中筛选文档中的嵌套对象

使用 Azure SQL 和 SQL Server,可以使用架构中定义的对象或数组关系,从而可以对嵌套对象执行筛选操作。

query {
  books(filter: { series: { name: { eq: "Foundation" } } }) {
    items {
      title
      year
      pages
    }
  }
}

改进了存储过程支持

完全支持 REST 和 GraphQL 中的存储过程。 现在 100% 支持具有参数的存储过程。 请查看 存储过程 文档,了解如何将数据 API 生成器与存储过程配合使用。

为 Cosmos DB 重命名的新 database-type

我们添加了对 PostgreSQL API 和 Cosmos DB 的支持。 使用合并 data-source 节时,属性 database-type 表示数据库的类型。 由于 Cosmos DB 支持多个 API,当前支持的数据库类型为 cosmosdb_nosqlcosmosdb_postgresql

  "data-source": {
    "database-type": "cosmosdb_nosql",
    "options": {
      "database": "PlaygroundDB",
      "graphql-schema": "schema.gql"
    }
  }

重命名的 CLI 属性 cosmosdb_nosql

按照前面部分所述的配置更改,现在 CLI 属性将相应地重命名为 cosmosdb_nosql-database Cosmos DB NoSQL API 的 和 cosmosdb_nosql-container

dab init --database-type "cosmosdb_nosql" --graphql-schema schema.gql --cosmosdb_nosql-database PlaygroundDB  --cosmosdb_nosql-container "books" --connection-string "AccountEndpoint=https://localhost:8081/;AccountKey=REPLACEME;" --host-mode "Development"

Postgres 现在支持托管标识

现在,用户可以在配置中指定访问令牌,以使用托管标识进行身份验证。 或者,现在用户无法指定连接字符串中的密码,运行时会尝试提取默认托管标识令牌。 如果此操作失败,则会在连接字符串中不带密码的情况下尝试连接。

支持 Azure MySQL 的 Microsoft Entra ID 用户身份验证

添加了用户令牌作为密码字段,以便使用 Microsoft Entra ID 插件对 MySQL 进行身份验证。

版本 0.3.7 中的新增功能

GitHub 上提供了此版本的发行说明的完整列表: https://github.com/Azure/data-api-builder/releases/tag/v0.3.7-alpha

查看支持

REST 和 GraphQL 现在都支持视图。 如果你有一个视图,例如 dbo.vw_books_details ,可以使用以下命令 dab 公开它:

dab add BookDetail --source dbo.vw_books_details --source.type View --source.key-fields "id" --permissions "anonymous:read"

选项 source.key-fields 用于指定视图中的哪些字段用于唯一标识项,以便也可以为视图实现主键导航。 开发人员负责配置 DAB 以启用或禁用操作 (例如, create 操作) 具体取决于视图是否可更新。

存储过程支持

REST 请求现在支持存储过程。 如果你有一个存储过程,例如 dbo.stp_get_all_cowritten_books_by_author ,可以使用以下命令 dab 公开它:

dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" --permissions "anonymous:read" --rest true

调用 REST 终结点时,可以在 URL 查询字符串中传递 参数:

http://<dab-server>/api/GetCowrittenBooksByAuthor?author=isaac%20asimov

注意

开发人员负责将 DAB 配置为启用或禁用操作 (例如, create 在调用存储过程时,操作) 允许或拒绝特定的 HTTP 谓词。 例如,对于此示例中使用的存储过程,鉴于其用途是返回某些数据,因此仅允许 read 操作是有意义的。

Microsoft Entra ID 身份验证

Microsoft Entra ID 身份验证现已完全正常工作。 有关详细信息,请参阅 使用 Microsoft Entra ID 进行身份验证

用于本地身份验证的新模拟器身份验证提供程序

为了在本地开发时简化对经过身份验证的请求的测试,可以使用新的 simulator 身份验证提供程序。 提供程序 simulator 是可配置的身份验证提供程序,它指示数据 API 生成器引擎将所有请求视为经过身份验证。 此处的更多详细信息: 本地身份验证

支持在 Azure Cosmos DB 中筛选文档中的嵌套对象

使用 Azure Cosmos DB,可以使用架构中定义的对象或数组关系,从而可以对嵌套对象执行筛选操作。

query {
  books(first: 1, filter : { author : { profile : { twitter : {eq : ""@founder""}}}})
    id
    name
  }
}