AWS CLI での AWS CLI の再試行

このトピックでは、予期しない問題による AWS CLI のサービスへの呼び出し失敗を AWS がどのように判断するかについて説明します。これらの問題は、サーバー側で発生するか、呼び出しを実行しようとしている AWS のサービスからのレート制限が原因で発生する可能性があります。通常、これらの種類のエラーは特別な処理を必要とせず、多くの場合、短い待機期間の後に自動的に再度呼び出しが実行されます。AWS CLI には、このようなエラーまたは例外が発生した場合に、AWS のサービスへのクライアント呼び出しの再試行を支援する多くの機能があります。

トピック

使用可能な再試行モード
再試行モードの設定
再試行ログの表示

使用可能な再試行モード

レガシー再試行モード

レガシーモードでは、以下を含む、機能が制限された古い再試行ハンドラーが使用されます。

最大再試行回数のデフォルト値は 4 で、呼び出しの試行回数は合計 5 回です。この値は、max_attempts 設定パラメータを使用して上書きできます。
DynamoDB では、最大再試行回数のデフォルト値は 9 で、呼び出しの試行回数は合計 10 回です。この値は、max_attempts 設定パラメータを使用して上書きできます。
次の限られた数のエラー/例外を再試行します。
- 一般的なソケット/接続エラー:
  - ConnectionError
  - ConnectionClosedError
  - ReadTimeoutError
  - EndpointConnectionError
- サービス側のスロットリング/制限エラーと例外:
  - Throttling
  - ThrottlingException
  - ThrottledException
  - RequestThrottledException
  - ProvisionedThroughputExceededException
429、500、502、503、504、509 など、複数の HTTP ステータスコードで再試行します。
再試行には、基本係数 2 によるエクスポネンシャルバックオフが含まれます。

標準再試行モード

標準モードは、レガシーよりも多くの機能を備えた SDK 全体での再試行ルールの標準セットです。このモードは、AWS CLI バージョン 2 のデフォルトです。AWS CLI バージョン 2 には標準モードが作成されており、AWS CLI バージョン 1 にバックポートされます。標準モードの機能は次のとおりです。

最大再試行回数のデフォルト値は 2 で、合計で 3 回呼び出しが試みられます。この値は、max_attempts 設定パラメータを使用して上書きできます。
次の拡張されたエラー/例外リストを再試行します。
- 一時的なエラー/例外
  - RequestTimeout
  - RequestTimeoutException
  - PriorRequestNotComplete
  - ConnectionError
  - HTTPClientError
- サービス側のスロットリング/制限エラーと例外:
  - Throttling
  - ThrottlingException
  - ThrottledException
  - RequestThrottledException
  - TooManyRequestsException
  - ProvisionedThroughputExceededException
  - TransactionInProgressException
  - RequestLimitExceeded
  - BandwidthLimitExceeded
  - LimitExceededException
  - RequestThrottled
  - SlowDown
  - EC2ThrottledException

わかりにくい一時的なエラーコードに対して再試行します。具体的には、これらの HTTP ステータスコードは 500、502、503、504 です。
再試行には、最大バックオフ時間が 20 秒の場合、基本係数 2 によるエクスポネンシャルバックオフが含まれます。

アダプティブ再試行モード

警告

アダプティブモードは実験的なモードであり、機能と動作の両方について変更される可能性があります。

アダプティブ再試行モードは、標準モードのすべての機能を含む実験的な再試行モードです。アダプティブモードでは、標準モード機能に加えて、トークンバケットおよびレート制限変数の使用を通じて、クライアント側のレート制限も導入されます。これらの変数は、再試行するたびに動的に更新されます。このモードは、AWS のサービスからのエラー/例外状態のレスポンスに適応するクライアント側の再試行における柔軟性を提供します。

新しい再試行ごとに、アダプティブモードは、AWS のサービスからのレスポンスに表示されるエラー、例外、または HTTP ステータスコードに基づいて、レート制限変数を変更します。その後、クライアントの新しい呼び出しレートを計算するためにこれらのレート制限変数が使用されす。成功する、トークンバケットを使い果たす、または設定された最大試行値に達するまでは再試行が発生するため、AWS のサービスからの例外/エラーまたは成功以外の HTTP レスポンス (上記のリストを参照) がレート制限変数を更新します。

再試行モードの設定

AWS CLI には、クライアントオブジェクトの作成時に考慮する必要がある、さまざまな再試行設定と設定方法が用意されています。

使用可能な設定方法

AWS CLI では、次の方法で再試行を設定できます。

環境変数
AWS CLI 設定ファイル

次の再試行オプションをカスタマイズできます。

再試行モード - AWS CLI が使用する再試行モードを指定します。前述のように、レガシー、標準、アダプティブの 3 つの再試行モードを使用できます。、AWS CLI バージョン 2 のデフォルト値が標準です。
最大試行回数 - AWS CLI 再試行ハンドラーが使用する最大再試行回数を指定します。最初の呼び出しは、指定した値に対してカウントされます。デフォルト値は再試行モードに基づきます。

環境変数での再試行設定の定義

AWS CLI の再試行設定を定義するには、オペレーティングシステムの環境変数を更新します。

再試行環境変数は次のとおりです。

AWS_RETRY_MODE
AWS_MAX_ATTEMPTS

環境変数の詳細については、「AWS CLI の環境変数の設定」を参照してください。

AWS 設定ファイルでの再試行設定の定義

再試行設定を変更するには、グローバル AWS 設定ファイルを更新します。AWS 設定ファイルのデフォルトの場所は～/.aws/config です。

以下は AWS 設定ファイルの例です。


[default]
retry_mode = standard
max_attempts = 6

設定ファイルの詳細については、「AWS CLI での設定と認証情報ファイル設定」を参照してください。

再試行ログの表示

AWS CLI は、Boto3 の再試行方法とログ記録を使用します。任意のコマンドで --debug オプションを使用して、デバッグログを受け取ることができます。--debugオプションの使用方法の詳細については、「AWS CLI のコマンドラインオプション」を参照してください。

デバッグログで「retry」を検索すると、必要な再試行情報が表示されます。再試行のクライアントログエントリは、有効にした再試行モードによって異なります。

レガシーモード:

再試行メッセージは、botocore.retryhandler によって生成されます。次の 3 つのメッセージのいずれかが表示されます。

No retry needed
Retry needed, action of: <action_name>
Reached the maximum number of retry attempts: <attempt_number>

標準モードまたはアダプティブモード:

再試行メッセージは、botocore.retries.standard によって生成されます。次の 3 つのメッセージのいずれかが表示されます。

No retrying request
Retry needed, retrying request after delay of: <delay_value>
Retry needed but retry quota reached, not retrying request

botocore 再試行の完全な定義ファイルについては、botocore GitHub リポジトリの _retry.json を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

AWS CLI でコマンド補完を設定する

AWS CLI での HTTP プロキシの使用