疑難排解總覽

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

API 要求傳回 HTTP 403 錯誤

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

部署的 API 具有與角色相關聯的權限，這些角色是授予您建立 API 設定時所用服務帳戶的權限。通常發生 HTTP 403 錯誤的原因是服務帳戶沒有存取後端服務的必要權限。

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

API 要求傳回 HTTP 401 或 500 錯誤

如果已部署的 API 要求傳回 HTTP 401 或 500 錯誤給 API 用戶端，可能是因為您在建立 API 設定時使用的服務帳戶有問題，導致無法呼叫後端服務。

部署的 API 具有與授予服務帳戶的角色相關聯的權限，系統會檢查服務帳戶，確保該帳戶存在，且 API 部署時可供 API Gateway 使用。

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

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

  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 函式實作，請檢查相關聯 Cloud Functions 要求記錄的 Cloud Logging 項目。

無法查看記錄資訊

如果 API 回應正確，但記錄檔沒有資料，通常表示您尚未啟用 API Gateway 需要的所有 Google 服務。

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

名稱 標題
apigateway.googleapis.com API Gateway API
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

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

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

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