本頁面由 Cloud Translation API 翻譯而成。

疑難排解總覽

本頁面提供 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 \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

請確認您已為服務帳戶指派必要權限，如「設定開發環境」一文所述。

判斷 API 錯誤回應的來源

如果對已部署 API 的請求導致錯誤 (HTTP 狀態碼 400 到 599)，則回應本身可能無法清楚指出錯誤是來自 Gateway 還是後端。如要判斷是否有此問題，請按照下列步驟操作：

前往「Logs Explorer」頁面，然後選取專案。

前往「Logs Explorer」
使用下列記錄查詢，篩選出相關的閘道資源：
```
resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
resource.labels.location="GCP_REGION"
```
其中：
- GATEWAY_ID 會指定閘道的名稱。
- GCP_REGION 是部署閘道的 Google Cloud 地區。
找出與您要調查的 HTTP 錯誤回應相符的記錄項目。例如，依據 httpRequest.status 篩選。
檢查 jsonPayload.responseDetails 欄位的內容。

如果 jsonPayload.responseDetails 欄位的值為 "via_upstream"，則錯誤回應來自後端，您必須直接對後端進行疑難排解。如果是其他值，則錯誤回應來自 Gateway。請參閱本文件後續章節，瞭解進一步的疑難排解提示。

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 時供 API Gateway 使用。

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

服務帳戶刪除或停用後，您可能會在閘道記錄中看到 401 HTTP 回應。如果記錄項目的 jsonPayload 中 jsonPayload.responseDetails 欄位設為 "via_upstream"，表示刪除或停用服務帳戶是導致錯誤的原因。
您也可能會看到 HTTP 500 錯誤，但 API Gateway 的記錄中沒有任何對應的記錄項目。如果服務帳戶遭到刪除或停用後，沒有立即向閘道提出要求，您可能不會看到 HTTP 401 回應，但如果沒有對應的 API 閘道記錄，則表示閘道的服務帳戶可能已不再處於活動狀態。500

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

延遲時間長的 API 要求

與 Cloud Run 和 Cloud Run 函式一樣，API Gateway 也會有「冷啟動」延遲現象。如果網關在 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 list

如果必要的服務並未列出，請執行下列指令加以啟用：

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

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