Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

API Gateway 中的 OpenAPI 3.x 扩展程序

API Gateway 接受一组 Google 特定的 OpenAPI 规范扩展程序，用于配置网关的行为。借助这些扩展程序，您可以直接在 OpenAPI 文档中指定 API 管理设置、身份验证方法、配额限制和后端集成。了解这些扩展程序有助于您定制服务行为并与 API Gateway 功能集成。

本页介绍了 Google 针对 OpenAPI 规范 3.x 提供的特定扩展功能。

虽然给出的示例采用的是 YAML 格式，但 JSON 也受支持。

`x-google-api-management`

必填。

x-google-api-management 扩展程序用于定义服务的顶级 API 管理设置。将此扩展程序放置在 OpenAPI 文档的根目录中。

下表介绍了 x-google-api-management 的字段：

字段	类型	必填	默认	说明
`metrics`	`map[string]Metric`	否	空	定义用于强制执行配额限制的指标。
`quota`	`map[string]Quota`	否	空	为您的服务指定配额限制。
`backends`	`map[string]Backend`	是	空	配置后端服务。
`apiName`	`string`	否	空	将名称与 OpenAPI 文档中定义的操作相关联。
`ai`	`AI`	否	空	配置人工智能功能，包括模型路由。
`mcp`	`MCP` 或 `bool`	否	空	启用或配置 Model Context Protocol (MCP) 功能。

`Metric` 对象

Metric 对象定义了用于强制执行配额的指标。

下表介绍了 Metric 的字段：

字段	类型	必填	默认	说明
`displayName`	`string`	否	空	指标的显示名称。

`Quota` 对象

Quota 对象用于定义配额限制。

下表介绍了 Quota 的字段：

字段	类型	必填	默认	说明
`limits`	`map[string]QuotaLimit`	否	空	指定配额限制。

`QuotaLimit` 对象

QuotaLimit 对象用于定义特定的配额限制。

下表介绍了 QuotaLimit 的字段：

字段	类型	必填	说明
`metric`	`string`	是	引用此 OpenAPI 文档中声明的指标。
`values`	`int64`	是	设置在拒绝客户端请求之前，指标可达到的最大值。

`Backends` 对象

必填。

Backends 对象用于配置后端服务。您必须设置 jwtAudience 或 disableAuth。

下表介绍了 Backends 的字段：

字段	类型	必填	默认	说明
`address`	`string`	是	空	指定后端的网址。
`jwtAudience`	`string`	否	空	默认情况下，API Gateway 将创建实例 ID 令牌，其 JWT 受众群体与地址字段相匹配。仅当目标后端使用基于 JWT 的身份验证且预期受众群体与地址字段中指定的值不同时，才需要手动指定 `jwt_audience`。对于部署在 App Engine 上或使用 IAP 的远程后端，您必须替换 JWT 受众群体。App Engine 和 IAP 使用其 OAuth 客户端 ID 作为预期目标对象。
`disableAuth`	`bool`	否	`False`	防止数据平面代理获取实例 ID 令牌并将其附加到请求中。
`pathTranslation`	`string`	否	`APPEND_PATH_TO_ADDRESS` 或 `CONSTANT_ADDRESS`	在将请求代理到目标后端时，设置路径转换策略。如果在顶级设置了 `x-google-backend` 且未指定 `path_translation`，则默认 `pathTranslation` 为 `APPEND_PATH_TO_ADDRESS`。如果在操作级别设置了 `x-google-backend`，但未指定 `path_translation`，则默认值为 `CONSTANT_ADDRESS`。
`deadline`	`double`	否	`15.0`	指定等待请求的完整响应的秒数。如果响应时间超过此截止时间，则会超时。在 SSE 或分块传输端点上，截止时间仍会限制整个流的持续时间；而在 gRPC 或 WebSocket 端点上，截止时间会限制消息之间的间隔。如需了解适用于每种请求的超时时间，请参阅设置流截止时间。最长可将时限配置为 3,600 秒。非流式网关强制执行的上限较低，为 600 秒，会在创建或更新网关时拒绝较高的截止时间，而不是在创建 API 配置时拒绝。
`protocol`	`string`	否	`http/1.1`	设置向后端发送请求的协议。支持的值包括 `http/1.1` 和 `h2`。协议要求取决于流式传输类型： - gRPC：您必须将协议设置为 `h2`。 - WebSockets：您必须使用 `http/1.1`。 - 服务器发送的事件 (SSE) 和增量响应传递：您可以使用 `http/1.1` 或 `h2`。我们建议使用 `h2` 以提升性能。

`AI` 对象

AI 对象用于为服务配置人工智能功能，例如模型路由。

下表介绍了 AI 的字段：

字段	类型	必填	默认	说明
`models`	`Models`	否	空	配置 AI 模型集成。

`Models` 对象

Models 对象定义了特定于模型的配置。

下表介绍了 Models 的字段：

字段	类型	必填	默认	说明
`routing`	`Routing`	否	空	配置模型路由设置。

`Routing` 对象

Routing 对象定义了模型路由规则和路由器。

下表介绍了 Routing 的字段：

字段	类型	必填	默认	说明
`routers`	`map[string]Router`	否	空	定义命名模型路由器。

`Router` 对象

Router 对象定义了命名模型路由器。

下表介绍了 Router 的字段：

字段	类型	必填	默认	说明
`defaultModel`	`DefaultModel`	是	空	当传入的请求与任何明确的规则都不匹配时，所使用的必需回退模型目标。
`rules`	`[Rule]`	否	空	显式模型路由规则的列表。

`DefaultModel` 对象

DefaultModel 对象用于指定回退目的地。

下表介绍了 DefaultModel 的字段：

字段	类型	必填	默认	说明
`backend`	`string`	是	空	引用在 `x-google-api-management.backends` 中声明的后端。
`targetModel`	`string`	是	空	以 `<provider>/<model-id>` 格式指定目标模型标识符。对于 OpenAI 兼容的路由，发生回退时，此值会作为请求正文中的传出 `model` 属性转发。

`Rule` 对象

Rule 对象定义了显式模型路由规则。

下表介绍了 Rule 的字段：

字段	类型	必填	默认	说明
`model`	`string`	是	空	与客户端 JSON 载荷中的 `model` 属性匹配的传入字符串。对于 OpenAI 兼容的路由，此字符串会作为请求正文中的传出 `model` 属性转发，并且必须是有效的 `<provider>/<model-id>` 字符串。
`backend`	`string`	是	空	引用在 `x-google-api-management.backends` 中声明的后端。
`targetModel`	`string`	是	空	以 `<provider>/<model-id>` 格式指定目标模型标识符。此值用于选择提供商翻译，并在响应的 `model` 字段中回显。

`MCP` 对象

MCP 对象用于为您的服务配置 Model Context Protocol (MCP) 功能。您可以将 mcp 设置为布尔值或对象。设置为 true 可为所有符合条件的操作启用 MCP，并采用默认设置。

下表介绍了 MCP 对象的字段：

字段	类型	必填	默认	说明
`tools-list`	`ToolsList`	否	空	为 `tools/list` MCP 方法配置设置。

`ToolsList` 对象

ToolsList 对象用于配置 tools/list MCP 方法的设置。

下表介绍了 ToolsList 的字段：

字段	类型	必填	默认	说明
`security`	`map`	否	空	在 `tools/list` 上启用身份验证。作为安全最佳实践，强烈建议您配置此选项。必须准确命名 `components.securitySchemes` 下定义的 JWT 安全方案。公开预览版不支持 API 密钥身份验证。

`x-google-auth`

可选。

x-google-auth 扩展程序在安全方案对象中定义身份验证设置。

下表介绍了 x-google-auth 的字段：

字段	类型	必填	默认	说明
`issuer`	`string`	否	空	指定凭据的签发者。值可以是主机名或电子邮件地址。
`jwksUri`	`string`	否	空	提供提供方的公钥集的 URI，以验证 JSON Web 令牌的签名。API Gateway 支持此 OpenAPI 扩展程序定义的两种非对称公钥格式： JWK 集格式。例如 `jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"` X509。例如 `jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"` 如果您使用的是对称密钥格式，请将 `jwksUri` 设置为包含 base64url 编码的密钥字符串的文件的 URI。
`audiences`	`[string]`	否	空	列出在 JWT 身份验证期间 JWT `aud` 字段必须匹配的受众群体。
`jwtLocations`	`[JwtLocations]`	否	空	自定义 JWT 令牌的位置。默认情况下，JWT 在 `Authorization` 标头（以“Bearer ”为前缀）、`X-Goog-Iap-Jwt-Assertion` 标头或 `access_token` 查询参数中传递。

`JwtLocations` 对象

JwtLocations 对象可为 JWT 令牌提供自定义位置。

下表介绍了 JwtLocations 的字段：

字段	类型	必填	默认	说明
`header` \| `query`	`string`	是	不适用	指定包含 JWT 的标头的名称，或包含 JWT 的查询参数的名称。
`valuePrefix`	`string`	否	空	仅适用于标头。如果设置了此属性，其值必须与包含 JWT 的标头值的前缀一致。

`x-google-quota`

可选。

x-google-quota 扩展程序用于在各个操作中指定 x-google-api-management.metrics 中定义的哪些指标会受到对相应操作的请求的影响。

x-google-quota 是一个包含键值对的对象，其中每个键都是一个指标名称，值是每次请求操作的整数费用。例如：

x-google-api-management:
  metrics:
    read-requests:
      displayName: "Greeter requests"
    write-requests:
      displayName: "Greeter requests by name"
  quota:
    limits:
      read-requests-limit:
        metric: read-requests
        values: 1
# Set at the top-level so this applies to all operations (unless overridden)
x-google-quota:
    read-requests: 1
paths:
  /v1/projects/projectId/pets:
    get:
      # Set at the path level, so it overrides the top level quota
      x-google-quota:
          write-requests: 1

`x-google-backend`

必填。

x-google-backend 扩展程序引用了 x-google-api-management.backends 中定义的后端。如果使用此属性，其值必须是与 x-google-api-management.backends 中定义的后端名称相匹配的字符串。您必须为 API Gateway 设置此扩展程序。您可以在 OpenAPI 文档的顶层定义此扩展程序，也可以针对单个操作定义此扩展程序以替换顶层后端。

例如：

x-google-api-management:
  backends:
    my-backend:
      address: myapp.run.app
x-google-backend: my-backend

`x-google-model-router`

可选。

x-google-model-router 扩展程序引用了在 x-google-api-management.ai.models.routing.routers 中定义的模型路由器。如果使用，其值必须是与 x-google-api-management.ai.models.routing.routers 中定义的路由器的名称匹配的字符串。

此扩展程序仅在 OpenAPI 3.x 规范中受支持；不能与 OpenAPI 2.0 (Swagger) 规范搭配使用。您只能针对使用 POST HTTP 方法的操作在单个操作级别定义此扩展程序。您无法在同一操作中同时指定 x-google-model-router 和 x-google-backend，也无法在同一 API 规范中混合使用模型路由和非模型路由操作。此外，您无法将模型路由与 Model Context Protocol (MCP) 搭配使用；启用 x-google-api-management.mcp 会使此扩展程序不可用。

例如：

x-google-api-management:
  backends:
    gemini-backend:
      address: https://aiplatform.googleapis.com/v1/...
  ai:
    models:
      routing:
        routers:
          my-router:
            defaultModel:
              backend: gemini-backend
              targetModel: google/gemini-3.5-flash-lite
paths:
  /v1/chat:
    post:
      x-google-model-router: my-router

`x-google-mcp-tool`

可选。

x-google-mcp-tool 扩展程序用于在各个操作中将它们公开为 MCP 工具，并可选择替换生成的工具名称和说明。

此扩展程序仅在 OpenAPI 3.x 规范中受支持；不能与 OpenAPI 2.0 (Swagger) 规范搭配使用。您只能在单个操作级别定义此扩展程序。

接受布尔值或对象。

布尔值形式：设置为 true 可选择启用此操作。设置为 false 可选择停用，从而覆盖全局启用设置。
对象表单：选择启用并替换生成的工具设置。

下表介绍了 x-google-mcp-tool 用作对象时的字段：

字段	类型	必填	默认	说明
`name`	`string`	否	相应操作的 `operationId`	MCP 工具名称。必须与 `[A-Za-z0-9_.-]{1,128}` 匹配，并且在整个规范中是唯一的。
`description`	`string`	否	操作的说明，如果不存在，则回退到摘要	MCP 工具说明。这是 LLM 用于选择工具的主要信号。

例如：

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

`x-google-endpoint`

可选。

x-google-endpoint 扩展程序用于配置 OpenAPI 3.x 文档的 servers 数组中定义的服务器的属性。OpenAPI 文档中只能有一个服务器条目使用 x-google-endpoint 扩展元素。

扩展程序还定义了其他后端功能，包括：

CORS：您可以通过将 allowCors 属性设置为 true 来启用跨域资源共享 (CORS)。
基本路径：服务器上使用 x-google-endpoint 设置的基本路径将用于您的 API。例如，以下配置将 v1 设置为基本路径：

servers:
  - url: https://API_NAME.apigateway.PROJECT_ID.cloud.goog/v1
    x-google-endpoint: {}

下表介绍了 x-google-endpoint 的字段：

字段	类型	必填	默认	说明
`allowCors`	`bool`	否	`false`	允许 CORS 请求。

`x-google-parameter`

可选。

x-google-parameter 扩展程序是在 parameter 项上定义的。当路径使用路径模板时，可以使用此属性来指定应使用双通配符匹配行为。

下表介绍了 x-google-parameter 的字段：

字段	类型	必填	说明
`pattern`	`string`	是	此值必须设置为 `**`。

了解 OpenAPI 扩展程序的限制

这些 OpenAPI 扩展具有特定限制。如需了解详情，请参阅 OpenAPI 3.x 功能限制。

后续步骤

探索 OpenAPI 规范。
修改网关以使用 OpenAPI 3.0。

API Gateway 中的 OpenAPI 3.x 扩展程序

x-google-api-management

Metric 对象

Quota 对象

QuotaLimit 对象

Backends 对象

AI 对象

Models 对象

Routing 对象

Router 对象

DefaultModel 对象

Rule 对象

MCP 对象

ToolsList 对象

x-google-auth

JwtLocations 对象

x-google-quota

x-google-backend

x-google-model-router

x-google-mcp-tool

x-google-endpoint

x-google-parameter

了解 OpenAPI 扩展程序的限制

后续步骤

`x-google-api-management`

`Metric` 对象

`Quota` 对象

`QuotaLimit` 对象

`Backends` 对象

`AI` 对象

`Models` 对象

`Routing` 对象

`Router` 对象

`DefaultModel` 对象

`Rule` 对象

`MCP` 对象

`ToolsList` 对象

`x-google-auth`

`JwtLocations` 对象

`x-google-quota`

`x-google-backend`

`x-google-model-router`

`x-google-mcp-tool`

`x-google-endpoint`

`x-google-parameter`