翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# で再試行動作を設定する AWS SDK for Java 2.x
への呼び出し AWS のサービス は、予期しない理由で失敗することがあります。呼び出しを再試行すると、スロットリング (レート超過) や一時的なエラーなどの特定のエラーが成功する可能性があります。 AWS SDK for Java 2.x には、このようなエラーを検出し、すべてのクライアントでデフォルトで有効になっている呼び出しを自動的に再試行するメカニズムが組み込まれています。
このページでは、その仕組み、個別のモード設定方法、再試行動作の調整方法について説明します。
## 再試行戦略
再試行戦略は、SDK で再試行を実装するために使用するメカニズムです。各 SDK クライアントにはビルド時に作成された再試行戦略があり、これはクライアントの構築後に変更できません。
再試行戦略には次の役割があります。
+ 例外を再試行可能または不可能として分類します。
+ 提案された遅延を計算して、次の試行まで待ちます。
+ 大量のリクエストが失敗し、再試行が失敗したときに再試行を停止するメカニズムを提供する[トークンバケット](https://en.wikipedia.org/wiki/Token_bucket)を保持します。
**注記**
SDK のバージョン 2.26.0 で再試行戦略**がリリースされる前は、再試行ポリシー**が SDK で再試行メカニズムを提供していました。再試行ポリシー** API は `software.amazon.awssdk.core.retry` パッケージのコア [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryPolicy.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryPolicy.html) クラスで構成されますが、 `[software.amazon.awssdk.retries](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/package-summary.html)` パッケージには再試行戦略** API 要素が含まれています。
再試行戦略 API は、SDK のコアコンポーネントのインターフェイスと動作を統合するための AWS全体的な取り組みの一環として導入されました。 SDKs
SDK for Java 2.x には、標準、レガシー、アダプティブの 3 つの再試行戦略が組み込まれています。3 つの再試行戦略はすべて、一連の再試行可能な例外に対して再試行するように事前設定されています。再試行可能なエラーの例としては、ソケットタイムアウト、サービス側のスロットリング、同時実行または楽観的ロックの失敗、一時的なサービスエラーなどがあります。
### 標準再試行戦略
[標準再試行戦略](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/StandardRetryStrategy.html)は、通常のユースケースで推奨される `RetryStrategy` 実装です。`AdaptiveRetryStrategy` とは異なり、標準戦略は一般的にすべての再試行ユースケースで役立ちます。
デフォルトでは、標準の再試行戦略は以下を実行します。
+ ビルド時に設定された条件で再試行します。これは `[StandardRetryStrategy.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/StandardRetryStrategy.Builder.html)#retryOnException` で調整できます。
+ 2 回再試行し、合計 3 回試行します。これは `StandardRetryStrategy.Builder#maxAttempts(int)` で調整できます。
+ スロットリング以外の例外の場合は、`[BackoffStrategy](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html)#exponentialDelay` バックオフ戦略を使用します。この場合の基本遅延は 100 ミリ秒、最大遅延は 20 秒です。これは `StandardRetryStrategy.Builder#backoffStrategy` で調整できます。
+ スロットリング例外の場合は、`BackoffStrategy#exponentialDelay` バックオフ戦略を使用します。この場合の基本遅延は 1 秒、最大遅延は 20 秒です。これは `StandardRetryStrategy.Builder#throttlingBackoffStrategy` で調整できます。
+ ダウンストリームで障害が多発している場合に、回路遮断（リトライの無効化）を実行します。最初の試行は常に実行され、再試行のみが無効になります。`StandardRetryStrategy.Builder#circuitBreakerEnabled` で調整します。
### レガシー再試行戦略
[レガシー再試行戦略](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/LegacyRetryStrategy.html)は通常のユースケースの `RetryStrategy` ですが、`StandardRetryStrategy` がより優先されるため、非推奨です。これは、別の戦略を指定しない場合にクライアントが使用するデフォルトの再試行戦略です。
スロットリング例外とスロットリング以外の例外を異なる方法で扱うことが特徴です。スロットリング例外の場合、バックオフの基本遅延はスロットリング以外の例外の基本遅延 (100 ミリ秒) よりも大きくなり (500 ミリ秒）、スロットリング例外はトークンバケットの状態に影響を与えません。
この戦略を内部で大規模に使用した経験 AWS から、 は標準の再試行戦略よりも特に優れていないことがわかりました。さらに、ダウンストリームサービスを再試行ストームから保護できず、クライアント側でリソースが枯渇する可能性があります。
デフォルトでは、レガシー再試行戦略は以下を実行します。
+ ビルド時に設定された条件で再試行します。これは `[LegacyRetryStrategy.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/LegacyRetryStrategy.Builder.html)#retryOnException` で調整できます。
+ 3 回再試行し、合計 4 回試行します。これは `LegacyRetryStrategy.Builder#maxAttempts(int)` で調整できます。
+ スロットリング以外の例外の場合は、`BackoffStrategy#exponentialDelay` バックオフ戦略を使用します。この場合の基本遅延は 100 ミリ秒、最大遅延は 20 秒です。これは `LegacyRetryStrategy.Builder#backoffStrategy.` で調整できます。
+ スロットリング例外の場合は、`BackoffStrategy#exponentialDelay` バックオフ戦略を使用します。この場合の基本遅延は 500 ミリ秒、最大遅延は 20 秒です。これは `LegacyRetryStrategy.Builder#throttlingBackoffStrategy` で調整できます。
+ ダウンストリームで障害が多発している場合に、回路遮断（リトライの無効化）を実行します。回路遮断が、最初の試行が成功することを妨げることはありません。この動作は `LegacyRetryStrategy.Builder#circuitBreakerEnabled` で調整できます。
+ サーキットブレーカーの状態は、スロットリング例外の影響を受けません。
### アダプティブ再試行戦略
[アダプティブ再試行戦略](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/AdaptiveRetryStrategy.html)は、リソースの制約が高いユースケース向けの `RetryStrategy` です。
アダプティブ再試行戦略には標準戦略のすべての機能が含まれており、スロットリングされていないリクエストとスロットリングされたリクエストの比率を測定するクライアント側のレートリミッターが追加されています。この戦略は、この計測値を使用してリクエストを減速させて安全な帯域幅内に収まるようにし、理想的にはスロットリングエラーをゼロに抑えます。
デフォルトでは、アダプティブ再試行戦略は以下を実行します。
+ ビルド時に設定された条件で再試行します。これは `[AdaptiveRetryStrategy.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/AdaptiveRetryStrategy.Builder.html)#retryOnException` で調整できます。
+ 2 回再試行し、合計 3 回試行します。これは `AdaptiveRetryStrategy.Builder#maxAttempts(int)` で調整できます。
+ ダウンストリームのリソースに対する現在の負荷に基づく動的なバックオフ遅延を使用します。
+ ダウンストリーム障害の数が多い場合に、回路破壊 (再試行の無効化) を実行します。回路遮断は、ダウンストリームのサービスを保護するために、障害シナリオで 2 回目の試行を妨げる場合があります。
**警告**
アダプティブ再試行戦略では、クライアントが単一のリソース (1 つの DynamoDB テーブルまたは 1 つの Amazon S3 バケットなど) に対して動作することを前提としています。
1 つのクライアントを複数のリソースに使用すると、1 つのリソースに関連するスロットリングまたは停止により、クライアントが他のすべてのリソースにアクセスするときにレイテンシーが増加し、失敗します。アダプティブ再試行戦略を使用する場合は、リソースごとに 1 つのクライアントを使用することをお勧めします。
また、すべてのクライアントがリソースに対してアダプティブ再試行戦略を使用する状況でも、この戦略を使用することをお勧めします。
**重要**
Java SDK の 2.26.0 での再試行戦略のリリースには、新しい [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryMode.html#ADAPTIVE_V2](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryMode.html#ADAPTIVE_V2) 列挙値が含まれています。`ADAPTIVE_V2` モードは、スロットリングエラーが以前に検出されたときに最初の試行を遅延できなかったエラーを修正します。
2.26.0 リリースでは、ユーザーは環境変数、システムプロパティ、またはプロファイル設定を使用してモードを `adaptive` として設定することで、`ADAPTIVE_V2` モードの動作を自動的に利用できます。これらの設定には `adaptive_v2` 値はありません。モードの設定方法については、次の [戦略を指定する](#retry-strategies-specify) セクションを参照してください。
ユーザーは、`RetryMode.ADAPTIVE` を使用してコードでモードを設定することで、前述の動作を取得できます。
### 概要: 再試行戦略のデフォルト値の比較
次の表は、各再試行戦略のプロパティのデフォルト値を示しています。
| 方針 | 最大試行回数 | スロットリング以外のエラーの基本遅延 | スロットリングエラーの基本遅延 | トークンバケットサイズ | スロットリング以外の再試行あたりのトークンコスト | スロットリングの再試行あたりのトークンコスト |
| --- | --- | --- | --- | --- | --- | --- |
| 標準 | 3 | 100 ミリ秒 | 1000 ミリ秒 | 500 | 5 | 5 |
| Legacy | 4 | 100 ミリ秒 | 500 ミリ秒 | 500 | 5 | 0 |
| アダプティブ | 3 | 100 ミリ秒 | 100 ミリ秒 | 500 | 5 | 5 |
**注記**
DynamoDB クライアントは、すべての再試行戦略にデフォルトの最大再試行回数 8 を使用します。これは、他の AWS のサービス クライアントの上記の表に示す値よりも高くなります。
## 戦略を指定する
サービスクライアントの戦略を指定する方法は 4 つあります。
### コード内
クライアントを構築するときに、再試行戦略を使用して Lambda 式を設定できます。次のスニペットは、DynamoDB サービスクライアントでデフォルト値を使用する標準再試行戦略を設定します。
```
DynamoDbClient client = DynamoDbClient.builder()
.overrideConfiguration(o -> o.retryStrategy(RetryMode.STANDARD))
.build();
```
`RetryMode.STANDARD` の代わりに `RetryMode.ADAPTIVE` または `RetryMode.LEGACY` を指定できます。
### プロファイル設定として
共有設定ファイルにプロファイル設定`retry_mode`として を含めます。 [AWS](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)`standard`、`legacy`、または `adaptive` を値として指定します。プロファイル設定として設定すると、プロファイルがアクティブの間に作成されたすべてのサービスクライアントは、指定された再試行戦略をデフォルト値で使用します。この設定は、前述のようにコードで再試行戦略を設定することで上書きできます。
次のプロファイルでは、すべてのサービスクライアントが標準の再試行戦略を使用します。
```
[profile dev]
region = us-east-2
retry_mode = standard
```
### JVM システムプロパティとして
コードで上書きされない限り、システムプロパティ `aws.retryMode` を使用してすべてのサービスクライアントに再試行ステートを設定できます。`standard`、`legacy`、または `adaptive` を値として指定します。
次のコマンドに示すように、Java を呼び出すときに `-D` スイッチを使用します。
```
java -Daws.retryMode=standard ...
```
または、次のスニペットに示すように、クライアントを作成する*前に*コードでシステムプロパティを設定します。
```
public void main(String[] args) {
// Set the property BEFORE any AWS service clients are created.
System.setProperty("aws.retryMode", "standard");
...
}
```
### 環境変数の使用
`AWS_RETRY_MODE` 環境変数は、`standard`、`legacy`、または `adaptive` の値でも使用できます。プロファイル設定または JVM システムプロパティと同様に、 コードでクライアントを設定しない限り、環境変数はすべてのサービスクライアントを指定された再試行モードで設定します。
次のコマンドは、現在のシェルセッションの再試行モードを `standard` に設定します。
```
export AWS_RETRY_MODE=standard
```
## 戦略をカスタマイズする
最大試行回数、バックオフ戦略、再試行可能な例外を設定することで、再試行戦略をカスタマイズできます。再試行戦略を構築するとき、または設定された戦略をさらに改良するための上書きビルダーを使用してクライアントを構築するときにカスタマイズできます。
### 最大試行回数をカスタマイズする
次のステートメントに示すように、クライアント構築中に最大試行回数を設定できます。次のステートメントは、クライアントのデフォルトの再試行戦略を最大 5 回の試行にカスタマイズします (最初の試行と 4 回の再試行)。
```
DynamoDbClient client = DynamoDbClient.builder()
.overrideConfiguration(o -> o.retryStrategy(b -> b.maxAttempts(5)))
.build();
```
または、次のコード例が示すように、戦略を構築し、クライアントに提供することもできます。次のコードは、標準の最大試行回数 3 回を 10 回に置き換え、カスタマイズされた戦略で DynamoDB クライアントを設定します。
```
StandardRetryStrategy strategy = AwsRetryStrategy.standardRetryStrategy()
.toBuilder()
.maxAttempts(10)
.build();
DynamoDbClient client = DynamoDbClient.builder()
.overrideConfiguration(o -> o.retryStrategy(strategy))
.build();
```
**警告**
各クライアントに一意の `RetryStrategy` インスタンスを設定することをお勧めします。`RetryStrategy` インスタンスが共有されている場合、一方のクライアントで障害が発生すると、他のクライアントの再試行動作に影響する可能性があります。
コードの代わりに[外部設定](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html)を使用して、すべてのクライアントの最大試行回数を設定することもできます。この設定は、「[戦略を指定する](#retry-strategies-specify)」セクションの説明に従って設定します。
### 再試行可能な例外のカスタマイズ
クライアントの構築中に、再試行をトリガーする追加の例外を設定できます。このカスタマイズは、再試行可能な例外のデフォルトセットに含まれていない例外がスローされるエッジケースに向けて使用できます。
`retryOnException` メソッドと `retryOnExceptionOrCause` メソッドは、既存の再試行可能な例外セットに新しい例外タイプを**追加します**。デフォルトのセットを置き換えるわけではありません。これにより、SDK のデフォルトの再試行機能を維持しながら、再試行動作を拡張できます。
`retryOnExceptionOrCause` メソッドは、SDK が直接例外をスローした場合、または例外が別の例外の原因としてラッピングされた場合に、再試行可能な例外を追加します。
次のコードスニペットは、再試行例外のカスタマイズに使用するメソッド `retryOnException` および `retryOnExceptionOrCause` を示しています。SDK が直接例外をスローした場合、または例外がラッピングされた場合、`retryOnExceptionOrCause` メソッドは再試行可能な例外を追加します。
```
DynamoDbClient client = DynamoDbClient.builder()
.overrideConfiguration(o -> o.retryStrategy(
b -> b.retryOnException(EdgeCaseException.class)
.retryOnExceptionOrCause(WrappedEdgeCaseException.class)))
.build();
```
**重要**
再試行戦略の設定に関係なく、[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kinesis/KinesisAsyncClient.html#subscribeToShard(software.amazon.awssdk.services.kinesis.model.SubscribeToShardRequest,software.amazon.awssdk.services.kinesis.model.SubscribeToShardResponseHandler)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kinesis/KinesisAsyncClient.html#subscribeToShard(software.amazon.awssdk.services.kinesis.model.SubscribeToShardRequest,software.amazon.awssdk.services.kinesis.model.SubscribeToShardResponseHandler)) メソッドを呼び出すと、Kinesis 非同期クライアントの再試行は無効になります。
### バックオフ戦略をカスタマイズする
バックオフ戦略を構築し、クライアントに提供できます。
次のコードは、デフォルトの標準戦略の指数関数的な遅延バックオフ戦略を置き換える `BackoffStrategy` を構築します。
```
BackoffStrategy backoffStrategy =
BackoffStrategy.exponentialDelay(Duration.ofMillis(150), // The base delay.
Duration.ofSeconds(15)); // The maximum delay.
DynamoDbClient client = DynamoDbClient.builder()
.overrideConfiguration(o -> o.retryStrategy(
b -> b.backoffStrategy(backoffStrategy)))
.build();
```
## `RetryPolicy` から `RetryStrategy` への移行
`RetryPolicy` (再試行ポリシー API) は、近日サポート予定です。現在 `RetryPolicy` のインスタンスを使用してクライアントを設定している場合、すべてが以前と同じように機能します。バックグラウンドで、Java SDK はそれを `RetryStrategy` に適応させます。新しい再試行戦略インターフェイスは、`RetryPolicy` と同じ機能を提供しますが、作成と設定の方法は異なります。