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

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

数据库版本支持

许多传统数据库要求最低版本与数据 API 生成器（DAB）兼容。

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

Azure SQL 和 SQL Server

SQL 有一些特定于 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 查询传递的键值对。 这些声明包括但不限于：

有关声明的详细信息，请参阅 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 生成器与用于 NoSQL 的 API 配合使用，必须创建一个 GraphQL 架构文件，该文件包含表示容器的数据模型的对象类型定义。 数据 API 生成器还希望 GraphQL 对象类型定义和字段包含 GraphQL 架构指令 authorize （如果想要强制实施比限制性更高的读取访问 anonymous）。

例如，此架构文件表示容器中的项 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" ]
      }
    ]
  }
  ...
}

该 @authorize 指令将 roles:["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 中的数据建模。