API Gateway での HTTP 呼び出しに関する問題のトラブルシューティング方法を教えてください。

所要時間3分

Amazon API Gateway での呼び出しに関するエラーをトラブルシューティングしたいです。

解決策

リソースと操作のリクエストの記録用に設定した REST API での 5xx エラーをトラブルシューティングするには、AWSSupport-TroubleshootAPIGatewayHttpErrors ランブックを使用します。

5xx エラーは、手動でトラブルシューティングすることもできます。

注: AWS コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、「AWS CLI で発生したエラーのトラブルシューティング」を参照してください。また、AWS CLI の最新バージョンを使用していることを確認してください。

自動ランブックを使用してエラーをトラブルシューティングする

AWSSupport-TroubleshootAPIGatewayHttpErrors ランブックは、Amazon CloudWatch Logs を分析する前に、API、リソース、操作、ステージを検証します。

必要なアクセス許可を付与する

ランブックを実行する前に、AWS Identity and Access Management (IAM) ユーザーまたはロールに正しいアクセス許可があることを確認してください。IAM ユーザーまたはロールに、ランブックへのアクセス許可があることを確認します。

自動化を実行する IAM ユーザーまたは引き受けたサービスロールには、次のアクセス許可も必要です。

apigateway:GET
logs:GetQueryResults
logs:StartQuery
ssm:DescribeAutomationExecutions
ssm:GetAutomationExecution
ssm:DescribeAutomationStepExecutions
ssm:StartAutomationExecution
ssm:DescribeDocument
ssm:GetDocument
ssm:ListDocuments

オートメーションを実行する

次の手順を実行します。

AWSSupport-TroubleshootAPIGatewayHttpErrors ランブックを開きます。
[オートメーションの実行] を選択します。
入力パラメーターに次の情報を入力します。
RestApiId: トラブルシューティングする API の API ID。
StageName: デプロイしたステージ名。
ResourcePath: 操作のリソースパス。
HttpMethod: 設定したリソースパスのメソッド。
StartTime: CloudWatch ログのクエリを開始する日付と時刻。形式は yyyy-MM-ddTHH:mm:ss であり、タイムゾーンは UTC である必要があります。
EndTime: CloudWatch ログのクエリを停止する日付と時刻。形式は yyyy-MM-ddTHH:mm:ss であり、タイムゾーンは UTC である必要があります。
AccessLogs: Runbook で分析する対象のアクセスログ。
ExecutionId: エラーが発生したリクエストの実行ID。
AutomationAssumeRole: Automation がユーザーに代わってアクションを実行できるようにする IAM ロールの ARN。ロールを指定しない場合、Automation はランブックを起動したユーザーのアクセス許可を使用します。
StageName: デプロイしたステージ名。
[実行] を選択します。
[出力] セクションで詳細な結果を確認できます。
注: Runbook がログを見つけられなかった場合も、自動化は正常に完了します。

5xx ステータスコードエラーの手動トラブルシューティング

注: 次の解決策は REST API にのみ適用されます。

始める前に、API Gateway のエラーをトラブルシューティングするために Amazon CloudWatch Logs を有効化します。実行ログ内の 5xx エラーを見つける方法については、「CloudWatch ログ内の API Gateway REST API エラーを見つける方法を教えてください」を参照してください。 API Gateway の 5XXError メトリクスは、指定した期間におけるサーバー側のエラーの数をキャプチャします。

Lambda 関数コードにおけるエラー

AWS Lambda との統合 API エンドポイントでの 500 エラーについては、「Amazon API Gateway と AWS Lambda におけるエラー処理パターン」を参照してください。

ステージ変数に対するアクセス許可が欠けている

ステージ変数を使用して API Gateway を設定し、Lambda 関数を呼び出す場合、Internal server エラーが発生する可能性があります。この問題を解決するには、「ステージ変数を使用して API Gateway で Lambda 統合を定義したところ、API メソッドの呼び出し時に Internal server エラーが発生し、500 ステータスコードが表示される理由を知りたいです」を参照してください。

HTTP ステータスコードのマッピングが正しくないか、欠けている

この問題を解決するには、API Gateway でモック統合を設定します。

スロットリングに関する問題

リクエスト数が多いことが原因でバックエンドサービスでスロットリングが発生した場合、API Gateway API が Internal server エラーを返す場合があります。この問題を解決するには、エクスポネンシャルバックオフと再試行メカニズムをアクティブにしてから、リクエストを再試行します。それでも問題が解決しない場合は、API Gateway のクォータを確認します。サービスクォータを超えている場合は、クォータの増加をリクエストできます。

POST の HTTP メソッドが定義されていない

Lambda 統合では、統合リクエストには POST の HTTP メソッドを使用する必要があります。次の AWS CLI コマンド put-integration を実行し、メソッド統合リクエストを更新します。

aws apigateway put-integration \
    --rest-api-id id \
   --resource-id id \
    --http-method ANY \
    --type AWS_PROXY \
    --integration-http-method POST \
    --uri arn:aws:apigateway:us-east-2:lambda:path//2015-03-31/functions/arn:aws:lambda:us-east-2:account_id:function:helloworld/invocations

注: 実際のものでそれぞれ、rest-api-id を REST API の ID に、resource-id をリソース ID に置き換え、URI 例を実際の URI に置き換えます。

次に、以下の AWS CLI コマンド create-deployment を実行し、REST API をデプロイします。

aws apigateway create-deployment \
    --rest-api-id id \
    --stage-name stage-resource

注: 実際のものでそれぞれ、rest-api-id を REST API の ID に、stage-resource を作成するデプロイリソース用のステージリソースに置き換えます。

Lambda のアクセス許可

Lambda 関数または Lambda オーソライザーのリソースベースのポリシーには、API が関数を呼び出すためのアクセス許可が必要です。

Lambda 関数が出力する JSON 形式の問題

統合された Lambda 関数からの出力が REST API で指定された JSON 形式に準拠していない場合、エラーが発生します。プロキシ統合用の Lambda 関数と Lambda オーソライザーからの出力では、正しい JSON 形式を使用する必要があります。次の JSON 形式の例を参照してください。

プロキシ統合用の Lambda 関数の例

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": "..."
}

Lambda オーソライザーの例

{
   "principalId": "user",
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      { "Action": "execute-api:Invoke",
        "Effect": "Deny",
        "Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/dev/GET/"
      }
    ]
  }
}

バックエンドのペイロードサイズが 10 MB を超えている

バックエンドのペイロードサイズでは、HTTP API クォータの最大サイズは 10 MB です。このサイズは増やせないため、バックエンドのペイロードサイズが 10 MB のクォータを超えないようにしてください。

プライベートエンドポイント統合

プライベート API エンドポイントを使用している場合は、API Gateway のプライベート統合も設定する必要があります。

内部サービスの障害

AWS で内部サービスの問題が発生した場合、500 エラーが発生する場合があります。AWS または API Gateway サービス内の問題が解決するまで待ってから、エクスポネンシャルバックオフを使用してリクエストを再試行してください。

502 ステータスコードエラー: Bad gateway

API Gateway がゲートウェイまたはプロキシとして応答を処理できない場合、502 ステータスコード Bad gateway が発生します。この問題をトラブルシューティングするには、「Lambda プロキシ統合での、API Gateway REST API が返す HTTP 502 エラーを解決する方法を教えてください」を参照してください。

注: API Gateway は、バックエンドサービスからの応答を読み取る際、マッピングテンプレートを使用して統合応答セクションのフォーマットをマッピングします。詳細については、「API Gateway で統合レスポンスを設定する」を参照してください。

503 ステータスコードエラー: Service unavailable

503 ステータスコードエラーは、バックエンド統合を使用できず、API Gateway API が応答を受信できない場合に発生します。

このエラーは、次の原因で発生する場合があります。

バックエンドサーバーが容量を超えているため、新しいクライアントリクエストを処理できない。
バックエンドサーバーで一時的なメンテナンスが完了前である。

この問題を解決するには、バックエンドサーバーにリソースを追加し、クライアントでエクスポネンシャルバックオフと再試行のメカニズムを有効にします。その後、リクエストを再試行してください。

504 ステータスコードエラー: Endpoint request timed out

統合リクエストの所要時間が API Gateway REST API の最大統合タイムアウトパラメータよりも長い場合、API Gateway は HTTP 504 ステータスコードを返します。このエラーを解決するには、「API Gateway での API HTTP 504 タイムアウトエラーをトラブルシューティングする方法を教えてください」を参照してください。

API Gateway での HTTP 呼び出しに関する問題のトラブルシューティング方法を教えてください。

解決策

自動ランブックを使用してエラーをトラブルシューティングする

5xx ステータスコードエラーの手動トラブルシューティング

関連情報

関連するコンテンツ