適用於資料 API 產生器的資料庫特定功能

發行項
04/13/2024

數據 API 產生器可讓每個資料庫有自己的特定功能。本文詳述每個資料庫支援的功能。

資料庫版本支援

許多傳統資料庫需要最低版本才能與數據 API 產生器相容， (DAB) 。

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

相反地，Azure 雲端資料庫服務會立即使用 DAB，而不需要特定版本。

	最低支援版本
Azure SQL	n/a
適用於 NoSQL 的 Azure Cosmos DB	n/a
適用於 PostgreSQL 的 Azure Cosmos DB	n/a

Azure SQL 和 SQL Server

SQL 有一些專屬的特定屬性，包括 Azure SQL 和 SQL Server。

SESSION_CONTEXT

Azure SQL 和 SQL Server 支援使用 SESSION_CONTEXT 函式來存取目前使用者的身分識別。當您想要套用數據列層級安全性的原生支援 (RLS) Azure SQL 和 SQL Server 時，此功能非常有用。

針對 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`	Issuer
`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 都有一些獨特的特定屬性。

適用於 NoSQL 的 API 中的架構

Azure Cosmos DB for NoSQL 與結構描述無關。若要搭配 NoSQL 的 API 使用資料 API 產生器，您必須建立 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" ]
      }
    ]
  }
  ...
}

@authorize的 roles:["metadataviewer","authenticated"] 指示詞會將欄位的title存取限制為只有具有角色metadataviewer和authenticated的使用者。對於已驗證的要求者，系統角色 authenticated 會自動指派，而不需要 X-MS-API-ROLE 標頭。

如果需要在的內容metadataviewer中執行已驗證的要求，它應該隨附設定為 metadataviewer類型的X-MS-API-ROLE要求標頭。不過，如果需要匿名存取，您必須省略授權指示詞。

指示 @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": [ "*" ]
      }
    ]
  }
}

適用於 NoSQL 的 API 中的跨容器查詢

不支援跨容器的 GraphQL 作業。引擎會回應錯誤訊息，指出： Adding/updating Relationships is currently not supported in Azure Cosmos DB for NoSQL.

您可以藉由更新數據模型，以內嵌格式將實體儲存在相同的容器內，以解決此問題。如需詳細資訊，請參閱適用於 NoSQL 的 Azure Cosmos DB 中的數據模型化。

共用方式為