共用方式為


Runtime

決定運行時間行為的組態設定。

分頁設定

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-introspectionfalse 以隱藏 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

屬性附註

  • 如果全域 enabledfalse,則個別實體層級 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.modedevelopment才會運作。 若模擬器設定為生產模式,DAB 無法啟動。

角色選擇

除了 Simulator 外,所有提供者的 X-MS-API-ROLE 標頭會從已認證使用者的聲明中選擇要使用的角色。 若省略,請求將使用 Authenticated 系統角色。 關於角色評估的詳細資訊,請參見 授權與角色

JWT (驗證主機執行時間)

Parent Property 類型 Required Default
runtime.host.authentication jwt 物件 ❌ 否 -

全域 JSON Web 令牌 (JWT) 設定。

數據 API 產生器中 JSON Web 令牌支援的圖表。

巢狀屬性

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-relativetrue時,分頁 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] 設定$limitfirst-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

如果全域 enabledfalse,則個別實體層級 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

如果全域 enabledfalse,則個別實體層級 enabled 並不重要。

Example

{
  "health": {
    "enabled": true,
    "roles": ["admin", "support"],
    "cache-ttl-seconds": 10,
    "max-query-parallelism": 6
  }
}