数据 API 生成器的数据库特定功能

项目
04/13/2024

数据 API 生成器允许每个数据库都有其自己的特定功能。本文详细介绍了每个数据库支持的功能。

数据库版本支持

许多传统数据库需要最低版本才能与数据 API 生成器 (DAB) 兼容。

	最低支持版本
SQL Server	2016
MySQL	8
PostgreSQL	11

相反，Azure 云数据库服务使用 DAB 开箱即用，无需特定版本。

	最低支持版本
Azure SQL	N/A
Azure Cosmos DB for NoSQL	N/A
Azure Cosmos DB for PostgreSQL	N/A

Azure SQL 和 SQL Server

SQL 有一些特定的属性是独一无二的，包括Azure SQL和SQL Server。

SESSION_CONTEXT

Azure SQL和SQL Server支持使用 SESSION_CONTEXT 函数访问当前用户的标识。如果要应用对 Azure SQL 和 SQL Server 中提供的 RLS) 行级别安全性 (本机支持，此功能非常有用。

对于Azure SQL和SQL Server，数据 API 生成器可以利用将SESSION_CONTEXT用户指定的元数据发送到基础数据库。此类元数据可通过访问令牌中的声明提供给数据 API 生成器。然后，可以使用发送到数据库的数据配置额外的安全 (级别，例如，通过配置安全策略) 进一步阻止访问 SELECT、UPDATE、DELETE 等操作中的数据。在数据库连接期间，数据 SESSION_CONTEXT 可供数据库使用，直到该连接关闭。同样，可以在存储过程内使用相同的数据。

有关设置 SESSION_CONTEXT 数据的详细信息，请参阅 sp_set_session_context (Transact-SQL) 。

SESSION_CONTEXT使用options配置文件中节的 data-source 属性进行配置。有关详细信息，请参阅 data-source 配置参考。

{
  ...
  "data-source": {
    "database-type": "mssql",
    "options": {
      "set-session-context": true
    },
    "connection-string": "<connection-string>"
  },
  ...
}

或者，将 --set-session-context 参数与命令一起使用 dab init 。

dab init --database-type mssql --set-session-context true

EasyAuth/JWT 令牌中的所有声明都通过 SESSION_CONTEXT 发送到基础数据库。令牌中的所有声明都转换为通过 SESSION_CONTEXT 查询传递的键值对。这些声明包括但不限于：

	说明
`aud`	读者
`iss`	颁发者
`iat`	颁发时间
`exp`	过期时间
`azp`	应用程序标识符
`azpacr`	客户端的身份验证方法
`name`	使用者
`uti`	唯一令牌标识符

有关声明的详细信息，请参阅Microsoft Entra ID访问令牌声明参考。

这些声明将转换为 SQL 查询。此截断的示例演示了如何 sp_set_session_context 在此上下文中使用：

EXEC sp_set_session_context 'aud', '<AudienceID>', @read_only = 1;
EXEC sp_set_session_context 'iss', 'https://login.microsoftonline.com/<TenantID>/v2.0', @read_only = 1;
EXEC sp_set_session_context 'iat', '1637043209', @read_only = 1;
...
EXEC sp_set_session_context 'azp', 'a903e2e6-fd13-4502-8cae-9e09f86b7a6c', @read_only = 1;
EXEC sp_set_session_context 'azpacr', 1, @read_only = 1;
..
EXEC sp_set_session_context 'uti', '_sSP3AwBY0SucuqqJyjEAA', @read_only = 1;
EXEC sp_set_session_context 'ver', '2.0', @read_only = 1;

然后，可以使用会话数据 (RLS) 实现行级别安全性。有关详细信息，请参阅使用会话上下文实现行级安全性。

Azure Cosmos DB

Azure Cosmos DB 中的各种 API 具有一些唯一的特定属性。

API for NoSQL 中的架构

Azure Cosmos DB for NoSQL 与架构无关。若要将数据 API 生成器与 API for NoSQL 配合使用，必须创建一个包含表示容器数据模型的对象类型定义的GraphQL架构文件。当想要强制实施比 anonymous更严格的读取访问时，数据 API 生成器还要求GraphQL对象类型定义和字段包含 GraphQL 架构指令authorize。

例如，此架构文件表示 Book 容器中的项。此项至少 title 包含和 Authors 属性。

type Book @model(name:"Book"){
  id: ID
  title: String @authorize(roles:["metadataviewer","authenticated"])
  Authors: [Author]
}

此示例架构对应于 DAB 配置文件中的以下实体配置。有关详细信息，请参阅 entities 配置参考。

{
  ...
  "Book": {
    "source": "Book",
    "permissions": [
      {
        "role": "anonymous",
        "actions": [ "read" ]
      },
      {
        "role": "metadataviewer",
        "actions": [ "read" ]
      }
    ]
  }
  ...
}

具有的 @authorizeroles:["metadataviewer","authenticated"] 指令将字段的访问 title 限制为仅具有角色 metadataviewer 和 authenticated的用户。对于经过身份验证的请求者，系统角色 authenticated 会自动分配，无需标头 X-MS-API-ROLE 。

如果需要在的上下文 metadataviewer中执行经过身份验证的请求，应附带类型 X-MS-API-ROLE 设置为 metadataviewer的请求标头。但是，如果需要匿名访问，则必须省略授权指令。

指令@model用于建立此GraphQL对象类型与运行时配置中相应实体名称之间的关联。指令的格式为：@model(name:"<Entity_Name>")

作为更深层次的示例， @authorize 可以在顶级类型定义中应用指令。此应用程序将类型及其字段的访问限制为指令中指定的角色。

type Series @model(name:"Series") @authorize(roles:["editor","authenticated"]) {
  id: ID
  title: String
  Books: [Book]
}

{
  "Book": {
    "source": "Series",
    "permissions": [
      {
        "role": "authenticated",
        "actions": [ "read" ]
      },
      {
        "role": "editor",
        "actions": [ "*" ]
      }
    ]
  }
}

API for NoSQL 中的跨容器查询

不支持跨容器GraphQL操作。引擎响应并显示一条错误消息，指出： Adding/updating Relationships is currently not supported in Azure Cosmos DB for NoSQL.

可以通过更新数据模型以嵌入格式将实体存储在同一容器中来绕过此限制。有关详细信息，请参阅 Azure Cosmos DB for NoSQL 中的数据建模。

通过