數據源

區 data-source 段會定義數據庫存取詳細數據。它也會定義資料庫選項。

數據源設定

Property	Description
資料來源	包含資料庫連線設定的物件
Data-Source.database-type	後端使用的資料庫：`mssql`， `postgresql`， `mysqlcosmosdb_nosqlcosmosdb_postgresql`
Data-Source.Connection-string	所選資料庫類型的連接字串
data-source.options	資料庫特定屬性（例如，SQL Server、Cosmos DB 等的選項）
Data-Source.options.database	適用於 NoSQL 資料庫的 Azure Cosmos DB 名稱（需要時 `database-type = cosmosdb_nosql`）
Data-source.options.container	適用於 NoSQL 的 Azure Cosmos DB 容器名稱（需要時 `database-type = cosmosdb_nosql`）
Data-Source.options.schema	GraphQL 架構檔案的路徑（需要時 `database-type = cosmosdb_nosql`）
Data-Source.options.set-session-context	啟用將 JSON Web 令牌（JWT）宣告傳送為工作階段內容（僅限 SQL Server）
Data-source.health	設定數據源健康情況檢查的物件
data-source.health.enabled	啟用健康情況檢查端點
data-source.health.name	健康情況報告中使用的標識碼
data-source.health.threshold-ms	健康情況檢查查詢的持續時間上限，以毫秒為單位
Data-Source.user-delegated-auth	物件配置 On-Behalf-Of（OBO）使用者委派認證（僅限 mssql）
data-source.user-delegated-auth.enabled	啟用 OBO 認證
data-source.user-delegated-auth.provider（資料來源）	OBO 身份提供者（目前 `EntraId` 僅有）
Data-Source.user-delegated-auth.database-audience	下游 SQL 代幣的目標受眾

格式概觀

{
  "data-source": {
    "database-type": <string>,
    "connection-string": <string>,
    "options": {
      // mssql only
      "set-session-context": <true> (default) | <false>,
      // cosmosdb_nosql only
      "database": <string>,
      "container": <string>,
      "schema": <string>
    },
    "health": {
      "enabled": <true> (default) | <false>,
      "name": <string>,
      "threshold-ms": <integer; default: 1000>
    },
    "user-delegated-auth": {
      "enabled": <true> | <false> (default),
      "provider": <string>,
      "database-audience": <string>
    }
  },
  "data-source-files": ["<string>"]
}

數據源

Parent	Property	類型	Required	Default
`$root`	`data-source`	物件	✔️ 是的	-

巢狀屬性

Parent	Property	類型	Required	Default
`data-source`	`database-type`	列舉	✔️ 是的	None
`data-source`	`connection-string`	字串	✔️ 是的	None
`data-source`	`options`	物件	❌ 否	None

屬性值

`database-type`	Description	最小版本
`mssql`	網狀架構中的 SQL	-
`mssql`	Azure SQL Database	-
`mssql`	Azure SQL MI	-
`mssql`	SQL Server	2016
`dwsql`	Azure Synapse Analytics	-
`dwsql`	布料倉庫	-
`dwsql`	網狀架構 SQL 分析端點	-
`postgresql`	PostgreSQL	ver. 11
`mysql`	MySQL	ver. 8
`cosmosdb_nosql`	Azure Cosmos DB for NoSQL	-
`cosmosdb_postgresql`	Azure Cosmos DB for PostgreSQL	-

Format

{
  "data-source": {
    "database-type": <string>,
    "connection-string": <string>,
    "options": {
      "<key-name>": <string>
    }
  }
}

範例：Azure SQL 和 SQL Server

"data-source": {
  "database-type": "mssql",
  "connection-string": "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=MyDatabase;User ID=MyUser;Password=MyPassword;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;",
    "options": {
      "set-session-context": true
    }
}

Note

資料 API 建構器使用 SqlClient 來Azure SQL 和 SQL Server，支援 these 連接字串變體。

使用 `SESSION_CONTEXT`

針對 Azure SQL 和 SQL Server，數據 API 產生器可以在 SQL 的 SESSION_CONTEXT中包含宣告資訊。

CREATE PROC GetUser @userId INT AS
BEGIN
    -- Use claims
    IF SESSION_CONTEXT(N'user_role') = 'admin' 
    BEGIN
        RAISERROR('Unauthorized access', 16, 1);
    END

    SELECT Id, Name, Age, IsAdmin
    FROM Users
    WHERE Id = @userId;
END;

範例：Azure Cosmos DB

"data-source": {
  "database-type": "cosmosdb_nosql",
  "connection-string": "@env('SQL_CONNECTION_STRING')",
  "options": {
    "database": "Your_CosmosDB_Database_Name",
    "container": "Your_CosmosDB_Container_Name",
    "schema": "Path_to_Your_GraphQL_Schema_File"
  }
}

Note

指定的「選項」是 Azure Cosmos DB 特有的。databasecontainerschema。

環境變數

使用環境變數，將純文本秘密保留在組態檔中。

Tip

Data API 建構器同時支援函@env()式與.env檔案。

"data-source": {
  "database-type": "mssql",
  "connection-string": "@env('SQL_CONNECTION_STRING')"
}

連線彈性

數據 API 產生器會使用指數輪詢，在暫時性錯誤之後重試資料庫要求。

Attempts	First	Second	Third	Fourth	Fifth
Seconds	2s	4s	8s	16s	32s

管理服務身份（MSI）

管理服務身份（MSI）支援於 DefaultAzureCredential 函式庫中定義的 Azure.Identity。深入瞭解 Azure SQL Microsoft Entra 中的受控識別。

使用者指派管理身份（UAMI）

對於使用者指派的管理身份，請在連接字串上加上 Authentication 和 User ID屬性，並以使用者指派的管理身份的用戶端 ID：Authentication=Active Directory Managed Identity; User Id=<UMI_CLIENT_ID>; 替換。

系統指派管理身份（SAMI）

對於系統指派的管理身份，請附加 Authentication 屬性，並從連接字串中排除 UserId 和 Password 參數：Authentication=Active Directory Managed Identity;。

健康情況（資料來源）

Parent	Property	類型	Required	Default
`data-source`	`health`	物件	No	–

數據 API 產生器支援多個組態檔，每個組態檔都有自己的數據源。此組態區塊可讓每個數據源有自己的健康情況設定。

巢狀屬性

Parent	Property	類型	Required	Default
`data-source.health`	`enabled`	boolean	No	true
`data-source.health`	`name`	字串	No	database-type
`data-source.health`	`threshold-ms`	整數	No	1000

檢查名稱

由於多個組態檔可以指向相同類型的數據源，因此無法在健康情況報告中區分這些數據源。用來 name 指派唯一且可識別的標籤，只用於健康情況報告。

檢查行為

針對指定的數據源執行最簡單的可能查詢，這是針對指定的數據源執行，以驗證是否可以開啟連線。 threshold-ms使用屬性來設定該查詢完成的最大可接受持續時間（以毫秒為單位）。

Format

{
  "data-source": {
    "health": {
      "enabled": <true> (default) | <false>,
      "name": <string>,
      "threshold-ms": <integer; default: 1000>
    }
  }
}

使用者委派認證

Parent	Property	類型	Required	Default
`data-source`	`user-delegated-auth`	物件	No	–

On-Behalf-Of（OBO）SQL Server 與 Azure SQL 的使用者委派認證。啟用後，DAB 會將接收的使用者令牌交換為下游的 SQL 令牌，使資料庫以實際呼叫使用者身份進行認證。此功能僅支援 mssql 資料來源，且需Microsoft Entra ID上游驗證。

Note

本節所述的資料 API 建構器功能可在 2.0 版本及更新版本中使用。欲了解更多資訊，請參閱 2.0 版本的新內容。

巢狀屬性

Parent	Property	類型	Required	Default
`data-source.user-delegated-auth`	`enabled`	boolean	No	假的
`data-source.user-delegated-auth`	`provider`	enum（`EntraId`）	No	`EntraId`
`data-source.user-delegated-auth`	`database-audience`	字串	啟用時是的。	None

enabled—開啟或關閉OBO。
provider—— 為令牌交換的身份提供者。目前僅支援 EntraId。
database-audience—下游 SQL 代幣的目標受眾（例如， https://database.windows.net）。

必要的環境變數

啟用 OBO 時，DAB 會讀取以下環境變數以進行代幣交換：

變數	Description
`DAB_OBO_CLIENT_ID`	Microsoft Entra ID 應用程式註冊的應用程式（用戶端）ID
`DAB_OBO_CLIENT_SECRET`	應用程式註冊的用戶端秘密
`DAB_OBO_TENANT_ID`	Microsoft Entra ID 租戶識別碼

每用戶連線池

啟用 OBO 時，DAB 會為每位使用者維護獨立的 SQL 連線池，確保某位使用者的存取權杖不會被重複用於另一位使用者的請求。

Note

每使用者連線池僅在 OBO 認證啟用時適用。標準部署則不受影響。

Format

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "user-delegated-auth": {
      "enabled": <true> | <false> (default),
      "provider": <string>,
      "database-audience": <string>
    }
  }
}

範例

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "user-delegated-auth": {
      "enabled": true,
      "provider": "EntraId",
      "database-audience": "https://database.windows.net"
    }
  }
}

這很重要

OBO 僅 mssql支援。啟用 OBO 時必須具備此 database-audience 特性。對非 MSSQL 資料來源執行此設定會無法驗證。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-06-04

數據源

數據源設定

格式概觀

數據源

巢狀屬性

屬性值

Format

範例：Azure SQL 和 SQL Server

使用 SESSION_CONTEXT

範例：Azure Cosmos DB

環境變數

連線彈性

管理服務身份（MSI）

使用者指派管理身份（UAMI）

系統指派管理身份（SAMI）

健康情況 （資料來源）

巢狀屬性

檢查名稱

檢查行為

Format

使用者委派認證

巢狀屬性

必要的環境變數

每用戶連線池

Format

範例

意見反應

其他資源

使用 `SESSION_CONTEXT`

健康情況（資料來源）