決定運行時間行為的組態設定。
分頁設定
| Property | Default | Description |
|---|---|---|
| runtime.pagination.max-page-size | 定義每頁的記錄上限 | |
| runtime.pagination.default-page-size | 設定每個回應的默認記錄 |
REST 設定
| Property | Default | Description |
|---|---|---|
| 運行時.rest.path | "/api" |
REST 端點的基底路徑 |
| runtime.rest.enabled | true |
允許啟用或停用所有實體的 REST 要求 |
| runtime.rest.request-body-strict | true |
當為 true 時,不允許要求本文中的無關欄位 |
GraphQL 設定
| Property | Default | Description |
|---|---|---|
| runtime.graphql.allow-introspection | true |
允許查詢基礎 GraphQL 架構 |
| runtime.graphql.path | "/graphql" |
GraphQL 端點的基底路徑 |
| runtime.graphql.enabled | true |
允許啟用或停用所有實體的 GraphQL 要求 |
| runtime.graphql.深度限制 | null |
GraphQL 查詢允許的最大深度 |
| runtime.graphql.multiple-mutations.create.enabled | false |
允許針對所有實體進行多重建立突變 |
主機設定
| Property | Default | Description |
|---|---|---|
| runtime.host.max-回應大小-mb | 158 |
單一結果中允許的資料庫回應大小上限 (MB) |
| runtime.host.mode | "production" |
執行模式; "production" 或 "development" |
CORS 設定
| Property | Default | Description |
|---|---|---|
| runtime.host.cors.origins | [] |
允許的 CORS 來源 |
| runtime.host.cors.allow-credentials | false |
設定 Access-Control-Allow-Credentials 標頭的值 |
驗證設定
| Property | Default | Description |
|---|---|---|
| runtime.host.authentication.provider | null |
驗證提供者 |
| runtime.host.authentication.jwt.audience | null |
JWT 對象 |
| runtime.host.authentication.jwt.issuer | null |
JWT 發行者 |
快取設定
| Property | Default | Description |
|---|---|---|
| runtime.cache.enabled | false |
啟用全域回應的快取 |
| runtime.cache.ttl-秒 | 5 |
全域快取的存留時間(秒) |
遙測設置
| Property | Default | Description |
|---|---|---|
| runtime.telemetry.application-insights.connection-string | null |
Application Insights 連接字串 |
| runtime.telemetry.application-insights.enabled | false |
啟用或停用 Application Insights 遙測 |
| runtime.telemetry.open-telemetry.endpoint | null |
OpenTelemetry 收集器 URL |
| runtime.telemetry.open-telemetry.headers | {} |
OpenTelemetry 匯出標頭 |
| runtime.telemetry.open-telemetry.service-name | "dab" |
OpenTelemetry 服務名稱 |
| runtime.telemetry.open-telemetry.exporter-protocol | "grpc" |
OpenTelemetry 通訊協定 (“grpc” 或 “httpprotobuf”) |
| runtime.telemetry.open-telemetry.enabled | true |
啟用或停用 OpenTelemetry |
| runtime.telemetry.log-level.namespace | null |
命名空間特定的記錄層級覆寫 |
| runtime.health.enabled | true |
啟用或停用全域健康情況檢查端點 |
| runtime.health.roles | null |
完整健康情況端點的允許角色 |
| runtime.health.cache-ttl-秒 | 5 |
健康情況檢查報表快取專案的存留時間(秒) |
| runtime.health.max-查詢平行 | 4 |
最大同時健康檢查查詢(範圍:1-8) |
格式概觀
{
"runtime": {
"pagination": {
"max-page-size": <integer|null> (default: `100000`),
"default-page-size": <integer|null> (default: `100`)
},
"rest": {
"path": <string> (default: "/api"),
"enabled": <true>|<false>,
"request-body-strict": <true>|<false> (default: `true`)
},
"graphql": {
"path": <string> (default: "/graphql"),
"enabled": <true>|<false>,
"allow-introspection": <true>|<false>,
"depth-limit": <integer|null> (default: `null`),
"multiple-mutations": {
"create": {
"enabled": <true>|<false> (default: `false`)
}
}
},
"host": {
"mode": <"production"> (default) | <"development">,
"max-response-size-mb": <integer|null> (default: `158`),
"cors": {
"origins": [ "<string>" ],
"allow-credentials": <true>|<false> (default: `false`)
},
"authentication": {
"provider": <string> (default: "AppService"),
"jwt": {
"audience": "<string>",
"issuer": "<string>"
}
}
}
},
"cache": {
"enabled": <true>|<false> (default: `false`),
"ttl-seconds": <integer> (default: `5`)
},
"telemetry": {
"application-insights": {
"connection-string": "<string>",
"enabled": <true>|<false> (default: `true`)
},
"open-telemetry": {
"endpoint": "<string>",
"headers": "<string>",
"service-name": <string> (default: "dab"),
"exporter-protocol": <"grpc"> (default) | <"httpprotobuf">,
"enabled": <true>|<false> (default: `true`)
},
"log-level": {
// namespace keys
"<namespace>": <"trace"|"debug"|"information"|"warning"|"error"|"critical"|"none"|null>
}
},
"health": {
"enabled": <true>|<false> (default: `true`),
"roles": [ "<string>" ],
"cache-ttl-seconds": <integer> (default: `5`),
"max-query-parallelism": <integer> (default: `4`)
}
}
模式 (主機執行時間)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime |
host |
enum (production | development) |
❌ 否 | production |
開發行為
- Enabled Nitro (先前稱為香蕉蛋糕流行) 用於 GraphQL 測試
- 已啟用用於 REST 測試的 Swagger UI
- 已啟用匿名健康情況檢查
- 增加記錄詳細資訊 (偵錯)
Format
{
"runtime": {
"host": {
"mode": "production" (default) | "development"
}
}
}
回應大小上限 (主機執行時間)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.host |
max-response-size-mb |
整數 | ❌ 否 | 158 |
設定任何指定結果的大小上限(以 MB 為單位)。 由於大型回應可能會使系統緊張, max-response-size-mb 因此會限制總大小(與數據列計數不同),以防止多載,尤其是文字或 JSON 等大型數據行。
| Value | Result |
|---|---|
| 未設定 | 使用預設值 |
null |
使用預設值 |
integer |
任何正32位整數 |
<= 0 |
不支援 |
Format
{
"runtime": {
"host": {
"max-response-size-mb": <integer; default: 158>
}
}
}
GraphQL (執行時間)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime |
graphql |
物件 | ❌ 否 | - |
全域 GraphQL 組態。
巢狀屬性
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.graphql |
enabled |
boolean | ❌ 否 | None |
runtime.graphql |
path |
字串 | ❌ 否 | "/graphql" |
runtime.graphql |
depth-limit |
整數 | ❌ 否 | 無(無限制) |
runtime.graphql |
allow-introspection |
boolean | ❌ 否 | True |
runtime.graphql |
multiple-mutations.create.enabled |
boolean | ❌ 否 | False |
屬性附註
- 該物業不允許
path使用分道。 - 使用
depth-limit來限制巢狀查詢。 - 設定
allow-introspection為false以隱藏 GraphQL 架構。 - 用來
multiple-mutations在單一突變中插入多個實體。
Format
{
"runtime": {
"graphql": {
"enabled": <true> (default) | <false>
"depth-limit": <integer|null> (default: `null`),
"path": <string> (default: /graphql),
"allow-introspection": <true> (default) | <false>,
"multiple-mutations": {
"create": {
"enabled": <true> (default) | <false>
}
}
}
}
範例:多個突變
Configuration
{
"runtime": {
"graphql": {
"multiple-mutations": {
"create": {
"enabled": true
}
}
}
},
"entities": {
"User": {
"source": "dbo.Users",
"permissions": [
{
"role": "anonymous",
"actions": ["create"] // entity permissions are required
}
]
}
}
}
GraphQL 突變
mutation {
createUsers(input: [
{ name: "Alice", age: 30, isAdmin: true },
{ name: "Bob", age: 25, isAdmin: false },
{ name: "Charlie", age: 35, isAdmin: true }
]) {
id
name
age
isAdmin
}
}
REST (執行階段)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime |
rest |
物件 | ❌ 否 | - |
全域 REST 組態。
巢狀屬性
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.rest |
enabled |
boolean | ❌ 否 | None |
runtime.rest |
path |
字串 | ❌ 否 | "/api" |
runtime.rest |
request-body-strict |
boolean | ❌ 否 | True |
屬性附註
- 如果全域
enabled為false,則個別實體層級enabled並不重要。 - 屬性
path不支援子路徑值,例如/api/data。 -
request-body-strict引進有助於簡化 .NET POCO 物件。
request-body-strict |
Behavior |
|---|---|
true |
要求本文中的額外欄位會造成 BadRequest 例外狀況。 |
false |
要求本文中的額外欄位會被忽略。 |
Format
{
"runtime": {
"rest": {
"enabled": <true> (default) | <false>,
"path": <string> (default: /api),
"request-body-strict": <true> (default) | <false>
}
}
}
範例:request-body-strict
-
default()只有在承載INSERT中的數據行值為 時,才會忽略null具有值的數據行。 因此,當是 時,INSERT資料default()列中的作業無法產生明確的request-body-strict值。truenull為了達成此行為,需要一個UPDATE操作。 - 不論承載值為何,都不會忽略
default()具有UPDATE的數據行。 - 計算數據行一律會被忽略。
- 自動產生的數據行一律會被忽略。
範例數據表
CREATE TABLE Users (
Id INT PRIMARY KEY IDENTITY, -- auto-generated column
Name NVARCHAR(50) NOT NULL,
Age INT DEFAULT 18, -- column with default
IsAdmin BIT DEFAULT 0, -- column with default
IsMinor AS IIF(Age <= 18, 1, 0) -- computed column
);
請求載荷
{
"Id": 999,
"Name": "Alice",
"Age": null,
"IsAdmin": null,
"IsMinor": false,
"ExtraField": "ignored"
}
插入行為時機 request-body-strict = false
INSERT INTO Users (Name) VALUES ('Alice');
-- Default values for Age (18) and IsAdmin (0) are applied by the database.
-- IsMinor is ignored because it’s a computed column.
-- ExtraField is ignored.
-- The database generates the Id value.
回應負載
{
"Id": 1, // Auto-generated by the database
"Name": "Alice",
"Age": 18, // Default applied
"IsAdmin": false, // Default applied
"IsMinor": true // Computed
}
更新行為時機 request-body-strict = false
UPDATE Users
SET Name = 'Alice Updated', Age = NULL
WHERE Id = 1;
-- IsMinor and ExtraField are ignored.
回應負載
{
"Id": 1,
"Name": "Alice Updated",
"Age": null,
"IsAdmin": false,
"IsMinor": false // Recomputed by the database (false when age is `null`)
}
CORS (主機執行時間)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.host |
cors |
物件 | ❌ 否 | - |
全域 CORS 設定。
Tip
CORS 代表「跨原產資源共享」(Cross-Origin Resource Sharing)。這是瀏覽器的安全功能,用來控制網頁是否能向與原本網域不同的網域發出請求。
巢狀屬性
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.host.cors |
allow-credentials |
boolean | ❌ 否 | False |
runtime.host.cors |
origins |
字串陣列 | ❌ 否 | None |
Note
屬性會allow-credentialsAccess-Control-Allow-Credentials設定 CORS 標頭。
Format
{
"runtime": {
"host": {
"cors": {
"allow-credentials": <true> (default) | <false>,
"origins": ["<array-of-strings>"]
}
}
}
}
Note
通配符 * 作為的值 origins有效。
提供者(驗證主機執行時間)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.host.authentication |
provider |
列舉 (AppService | EntraId | Custom | Simulator) |
❌ 否 | None |
選擇認證方式。 每個提供者對身份的驗證方式都不同。 關於逐步安裝,請參閱下方連結的操作指南。
提供者摘要
| Provider | 用例 | 身份來源 | 操作指南 |
|---|---|---|---|
| (省略) | 僅限匿名存取 | None | — |
AppService |
Azure-hosted apps (EasyAuth) |
X-MS-CLIENT-PRINCIPAL 標頭 |
設定 App Service 認證 |
EntraID |
Microsoft Entra ID (Azure AD) | JWT 持有人代幣 | 設定 Entra ID 驗證 |
Custom |
第三方 IDP(Okta、Auth0) | JWT 持有人代幣 | 設定自訂 JWT 認證 |
Simulator |
僅限本地測試 | 模擬 | 設定模擬器認證 |
Note
該 EntraId 提供者先前名為 AzureAd。 舊名稱仍可相容。
僅限匿名(無提供者)
當 authentication 該區段被省略時,DAB 會以僅匿名模式運作。 所有請求都會被分配系統 Anonymous 角色。
{
"host": {
// authentication section omitted
}
}
AppService
Trusts identity headers injected by Azure App Service EasyAuth.
{
"host": {
"authentication": {
"provider": "AppService"
}
}
}
EntraID
驗證由 Microsoft Entra ID 發行的 JWT 令牌。
{
"host": {
"authentication": {
"provider": "EntraId",
"jwt": {
"audience": "<application-id>",
"issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0"
}
}
}
}
Custom
驗證第三方身份提供者的 JWT 代幣。
{
"host": {
"authentication": {
"provider": "Custom",
"jwt": {
"audience": "<api-audience>",
"issuer": "https://<your-idp-domain>/"
}
}
}
}
模擬器
模擬本地開發與測試的認證。
{
"host": {
"authentication": {
"provider": "Simulator"
}
}
}
Important
Simulator該服務提供者只有在 runtime.host.mode 時development才會運作。 若模擬器設定為生產模式,DAB 無法啟動。
角色選擇
除了 Simulator 外,所有提供者的 X-MS-API-ROLE 標頭會從已認證使用者的聲明中選擇要使用的角色。 若省略,請求將使用 Authenticated 系統角色。 關於角色評估的詳細資訊,請參見 授權與角色。
JWT (驗證主機執行時間)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.host.authentication |
jwt |
物件 | ❌ 否 | - |
全域 JSON Web 令牌 (JWT) 設定。
巢狀屬性
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.host.authentication.jwt |
audience |
字串 | ❌ 否 | None |
runtime.host.authentication.jwt |
issuer |
字串 | ❌ 否 | None |
Format
{
"runtime": {
"host": {
"authentication": {
"jwt": {
"audience": "<client-id>",
"issuer": "<issuer-url>"
}
}
}
}
}
分頁 (執行階段)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime |
pagination |
物件 | ❌ 否 | - |
REST 和 GraphQL 端點的全域分頁限制。
巢狀屬性
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.pagination |
max-page-size |
int | ❌ 否 | 100,000 |
runtime.pagination |
default-page-size |
int | ❌ 否 | 100 |
runtime.pagination |
next-link-relative |
boolean | ❌ 否 | false |
支援的最大頁面大小值
| Value | Result |
|---|---|
integer |
支援任何正32位整數。 |
0 |
不支援。 |
-1 |
預設為支援的最大值。 |
< -1 |
不支援。 |
默認頁面大小支援的值
| Value | Result |
|---|---|
integer |
小於目前 max-page-size的任何正整數。 |
0 |
不支援。 |
-1 |
預設為目前的 max-page-size 設定。 |
< -1 |
不支援。 |
下一連結相對行為
當 next-link-relative 為 true時,分頁 nextLink 值使用相對網址而非絕對網址。
| Value | Example |
|---|---|
false (預設值) |
"nextLink": "https://localhost:5001/api/users?$after=..." |
true |
"nextLink": "/api/users?$after=..." |
Format
{
"runtime": {
"pagination": {
"max-page-size": <integer; default: 100000>,
"default-page-size": <integer; default: 100>,
"next-link-relative": <boolean; default: false>
}
}
}
Note
當值大於 max-page-size時,結果會限制在 max-page-size。
範例:REST 中的分頁
Request
GET https://localhost:5001/api/users
回應負載
{
"value": [
{
"Id": 1,
"Name": "Alice",
"Age": 30,
"IsAdmin": true,
"IsMinor": false
},
{
"Id": 2,
"Name": "Bob",
"Age": 17,
"IsAdmin": false,
"IsMinor": true
}
],
"nextLink": "https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}
要求下一頁
GET https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==
範例:GraphQL 中的分頁
要求承載 (查詢)
query {
users {
items {
Id
Name
Age
IsAdmin
IsMinor
}
hasNextPage
endCursor
}
}
回應負載
{
"data": {
"users": {
"items": [
{
"Id": 1,
"Name": "Alice",
"Age": 30,
"IsAdmin": true,
"IsMinor": false
},
{
"Id": 2,
"Name": "Bob",
"Age": 17,
"IsAdmin": false,
"IsMinor": true
}
],
"hasNextPage": true,
"endCursor": "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}
}
}
要求下一頁
query {
users(after: "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==") {
items {
Id
Name
Age
IsAdmin
IsMinor
}
hasNextPage
endCursor
}
}
範例:在 max-page-size 要求中存取
將 [REST] 或 max-page-size [GraphQL] 設定$limit為 first,-1以使用 值。
REST
GET https://localhost:5001/api/users?$limit=-1
GraphQL
query {
users(first: -1) {
items {
...
}
}
}
快取 (執行階段)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime |
cache |
物件 | ❌ 否 | - |
全域快取組態。
巢狀屬性
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.cache |
enabled |
boolean | ❌ 否 | False |
runtime.cache |
ttl-seconds |
整數 | ❌ 否 | 5 |
Tip
實體層級 cache.ttl-seconds 屬性預設為這個全域值。
Format
{
"runtime": {
"cache": {
"enabled": <boolean>,
"ttl-seconds": <integer>
}
}
}
Important
如果全域 enabled 為 false,則個別實體層級 enabled 並不重要。
遙測 (執行階段)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime |
telemetry |
物件 | ❌ 否 | - |
全域遙測設定。
巢狀屬性
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.telemetry |
log-level |
字典 | ❌ 否 | None |
runtime.telemetry |
application-insights |
物件 | ❌ 否 | - |
runtime.telemetry |
open-telemetry |
物件 | ❌ 否 | - |
設定每個命名空間的記錄詳細資訊。 這會遵循標準 .NET 記錄慣例並允許細微控制,不過它假設對數據 API 產生器內部有一些熟悉。 資料 API 產生器是開放原始碼: https://aka.ms/dab
Format
{
"runtime": {
"telemetry": {
"log-level": {
"namespace": "log-level",
"namespace": "log-level"
}
}
}
}
Tip
log-level 可以在開發和生產環境中進行熱重載。 它目前是唯一支援生產環境中熱重載的屬性。
Example
{
"runtime": {
"telemetry": {
"log-level": {
"Azure.DataApiBuilder.Core.Configurations.RuntimeConfigValidator": "debug",
"Azure.DataApiBuilder.Core": "information",
"default": "warning"
}
}
}
}
Application Insights (遙測)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.telemetry |
application-insights |
物件 | ❌ 否 | - |
設定記錄至 Application Insights。
巢狀屬性
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.telemetry.application-insights |
enabled |
boolean | ❌ 否 | False |
runtime.telemetry.application-insights |
connection-string |
字串 | ✔️ 是的 | None |
Format
{
"runtime": {
"telemetry": {
"application-insights": {
"enabled": <true; default: true> | <false>
"connection-string": <string>
}
}
}
}
OpenTelemetry (遙測)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.telemetry |
open-telemetry |
物件 | ❌ 否 | - |
設定記錄以開啟遙測。
巢狀屬性
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime.telemetry.open-telemetry |
enabled |
boolean | ❌ 否 | true |
runtime.telemetry.open-telemetry |
endpoint |
字串 | ✔️ 是的 | None |
runtime.telemetry.open-telemetry |
headers |
字串 | ❌ 否 | None |
runtime.telemetry.open-telemetry |
service-name |
字串 | ❌ 否 | “dab” |
runtime.telemetry.open-telemetry |
exporter-protocol |
enum (grpc | httpprotobuf) |
❌ 否 | grpc |
多個標頭會 , 以逗號分隔。
Format
{
"runtime": {
"telemetry": {
"open-telemetry": {
"enabled": <true> (default) | <false>,
"endpoint": <string>,
"headers": <string>,
"service-name": <string> (default: "dab"),
"exporter-protocol": <"grpc" (default) | "httpprotobuf">
}
}
}
}
Example
{
"runtime": {
"telemetry": {
"open-telemetry": {
"enabled": true,
// a gRPC endpoint example
"endpoint": "http://localhost:4317",
// an HTTP/protobuf endpoint example
"endpoint": "http://localhost:4318/v1/metrics",
"headers": "api-key=key,other-config-value=value",
"service-name": "dab",
}
}
}
}
深入瞭解 OTEL_EXPORTER_OTLP_HEADERS。
Note
gRPC(4317)速度較快且支援串流,但需要更多設定步驟。 HTTP/protobuf (4318) 較簡單且更容易偵錯,但效率較低。
健康情況 (執行階段)
| Parent | Property | 類型 | Required | Default |
|---|---|---|---|---|
runtime |
health |
物件 | ❌ 否 | - |
全域 健康情況檢查端點 (/health) 組態。
巢狀屬性
| Parent | Property | 類型 | Required | Default | 音域/註解 |
|---|---|---|---|---|---|
runtime.health |
enabled |
boolean | ❌ 否 | true |
|
runtime.health |
roles |
字串陣列 | ✔️ 是* | null |
*生產模式下必須 |
runtime.health |
cache-ttl-seconds |
整數 | ❌ 否 | 5 |
最小值:0 |
runtime.health |
max-query-parallelism |
整數 | ❌ 否 | 4 |
最小:1,最大:8(夾緊) |
開發與生產環境的行為
| Condition | 開發行為 | 生產行為 |
|---|---|---|
health.enabled = 假 |
403 地位 |
403 地位 |
health.enabled = 真 |
視角色而定 | 視角色而定 |
roles 省略 或 null |
顯示健康情況 |
403 地位 |
目前的角色不在 roles |
403 地位 |
403 地位 |
中目前的角色 roles |
顯示健康情況 | 顯示健康情況 |
roles 包括 anonymous |
顯示健康情況 | 顯示健康情況 |
Format
{
"health": {
"enabled": <true> (default) | <false>,
"roles": [ <string> ], // required in production
"cache-ttl-seconds": <integer; default: 5>,
"max-query-parallelism": <integer; default: 4>
}
}
Note
如果全域 enabled 為 false,則個別實體層級 enabled 並不重要。
Example
{
"health": {
"enabled": true,
"roles": ["admin", "support"],
"cache-ttl-seconds": 10,
"max-query-parallelism": 6
}
}