**このドキュメントはバージョン 1 の AWS CLI のみを対象としています。**

AWS CLI バージョン 1 のサポート終了を発表しました。AWS CLI バージョン 2 に移行することをお勧めします。日付、その他の詳細、移行方法については、「[お知らせ](https://aws.amazon.com/blogs/developer/cli-v1-maintenance-mode-announcement/)」を参照してください。AWS CLI のバージョン 2 に関連するドキュメントについては、[バージョン 2 用ユーザーガイド](https://docs.aws.amazon.com/cli/latest/userguide/)を参照してください。

# AWS CLI retries in the AWS CLI
<a name="cli-configure-retries"></a>

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

**Topics**
+ [使用可能な再試行モード](#cli-usage-retries-modes)
+ [再試行モードの設定](#cli-usage-retries-configure)
+ [再試行ログの表示](#cli-usage-retries-validate)

## 使用可能な再試行モード
<a name="cli-usage-retries-modes"></a>

**Topics**
+ [標準再試行モード](#cli-usage-retries-modes-standard.title)
+ [レガシー再試行モード (デフォルト)](#cli-usage-retries-legacy)
+ [アダプティブ再試行モード](#cli-usage-retries-modes-adaptive)

### 標準再試行モード
<a name="cli-usage-retries-modes-standard.title"></a>

`Standard` モードは、レガシーよりも多くの機能を備えた AWS SDK 全体の再試行ルールの標準セットであり、AWS CLI のデフォルトです。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 によるエクスポネンシャルバックオフが含まれます。

### レガシー再試行モード (デフォルト)
<a name="cli-usage-retries-legacy"></a>

`Legacy` モードでは、以下を含む、機能が制限された古い再試行ハンドラーが使用されます。
+ 最大再試行回数のデフォルト値は 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 によるエクスポネンシャルバックオフが含まれます。

### アダプティブ再試行モード
<a name="cli-usage-retries-modes-adaptive"></a>

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

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

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

## 再試行モードの設定
<a name="cli-usage-retries-configure"></a>

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

### 使用可能な設定方法
<a name="cli-usage-retries-configure-options"></a>

AWS CLI では、次の方法で再試行を設定できます。
+ 環境変数
+ AWS CLI 設定ファイル

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

### 環境変数での再試行設定の定義
<a name="cli-usage-retries-configure-envvar"></a>

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

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

環境変数の詳細については、「[Configuring environment variables for the AWS CLI](cli-configure-envvars.md)」を参照してください。

## 再試行ログの表示
<a name="cli-usage-retries-validate"></a>

AWS CLI は、Boto3 の再試行方法とログ記録を使用します。任意のコマンドで `--debug` オプションを使用して、デバッグログを受け取ることができます。`--debug`オプションの使用方法の詳細については、「[Command line options in the AWS CLI](cli-configure-options.md)」を参照してください。

デバッグログで「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 リポジトリ*の [\$1retry.json](https://github.com/boto/botocore/blob/develop/botocore/data/_retry.json) を参照してください。