疑難排解總覽

本頁提供 API Gateway 的一般疑難排解資訊。

無法執行「gcloud api-gateway」指令

如要執行 gcloud api-gateway ... 指令，您必須更新 Google Cloud CLI，並啟用必要的 Google 服務。詳情請參閱「設定開發環境」。

「gcloud api-gateway api-configs create」指令指出服務帳戶不存在

如果您執行 gcloud api-gateway api-configs create ... 指令，並收到以下格式的錯誤：

ERROR: (gcloud.api-gateway.api-configs.create) FAILED_PRECONDITION:
Service Account "projects/-/serviceAccounts/service_account_email" does not exist

重新執行指令，但這次加入 --backend-auth-service-account 選項，明確指定要使用的服務帳戶電子郵件地址：

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

請確認您已按照「設定開發環境」中的說明，將必要權限指派給服務帳戶。

判斷 API 錯誤回應的來源

如果對已部署 API 的要求導致錯誤 (HTTP 狀態碼 400 到 599)，回應本身可能無法清楚指出錯誤是來自閘道還是後端。判斷方式如下：

  1. 前往「Logs Explorer」頁面，選取專案。

    前往 Logs Explorer

  2. 使用下列記錄查詢，篩選出相關的閘道資源：

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
resource.labels.location="GCP_REGION"

    其中：

    • GATEWAY_ID 指定閘道名稱。
    • GCP_REGION 是部署閘道的 Google Cloud 區域。

  3. 找出與要調查的 HTTP 錯誤回應相符的記錄項目。例如，依 httpRequest.status 篩選。

  4. 檢查 jsonPayload.responseDetails 欄位的內容。

如果 jsonPayload.responseDetails 欄位的值為 "via_upstream"，則錯誤回應來自後端，您必須直接排解後端問題。如果是其他值，則錯誤回應來自閘道；請參閱本文後續章節，瞭解更多疑難排解提示。

API 要求傳回 HTTP 403 錯誤

如果對已部署 API 的要求向 API 用戶端傳回 HTTP 403 錯誤，表示要求的網址有效，但因某些原因而禁止存取。

已部署的 API 具備與服務帳戶角色相關聯的權限，該服務帳戶是您在建立 API 設定時使用的帳戶。通常，HTTP 403 錯誤的原因是服務帳戶沒有存取後端服務的必要權限。

如果您在同一個 Google Cloud 雲端專案中定義 API 和後端服務，請確認服務帳戶已獲派 Editor 角色，或具備存取後端服務所需的角色。舉例來說，如果後端服務是使用 Cloud Run functions 實作，請確認服務帳戶已獲派 Cloud Function Invoker 角色。

API 要求傳回 HTTP 401 或 500 錯誤

如果對已部署 API 的要求向 API 用戶端傳回 HTTP 401 或 500 錯誤，可能是您在建立 API 設定時使用的服務帳戶，在呼叫後端服務時發生問題。

已部署的 API 具備與服務帳戶角色相關聯的權限，該帳戶是您在建立 API 設定時使用的帳戶。系統會檢查服務帳戶，確保帳戶存在，且 API 部署後可供 API Gateway 使用。

如果在部署閘道後刪除或停用服務帳戶，可能會發生下列事件：

  1. 服務帳戶刪除或停用後，您可能會立即在閘道記錄中看到 401 HTTP 回應。如果記錄項目的 jsonPayload 中，jsonPayload.responseDetails 欄位設為 "via_upstream"，表示刪除或停用服務帳戶是造成錯誤的原因。

  2. 您也可能看到 HTTP 500 錯誤，但 API Gateway 記錄中沒有對應的記錄項目。如果服務帳戶刪除或停用後，閘道未立即收到要求，您可能不會看到 HTTP 401 回應，但如果出現 HTTP 500 錯誤，且沒有對應的 API Gateway 記錄，則表示閘道的服務帳戶可能已不再有效。

如果失敗要求的後端是另一個 Google Cloud API (例如 bigquery.googleapis.com)，您會在閘道記錄中看到 401 HTTP 回應，且 jsonPayload.responseDetails 欄位設為 "via_upstream"。這是因為 API Gateway 使用 ID 權杖向後端進行驗證，而其他 Google Cloud API 則需要存取權杖。

API 要求針對強制執行配額的方法傳回 HTTP 500 錯誤

如果收到下列錯誤，表示閘道無法為您的要求分配配額：

HTTP/2 500
{"code":500,"message":"Failed to call Service Control Quota."}

如果呼叫的方法已設定配額，但 API 已不含配額指標，通常就會發生這項錯誤。在 gRPC 閘道上，系統會傳回相同的失敗，並顯示 gRPC 狀態碼 Internal。

在閘道記錄中確認原因

  1. 前往「Logs Explorer」頁面，選取專案。

    前往 Logs Explorer

  2. 執行下列記錄查詢：

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
jsonPayload.responseDetails="service_control_quota_error"
httpRequest.status=500

    其中 GATEWAY_ID 指定閘道名稱。

    查詢會篩選狀態碼和 jsonPayload.responseDetails，因為 API Gateway 會針對每次配額拒絕使用相同的 responseDetails 值。如果要求合法超過配額，則會產生相同的值，且 httpRequest.status 為 429。

  3. 檢查任何相符項目的 jsonPayload.apiConfig 和 jsonPayload.apiMethod 欄位。這些訊息會指出 API 設定和配額設定無效的方法。

API 設定的配額設定無效的原因

您可以在 API 設定中定義配額指標和限制，但 API Gateway 會將這些指標和限制套用至整個 API。每次建立 API 設定時，其中宣告的指標和限制都會取代 API 先前 API 設定宣告的指標和限制。系統只會強制執行最近建立的 API 設定值。

相較之下，各方法使用的指標則定義在閘道提供的 API 設定中。如果閘道執行舊版 API 設定，會要求 Service Control 根據自身設定中存在的指標分配配額，但該指標可能不存在於 API 中。如果指標不存在，分配呼叫就會失敗，閘道也會拒絕要求。

舉例來說，下列序列會導致第一個閘道中斷：

  1. 您建立 API 設定 config-v1，宣告指標 quota-metric-v1，並將其部署至 gateway-1。
  2. 您為同一個 API 建立 API 設定 config-v2，宣告指標 quota-metric-v2，並部署至 gateway-2。

gateway-2 仍可運作，但對 gateway-1 設有配額限制的方法提出的要求會開始失敗，因為 API 不再定義 quota-metric-v1。

如果閘道仍部署舊版 API 設定，下列變更可能會導致錯誤：

  • 重新命名或移除指標。
  • 變更配額限制適用的指標。
  • 變更每項方法配額費用中指定的指標 (OpenAPI 文件的 x-google-quota，或 gRPC 服務設定的 quota.metric_rules)。

如果只變更限制的值，不會造成錯誤。不過，由於限制也會在 API 層級套用，因此該 API 的每個閘道 (包括使用舊版 API 設定部署的閘道) 都會強制執行新值。

比較已部署的配額設定

  1. 列出閘道和各閘道提供的 API 設定：

    gcloud api-gateway gateways list \
 --format="table(name.basename(),apiConfig)"

  2. 列出受影響 API 的 API 設定，並依建立時間由新到舊排序：

    gcloud api-gateway api-configs list --api=API_ID \
 --format="table(name.basename(),createTime:sort=1:reverse)"

    第一個項目是 API 設定，其配額指標和限制會套用至整個 API。使用 --format 旗標排序，如下所示：這個指令不支援 --sort-by 旗標，且不會以可預測的順序傳回 API 設定。

  3. 顯示用來建立 API 設定的 API 定義：

    gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID \
 --view=FULL --format="value(openapiDocuments[0].document.contents)" \
 | tr '_-' '/+' | base64 --decode

    contents 欄位採用 base64url 編碼，base64 --decode 無法直接讀取，因此必須使用 tr 指令。

    如果是 gRPC API，配額設定位於服務設定中，而非 OpenAPI 文件，因此請將 openapiDocuments[0].document.contents 替換為 managedServiceConfigs[0].contents。

  4. 針對步驟 2 清單頂端的 API 設定，執行步驟 3 的指令，然後針對步驟 1 顯示仍部署至閘道的其他 API 設定，執行相同指令。

  5. 比較結果。舊版 API 設定向其方法收費的每項指標，也必須在最近建立的 API 設定中定義。如果該設定缺少指標，則提供舊版 API 設定的閘道會失敗。

還原有效的配額設定

請檢查配額指標和限制，確保所有有效設定都一致。方法是採取下列任一做法：

  • 按照「更新閘道」一文的說明，更新 API 的每個閘道，使用最近建立的 API 設定。
  • 建立新的 API 設定，宣告仍部署的 API 設定使用的所有指標，並將現有閘道保留在目前的 API 設定。

為避免分配錯誤，請在 API 的 API 設定中保持指標名稱一致。變更配額時，請變更限制值，而非指標名稱。

高延遲 API 要求

與 Cloud Run 和 Cloud Run functions 一樣，API Gateway 也會發生「冷啟動」延遲。如果閘道在 15 到 20 分鐘內未收到流量，則在冷啟動的前 10 到 15 秒內，向閘道提出的要求會延遲 3 到 5 秒。

如果問題在初始「暖機」期後仍未解決，請檢查您在 API 設定中設定的後端服務要求記錄。舉例來說，如果後端服務是使用 Cloud Run functions 實作，請查看相關聯 Cloud 函式要求記錄的 Cloud Logging 記錄項目。

無法查看記錄資訊

如果 API 回應正確，但記錄不含任何資料，通常表示您未啟用 API Gateway 所需的所有 Google 服務。

API Gateway 需要啟用下列 Google Cloud 服務：

名稱 服務名稱
API Gateway API apigateway.googleapis.com
Service Management API servicemanagement.googleapis.com
Service Control API servicecontrol.googleapis.com

如要啟用必要服務，請按照下列步驟操作：

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，依序前往「APIs & Services」(API 與服務) >「API Library」(API 程式庫) 頁面。

    前往 API 程式庫

  2. 在「API Library」(API 程式庫) 頁面的搜尋列中，輸入所需 API 名稱。
  3. 在搜尋結果中選取 API 頁面。
  4. 在 API 頁面中，按一下「啟用」。
  5. 針對上表列出的每項服務，重複執行這些步驟。

Google Cloud CLI

請使用下列指令啟用服務：

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

如要進一步瞭解 gcloud 服務，請參閱「gcloud 服務」。