疑難排解總覽

本頁提供 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 要求延遲時間過長

與 Cloud Run 和 Cloud Run 函式一樣，API 閘道也會有「冷啟動」延遲。如果閘道 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 服務。