Runtime

用于确定运行时行为的配置设置。

分页设置

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

属性说明

  • 如果全局 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

  • 仅当有效负载中的列的值为 /> 时,才会忽略具有值的列。 因此,INSERTdefault()列的作(如果为request-body-stricttrue不能导致显式null值。 若要完成此行为,需要一个 UPDATE 作。
  • 无论有效负载值如何,都不忽略default()具有 a 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 代表“跨域资源共享”。它是一项浏览器安全功能,用于控制网页是否可以向服务域以外的域发出请求。

嵌套属性

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仅在是developmentruntime.host.mode有效。 如果在生产模式下配置了模拟器,DAB 将无法启动。

角色选择

对于除模拟器之外的所有提供程序, 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值使用相对 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

如果全局 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 枚举 (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
  }
}