疑難排解總覽

本頁提供 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

  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"，則錯誤回應來自後端，您需要直接排解後端問題。如果是其他值，則表示錯誤回應來自 Gateway；如需進一步的疑難排解提示，請參閱本文的後續章節。

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 要求傳回 HTTP 401 或 500 錯誤給 API 用戶端，可能是因為您在建立 API 設定時使用的服務帳戶有問題，導致無法呼叫後端服務。

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

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

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

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

如果失敗要求的後端是另一個 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

  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 設定，執行步驟 3 的指令。

  5. 最後再比較大家的成果。舊版 API 設定對方法收取的每項指標，都必須在最新建立的 API 設定中定義。如果該設定缺少指標，提供舊版 API 設定的閘道就會失敗。

還原有效的配額設定

稽核配額指標和限制，確保所有有效設定都一致。如要這麼做，請採取下列任一做法：

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

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

API 要求延遲時間過長

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

如果初始「暖機」期過後問題仍未解決，請檢查您在 API 設定中設定的後端服務要求記錄。舉例來說，如果後端服務是使用 Cloud Run functions 實作，請檢查相關聯 Cloud Functions 要求記錄的 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 服務。