API ゲートウェイのログを使用して API の問題をトラブルシューティングする方法を教えてください。

所要時間3分

Amazon API ゲートウェイのログを使用して API の問題をトラブルシューティングしたいと考えています。

概要

API Gateway REST API または WebSocket API のトラブルシューティングを行うには、Amazon CloudWatch Logs を使用して実行ログ記録を有効にし、ログにアクセスします。API Gateway AWS Identity and Access Management (IAM) ロールに、必要なすべてのアクセス許可がアタッチされていることを確認してください。手順については「API Gateway REST API または WebSocket API のトラブルシューティング用に、CloudWatch Logs を有効にする方法を教えてください」を参照してください。

注: HTTP API は、アクセスログ記録のみをサポートします。これらの API のログ記録を設定する方法の詳細については、「API Gateway で HTTP API のログ記録を設定する」を参照してください。

解決策

ログ記録を有効にすると、API Gateway は API-Gateway-Execution-logs/{REST-API-ID}/{stage-name} という名前の CloudWatch ロググループを自動的に作成します。このグループを使用して、問題をさらにトラブルシューティングしてください。詳細については、「API Gateway での CloudWatch によるログの形式」を参照してください。

認証エラーをチェック

API で AWS Lambda オーソライザーを有効にすると、ログにはリクエストが承認されたかどうかが示され、オーソライザーとリクエスト ID が含まれます。

認証済みログの例:

Starting authorizer: 62mgrc for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0
Successfully completed authorizer execution

不正ログの例:

Starting authorizer: 62mgrc for request: fd443056-60d0-425f-874e-e93e5d61351e  
Unauthorized request: fd443056-60d0-425f-874e-e93e5d61351e

詳細については、「Lambda オーソライザーの作成後、API Gateway が "401 Unauthorized" エラーを返す原因を教えてください」を参照してください。

使用量プランの設定を更新する

Lambda オーソライザーがログを記録した後、API Gateway は API リクエストの使用量プランを確認します。使用量プランを設定していない場合、API リクエストはスロットリング制限にカウントされません。

使用プランログの例:

Verifying Usage Plan for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0. API Key: API Stage: <api_id>/<stage>
API Key authorized because method 'GET /' does not require API Key. Request will not contribute to throttle or quota limits
Usage Plan check succeeded for API Key and API Stage <api_id>/<stage>

API キーを使用して API を設定したときに X-API-Key ヘッダーがない場合、ログには次のメッセージのようなエラーが返されます。

"API Key not authorized because method 'GET /' requires API Key and API Key is not associated with a Usage Plan for API Stage <api_id>/<stage>: API Key was required but not present"

この問題を解決するには、API 設定を確認してください。API キーを必要な使用量プランに関連付け、そのキーを正しい値の X-API-KEY ヘッダーとしてリクエストに含める必要があります。

ヘッダーに正しい API キーを追加し、API Gateway がリクエストを抑制すると、ログは次のメッセージのようなエラーを返します。

"API Key **FGQes7 exceeded throttle limit for API Stage <api_id>/<stage>: Key throttle limit exceeded for Usage Plan ID iwuzkt.Limit: 5.00 Burst: 0
Method completed with status: 429"

この問題を解決するには、「API Gateway での "429 Too Many Requests" または "Limited Exceeded" エラーを解決する方法を教えてください」の手順を実行してください。

リクエストログタイプ

データトレースとエラーログと情報ログを有効にすると、API Gateway ログにはトラブルシューティングに役立つ詳細が含まれます。API Gateway リクエストが失敗した場所を確認するには、以下のログタイプで詳細を確認してください。

注: リクエストログの場合は、CloudWatch Logs ドロップダウンメニューから [エラーと情報ログ] を選択する必要があります。次に、実行ログの [データトレース] を有効にします。データトレースにより、機密データがログに記録される可能性があるため、本番用 API では [データトレース] を有効にしないことをお勧めします。

メソッドリクエストログ

メソッドリクエストログには、リクエストパス、クエリパラメータ、リクエストヘッダー、リクエスト本文など、API リクエストが受け取る詳細情報が含まれます。

メソッドリクエストログの例:

(####) Method request path: {...}
(####) Method request query string: {...}
(####) Method request headers: {User-Agent=...}
(####) Method request body before transformations: ...

エンドポイントリクエストログ

エンドポイントリクエストログには、URI、リクエストヘッダー、リクエスト本文など、API リクエストが受け取る詳細情報が含まれます。

エンドポイントリクエストログの例:

(####) Endpoint request URI: ...
(####) Endpoint request headers: {...}
(####) Endpoint request body after transformations: {...}

エンドポイントリクエストに含まれるデータは、さらなる処理のためにバックエンドインテグレーションに送信されます。

エンドポイントレスポンスログ

エンドポイントレスポンスログには、ステータスコード、ヘッダー、本文、インテグレーションレイテンシーなど、バックエンドインテグレーションが返すデータが含まれます。

エンドポイント応答ログの例:

(####) Received response. Status: YYY, Integration latency: ZZZ ms
(####) Endpoint response headers: {...}
(####) Endpoint response body before transformations: {...}

**メソッドレスポンスログ **

メソッドレスポンスログには、変換後にクライアントに送信されるヘッダーと本文が含まれます。

メソッドレスポンスログの例:

(####) Method response body after transformations: ...
(####) Method response headers: {...}

重要: API Gateway は、ログイベントを 1024 バイトに制限します。API Gateway は、ログが CloudWatch Logs に送信される前に、リクエスト本文やレスポンス本文などの 1024 バイトを超えるログイベントを切り捨てます。

API ゲートウェイのログを使用して API の問題をトラブルシューティングする方法を教えてください。

概要

解決策

認証エラーをチェック

使用量プランの設定を更新する

リクエストログタイプ

関連情報

関連するコンテンツ