用于确定运行时行为的配置设置。
分页设置
| Property | Default | Description |
|---|---|---|
| runtime.pagination.max页大小 | 定义每页的最大记录数 | |
| runtime.pagination.default-page-size | 为每个响应设置默认记录 |
REST 设置
| Property | Default | Description |
|---|---|---|
| runtime.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.depth-limit | null |
GraphQL 查询允许的最大深度 |
| runtime.graphql.multiple-mutations.create.enabled | false |
允许对所有实体进行多创建突变 |
主机设置
| Property | Default | Description |
|---|---|---|
| runtime.host.max-response-size-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-seconds | 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-seconds | 5 |
运行状况检查报告缓存条目的生存时间(秒) |
| runtime.health.max-query-parallelism | 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 |
枚举 (production | development) |
❌ 否 | production |
开发行为
- 为 GraphQL 测试启用了 Nitro (前香蕉蛋糕流行)
- 为 REST 测试启用了 Swagger UI
- 已启用匿名运行状况检查
- 日志记录详细程度增加 (调试)
Format
{
"runtime": {
"host": {
"mode": "production" (default) | "development"
}
}
}
最大响应大小(主机运行时)
| Parent | Property | 类型 | Required | Default |
|---|---|---|---|---|
runtime.host |
max-response-size-mb |
整数 | ❌ 否 | 158 |
设置任何给定结果的最大大小(以兆字节为单位)。 由于大型响应可能会给系统造成压力, 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 |
对象 | ❌ 否 | - |
Global 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
- 仅当有效负载中的列的值为
/> 时 ,才会忽略具有值的列。 因此, INSERT对default()列的作(如果为request-body-strict)true不能导致显式null值。 若要完成此行为,需要一个UPDATE作。 - 无论有效负载值如何,都不忽略
default()具有 aUPDATE的列。 - 始终忽略计算列。
- 自动生成的列始终被忽略。
示例表
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 代表“跨域资源共享”。它是一项浏览器安全功能,用于控制网页是否可以向服务域以外的域发出请求。
嵌套属性
| Parent | Property | 类型 | Required | Default |
|---|---|---|---|---|
runtime.host.cors |
allow-credentials |
boolean | ❌ 否 | False |
runtime.host.cors |
origins |
字符串数组 | ❌ 否 | None |
Note
该 allow-credentials 属性设置 Access-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 托管的应用 (EasyAuth) |
X-MS-CLIENT-PRINCIPAL 标头 |
配置应用服务身份验证 |
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
}
}
应用服务
信任 Azure 应用服务 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仅在是development时runtime.host.mode有效。 如果在生产模式下配置了模拟器,DAB 将无法启动。
角色选择
对于除模拟器之外的所有提供程序, 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 行为
如果为next-link-relative,true分页nextLink值使用相对 URL 而不是绝对 URL。
| 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 请求中访问
通过将max-page-size值(REST)或 $limit (GraphQL) 设置为 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 |
枚举 (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
}
}