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

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

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

本页面介绍了 OpenAPI 规范 3.x 的 Google 专用扩展。

虽然给出的示例采用 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 会使用与地址字段匹配的 JWT 受众群体创建实例 ID 令牌。仅当目标后端使用基于 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 端点上，截止时间则会限制消息之间的间隔。如需了解适用于每种请求的超时，请参阅设置流截止时间。省略该字段或将其设置为 `0`，以使用默认值。负值会被拒绝。时限最长可配置为 3600 秒。非流式网关强制执行较低的上限（600 秒），在网关创建或更新时（而不是在 API 配置创建时）拒绝更高的截止时间。
`protocol`	`string`	否	`http/1.1`	设置用于向后端发送请求的协议。支持的值包括 `http/1.1` 和 `h2`。协议要求取决于流式传输类型： - gRPC：您必须将协议设置为 `h2`。 - WebSocket：您必须使用 `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 `aud` 字段在 JWT 身份验证期间必须匹配的受众群体。
`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`