版本 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 发行说明
查看这些发布页面,获取所有更改和改进的完整列表:
- 2024-02-06 - 版本 0.10.23
- 2024-01-31 - 版本 0.10.21
- 2023-12-07 - 版本 0.10.11
内存中缓存
版本 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
检查配置文件中的错误或不一致,从而增强开发工作流。
验证步骤
- 架构验证
- 配置属性验证
- 配置权限验证
- 数据库连接验证
- 实体元数据验证
预览功能
版本 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-strict
false
,将忽略没有映射到相关数据库对象的字段,而不会生成任何错误。
为连接添加应用程序名称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
}
将 Azure 存储链接替换为 GitHub 链接
由于 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,operation
graphql
部分中的 可以替代 为 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
}
}
使用日志级别增强的日志记录支持
- 当 为
Production
和Development
时,引擎host.mode
的默认日志级别分别更新为Error
和Debug
。 - 在引擎启动期间,对于实体的每个列,将记录公开的字段名称和主键等信息。 当自动生成字段映射时,甚至类型也会发生此行为。
- 在本地执行方案中,在引擎启动期间生成和执行的所有查询都按
Debug
级别记录。 - 对于每个实体,都会记录关系字段,例如
source.fields
、target.fields
和cardinality
。 如果存在多多关系,linking.object
linking.source.fields
则会记录从数据库 (或从配置文件推断) 、 和linking.target.fields
。 - 对于每个传入请求,都会记录请求的角色和身份验证状态。
- 在 CLI 中,版本
Microsoft.DataAPIBuilder
与与相应命令的执行关联的日志一起记录。
更新的 CLI
--no-https-redirect
选项已添加到start
命令。 使用此选项,可以阻止从http
到https
的请求自动重定向。在 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_nosql
和 cosmosdb_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
}
}