Runtime

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

分页设置

REST 设置

GraphQL 设置

主机设置

CORS 设置

身份验证设置

缓存设置

遥测设置

格式概述

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

模式（主机运行时）

开发行为

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

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

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

定义数据 API 生成器使用的身份验证方法。

仅匿名（身份验证提供程序）

{
 "host": {
    // omit the authentication section
 }
}

当从 dab-config.json 文件中省略整个 authentication 部分时，不使用身份验证提供程序。 在这种情况下，数据 API 生成器以“无身份验证”模式运行。 在此模式下，DAB 不会查找任何令牌或 Authorization 标头。 此 X-MS-API-ROLE 配置中也会忽略标头。

[!注意] 进入引擎的每个请求都会自动并立即分配系统角色 anonymous。 然后，访问控制由对每个实体定义的权限进行独占处理。

实体权限的示例。

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        {
          "role": "anonymous",
          "actions": [ "read" ]
        }
      ]
    }
  }
}

在此示例中，由于未 authentication 配置任何提供程序，因此所有传入请求都将自动被视为来自 anonymous 用户。 实体 permissions 的 Book 数组显式授予 anonymous 角色执行 read 作的能力。 拒绝执行其他作（例如 create， update） delete或访问未配置为 anonymous 访问的其他实体的任何尝试。

StaticWebApps （身份验证提供程序） [已弃用]

{
 "host": {
  "authentication": {
   "provider": "StaticWebApps"
  }
 }
}

此提供程序已弃用，因为静态 Web 应用预览功能 Data Connections 已于 2025 年 11 月停用。 虽然它仍然正常运行，但它是为 Azure Static Web Apps 中的身份验证的旧实现而设计的。 开发人员应迁移到提供商， AppService 以便更好地获得与 Azure 更广泛的“轻松身份验证”平台的长期支持和一致性。

[!注意] 迁移不如更改配置文件中的提供程序名称那么简单。 提供程序StaticWebAppsAppService需要标头中x-ms-client-principal用于处理角色的不同 JSON 结构。

AppService （身份验证提供程序）

{
 "host": {
  "authentication": {
   "provider": "AppService"
  }
 }
}

此提供程序适用于托管在 Azure 应用服务上的应用程序，例如 Azure 容器应用。 Azure 托管环境处理身份验证，然后通过请求标头将用户的标识信息传递给应用程序。 它适用于需要由 Azure 平台管理的简单现用身份验证解决方案的开发人员。

此提供程序不使用标头中的 Authorization JWT 令牌。 它依赖于应用服务平台注入的特殊标头 X-MS-CLIENT-PRINCIPAL。 此标头包含具有用户标识详细信息的 base64 编码 JSON 对象。

匿名：如果 AppService 提供程序已配置，但请求到达时没有 X-MS-CLIENT-PRINCIPAL 标头，则将请求分配给系统角色 anonymous。

标头中解码的 X-MS-CLIENT-PRINCIPAL JSON 通常如下所示：

{
  "auth_typ": "aad",
  "claims": [
    {"typ": "roles", "val": "admin"},
    {"typ": "roles", "val": "contributor"}
  ],
  "name_typ": "...",
  "role_typ": "..."
}

角色包含在数组中 claims 。

关于 X-MS-API-ROLE 标头

• 角色和行为：标头 X-MS-API-ROLE 用于指定用户希望为当前请求承担的角色。 此标头的值必须与对象数组X-MS-CLIENT-PRINCIPAL中找到claims的角色值之一匹配。
• 是否需要？：否。 X-MS-API-ROLE如果标头不存在，则会在系统角色的authenticated上下文中处理请求。 这意味着用户被识别为已登录，但不识别为令牌中的任何特定应用程序定义角色。
• Match 上的行为：如果 X-MS-API-ROLE 提供标头并且其值与客户端主体 claims中的角色匹配，则用户假定请求具有该角色。
• 不匹配行为：如果 X-MS-API-ROLE 提供了标头，但值与客户端主体中的任何角色不匹配，则请求将被拒绝并显示 403 Forbidden 状态代码。 这可确保用户无法声明他们尚未分配的角色。

EntraId （身份验证提供程序）

{
 "host": {
  "authentication": {
   "provider": "EntraId", // previously AzureAd
   "jwt": {
    "audience": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "issuer": "https://login.microsoftonline.com/98765f43-21ba-400c-a5de-1f2a3d4e5f6a/v2.0"
   }
  }
 }
}

此提供程序使用 Microsoft Entra 中的用户和应用程序标识保护终结点。 它非常适合用户或其他服务需要在 Entra 租户内进行安全访问的任何服务。

[!注意] 提供程序 EntraId 以前已命名 AzureAd。 旧名称仍然有效，但鼓励开发人员将其配置从 AzureAd 中 EntraId迁移到 。

此提供程序需要由 Microsoft Entra 颁发的标头中的 Authorization 标准 JWT 持有者令牌。 必须为特定应用程序（使用 audience 声明）配置令牌。 用户或服务主体的角色应位于令牌中的声明中。 默认情况下，代码会查找 roles 声明。

匿名：如果 EntraId 提供程序已配置，但请求到达时没有 Authorization 标头，则将请求分配给系统角色 anonymous。

解码的 JWT 有效负载可能如下所示：

{
  "aud": "...", // Audience - your API
  "iss": "https://login.microsoftonline.com/{tenant-id}/v2.0", // Issuer
  "oid": "...", // User or principal object ID
  "roles": [
    "reader",
    "writer"
  ],
  // ... other claims
}

关于 X-MS-API-ROLE 标头

• 角色和行为：标头 X-MS-API-ROLE 用于指定用户希望为请求承担的角色。 此标头的值必须与 JWT 令牌声明中找到 roles 的角色值之一匹配。
• 是否需要？：否。 X-MS-API-ROLE如果标头不存在，则会在系统角色的authenticated上下文中处理请求。 这意味着用户被识别为已登录，但不识别为令牌中的任何特定应用程序定义角色。
• Match 上的行为：如果 X-MS-API-ROLE 提供了标头，并且它与声明中 roles 的角色匹配，则用户的上下文将设置为该角色。
• 不匹配行为：如果 X-MS-API-ROLE 提供了标头，但其值与声明中的任何 roles 角色不匹配，则请求将被拒绝并带有 403 Forbidden 状态代码。 这可确保用户无法声明他们尚未分配的角色。

自定义（身份验证提供程序）

{
 "host": {
  "authentication": {
   "provider": "Custom",
   "jwt": {
    "audience": "<client-id-or-api-audience>",
    "issuer": "https://<your-domain>/oauth2/default"
   }
  }
 }
}

此提供程序适用于希望将数据 API 生成器与颁发 JWT 的第三方标识提供者（如 Auth0、Okta 或自定义标识服务器）集成。 它提供配置预期 audience 令牌和 issuer 令牌的灵活性。

提供程序 Custom 需要标头中的 Authorization 标准 JWT 持有者令牌。 与 EntraId 提供程序的主要区别在于，在数据 API 生成器的配置文件中配置有效 issuer 和 audience 配置。 提供程序通过检查受信任的颁发机构是否颁发令牌来验证令牌。 用户的角色应位于 roles JWT 有效负载中的声明中。

[!注意] 在某些情况下，根据第三方标识提供者，开发人员需要强制其 JWT 的结构，以匹配数据 API 生成器预期的结构（如下所示）。

匿名：如果 Custom 提供程序已配置，但请求到达时没有 Authorization 标头，则将请求分配给系统角色 anonymous。

提供程序的解码 JWT 有效负载 custom 可能如下所示：

{
  "aud": "my-api-audience", // Must match configuration
  "iss": "https://my-custom-issuer.com/", // Must match configuration
  "sub": "user-id",
  "roles": [
    "editor",
    "viewer"
  ],
  // ... other claims
}

关于 X-MS-API-ROLE 标头

• 角色和行为： X-MS-API-ROLE 标头函数与提供程序完全相同 EntraId 。 它允许用户选择其分配的角色之一。 此标头的值必须与自定义 JWT 令牌中声明的角色 roles 之一匹配。
• 是否需要？：否。 X-MS-API-ROLE如果标头不存在，则用户被视为处于系统角色中authenticated。
• Match 的行为：如果 X-MS-API-ROLE 标头的值与 JWT roles 声明中的角色匹配，则用户的上下文将设置为该角色以进行授权。
• 不匹配行为：如果 X-MS-API-ROLE 标头的值与声明中的任何 roles 角色不匹配，则请求将被拒绝并带有 403 Forbidden 状态代码。 这可确保用户无法声明他们尚未分配的角色。

模拟器（身份验证提供程序）

此提供程序旨在方便开发人员测试其配置，尤其是 authorization 策略，而无需设置完整的身份验证提供程序，例如 Entra Identity 或 EasyAuth。 它模拟用户 authenticated 。

提供程序 Simulator 不使用 JWT 令牌。 身份验证是模拟的。 使用此提供程序时，所有请求都被视为来自经过身份验证的用户。

关于 X-MS-API-ROLE 标头

• 角色和行为：标头 X-MS-API-ROLE 是使用 Simulator 时指定角色的唯一方法。 由于没有包含角色列表的令牌，因此系统隐式信任在此标头中发送的角色。
• 是否需要？：否。
• 缺席行为：如果 X-MS-API-ROLE 标头不存在，则会在系统角色的 authenticated 上下文中处理请求。
• 状态行为：如果 X-MS-API-ROLE 标头存在，则请求在标头值中指定的角色的上下文中进行处理。 没有针对声明列表的验证，因此开发人员可以模拟测试策略所需的任何角色。

生产中的模拟器

如果设置为 is production时，Simulatorauthentication.providerruntime.host.mode数据 API 生成器将无法启动。

"host": {
  "mode": "production", // or "development"
  "authentication": {
    "provider": "Simulator" 
  }
}

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

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

嵌套属性

Format

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

分页 （运行时）

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

嵌套属性

支持的最大页大小值

默认页面大小支持的值

Format

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>,
      "default-page-size": <integer; default: 100>
    }
  }
}

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

缓存（运行时）

全局缓存配置。

嵌套属性

Format

{
  "runtime": {
    "cache":  {
      "enabled": <boolean>,
      "ttl-seconds": <integer>
    }
  }
}

遥测（运行时）

全局遥测配置。

嵌套属性

为每个命名空间配置日志记录详细程度。 这遵循标准 .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。

运行状况（运行时）

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

嵌套属性

开发中的行为与生产行为

Format

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

Example

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