API Gateway 中的 OpenAPI 2.0 擴充功能
API Gateway 接受一組 Google 專屬的 OpenAPI 規格擴充功能，這些擴充功能可設定閘道的行為。本頁說明 Google 專屬的自訂 OpenAPI 規格 2.0 擴充功能，可用於設定 API Gateway 行為，例如後端路由、驗證和 API 管理功能。
雖然以下提供的範例為 YAML 格式，但也支援 JSON 格式。
命名慣例
Google OpenAPI 擴充功能的名稱會以前置字串「x-google-」開頭。
x-google-allow
x-google-allow: [configured | all]
這項擴充功能用於 OpenAPI 規格的頂層，可指出您應允許哪些網址路徑通過 API Gateway。
可能的值為 configured 和 all。
預設值為 configured，代表只有 OpenAPI 規格中列出的 API 方法才能透過 API Gateway 提供。
如果您使用了 all，無論未經設定的呼叫是否具備 API 金鑰或通過使用者驗證，都會透過 API Gateway 傳送至您的 API。
API Gateway 會以區分大小寫的方式處理傳送至 API 的呼叫。舉例來說，API Gateway 會將 /widgets 和 /Widgets 視為不同的 API 方法。
使用 all 時，請特別留意兩個部分：
- API 金鑰或驗證規則。
- 服務中的後端路徑轉送。
建議您將 API 設定為使用區分大小寫路徑轉送功能。使用區分大小寫的轉送功能後，如果網址中要求的方法與 OpenAPI 規格中列出的 API 方法名稱不相符，API 將傳回 HTTP 狀態碼 404。請注意，Node.js Express 等網頁應用程式架構中包含啟用或停用區分大小寫轉送功能的設定選項。預設行為視您使用的架構而定。建議您查看架構中的設定，以確定啟用區分大小寫轉送功能。這項建議與以下 OpenAPI 規格 v2.0 規範一致：「規格中的所有欄位名稱都必須區分大小寫」。
範例
假設：
x-google-allow設為all。- OpenAPI 規格中列出的 API 方法是
widgets，而非Widgets。 - 您已將 OpenAPI 規格設為必須使用 API 金鑰。
由於 widgets 已列在您的 OpenAPI 規格中，API Gateway 會封鎖以下要求，因為該要求沒有 API 金鑰：
https://my-project-id.appspot.com/widgets
Widgets 未列於您的 OpenAPI 規格，因此 API Gateway 會在沒有 API 金鑰的情況下將以下要求傳送至您的服務：
https://my-project-id.appspot.com/Widgets/
如果您的 API 採用了必須區分大小寫的轉送功能，您也尚未將傳送至「Widgets」的呼叫轉送至任何程式碼，API 後端就會傳回 404。不過，如果您使用了不區分大小寫的轉送功能，API 後端就會將這項呼叫轉送至「Widgets」。
不同的程式語言和架構對於控制區分大小寫與轉送功能有不同的方法。詳情請參閱您的架構說明文件。
x-google-backend
x-google-backend 擴充功能會指定如何將要求轉送至遠端後端。您可以在 OpenAPI 規格的頂層、作業層級或這兩個層級指定擴充功能。
x-google-backend 擴充功能也可以設定遠端後端的其他設定，例如驗證和逾時。所有這些設定都可以按作業套用。
x-google-backend 擴充功能包含下列欄位：
address
address: URL
這是必要旗標，目標後端的網址。
地址的架構必須是 http 或 https。
路由至遠端後端 (無伺服器) 時，應設定位址，且配置部分應為 https。
jwt_audience | disable_auth
請只設定這兩個屬性的其中一個。
如果作業使用 x-google-backend，但未指定 jwt_audience 或 disable_auth，API Gateway 會自動將 jwt_audience 預設為與 address 相符。如果未設定 address，API Gateway 會自動將 disable_auth 設為 true。
jwt_audience
jwt_audience: string
(選用步驟) API Gateway 取得執行個體 ID 權杖時指定的 JWT 目標對象，日後提出目標後端要求時即會使用這項設定。
為無伺服器設定 API Gateway 時，應確保遠端後端安全無虞，只允許來自 API Gateway 的流量。API Gateway 會在轉送要求時，將執行個體 ID 權杖附加至 Authorization 標頭。執行個體 ID 權杖代表用於部署 API Gateway 的執行階段服務帳戶。遠端後端隨後可根據這個附加權杖，驗證要求是否來自 API Gateway。
舉例來說，在 Cloud Run 上部署的遠端後端可以使用 Identity and Access Management (IAM) 執行下列操作：
- 如要限制未經驗證的叫用，請撤銷特殊
allUsers主體的roles/run.invoker。 - 將
roles/run.invoker角色授予 API Gateway 執行階段服務帳戶，只允許 API Gateway 叫用後端。
根據預設，API Gateway 會建立執行個體 ID 權杖，並使用與 address 欄位相符的 JWT 目標對象。只有在目標後端使用以 JWT 為基礎的驗證機制，且預期目標對象與 address 欄位中指定的值不同時，您才需要手動指定 jwt_audience。如果是部署在 App Engine 或使用 Identity-Aware Proxy (IAP) 的遠端後端，您必須覆寫 JWT 目標對象。App Engine 和 IAP 會使用其 OAuth 用戶端 ID 做為預期目標對象。
啟用這項功能後，API Gateway 會變更要求中的標頭。如果要求已設定 Authorization 標頭，API Gateway 會執行下列操作：
- 將原始值複製到新的標頭
X-Forwarded-Authorization。 - 使用執行個體 ID 權杖覆寫
Authorization標頭。
因此，如果 API 用戶端設定 Authorization 標頭，在 API Gateway 後方執行的後端應使用 X-Forwarded-Authorization 標頭擷取整個 JWT。後端必須驗證這個標頭中的 JWT，因為如果未設定驗證方法，API Gateway 就不會執行驗證。
如需設定範例，請參閱「建立 API 設定」。
disable_auth
disable_auth: bool
(選用步驟) 這項屬性會決定 API Gateway 是否應禁止取得執行個體 ID 權杖，以及禁止將權杖附加至要求。
設定目標後端時，如果符合下列任一條件，您可能不想使用 IAP 或 IAM 驗證來自 API 閘道的要求：
- 後端應允許未經驗證的叫用。
- 後端需要 API 用戶端的原始
Authorization標頭，且無法使用X-Forwarded-Authorization(如jwt_audience節所述)。
在本例中，請將這個欄位設為 true。
path_translation
path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]
(選用步驟) 設定 API Gateway 將要求轉送至目標後端時採用的路徑轉譯策略。
如要進一步瞭解路徑轉譯，請參閱「瞭解路徑轉譯」一節。
x-google-backend 用於 OpenAPI 規格的頂層時，path_translation 的預設值為 APPEND_PATH_TO_ADDRESS。x-google-backend 用於 OpenAPI 規格的操作層級時，path_translation 的預設值則為 CONSTANT_ADDRESS。如果缺少 address 欄位，path_translation 會維持未指定狀態，不會發生。
deadline
deadline: double
(選用步驟) 等待要求完整回應的秒數。
如果回應時間超過設定的期限，就會逾時。預設期限為 15.0 秒。
系統不會採用非正值。在這些情況下，API Gateway 會自動使用預設值。
截止期限無法停用，但可以設為較高的值，例如 600 秒 (截止期限上限)。
protocol
protocol: [ http/1.1 | h2 ]
(選用步驟) 用來將要求傳送至後端的通訊協定。
支援的值為 http/1.1 和 h2。
HTTP 和 HTTPS 後端的預設值為 http/1.1。
對於支援 HTTP/2 的安全 HTTP 後端 (https://)，請將此欄位設為 h2，以提升效能。這是無伺服器後端的建議選項。 Google Cloud
瞭解路徑轉譯
API Gateway 會在處理要求時擷取原始要求路徑，並在向目標後端提出要求前進行轉譯。這項轉譯作業的具體執行方法取決於您採用的路徑轉譯策略。路徑轉譯策略共有兩種：
APPEND_PATH_TO_ADDRESS：將原始要求路徑附加至x-google-backend擴充功能的address網址，藉此計算目標後端要求的路徑。CONSTANT_ADDRESS：如x-google-backend擴充功能的address網址所定義，目標要求路徑為固定值。如果相對應的 OpenAPI 路徑含有參數，參數名稱及其值會變為查詢參數。
範例：
APPEND_PATH_TO_ADDRESSaddress: https://my-project-id.appspot.com/BASE_PATH- 含有 OpenAPI 路徑參數
- OpenAPI 路徑：
/hello/{name} - 要求路徑：
/hello/world - 目標要求網址：
https://my-project-id.appspot.com/BASE_PATH/hello/world
- OpenAPI 路徑：
- 不含 OpenAPI 路徑參數
- OpenAPI 路徑：
/hello - 要求路徑：
/hello - 目標要求網址：
https://my-project-id.appspot.com/BASE_PATH/hello
- OpenAPI 路徑：
CONSTANT_ADDRESSaddress：https://us-central1-my-project-id.cloudfunctions.net/helloGET- 含有 OpenAPI 路徑參數
- OpenAPI 路徑：
/hello/{name} - 要求路徑：
/hello/world - 目標要求網址：
https://us-central1-my-project-id.cloudfunctions.net/helloGET?name=world
- OpenAPI 路徑：
- 不含 OpenAPI 路徑參數
- OpenAPI 路徑：
/hello - 要求路徑：
/hello - 目標要求網址：
https://us-central1-my-project-id.cloudfunctions.net/helloGET
- OpenAPI 路徑：
x-google-endpoints
本節將說明如何使用 x-google-endpoints 擴充功能。
將 API Gateway 設為允許 CORS 要求
如有位於不同來源的網頁應用程式呼叫您的 API，該 API 就必須支援跨來源資源共用 (CORS)。如要瞭解如何將 API Gateway 設為支援 CORS，請參閱「為 API Gateway 新增 CORS 支援」一節。
如要在後端程式碼中導入自訂 CORS 支援，請設定 allowCors: True，讓 API Gateway 將所有 CORS 要求傳送至您的後端程式碼：
x-google-endpoints: - name: "API_NAME.endpoints.PROJECT_ID.cloud.goog" allowCors: True
請在 OpenAPI 文件頂層 (未使用縮排或巢狀結構) 新增 x-google-endpoints 擴充功能，例如：
swagger: "2.0" host: "my-cool-api.endpoints.my-project-id.cloud.goog" x-google-endpoints: - name: "my-cool-api.endpoints.my-project-id.cloud.goog" allowCors: True
x-google-issuer
x-google-issuer: URI | EMAIL_ADDRESS
這項擴充功能用於 OpenAPI securityDefinitions 區段，可指定憑證的核發者，其值可以採用主機名稱或電子郵件地址的形式。
x-google-jwks_uri
x-google-jwks_uri: URI
將提供者公開金鑰的 URI 設為驗證 JSON Web Token 的簽名。
x-google-jwks_uri (OpenAPI 2.0) 或 jwksUri (OpenAPI 3.x) 欄位為必填。
API Gateway 支援此 OpenAPI 擴充功能定義的兩種非對稱公開金鑰格式：
-
JWK 集格式。
例如：
OpenAPI 2.0
x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
OpenAPI 3.x
jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
-
X509。例如：
OpenAPI 2.0
x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"
OpenAPI 3.x
jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"
如果您使用對稱金鑰格式，請將 x-google-jwks_uri (OpenAPI 2.0) 或 jwksUri (OpenAPI 3.x) 設為包含 base64url 編碼金鑰字串的檔案 URI。
x-google-jwt-locations
根據預設，系統會透過 Authorization 標頭 (以 "Bearer " 為前置字元)、X-Goog-Iap-Jwt-Assertion 標頭或 access_token 查詢參數傳遞 JWT。
或者，您也可以在 OpenAPI securityDefinitions 區段中使用 x-google-jwt-locations 擴充功能，提供自訂位置，從中擷取 JWT 權杖。
x-google-jwt-locations 擴充功能接受 JWT 位置清單。每個 JWT 位置都包含下列欄位：
| 元素 | 說明 |
|---|---|
header/query |
這是必要旗標，含有 JWT 的標頭名稱，或含有 JWT 的查詢參數名稱。 |
value_prefix |
(選用步驟) 僅限標頭。設定 value_prefix 時，其值必須與包含 JWT 的標頭值前置字元相符。 |
例如：
x-google-jwt-locations:
# Expect header "Authorization": "MyBearerToken <TOKEN>"
- header: "Authorization"
value_prefix: "MyBearerToken "
# expect header "jwt-header-foo": "jwt-prefix-foo<TOKEN>"
- header: "jwt-header-foo"
value_prefix: "jwt-prefix-foo"
# expect header "jwt-header-bar": "<TOKEN>"
- header: "jwt-header-bar"
# expect query parameter "jwt_query_bar=<TOKEN>"
- query: "jwt_query_bar"
如要僅支援部分預設 JWT 位置，請在 x-google-jwt-locations 擴充功能中明確列出這些位置。舉例來說，如要僅支援含有 "Bearer " 前置字串的 Authorization 標頭：
x-google-jwt-locations:
# Support the default header "Authorization": "Bearer <TOKEN>"
- header: "Authorization"
value_prefix: "Bearer "
x-google-audiences
x-google-audiences: STRING
這項擴充功能用於 OpenAPI securityDefinitions 區段，可提供 JWT 驗證期間 JWT aud 欄位應相符的目標對象清單。這項擴充功能接受以逗號分隔資料值的單一字串，但不同目標對象之間不得使用空格。如未指定，JWT aud 欄位應與 OpenAPI 文件中的 host 欄位相符。
securityDefinitions:
google_id_token:
type: oauth2
authorizationUrl: ""
flow: implicit
x-google-issuer: "https://accounts.google.com"
x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"
x-google-audiences: "848149964201.apps.googleusercontent.com,841077041629.apps.googleusercontent.com"
x-google-management
x-google-management 擴充功能可以控制 API 管理作業的各個不同層面，並包含本節所述的欄位。
metrics
您可以將 metrics 與配額和 x-google-quota 搭配使用，為您的 API 設定配額。設定配額之後，您就能控制應用程式呼叫 API 中方法的頻率。例如：
x-google-management:
metrics:
- name: read-requests
displayName: Read requests
valueType: INT64
metricKind: DELTA
metrics 欄位中包含具備以下鍵/值組合的清單：
| 元素 | 說明 |
|---|---|
| name | (必填) 這個指標的名稱。通常這是專門用來辨識指標的要求類型 (例如，「read-requests」或「write-requests」)。 |
| displayName | (選填，但建議使用) 在Google Cloud console 的「Endpoints」 >「Services」(服務) 頁面中，顯示的文字可用來識別「Quotas」(配額) 分頁中的指標。API 的使用者也會在「Quotas」(配額) 頁面的「IAM & admin」(IAM 與管理員) 和「APIs & Services」(API 和服務) 下方看見這段文字。顯示名稱長度上限為 40 個字元。 為方便閱讀，相關聯配額限制的單位會自動附加至Google Cloud console 中的顯示名稱後方。舉例來說，如果您將顯示名稱指定為「Read requests」(讀取要求)，Google Cloud 控制台中就會顯示「Read requests per minute per project」(每項專案每分鐘的讀取要求數)。如未指定，則 API 使用者會在「Quotas」(配額) 頁面的「IAM & admin」(IAM 與管理員) 和「APIs & Services」(API 和服務) 下方看見「unlabeled quota」(未加標籤的配額)。 為了與 API 消費者在「配額」頁面上看到的 Google 服務顯示名稱保持一致，我們對於顯示名稱有以下建議：
|
| valueType | (必填) 必須為 INT64 |
| metricKind | (必填) 必須為 DELTA |
quota
在 quota 區段中，您可以為已定義的指標指定配額限制。例如：
quota:
limits:
- name: read-requests-limit
metric: read-requests
unit: 1/min/{project}
values:
STANDARD: 5000
quota.limits 欄位中包含具備以下鍵/值組合的清單：
| 元素 | 說明 |
|---|---|
| name | (必填) 限制的名稱，在服務中不能重複。該名稱可以包含大小寫字母、數字和「-」(連字號字元)，長度必須在 64 個字元以內。 |
| metric | (必填) 此限制適用的指標名稱。此名稱必須與指標名稱中指定的文字相符。如果指定的文字與指標名稱不相符，部署 OpenAPI 文件時就會發生錯誤。 |
| unit | (必填) 限制的單位。目前僅支援「1/min/{project}」，這代表該項限制是以「專案」為單位強制實行，且用量每分鐘重設一次。 |
| 值 | (必填) 指標的用量限制。您必須將這個值指定為鍵/值組合，格式如下：STANDARD: YOUR-LIMIT-FOR-THE-METRIC YOUR-LIMIT-FOR-THE-METRIC 替換為以指定單位 (目前只有「每分鐘」和「每項專案」) 計算的要求次數上限整數值，例如：values: STANDARD: 5000 |
x-google-quota
x-google-quota 擴充功能用於 OpenAPI 的 paths 區段，可連結 API 方法與指標。配額限制不會套用至未定義 x-google-quota 的方法，例如：
x-google-quota:
metricCosts:
read-requests: 1
x-google-quota 擴充功能中包含下列項目：
| 元素 | 說明 |
|---|---|
| metricCosts | 使用者定義的鍵/值組合："YOUR-METRIC-NAME": METRIC-COST。
|
配額範例
以下範例顯示如何為讀取要求和寫入要求新增指標與限制。
x-google-management:
metrics:
# Define a metric for read requests.
- name: "read-requests"
displayName: "Read requests"
valueType: INT64
metricKind: DELTA
# Define a metric for write requests.
- name: "write-requests"
displayName: "Write requests"
valueType: INT64
metricKind: DELTA
quota:
limits:
# Rate limit for read requests.
- name: "read-requests-limit"
metric: "read-requests"
unit: "1/min/{project}"
values:
STANDARD: 5000
# Rate limit for write requests.
- name: "write-request-limit"
metric: "write-requests"
unit: "1/min/{project}"
values:
STANDARD: 5000
paths:
"/echo":
post:
description: "Echo back a given message."
operationId: "echo"
produces:
- "application/json"
responses:
200:
description: "Echo"
schema:
$ref: "#/definitions/echoMessage"
parameters:
- description: "Message to echo"
in: body
name: message
required: true
schema:
$ref: "#/definitions/echoMessage"
x-google-quota:
metricCosts:
read-requests: 1
security:
- api_key: []
x-google-api-name
如果您的服務只有一個 API，則 API 名稱會與 API Gateway 服務名稱相同，(API Gateway 會使用您在 OpenAPI 文件的 host 欄位中指定的名稱來當做服務名稱)。如果您的服務含有多個 API，您可以將 x-google-api-name 擴充功能新增至 OpenAPI 文件，藉此指定各個 API 的名稱。x-google-api-name 擴充功能可讓您明確地為各個 API 命名，並為每個 API 建立獨立的版本管理機制。
舉例來說，針對含有 Producer 和 Consumer 這兩個 API 的 api.example.com 服務，您可以使用下列 OpenAPI 文件片段加以設定：
producer.yaml中的 Producer API：swagger: 2.0 host: api.example.com x-google-api-name: producer info: version: 1.0.3
consumer.yaml中的 Consumer API：swagger: 2.0 host: api.example.com x-google-api-name: consumer info: version: 1.1.0
您可以利用下列指令，同時部署這兩份 OpenAPI 文件：
gcloud api-gateway api-configs create API_CONFIG_ID \ --api=my-api \ --openapi-spec="producer.yaml,consumer.yaml" \ --project=my-project-id