Runtime

决定运行时行为的配置设置。

分页设置

属性	默认值	描述
runtime.pagination.max-page-size	定义每页最大记录数
runtime.pagination.default-page-size	设置每次响应的默认记录数

REST 设置

属性	默认值	描述
runtime.rest.path	`"/api"`	REST 端点的基础路径
runtime.rest.enabled	`true`	允许为所有实体启用或禁用 REST 请求
runtime.rest.request-body-strict	`true`	为 true 时不允许请求体中出现多余字段

GraphQL 设置

属性	默认值	描述
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`	为所有实体允许多创建变更

主机设置

属性	默认值	描述
runtime.host.max-response-size-mb	`158`	单个结果中允许的数据库响应最大大小 (MB)
runtime.host.mode	`"production"`	运行模式；`"production"` 或 `"development"`

CORS 设置

属性	默认值	描述
runtime.host.cors.origins	`[]`	允许的 CORS 来源
runtime.host.cors.allow-credentials	`false`	设置 Access-Control-Allow-Credentials 头的值

认证设置

属性	默认值	描述
runtime.host.authentication.provider	`Unauthenticated`	认证提供程序
runtime.host.authentication.jwt.audience	`null`	JWT 受众
runtime.host.authentication.jwt.issuer	`null`	JWT 颁发者

缓存设置

属性	默认值	描述
runtime.cache.enabled	`false`	全局启用响应缓存
runtime.cache.ttl-seconds	`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`	用于隔离分布式缓存空间的可选分区名称

压缩设置

属性	默认值	描述
runtime.compression.level	`optimal`	HTTP 响应压缩级别（`optimal`、`fastest` 或 `none`）

遥测设置

属性	默认值	描述
runtime.telemetry.open-telemetry.endpoint	`null`	OpenTelemetry 收集器 URL
runtime.telemetry.open-telemetry.headers	`{}`	OpenTelemetry 导出头
runtime.telemetry.open-telemetry.service-name	`"数据墙DBW"`	OpenTelemetry 服务名称
runtime.telemetry.open-telemetry.exporter-protocol	`"grpc"`	OpenTelemetry 协议（"grpc" 或 "httpprotobuf"）
runtime.telemetry.open-telemetry.enabled	`true`	启用或禁用 OpenTelemetry
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-seconds	`5`	健康检查报告缓存条目的生存时间（秒）
runtime.health.max-query-parallelism	`4`	最大并发健康检查查询数（范围：1-8）

MCP 设置

属性	默认值	描述
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 工具（布尔值或带 query-timeout 的对象）

格式概览

json

{
  "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: "数据墙DBW"),
        "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`)
        }
      }
    }
  }
}

Mode（主机运行时）

父级	属性	类型	必需	默认值
`runtime`	`host`	枚举（`production` \| `development`）	❌ 否	`production`

Development 行为

启用 Nitro（原 Banana Cake Pop）用于 GraphQL 测试
启用 Swagger UI 用于 REST 测试
启用匿名健康检查
增加日志详细程度（Debug）

格式

json

{
  "runtime": {
    "host": {
      "mode": "production" (default) | "development"
    }
  }
}

最大响应大小（主机运行时）

父级	属性	类型	必需	默认值
`runtime.host`	`max-response-size-mb`	整数	❌ 否	158

设置任何给定结果的最大大小（兆字节）。由于大型响应可能给系统带来压力，max-response-size-mb 限制总大小（与行数不同）以防止过载，这对于大型列（如文本或 JSON）尤其重要。

值	结果
未设置	使用默认值
`null`	使用默认值
`integer`	任何正 32 位整数
`<= 0`	不支持

格式

json

{
  "runtime": {
    "host": {
      "max-response-size-mb": <integer; default: 158>
    }
  }
}

GraphQL（运行时）

父级	属性	类型	必需	默认值
`runtime`	`graphql`	对象	❌ 否	-

全局 GraphQL 配置。

嵌套属性

父级	属性	类型	必需	默认值
`runtime.graphql`	`enabled`	布尔值	❌ 否	无
`runtime.graphql`	`path`	字符串	❌ 否	"/graphql"
`runtime.graphql`	`depth-limit`	整数	❌ 否	无（无限制）
`runtime.graphql`	`allow-introspection`	布尔值	❌ 否	True
`runtime.graphql`	`multiple-mutations.create.enabled`	布尔值	❌ 否	False

属性说明

path 属性不支持子路径。
使用 depth-limit 限制嵌套查询。
将 allow-introspection 设置为 false 可隐藏 GraphQL 架构。
使用 multiple-mutations 可在单个变更中插入多个实体。

格式

json

{
  "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)
        }
      }
    }
  }
}

示例：多变更

配置

json

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": true
        }
      }
    }
  },
  "entities": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["create"] // entity permissions are required
        }
      ]
    }
  }
}

GraphQL 变更

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（运行时）

父级	属性	类型	必需	默认值
`runtime`	`rest`	对象	❌ 否	-

全局 REST 配置。

嵌套属性

父级	属性	类型	必需	默认值
`runtime.rest`	`enabled`	布尔值	❌ 否	无
`runtime.rest`	`path`	字符串	❌ 否	"/api"
`runtime.rest`	`request-body-strict`	布尔值	❌ 否	True

属性说明

如果全局 enabled 为 false，则单个实体级别的 enabled 不起作用。
path 属性不支持 /api/data 等子路径值。
引入 request-body-strict 是为了简化 .NET POCO 对象。

`request-body-strict`	行为
`true`	请求体中的额外字段会导致 `BadRequest` 异常。
`false`	请求体中的额外字段将被忽略。

格式

json

{
  "runtime": {
    "rest": {
      "enabled": <true> (default) | <false>,
      "path": <string> (default: /api),
      "request-body-strict": <true> (default) | <false>
    }
  }
}

示例：request-body-strict

具有 default() 值的列仅在负载中的值为 null 时才会在 INSERT 期间被忽略。因此，当 request-body-strict 为 true 时，对 default() 列的 INSERT 操作不能产生显式 null 值。要实现此行为，需要 UPDATE 操作。
具有 default() 的列在 UPDATE 期间不会被忽略，无论负载值如何。
计算列始终被忽略。
自动生成的列始终被忽略。

示例表

sql

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
);

请求负载

json

{
  "Id": 999,
  "Name": "Alice",
  "Age": null,
  "IsAdmin": null,
  "IsMinor": false,
  "ExtraField": "ignored"
}

`request-body-strict = false` 时的插入行为

sql

INSERT INTO Users (Name) VALUES ('Alice');
-- Age (18) 和 IsAdmin (0) 的默认值由数据库应用。
-- IsMinor 被忽略，因为它是计算列。
-- ExtraField 被忽略。
-- 数据库生成 Id 值。

响应负载

json

{
  "Id": 1,          // Auto-generated by the database
  "Name": "Alice",
  "Age": 18,        // Default applied
  "IsAdmin": false, // Default applied
  "IsMinor": true   // Computed
}

`request-body-strict = false` 时的更新行为

sql

UPDATE Users
SET Name = 'Alice Updated', Age = NULL
WHERE Id = 1;
-- IsMinor 和 ExtraField 被忽略。

响应负载

json

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,
  "IsAdmin": false,
  "IsMinor": false // 由数据库重新计算（当 age 为 `null` 时为 false）
}

CORS（主机运行时）

父级	属性	类型	必需	默认值
`runtime.host`	`cors`	对象	❌ 否	-

全局 CORS 配置。

提示： CORS 代表"跨源资源共享"。它是一种浏览器安全功能，控制网页是否可以向不同于提供它们的域发出请求。

嵌套属性

父级	属性	类型	必需	默认值
`runtime.host.cors`	`allow-credentials`	布尔值	❌ 否	False
`runtime.host.cors`	`origins`	字符串数组	❌ 否	无

注意：allow-credentials 属性设置 Access-Control-Allow-Credentials CORS 头。

格式

json

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": <true> | <false> (default),
        "origins": ["<array-of-strings>"]
      }
    }
  }
}

注意： 通配符 * 可作为 origins 的有效值。

Provider（认证主机运行时）

父级	属性	类型	必需	默认值
`runtime.host.authentication`	`provider`	枚举（`Unauthenticated` \| `Custom` \| `Simulator`）	❌ 否	`Unauthenticated`

选择认证方法。每个提供程序以不同方式验证身份。有关分步设置，请参阅下表中的操作指南。

提供程序摘要

提供程序	用例	身份来源	操作指南
`Unauthenticated`	数据墙DBW 位于受信任的前端之后（默认）	无 - 所有请求以 `anonymous` 身份运行	配置 Unauthenticated 提供程序
`Custom`	第三方 IdP（Okta、Auth0）	JWT 承载令牌	配置自定义 JWT 认证
`Simulator`	仅本地测试	模拟	配置 Simulator 认证

Unauthenticated（默认）

设置为 Unauthenticated（或未指定提供程序）时，数据墙DBW 不检查或验证任何 JWT。所有请求以 anonymous 角色运行。前端服务或应用程序网关仍然可以在请求到达数据墙DBW 之前处理认证或访问策略，但数据墙DBW 继续仅以 anonymous 身份授权。

重要： 当 Unauthenticated 处于活动状态时，实体权限中定义的 authenticated 和自定义角色永远不会被激活。如果您的配置包含这些角色，数据墙DBW 在启动时会发出警告。

json

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

Custom

验证来自第三方身份提供程序的 JWT 令牌。

json

{
  "host": {
    "authentication": {
      "provider": "Custom",
      "jwt": {
        "audience": "<api-audience>",
        "issuer": "https://<your-idp-domain>/"
      }
    }
  }
}

Simulator

模拟本地开发和测试的认证。

json

{
  "host": {
    "authentication": {
      "provider": "Simulator"
    }
  }
}

重要：Simulator 提供程序仅在 runtime.host.mode 为 development 时有效。如果在生产模式下配置 Simulator，数据墙DBW 将无法启动。

角色选择

对于除 Simulator 之外的所有提供程序，X-MS-API-ROLE 头选择要从已认证用户的声明中使用的角色。如果省略，请求使用 Authenticated 系统角色。有关角色评估的详细信息，请参阅授权概述。

JWT（认证主机运行时）

父级	属性	类型	必需	默认值
`runtime.host.authentication`	`jwt`	对象	❌ 否	-

全局 JSON Web Token (JWT) 配置。

数据墙DBW 中 JSON web tokens 支持的图表。

嵌套属性

父级	属性	类型	必需	默认值
`runtime.host.authentication.jwt`	`audience`	字符串	✔️ 是*	无
`runtime.host.authentication.jwt`	`issuer`	字符串	✔️ 是*	无

* 当 jwt 对象存在时，audience 和 issuer 都是必需的。当提供程序为 EntraID、AzureAD 或 Custom 时，jwt 对象本身是必需的。

格式

json

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Pagination（运行时）

父级	属性	类型	必需	默认值
`runtime`	`pagination`	对象	❌ 否	-

REST 和 GraphQL 端点的全局分页限制。

嵌套属性

父级	属性	类型	必需	默认值
`runtime.pagination`	`max-page-size`	整数	❌ 否	100,000
`runtime.pagination`	`default-page-size`	整数	❌ 否	100
`runtime.pagination`	`next-link-relative`	布尔值	❌ 否	`false`

Max-page-size 支持的值

值	结果
`integer`	支持任何正 32 位整数。
`0`	不支持。
`-1`	默认为最大支持值。
`< -1`	不支持。

Default-page-size 支持的值

值	结果
`integer`	小于当前 `max-page-size` 的任何正整数。
`0`	不支持。
`-1`	默认为当前 `max-page-size` 设置。
`< -1`	不支持。

Next-link-relative 行为

当 next-link-relative 为 true 时，分页 nextLink 值使用相对 URL 而不是绝对 URL。

值	示例
`false`（默认）	`"nextLink": "https://localhost:5001/api/users?$after=..."`
`true`	`"nextLink": "/api/users?$after=..."`

格式

json

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>,
      "default-page-size": <integer; default: 100>,
      "next-link-relative": <boolean; default: false>
    }
  }
}

注意： 当值大于 max-page-size 时，结果将被限制为 max-page-size。

示例：REST 中的分页

请求

http

GET https://localhost:5001/api/users

响应负载

json

{
  "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=="
}

请求下一页

http

GET https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==

示例：GraphQL 中的分页

请求负载（Query）

graphql

query {
  users {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

响应负载

json

{
  "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=="
    }
  }
}

请求下一页

graphql

query {
  users(after: "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==") {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

示例：在请求中访问 `max-page-size`

通过将 $limit（REST）或 first（GraphQL）设置为 -1 来使用 max-page-size 值。

REST

http

GET https://localhost:5001/api/users?$limit=-1

GraphQL

graphql

query {
  users(first: -1) {
    items {
      ...
    }
  }
}

Compression（运行时）

注意： 此功能为数据墙DBW 2.0 预览版。

父级	属性	类型	必需	默认值
`runtime`	`compression`	对象	❌ 否	-

HTTP 响应压缩配置。启用后，数据墙DBW 会压缩响应体以减少负载大小并提高传输速度。

嵌套属性

父级	属性	类型	必需	默认值
`runtime.compression`	`level`	字符串	❌ 否	`"optimal"`

`level` 支持的值

值	描述	压缩节省	性能影响
`optimal`	平衡比率和速度（默认）	Gzip: 90.5% / Brotli: 92.2%	中等 CPU 使用，轻微延迟增加
`fastest`	优先速度而非比率	Gzip: 89.8% / Brotli: 91.1%	低 CPU 使用，最小延迟
`none`	无压缩	0%（基准：12,673 字节）	无

客户端 HTTP 头

压缩由客户端的 Accept-Encoding 头触发。支持的算法是 Gzip 和 Brotli。当客户端和服务器都支持多种算法时，level 设置配置压缩策略。

支持的头

HTTP 头	使用的算法
`Accept-Encoding: gzip`	Gzip
`Accept-Encoding: br`	Brotli

格式

json

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

示例

json

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

Cache（运行时）

父级	属性	类型	必需	默认值
`runtime`	`cache`	对象	❌ 否	-

全局缓存配置。

嵌套属性

父级	属性	类型	必需	默认值
`runtime.cache`	`enabled`	布尔值	❌ 否	False
`runtime.cache`	`ttl-seconds`	整数	❌ 否	5
`runtime.cache`	`level-2`	对象	❌ 否	-

父级	属性	类型	必需	默认值
`runtime.cache.level-2`	`enabled`	布尔值	❌ 否	False
`runtime.cache.level-2`	`provider`	字符串	❌ 否	`redis`
`runtime.cache.level-2`	`connection-string`	字符串	❌ 否	无
`runtime.cache.level-2`	`partition`	字符串	❌ 否	无

提示： 实体级别的 cache.ttl-seconds 属性默认为此全局值。

提示： 有关端到端设置、缓存级别行为和 Redis 示例，请参阅实现二级缓存。

格式

json

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

重要： 如果全局 enabled 为 false，则单个实体级别的 enabled 不起作用。

当 level-2.enabled 为 true 时，数据墙DBW 除了使用本地内存缓存外，还使用配置的分布式缓存提供程序。配置了缓存级别 L1L2 的实体会先检查本地缓存，然后检查分布式缓存，最后才访问数据库。

Telemetry（运行时）

父级	属性	类型	必需	默认值
`runtime`	`telemetry`	对象	❌ 否	-

全局遥测配置。

嵌套属性

父级	属性	类型	必需	默认值
`runtime.telemetry`	`log-level`	字典	❌ 否	无
`runtime.telemetry`	`open-telemetry`	对象	❌ 否	-
`runtime.telemetry`	`file`	对象	❌ 否	-

按命名空间配置日志详细程度。此配置遵循标准 .NET 日志约定并允许细粒度控制，但需要对数据墙DBW 内部结构有一定了解。数据墙DBW 是开源的：https://aka.ms/数据墙DBW

格式

json

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "namespace": "log-level",
        "namespace": "log-level"
      }
    }
  }
}

提示：log-level 可以在开发和生产环境中热重载。它目前是唯一支持在生产环境中热重载的属性。

示例

json

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "Azure.DataApiBuilder.Core.Configurations.RuntimeConfigValidator": "debug",
        "Azure.DataApiBuilder.Core": "information",
        "default": "warning"
      }
    }
  }
}

OpenTelemetry（遥测）

父级	属性	类型	必需	默认值
`runtime.telemetry`	`open-telemetry`	对象	❌ 否	-

配置到 Open Telemetry 的日志记录。

嵌套属性

父级	属性	类型	必需	默认值
`runtime.telemetry.open-telemetry`	`enabled`	布尔值	❌ 否	true
`runtime.telemetry.open-telemetry`	`endpoint`	字符串	✔️ 是	无
`runtime.telemetry.open-telemetry`	`headers`	字符串	❌ 否	无
`runtime.telemetry.open-telemetry`	`service-name`	字符串	❌ 否	"数据墙DBW"
`runtime.telemetry.open-telemetry`	`exporter-protocol`	枚举（`grpc` \| `httpprotobuf`）	❌ 否	`grpc`

多个头用 ,（逗号）分隔。

格式

json

{
  "runtime": {
    "telemetry": {
      "open-telemetry": {
        "enabled": <true> (default) | <false>,
        "endpoint": <string>,
        "headers": <string>,
        "service-name": <string> (default: "数据墙DBW"),
        "exporter-protocol": <"grpc" (default) | "httpprotobuf">
      }
    }
  }
}

示例

json

{
  "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": "数据墙DBW",
      }
    }
  }
}

了解更多关于 OTEL_EXPORTER_OTLP_HEADERS。

注意： gRPC（4317）更快并支持流式传输，但需要更多设置步骤。HTTP/protobuf（4318）更简单且更容易调试，但效率较低。

File（遥测）

父级	属性	类型	必需	默认值
`runtime.telemetry`	`file`	对象	❌ 否	-

配置将遥测日志写入本地文件。启用后，数据墙DBW 将结构化日志输出写入指定的文件路径，具有可配置的滚动间隔和大小限制。

注意： 此功能为数据墙DBW 2.0 预览版。

嵌套属性

父级	属性	类型	必需	默认值
`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`

* 当 enabled 为 true 时，path 是必需的。

滚动间隔值

值	描述
`Minute`	每分钟一个新日志文件
`Hour`	每小时一个新日志文件
`Day`	每天一个新日志文件（默认）
`Month`	每月一个新日志文件
`Year`	每年一个新日志文件
`Infinite`	永不滚动到新文件

格式

json

{
  "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)
      }
    }
  }
}

示例

json

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

MCP（运行时）

父级	属性	类型	必需	默认值
`runtime`	`mcp`	对象	❌ 否	-

配置 SQL Model Context Protocol (MCP) 服务器，它将数据库实体公开为 AI 代理的 MCP 工具。

注意： 此功能为数据墙DBW 2.0 预览版。

嵌套属性

父级	属性	类型	必需	默认值
`runtime.mcp`	`enabled`	布尔值	❌ 否	`true`
`runtime.mcp`	`path`	字符串	❌ 否	`"/mcp"`
`runtime.mcp`	`description`	字符串	❌ 否	`null`
`runtime.mcp`	`dml-tools`	布尔值或对象	❌ 否	`true`

dml-tools 属性接受布尔值来启用或禁用所有工具，或接受对象来控制单个工具：

父级	属性	类型	必需	默认值
`runtime.mcp.dml-tools`	`describe-entities`	布尔值	❌ 否	`true`
`runtime.mcp.dml-tools`	`create-record`	布尔值	❌ 否	`true`
`runtime.mcp.dml-tools`	`read-records`	布尔值	❌ 否	`true`
`runtime.mcp.dml-tools`	`update-record`	布尔值	❌ 否	`true`
`runtime.mcp.dml-tools`	`delete-record`	布尔值	❌ 否	`true`
`runtime.mcp.dml-tools`	`execute-entity`	布尔值	❌ 否	`true`
`runtime.mcp.dml-tools`	`aggregate-records`	布尔值或对象	❌ 否	`true`

aggregate-records 工具接受布尔值或包含更多设置的对象：

父级	属性	类型	必需	默认值	范围
`runtime.mcp.dml-tools.aggregate-records`	`enabled`	布尔值	❌ 否	`true`
`runtime.mcp.dml-tools.aggregate-records`	`query-timeout`	整数	❌ 否	`30`	1–600 秒

格式

json

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

示例

json

{
  "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

bash

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

Health（运行时）

父级	属性	类型	必需	默认值
`runtime`	`health`	对象	❌ 否	-

全局健康检查端点（/health）配置。

嵌套属性

父级	属性	类型	必需	默认值	范围/说明
`runtime.health`	`enabled`	布尔值	❌ 否	`true`
`runtime.health`	`roles`	字符串数组	✔️ 是*	`null`	*生产模式下必需
`runtime.health`	`cache-ttl-seconds`	整数	❌ 否	`5`	最小值：0
`runtime.health`	`max-query-parallelism`	整数	❌ 否	`4`	最小值：1，最大值：8（已限制）

开发环境与生产环境的行为

条件	开发环境行为	生产环境行为
`health.enabled` = false	`403` 状态	`403` 状态
`health.enabled` = true	取决于角色	取决于角色
`roles` 省略或 `null`	显示健康状态	`403` 状态
当前角色不在 `roles` 中	`403` 状态	`403` 状态
当前角色在 `roles` 中	显示健康状态	显示健康状态
`roles` 包含 `anonymous`	显示健康状态	显示健康状态

格式

json

{
  "health": {
    "enabled": <true> (default) | <false>,
    "roles": [ <string> ], // required in production
    "cache-ttl-seconds": <integer; default: 5>,
    "max-query-parallelism": <integer; default: 4>
  }
}

注意： 如果全局 enabled 为 false，则单个实体级别的 enabled 不起作用。

示例

json

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

Runtime ​

分页设置 ​

REST 设置 ​

GraphQL 设置 ​

主机设置 ​

CORS 设置 ​

认证设置 ​

缓存设置 ​

压缩设置 ​

遥测设置 ​

MCP 设置 ​

格式概览 ​

Mode（主机运行时） ​

Development 行为 ​

格式 ​

最大响应大小（主机运行时） ​

格式 ​

GraphQL（运行时） ​

嵌套属性 ​

属性说明 ​

格式 ​

示例：多变更 ​

REST（运行时） ​

嵌套属性 ​

属性说明 ​

格式 ​

示例：request-body-strict ​

request-body-strict = false 时的插入行为 ​

request-body-strict = false 时的更新行为 ​

CORS（主机运行时） ​

嵌套属性 ​

格式 ​

Provider（认证主机运行时） ​

提供程序摘要 ​

Unauthenticated（默认） ​

Custom ​

Simulator ​

角色选择 ​

JWT（认证主机运行时） ​

嵌套属性 ​

格式 ​

Pagination（运行时） ​

嵌套属性 ​

Max-page-size 支持的值 ​

Default-page-size 支持的值 ​

Next-link-relative 行为 ​

格式 ​

示例：REST 中的分页 ​

示例：GraphQL 中的分页 ​

示例：在请求中访问 max-page-size ​

Compression（运行时） ​

嵌套属性 ​

level 支持的值 ​

客户端 HTTP 头 ​

支持的头 ​

格式 ​

示例 ​

Cache（运行时） ​

嵌套属性 ​

格式 ​

Telemetry（运行时） ​

嵌套属性 ​

格式 ​

示例 ​

OpenTelemetry（遥测） ​

嵌套属性 ​

格式 ​

示例 ​

File（遥测） ​

嵌套属性 ​

滚动间隔值 ​

格式 ​

示例 ​

MCP（运行时） ​

嵌套属性 ​

格式 ​

示例 ​

使用 CLI ​

Health（运行时） ​

嵌套属性 ​

Runtime

分页设置

REST 设置

GraphQL 设置

主机设置

CORS 设置

认证设置

缓存设置

压缩设置

遥测设置

MCP 设置

格式概览

Mode（主机运行时）

Development 行为

格式

最大响应大小（主机运行时）

格式

GraphQL（运行时）

嵌套属性

属性说明

格式

示例：多变更

REST（运行时）

嵌套属性

属性说明

格式

示例：request-body-strict

`request-body-strict = false` 时的插入行为

`request-body-strict = false` 时的更新行为

CORS（主机运行时）

嵌套属性

格式

Provider（认证主机运行时）

提供程序摘要

Unauthenticated（默认）

Custom

Simulator

角色选择

JWT（认证主机运行时）

嵌套属性

格式

Pagination（运行时）

嵌套属性

Max-page-size 支持的值

Default-page-size 支持的值

Next-link-relative 行为

格式

示例：REST 中的分页

示例：GraphQL 中的分页

示例：在请求中访问 `max-page-size`

Compression（运行时）

嵌套属性

`level` 支持的值

客户端 HTTP 头

支持的头

格式

示例

Cache（运行时）

嵌套属性

格式

Telemetry（运行时）

嵌套属性

格式

示例

OpenTelemetry（遥测）

嵌套属性

格式

示例

File（遥测）

嵌套属性

滚动间隔值

格式

示例

MCP（运行时）

嵌套属性

格式

示例

使用 CLI

Health（运行时）

嵌套属性