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 文档中定义的操作相关联。 |
Metric 对象
Metric 对象定义了用于强制执行配额的指标。
下表介绍了 Metric 的字段：
| 字段 | 类型 | 必需 | 默认 | 说明 |
|---|---|---|---|---|
displayName |
string |
否 | 空 | 相应指标的显示名称。 |
Quota 对象
Quota 对象用于定义配额限制。
下表介绍了 Quota 的字段：
| 字段 | 类型 | 必需 | 默认 | 说明 |
|---|---|---|---|---|
limits |
map[string]QuotaLimit |
否 | 空 | 指定配额限制。 |
Quota Limit 对象
QuotaLimit 对象定义了具体的配额限制。
下表介绍了 QuotaLimit 的字段：
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
metric |
string |
是 | 引用此 OpenAPI 文档中声明的指标。 |
values |
int64 |
是 | 设置在拒绝客户端请求之前，指标可达到的最大值。 |
Backend 对象
Backend 对象用于配置后端服务。您必须设置 jwtAudience 或 disableAuth。
下表介绍了 Backend 的字段：
| 字段 | 类型 | 必需 | 默认 | 说明 |
|---|---|---|---|---|
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 |
指定等待请求完整响应的秒数。如果响应超过此截止期限，则会超时。 |
protocol |
string |
否 | http/1.1 |
设置用于向后端发送请求的协议。支持的值包括 http/1.1 和 h2。 |
x-google-auth
可选。
x-google-auth 扩展程序在安全方案对象中定义身份验证设置。
下表介绍了 x-google-auth 的字段：
| 字段 | 类型 | 必需 | 默认 | 说明 |
|---|---|---|---|---|
issuer |
string |
否 | 空 | 指定凭据的颁发者。值可以是主机名或电子邮件地址。 |
jwksUri |
string |
否 | 空 | 提供提供商公钥集的 URI，用于验证 JSON Web 令牌的签名。API Gateway 支持此 OpenAPI 扩展程序定义的两种非对称公钥格式：
如果您使用的是对称密钥格式，请将 |
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 扩展程序定义了配额限制。您可以在 OpenAPI 文档的顶层或针对单个操作定义此扩展程序。
下表介绍了 x-google-quota 的字段：
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
self |
map[string]int64 |
是 | quota 对象 (self) 引用对象内定义的任何指标。在这种情况下，请将某个指标（例如 read-requests）映射到用于递增该指标的金额。当指标值达到配额限制时，系统会拒绝请求。 |
x-google-backend
必填。
x-google-backend 扩展程序引用了 x-google-api-management 中定义的后端。您必须为 API Gateway 设置此扩展程序。您可以在 OpenAPI 文档的顶层或针对单个操作定义此扩展程序。
下表介绍了 x-google-backend 的字段：
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
self |
string |
是 | 引用 x-google-api-management 中定义的后端的 ID。 |
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 功能限制。