Data API 建構器資料庫專屬功能參考

本參考文獻涵蓋了Data API Builder（DAB）支援的一個或多個資料庫平台特有的功能、行為與需求。有關跨資料庫功能比較矩陣，請參見功能可用性。

資料庫版本支援

DAB 支援以下資料庫平台。自我管理部署適用最低版本要求。平台即服務（PaaS）資料庫沒有最低版本要求，因為服務本身就是管理版本。

資料庫平台	縮寫	最低版本	Notes
SQL Server	SQL 家族	2016
Azure SQL	SQL 家族	N/A （PaaS）
Microsoft Fabric SQL	SQL 家族	N/A （PaaS）
Azure Cosmos DB for NoSQL	Cosmos DB	N/A （PaaS）	僅支援 GraphQL;無 REST 端點
PostgreSQL	PGSQL	11
MySQL	MySQL	8
Azure Synapse Analytics （Dedicated SQL pool）	SQLDW	N/A （PaaS）	不支援無伺服器 SQL 池

這很重要

確認你的本地開發資料庫和任何已部署的資料庫都符合最低版本要求。 DAB 在兩個環境下使用相同的驅動程式連接。任一地點的舊版本都會造成執行時錯誤。

SQL Server 與 Azure SQL

SESSION_CONTEXT

對於 SQL Server 和 Azure SQL，DAB 可以在執行每個查詢前呼叫 sp_set_session_context ，將已認證的使用者權利聲明傳播到資料庫。此機制允許 SQL 原生的列級安全政策與儲存程序從資料庫引擎中讀取呼叫者的身份。

當在 DAB 配置中啟用時 set-session-context ，DAB 會將所有已認證的聲明以鍵值對形式傳送：

EXEC sp_set_session_context 'roles', 'editor', @read_only = 0;
EXEC sp_set_session_context 'oid', 'a1b2c3d4-...', @read_only = 0;
-- Your query executes after claims are set
SELECT * FROM dbo.Documents;

常見的申請包括 roles、 sub、 oid，以及您的身份提供者在 JWT 中包含的任何自訂申請。

啟用SESSION_CONTEXT

呼叫dab init時設定--set-session-context true：

dab init \
  --database-type mssql \
  --connection-string "@env('SQL_CONNECTION_STRING')" \
  --set-session-context true

或者直接將屬性設於：dab-config.json

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "options": {
      "set-session-context": true
    }
  }
}

警告

啟用該 set-session-context 資料來源會停用回應快取。由於每個請求會設定不同的會話值，一個使用者的快取回應不能送給另一個。

在 SQL 中使用 SESSION_CONTEXT

啟用 set-session-context後，您的 SQL 物件可以讀取聲明值：

-- Read a claim in a stored procedure
DECLARE @role NVARCHAR(256) = CAST(SESSION_CONTEXT(N'roles') AS NVARCHAR(256));

-- Use a claim in a row-level security predicate function
CREATE FUNCTION dbo.RlsPredicate(@claimRole NVARCHAR(256))
RETURNS TABLE
WITH SCHEMABINDING
AS RETURN SELECT 1 AS result
WHERE @claimRole = CAST(SESSION_CONTEXT(N'roles') AS NVARCHAR(256));

完整攻略請參閱「與會話上下文實作列級安全性」。

SESSION_CONTEXT與連線池化

DAB 會在每次請求開始時重置所有會話上下文值。然而，由於 set-session-context 強制以每位使用者的連線語義來處理，啟用此功能後，使用者間的連線重用會自動避免。

連接串的變體

DAB 用於 Microsoft.Data.SqlClient SQL Server 和 Azure SQL。函式庫支援這些連接字串格式。

常見格式：

驗證方法	連接串模式
SQL 登入	`Server=tcp:<server>.database.windows.net;Database=<db>;User ID=<user>;Password=<pwd>;`
受管理的識別	`Server=tcp:<server>.database.windows.net;Database=<db>;Authentication=Active Directory Managed Identity;`
使用者指派的管理身份	`Server=tcp:<server>.database.windows.net;Database=<db>;Authentication=Active Directory Managed Identity;User ID=<client-id>;`
Default Azure credential	`Server=tcp:<server>.database.windows.net;Database=<db>;Authentication=Active Directory Default;`

小提示

將連接字串儲存在環境變數中，並用 @env('SQL_CONNECTION_STRING')來參考。對於生產部署，將連接字串存放在 Azure Key Vault 中，並以 @akv()作為參考。

不支援的資料類型

以下 SQL Server 與 Azure SQL 資料型別不被 DAB 支援：

資料類型	Reason
`geography`	地理空間類型;不支援序列化
`geometry`	平面空間類型;不支援序列化
`hierarchyid`	階層式資料型別;不支援序列化
`json`	原生 JSON 類型（目前預覽階段）
`rowversion`	列版本控制類型;未包含在 API 回應中
`sql_variant`	變數型欄位;不支援型別推論
`vector`	向量類型（目前預覽階段）
`xml`	XML 類型;不支援序列化

Azure Cosmos DB for NoSQL

結構需求

與關聯式資料庫不同，Azure Cosmos DB for NoSQL 是結構無關的。 DAB 無法內視 Cosmos DB 容器來產生 GraphQL 類型。你必須提供一個定義文件結構的 GraphQL 結構檔（.gql）。

該結構檔案使用標準的 GraphQL 架構定義語言（SDL），並有兩個自訂指令：

指令	Required	Description
`@model`	是的	將 GraphQL 類型映射到 DAB 實體名稱
`@authorize`	No	限制欄位或類型存取至特定角色

@model 指令

@model(name: "...")這個指令是你透過 DAB 暴露的每個 GraphQL 類型所必須的。這個 name 數值必須完全符合你 DAB 設定檔中的實體名稱。

type Book @model(name: "Book") {
  id: ID
  title: String
  year: Int
}

@authorize 指令

指令 @authorize 提供 Cosmos DB GraphQL 查詢的現場層級與類型層級存取控制。它接受 roles 一個參數，列出可以存取該欄位或類型的角色。

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

你也可以申請 @authorize 以下類型：

type InternalReport @model(name: "InternalReport") @authorize(roles: ["auditor"]) {
  id: ID
  summary: String
}

這很重要

該 @authorize 指令 會增加 實體層級的權限。指令與實體的權限區塊都必須允許存取請求成功。如果欄位有 @authorize(roles: ["editor"]) ，但該實體沒有權限輸入， editor該請求將被拒絕。

備註

不支援 @authorize(policy: "...")。僅使用 @authorize(roles: [...]) 。

完整的設定指南請參考 Set Up Data API builder for Azure Cosmos DB for NoSQL。

REST API 不可用

DAB 不會為 Azure Cosmos DB for NoSQL 產生 REST 端點。 Azure Cosmos DB 提供完整的原生 REST API 用於文件操作。僅產生 GraphQL 端點。 OpenAPI 文件並非為 Cosmos DB 實體產生。

若要透過 REST 存取資料，請直接使用 Azure Cosmos DB REST API 。

Cosmos 資料庫中未支援的功能

以下功能不支援 Azure Cosmos DB for NoSQL：

Feature	Notes
REST 端點	改用原生的 Cosmos DB REST API 吧
資料庫政策	政策謂詞需要關聯查詢語意
預存程序	不支援作為 DAB 實體
關係	不支援跨容器關係
排序（`$orderby`）	GraphQL 查詢不支援此功能
Aggregation	不支援
多個突變	不支援
會話內容	SQL 專屬功能

PostgreSQL

最低版本

必須使用 PostgreSQL 11 或更新版本。 DAB 作為 Npgsql 其 PostgreSQL 驅動程式。

不支援的資料類型

以下 PostgreSQL 資料型別不支援 DAB：

資料類型	Notes
`bytea`	二進位弦;不支援序列化
`date`	使用`timestamp`或`timestamptz`
`smalldatetime`	不是原生的 PostgreSQL 類型
`datetime2`	不是原生的;通常由 `timestamp`
`timestamptz`	時間戳記並附上時區;不支援
`time`	時間無日期
`localtime`	系統時鐘基礎時間

預存程序

PostgreSQL 實體不支援儲存程序。改用表格和視圖。

MySQL

最低版本

必須使用 MySQL 8 或更新版本。

不支援的資料類型

以下 MySQL 資料型別不被 DAB 支援：

資料類型	Notes
`UUID`	通用唯一識別碼
`DATE`	日曆日期
`SMALLDATETIME`	較不精確的日期與時間儲存
`DATETIME2`	不是原生的;用途 `datetime`
`DATETIMEOFFSET`	日期與時間，並附時區
`TIME`	時間無日期
`LOCALTIME`	根據系統時鐘計算的當前時間

預存程序

MySQL 實體不支援儲存程序。改用表格吧。

Azure Synapse Analytics （Dedicated SQL pool）

支援的物件

專用 SQL 池支援資料表、檢視與儲存程序——與 SQL Server 及 Azure SQL 相同。不支援無伺服器 SQL 池。

不支援的功能

Feature	Notes
多個突變	不支援

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-01

共用方式為

Data API 建構器資料庫專屬功能參考

資料庫版本支援

SQL Server 與 Azure SQL

SESSION_CONTEXT

啟用SESSION_CONTEXT

在 SQL 中使用 SESSION_CONTEXT

SESSION_CONTEXT與連線池化

連接串的變體

不支援的資料類型

Azure Cosmos DB for NoSQL

結構需求

@model 指令

@authorize 指令

REST API 不可用

Cosmos 資料庫中未支援的功能

PostgreSQL

最低版本

不支援的資料類型

預存程序

MySQL

最低版本

不支援的資料類型

預存程序

Azure Synapse Analytics （Dedicated SQL pool）

支援的物件

不支援的功能

相關內容

意見反應

其他資源