Runtime

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

分页设置

REST 设置

GraphQL 设置

主机设置

CORS 设置

身份验证设置

缓存设置

压缩设置

遥测设置

MCP 设置

格式概述

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

模式（主机运行时）

开发行为

• 为 GraphQL 测试启用了 Nitro （前香蕉蛋糕流行）
• 为 REST 测试启用了 Swagger UI
• 已启用匿名运行状况检查
• 日志记录详细程度增加 （调试）

Format

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

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

设置任何给定结果的最大大小（以兆字节为单位）。 由于大型响应可能会给系统造成压力， max-response-size-mb 因此会限制总大小（不同于行计数），以防止重载，这尤其适用于文本或 JSON 等大型列。

Format

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

GraphQL （运行时）

Global GraphQL 配置。

嵌套属性

属性说明

• 属性不允许 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 （运行时）

全局 REST 配置。

嵌套属性

属性说明

• 如果全局 enabled ， false则各个实体级别 enabled 无关紧要。
• 该 path 属性不支持子路径值，如 /api/data.
• request-body-strict 引入了帮助简化 .NET POCO 对象。

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()具有 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 （主机运行时）

全局 CORS 配置。

嵌套属性

Format

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

提供程序（身份验证主机运行时）

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

提供程序摘要

未经身份验证（默认值）

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

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

应用服务

信任 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"
    }
  }
}

角色选择

对于除模拟器之外的所有提供程序， X-MS-API-ROLE 标头将从经过身份验证的用户声明中选择要使用的角色。 如果省略，则请求使用 Authenticated 系统角色。 有关角色评估的详细信息，请参阅 授权概述。

JWT （身份验证主机运行时）

全局 JSON Web 令牌 （JWT） 配置。

嵌套属性

* 当对象存在时audience，这两者均issuerjwt是必需的。 提供程序 为 或 < / / gt; 时，需要对象本身。

Format

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

分页 （运行时）

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

嵌套属性

支持的最大页大小值

默认页面大小支持的值

next-link-relative 行为

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

Format

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

示例：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 {
      ...
    }
  }
}

压缩 （运行时）

HTTP 响应压缩配置。 启用后，DAB 会压缩响应正文以减少有效负载大小并提高传输速度。

嵌套属性

支持的 值 level

客户端 HTTP 标头

由客户端标头 Accept-Encoding 调用压缩。 支持的算法是 Gzip 和 Brotli。 当客户端和服务器都支持多个算法时，该 level 设置将配置压缩策略。

支持的标头

Format

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

Example

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

缓存（运行时）

全局缓存配置。

嵌套属性

Format

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

level-2.enabled届时true，DAB 除了本地内存中缓存之外，还使用配置的分布式缓存提供程序。 配置有缓存级别的 L1L2 实体先检查本地缓存，然后是分布式缓存，然后再转到数据库。

遥测（运行时）

全局遥测配置。

嵌套属性

为每个命名空间配置日志记录详细程度。 此配置遵循标准 .NET 日志记录约定并允许精细控制，尽管它假定对数据 API 生成器内部有一些熟悉。 数据 API 生成器是开源的： https://aka.ms/dab

Format

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

Example

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

Application Insights （遥测）

配置 Application Insights 的日志记录。

嵌套属性

Format

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": <true; default: true> | <false>
        "connection-string": <string>
      }
    }
  }
}

OpenTelemetry （遥测）

配置日志记录以打开遥测。

嵌套属性

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

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。

Azure Log Analytics （遥测）

通过数据收集终结点配置到 Azure Log Analytics 的日志记录。 启用后，DAB 以可配置的间隔批量发送遥测数据。

嵌套属性

* auth 是当 enabled 为 true.

* 当 enabled 为 true.

• dab-identifier- 传递给 Log Analytics 的标签有助于区分来自数据 API 生成器的日志。
• flush-interval-seconds- 发送批遥测数据之间的时间间隔（以秒为单位）。
• custom-table-name- 存储数据的 Azure Log Analytics 中的自定义表的名称。
• dcr-immutable-id- 定义数据收集方式的数据收集规则的不可变 ID。
• dce-endpoint- 用于发送遥测数据的数据收集终结点 URL。

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

文件（遥测）

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

嵌套属性

* path 是当 enabled 为 true.

滚动间隔值

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

配置 SQL 模型上下文协议 （MCP） 服务器，该服务器将数据库实体公开为 AI 代理的 MCP 工具。

嵌套属性

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

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

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

运行状况（运行时）

全局 运行状况检查终结点 （/health） 配置。

嵌套属性

开发中的行为与生产行为

Format

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

Example

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