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

このページでは、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 リクエストが HTTP 403 エラーを返す

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

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

API とバックエンドサービスを同じ Google Cloud プロジェクトで定義した場合は、サービスアカウントに Editor のロールまたはバックエンドサービスへのアクセスに必要なロールが割り当てられていることを確認します。たとえば、Cloud 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 Functions と同様に、API ゲートウェイは「コールドスタート」レイテンシの影響を受けます。ゲートウェイが 15～20 分間トラフィックを受信していない場合は、コールドスタートの最初の 10～15 秒以内にゲートウェイに対して行われたリクエストでは 3～5 秒のレイテンシが発生します。

最初の「ウォームアップ」期間後も問題が解決しない場合は、API 構成で構成したバックエンドサービスのリクエストログを確認します。たとえば、バックエンドサービスが Cloud Functions を使用して実装されている場合は、関連する 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 サービスをご覧ください。