Endpoints 接受一組 Google 專屬的 OpenAPI 規格擴充功能，這些擴充功能可設定閘道的行為。您可以在 OpenAPI 文件中直接指定 API 管理設定、驗證方法、配額限制和後端整合。瞭解這些擴充功能有助於調整服務行為，並整合 Endpoints 功能。
這個頁面將說明 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 文件中定義的作業建立關聯。 |
allowCors |
bool |
否 | False |
將所有 CORS (OPTIONS) 要求傳送至後端。 |
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 |
否 | 空白 | 根據預設，Endpoints 會建立執行個體 ID 符記，並使用與位址欄位相符的 JWT 目標對象。只有在目標後端使用以 JWT 為基礎的驗證機制，且預期目標對象與地址欄位中指定的值不同時，才需要手動指定 jwt_audience。如果是部署在 App Engine 或使用 IAP 的遠端後端，您必須覆寫 JWT 目標對象。App Engine 和 IAP 會使用其 OAuth 用戶端 ID 做為預期目標對象。 |
disableAuth |
bool |
否 | False |
防止資料平面 Proxy 取得執行個體 ID 權杖，並將其附加至要求。 |
pathTranslation |
string |
否 | APPEND_PATH_TO_ADDRESS或CONSTANT_ADDRESS |
在將要求 Proxy 至目標後端時，設定路徑轉譯策略。如果頂層設定 x-google-backend，預設 pathTranslation 為 APPEND_PATH_TO_ADDRESS。如果作業設為 x-google-backend，預設值為 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 Token 簽章。 |
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 中定義的後端。您必須為 Endpoints 設定這個擴充功能。您可以在 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 的欄位：
| 欄位 | 類型 | 必填 | 預設 | 說明 |
|---|---|---|---|---|
target |
string |
否 | 指定主機解析的 IP 位址。 | |
allowCors |
bool |
否 | false |
允許 CORS 要求。 |
瞭解 OpenAPI 擴充功能限制
這些 OpenAPI 擴充功能有特定限制。詳情請參閱「OpenAPI 3.x 功能限制」。
後續步驟
- 瞭解 OpenAPI 規範。
- 如需特定 Endpoints 或 ESPv2 設定，請參閱 Endpoints 說明文件。