トラブルシューティングの概要

このページでは、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 なのかバックエンドなのかはレスポンス自体からは明確でない場合があります。確認する方法は次のとおりです。

[ログエクスプローラ] ページに移動して、プロジェクトを選択します。

[ログエクスプローラ] に移動
次のログクエリを使用して、関連する Gateway リソースにフィルタします。
```
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" の場合、エラーレスポンスはバックエンドから発生しているため、バックエンドを直接トラブルシューティングする必要があります。値が 0 以外の場合は、エラーレスポンスは Gateway から送信されたものです。トラブルシューティングのヒントについては、このドキュメントの次のセクションをご覧ください。

API リクエストが HTTP 403 エラーを返す

デプロイされた API に対するリクエストで API クライアントに HTTP 403 エラーが返された場合は、リクエストされた URL が有効であっても、なんらかの理由でアクセスが禁止されています。

デプロイされた API には、API 構成の作成時に使用したサービスアカウントに付与されたロールに関連付けられた権限があります。通常、HTTP 403 エラーが発生する理由は、サービスアカウントにバックエンドサービスへのアクセスに必要な権限が付与されていないことです。

API とバックエンドサービスを同じ Google Cloud プロジェクトで定義した場合は、サービスアカウントに Editor ロールまたはバックエンドサービスへのアクセスに必要なロールが割り当てられていることを確認します。たとえば、バックエンドサービスが Cloud Run functions を使用して実装されている場合は、サービスアカウントに Cloud Function Invoker ロールが割り当てられていることを確認します。

API リクエストが HTTP `401` または `500` エラーを返す

デプロイされた API に対するリクエストで API クライアントに HTTP 401 または 500 エラーが返された場合は、バックエンドサービスを呼び出す API 構成を作成したときに使用されたサービスアカウントの使用に問題がある可能性があります。

デプロイされた API には、API 構成の作成時に使用したサービスアカウントに付与されたロールに関連付けられた権限があります。両方が存在し、API のデプロイ時に API ゲートウェイで使用できることを確認するために、サービスアカウントがチェックされます。

ゲートウェイのデプロイ後にサービスアカウントが削除または無効にされると、次の一連のイベントが発生する可能性があります。

サービスアカウントが削除または無効に設定されると直ちに、ゲートウェイログに 401 HTTP レスポンスが表示される場合があります。ログエントリの jsonPayload で response_code_details フィールドが "via_upstream" に設定されている場合は、サービスアカウントを削除または無効にしたことがエラーの原因であることを示しています。
API Gateway のログに対応するログエントリがないと、HTTP 500 エラーが表示されることもあります。サービスアカウントが削除または無効になった直後にゲートウェイへのリクエストがない場合、HTTP 401 レスポンスは表示されませんが、対応する API Gateway ログがない HTTP 500 エラーは、ゲートウェイのサービスアカウントがアクティブではなくなった可能性を示しています。

レイテンシの高い API リクエスト

Cloud Run や Cloud Run functions と同様に、API Gateway には「コールドスタート」レイテンシが発生します。ゲートウェイが 15 ～ 20 分間トラフィックを受信していない場合は、コールドスタートの最初の 10 ～ 15 秒以内にゲートウェイに対して行われたリクエストでは 3 ～ 5 秒のレイテンシが発生します。

最初の「ウォームアップ」期間が経過しても問題が解決しない場合は、API 構成で構成したバックエンドサービスのリクエストログを確認します。たとえば、バックエンドサービスが Cloud Run functions を使用して実装されている場合は、関連する Cloud Functions リクエストログの Cloud Logging エントリを確認します。

ログ情報を表示できない

API が正しく応答していても、ログにデータが含まれていない場合は、通常、API Gateway に必要なすべての Google サービスが有効になっていないことを意味します。

API Gateway では、次の Google サービスを有効にする必要があります。

Name	Title
`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 サービスをご覧ください。