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	`Unauthenticated`	驗證提供者
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`	全域快取的存留時間（秒）
runtime.cache.level-2.enabled	`false`	全球啟用分散式二級快取
runtime.cache.level-2.provider	`"redis"`	第二層快取的分散式快取提供者
runtime.cache.level-2.connection-string	`null`	第二級快取提供者的連線字串
runtime.cache.level-2.partition	`null`	可選分割區名稱用於隔離分散式快取空間

壓縮設定

Property	Default	Description
runtime.compression.level	`optimal`	HTTP 回應壓縮等級（`optimal`、、 `fastest`或 `none`）

遙測設置

Property	Default	Description
runtime.telemetry.application-insights.connection-string	`null`	Application Insights 連接字串
runtime.telemetry.application-insights.enabled	`true`	啟用或停用 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.open-telemetry.enabled	`true`	啟用或停用 OpenTelemetry
Runtime.telemetry.azure-log-analytics.enabled	`false`	啟用或停用 Azure Log Analytics
Runtime.telemetry.azure-log-analytics.dab-identifier	`"DabLogs"`	Azure Log Analytics 中 DAB 識別碼
runtime.telemetry.azure-log-analytics.flush-interval-seconds	`5`	日誌批次推入間隔（秒數）
Runtime.telemetry.azure-log-analytics.auth.custom-table-name	`null`	Custom table name for Azure Log Analytics
Runtime.telemetry.azure-log-analytics.auth.dcr-immutable-id	`null`	資料收集規則不可變 ID
runtime.telemetry.azure-log-analytics.auth.dce-endpoint	`null`	資料收集端點網址
runtime.telemetry.file.enabled	`false`	啟用或停用檔案匯入日誌
runtime.telemetry.file.path	`"/logs/dab-log.txt"`	遙測日誌的檔案路徑
runtime.telemetry.file.rolling-interval	`"Day"`	日誌檔的滾動間隔
runtime.telemetry.file.retained-file-count-limit	`1`	保留日誌檔案的最大數量
runtime.telemetry.file.file-size-limit-bytes	`1048576`	滾動前的最大檔案大小（位元組）
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）

MCP 設定

Property	Default	Description
runtime.mcp.enabled	`true`	全域啟用或停用 MCP 端點
runtime.mcp.path	`"/mcp"`	MCP 端點的基底路徑
runtime.mcp.description	`null`	伺服器描述在初始化時傳送給 MCP 用戶端
Runtime.mcp.dml-tools	`true`	啟用或停用所有 DML 工具，或每個工具控制的物件
runtime.mcp.dml-tools.describe-entities	`true`	啟用describe_entities工具
runtime.mcp.dml-tools.create-record	`true`	啟用create_record工具
runtime.mcp.dml-tools.read-records	`true`	啟用read_records工具
Runtime.mcp.dml-tools.update-record	`true`	啟用update_record工具
Runtime.mcp.dml-tools.delete-record	`true`	啟用delete_record工具
runtime.mcp.dml-tools.execute-entity	`true`	啟用execute_entity工具
runtime.mcp.dml-tools.aggregate-records	`true`	啟用aggregate_records工具（布林值或帶有查詢逾時的物件）

格式概觀

{
  "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: "Unauthenticated"),
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  },
    "compression": {
      "level": <"optimal"> (default) | <"fastest"> | <"none">
    },
    "cache": {
      "enabled": <true>|<false> (default: `false`),
      "ttl-seconds": <integer> (default: `5`),
      "level-2": {
        "enabled": <true>|<false> (default: `false`),
        "provider": <"redis">,
        "connection-string": <string>,
        "partition": <string>
      }
    },
    "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`)
      },
      "azure-log-analytics": {
        "enabled": <true>|<false> (default: `false`),
        "dab-identifier": <string> (default: "DabLogs"),
        "flush-interval-seconds": <integer> (default: `5`),
        "auth": {
          "custom-table-name": <string>,
          "dcr-immutable-id": <string>,
          "dce-endpoint": <string>
        }
      },
      "file": {
        "enabled": <true>|<false> (default: `false`),
        "path": <string> (default: "/logs/dab-log.txt"),
        "rolling-interval": <string> (default: "Day"),
        "retained-file-count-limit": <integer> (default: `1`),
        "file-size-limit-bytes": <integer> (default: `1048576`)
      },
      "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`)
    },
    "mcp": {
      "enabled": <true>|<false> (default: `true`),
      "path": <string> (default: `"/mcp"`),
      "description": <string>,
      "dml-tools": <true>|<false> | {
        "describe-entities": <true>|<false> (default: `true`),
        "create-record": <true>|<false> (default: `true`),
        "read-records": <true>|<false> (default: `true`),
        "update-record": <true>|<false> (default: `true`),
        "delete-record": <true>|<false> (default: `true`),
        "execute-entity": <true>|<false> (default: `true`),
        "aggregate-records": <true>|<false> | {
          "enabled": <true>|<false> (default: `true`),
          "query-timeout": <integer> (default: `30`)
        }
      }
    }
  }
}

模式（主機執行時間）

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> | <false> (default)
        }
      }
    }
  }
}

範例：多個突變

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> | <false> (default),
        "origins": ["<array-of-strings>"]
      }
    }
  }
}

Note

通配符 * 作為的值 origins有效。

提供者（驗證主機執行時間）

Parent	Property	類型	Required	Default
`runtime.host.authentication`	`provider`	enum（`Unauthenticated` \| `StaticWebApps` \| `AppService` \| `EntraId` \| `Custom` \| `Simulator`）	❌ 否	`Unauthenticated`

選擇認證方式。每個提供者對身份的驗證方式都不同。關於逐步設定，請參考下表中的操作指南。

Note

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。欲了解更多資訊，請參閱 2.0 版本的新內容。

提供者摘要

Provider	用例	身份來源	操作指南
`Unauthenticated`	DAB 會設置在一個受信任的前端（預設）	無——所有請求都執行為 `anonymous`	設定未認證提供者
`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。舊名稱仍可相容。

未認證（預設）

當設定（或未指定供應商）時 Unauthenticated ，DAB 不會檢查或驗證任何 JWT。所有請求都以該 anonymous 角色執行。像 Azure API 管理或應用閘道這類前端服務，仍可在請求抵達 DAB 前處理認證或存取政策，但 DAB 仍 anonymous持續授權。

Important

當 Unauthenticated 是啟用時， authenticated 且實體權限中定義的自訂角色永遠不會被啟用。如果你的設定包含這些角色，DAB 在啟動時會發出警告。

{
  "host": {
    "authentication": {
      "provider": "Unauthenticated"
    }
  }
}

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）設定。

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

巢狀屬性

Parent	Property	類型	Required	Default
`runtime.host.authentication.jwt`	`audience`	字串	✔️ 是*	None
`runtime.host.authentication.jwt`	`issuer`	字串	✔️ 是*	None

* 當audience物件存在時，兩者皆issuerjwt為必要條件。 jwt當提供者為 EntraID、或 AzureADCustom時，物件本身是必需的。

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 {
      ...
    }
  }
}

壓縮（執行時）

Note

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。欲了解更多資訊，請參閱 2.0 版本的新內容。

Parent	Property	類型	Required	Default
`runtime`	`compression`	物件	❌ 否	-

HTTP 回應壓縮配置。啟用時，DAB 會壓縮響應體以縮小有效載荷大小並提升傳輸速度。

巢狀屬性

Parent	Property	類型	Required	Default
`runtime.compression`	`level`	字串	❌ 否	`"optimal"`

支援值為 `level`

Value	Description	壓縮節省	效能影響
`optimal`	平衡比率與速度（預設）	Gzip：90.5% / Brotli：92.2%	CPU 使用率適中，延遲略有增加
`fastest`	優先考量速度勝過傳動比	Gzip：89.8% / Brotli：91.1%	低 CPU 使用率，延遲極低
`none`	無壓縮	0%（基線：12,673 位元組）	None

用戶端 HTTP 標頭

壓縮是由用戶端 Accept-Encoding 標頭呼叫的。支援的演算法有 Gzip 和 Brotli。當客戶端與伺服器都支援多種演算法時，該 level 設定會配置壓縮策略。

支援標頭

HTTP 標頭	所用演算法
`Accept-Encoding: gzip`	Gzip
`Accept-Encoding: br`	布羅特利

Format

{
  "runtime": {
    "compression": {
      "level": <"optimal"> (default) | <"fastest"> | <"none">
    }
  }
}

Example

{
  "runtime": {
    "compression": {
      "level": "optimal"
    }
  }
}

快取（執行階段）

Parent	Property	類型	Required	Default
`runtime`	`cache`	物件	❌ 否	-

全域快取組態。

巢狀屬性

Parent	Property	類型	Required	Default
`runtime.cache`	`enabled`	boolean	❌ 否	False
`runtime.cache`	`ttl-seconds`	整數	❌ 否	5
`runtime.cache`	`level-2`	物件	❌ 否	-

Parent	Property	類型	Required	Default
`runtime.cache.level-2`	`enabled`	boolean	❌ 否	False
`runtime.cache.level-2`	`provider`	字串	❌ 否	`redis`
`runtime.cache.level-2`	`connection-string`	字串	❌ 否	None
`runtime.cache.level-2`	`partition`	字串	❌ 否	None

Tip

實體層級 cache.ttl-seconds 屬性預設為這個全域值。

Tip

關於端對端設定、快取層級行為及 Redis 範例，請參見「實作第二級快取」。

Format

{
  "runtime": {
    "cache":  {
      "enabled": <boolean>,
      "ttl-seconds": <integer>,
      "level-2": {
        "enabled": <boolean>,
        "provider": "redis",
        "connection-string": <string>,
        "partition": <string>
      }
    }
  }
}

Important

如果全域 enabled 為 false，則個別實體層級 enabled 並不重要。

當 level-2.enabled 時 true，DAB 除了本地記憶體快取外，還會使用已設定的分散式快取提供者。設定為快取層 L1L2 級的實體會先檢查本地快取，再檢查分散快取，最後才進入資料庫。

遙測（執行階段）

Parent	Property	類型	Required	Default
`runtime`	`telemetry`	物件	❌ 否	-

全域遙測設定。

巢狀屬性

Parent	Property	類型	Required	Default
`runtime.telemetry`	`log-level`	字典	❌ 否	None
`runtime.telemetry`	`application-insights`	物件	❌ 否	-
`runtime.telemetry`	`open-telemetry`	物件	❌ 否	-
`runtime.telemetry`	`azure-log-analytics`	物件	❌ 否	-
`runtime.telemetry`	`file`	物件	❌ 否	-

設定每個命名空間的記錄詳細資訊。此配置遵循標準 .NET 日誌慣例，允許細緻控制，但假設對 Data 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	❌ 否	`true`
`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）較簡單且更容易偵錯，但效率較低。

Azure Log Analytics （telemetry）

Parent	Property	類型	Required	Default
`runtime.telemetry`	`azure-log-analytics`	物件	❌ 否	-

透過資料收集端點配置 Azure Log Analytics 的日誌。啟用後，DAB 會以可設定的間隔批次傳送遙測資料。

Note

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。欲了解更多資訊，請參閱 2.0 版本的新內容。

巢狀屬性

Parent	Property	類型	Required	Default
`runtime.telemetry.azure-log-analytics`	`enabled`	boolean	❌ 否	`false`
`runtime.telemetry.azure-log-analytics`	`dab-identifier`	字串	❌ 否	`"DabLogs"`
`runtime.telemetry.azure-log-analytics`	`flush-interval-seconds`	整數	❌ 否	`5`
`runtime.telemetry.azure-log-analytics`	`auth`	物件	✔️ 是*	-

* auth 當 enabled 是 true時是必要的。

Parent	Property	類型	Required	Default
`runtime.telemetry.azure-log-analytics.auth`	`custom-table-name`	字串	✔️ 是*	`null`
`runtime.telemetry.azure-log-analytics.auth`	`dcr-immutable-id`	字串	✔️ 是*	`null`
`runtime.telemetry.azure-log-analytics.auth`	`dce-endpoint`	字串	✔️ 是*	`null`

* 當是 enabled時，必須 true 。

dab-identifier——這個標籤會傳給Log Analytics，以幫助區分哪些日誌來自Data API Builder。
flush-interval-seconds——傳送遙測資料批次之間的時間間隔（秒數）。
custom-table-name——Azure Log Analytics 中儲存資料的自訂資料表名稱。
dcr-immutable-id—— 是定義資料收集方式的不可變 ID。
dce-endpoint——用於傳送遙測資料的資料收集端點網址。

Format

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": <true> | <false> (default),
        "dab-identifier": <string> (default: "DabLogs"),
        "flush-interval-seconds": <integer> (default: 5),
        "auth": {
          "custom-table-name": "<string>",
          "dcr-immutable-id": "<string>",
          "dce-endpoint": "<string>"
        }
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": true,
        "dab-identifier": "MyDabInstance",
        "flush-interval-seconds": 10,
        "auth": {
          "custom-table-name": "DabTelemetry_CL",
          "dcr-immutable-id": "dcr-abc123def456",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

檔案（遙測）

Parent	Property	類型	Required	Default
`runtime.telemetry`	`file`	物件	❌ 否	-

設定將遙測日誌寫入本地檔案。啟用時，DAB 會將結構化日誌輸出寫入指定的檔案路徑，並可設定滾動間隔與大小限制。

Note

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。欲了解更多資訊，請參閱 2.0 版本的新內容。

巢狀屬性

Parent	Property	類型	Required	Default
`runtime.telemetry.file`	`enabled`	boolean	❌ 否	`false`
`runtime.telemetry.file`	`path`	字串	✔️ 是*	`"/logs/dab-log.txt"`
`runtime.telemetry.file`	`rolling-interval`	列舉	❌ 否	`"Day"`
`runtime.telemetry.file`	`retained-file-count-limit`	整數	❌ 否	`1`
`runtime.telemetry.file`	`file-size-limit-bytes`	整數	❌ 否	`1048576`

* path 當 enabled 是 true時是必要的。

滾動區間值

Value	Description
`Minute`	每分鐘新增日誌檔
`Hour`	每小時新增一個日誌檔
`Day`	每天新增日誌檔（預設值）
`Month`	每個月新增日誌檔
`Year`	每年更新日誌檔
`Infinite`	千萬不要擲骰到新檔案

Format

{
  "runtime": {
    "telemetry": {
      "file": {
        "enabled": <true> | <false> (default),
        "path": <string> (default: "/logs/dab-log.txt"),
        "rolling-interval": <"Day"> (default) | <"Minute"> | <"Hour"> | <"Month"> | <"Year"> | <"Infinite">,
        "retained-file-count-limit": <integer> (default: 1),
        "file-size-limit-bytes": <integer> (default: 1048576)
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "file": {
        "enabled": true,
        "path": "/var/log/dab/dab-telemetry.txt",
        "rolling-interval": "Hour",
        "retained-file-count-limit": 24,
        "file-size-limit-bytes": 5242880
      }
    }
  }
}

MCP（執行時）

Parent	Property	類型	Required	Default
`runtime`	`mcp`	物件	❌ 否	-

配置 SQL 模型情境協定（MCP）伺服器，將資料庫實體暴露為 AI 代理的 MCP 工具。

Note

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。欲了解更多資訊，請參閱 2.0 版本的新內容。

巢狀屬性

Parent	Property	類型	Required	Default
`runtime.mcp`	`enabled`	boolean	❌ 否	`true`
`runtime.mcp`	`path`	字串	❌ 否	`"/mcp"`
`runtime.mcp`	`description`	字串	❌ 否	`null`
`runtime.mcp`	`dml-tools`	布林值或物件	❌ 否	`true`

此 dml-tools 屬性接受布林值來啟用或停用所有工具，或使用物件來控制個別工具：

Parent	Property	類型	Required	Default
`runtime.mcp.dml-tools`	`describe-entities`	boolean	❌ 否	`true`
`runtime.mcp.dml-tools`	`create-record`	boolean	❌ 否	`true`
`runtime.mcp.dml-tools`	`read-records`	boolean	❌ 否	`true`
`runtime.mcp.dml-tools`	`update-record`	boolean	❌ 否	`true`
`runtime.mcp.dml-tools`	`delete-record`	boolean	❌ 否	`true`
`runtime.mcp.dml-tools`	`execute-entity`	boolean	❌ 否	`true`
`runtime.mcp.dml-tools`	`aggregate-records`	布林值或物件	❌ 否	`true`

此 aggregate-records 工具接受布林值或具有更多設定的物件：

Parent	Property	類型	Required	Default	範圍
`runtime.mcp.dml-tools.aggregate-records`	`enabled`	boolean	❌ 否	`true`
`runtime.mcp.dml-tools.aggregate-records`	`query-timeout`	整數	❌ 否	`30`	1–600秒

Format

{
  "runtime": {
    "mcp": {
      "enabled": <true> (default) | <false>,
      "path": <string> (default: "/mcp"),
      "description": <string>,
      "dml-tools": {
        "describe-entities": <true> | <false>,
        "create-record": <true> | <false>,
        "read-records": <true> | <false>,
        "update-record": <true> | <false>,
        "delete-record": <true> | <false>,
        "execute-entity": <true> | <false>,
        "aggregate-records": {
          "enabled": <true> | <false>,
          "query-timeout": <integer; default: 30>
        }
      }
    }
  }
}

Example

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

要一次啟用或停用所有 DML 工具，請設定 "dml-tools" 為 true 或 false。

當你在執行時層級停用工具時，該工具永遠不會出現在 MCP tools/list 回應中，且無法被調用，無論實體層級的權限如何。欲了解更多個別 DML 工具的資訊，請參閱資料操作語言（DML）工具。

使用 CLI

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true

健康情況（執行階段）

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`	最小：一，最大：八（夾緊）

開發與生產環境的行為

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
  }
}

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-01

Runtime

分頁設定

REST 設定

GraphQL 設定

主機設定

CORS 設定

驗證設定

快取設定

壓縮設定

遙測設置

MCP 設定

格式概觀

模式 （主機執行時間）

開發行為

Format

回應大小上限 （主機執行時間）

Format

GraphQL （執行時間）

巢狀屬性

屬性附註

Format

範例：多個突變

REST （執行階段）

巢狀屬性

屬性附註

Format

範例：request-body-strict

插入行為時機 request-body-strict = false

更新行為時機 request-body-strict = false

CORS （主機執行時間）

巢狀屬性

Format

提供者（驗證主機執行時間）

提供者摘要

未認證（預設）

AppService

EntraID

Custom

模擬器

角色選擇

JWT （驗證主機執行時間）

巢狀屬性

Format

分頁 （執行階段）

巢狀屬性

支援的最大頁面大小值

默認頁面大小支援的值

下一連結相對行為

Format

範例：REST 中的分頁

範例：GraphQL 中的分頁

範例：在 max-page-size 要求中存取

壓縮（執行時）

巢狀屬性

支援值為 level

用戶端 HTTP 標頭

支援標頭

Format

Example

快取 （執行階段）

巢狀屬性

Format

遙測 （執行階段）

巢狀屬性

Format

Example

Application Insights （遙測）

巢狀屬性

Format

OpenTelemetry （遙測）

巢狀屬性

Format

Example

Azure Log Analytics （telemetry）

巢狀屬性

Format

Example

檔案（遙測）

巢狀屬性

滾動區間值

模式（主機執行時間）

回應大小上限（主機執行時間）

插入行為時機 `request-body-strict = false`

更新行為時機 `request-body-strict = false`

分頁（執行階段）

範例：在 `max-page-size` 要求中存取

支援值為 `level`

快取（執行階段）

遙測（執行階段）

健康情況（執行階段）