翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS SDK for Java 2.x で再試行動作を設定する

AWS のサービス への呼び出しは、予期しない理由で失敗することがあります。呼び出しを再試行すると、スロットリング (レート超過) や一時的なエラーなどの特定のエラーが成功する可能性があります。AWS SDK for Java 2.x には、このようなエラーを検出し、すべてのクライアントでデフォルトで有効になっている呼び出しを自動的に再試行するメカニズムが組み込まれています。

このページでは、その仕組み、個別のモード設定方法、再試行動作の調整方法について説明します。

再試行戦略

再試行戦略は、SDK で再試行を実装するために使用するメカニズムです。各 SDK クライアントにはビルド時に作成された再試行戦略があり、これはクライアントの構築後に変更できません。

再試行戦略には次の役割があります。

SDK for Java 2.x には、標準、レガシー、アダプティブの 3 つの再試行戦略が組み込まれています。3 つの再試行戦略はすべて、一連の再試行可能な例外に対して再試行するように事前設定されています。再試行可能なエラーの例としては、ソケットタイムアウト、サービス側のスロットリング、同時実行または楽観的ロックの失敗、一時的なサービスエラーなどがあります。

標準再試行戦略

標準再試行戦略は、通常のユースケースで推奨される RetryStrategy 実装です。AdaptiveRetryStrategy とは異なり、標準戦略は一般的にすべての再試行ユースケースで役立ちます。

デフォルトでは、標準の再試行戦略は以下を実行します。

レガシー再試行戦略

レガシー再試行戦略は通常のユースケースの RetryStrategy ですが、StandardRetryStrategy がより優先されるため、非推奨です。これは、別の戦略を指定しない場合にクライアントが使用するデフォルトの再試行戦略です。

スロットリング例外とスロットリング以外の例外を異なる方法で扱うことが特徴です。スロットリング例外の場合、バックオフの基本遅延はスロットリング以外の例外の基本遅延 (100 ミリ秒) よりも大きくなり (500 ミリ秒）、スロットリング例外はトークンバケットの状態に影響を与えません。

この戦略を AWS の内部で大規模に使用した経験から、標準の再試行戦略よりも特に優れているわけではないことがわかりました。さらに、ダウンストリームサービスを再試行ストームから保護できず、クライアント側でリソースが枯渇する可能性があります。

デフォルトでは、レガシー再試行戦略は以下を実行します。

アダプティブ再試行戦略

アダプティブ再試行戦略は、リソースの制約が高いユースケース向けの RetryStrategy です。

アダプティブ再試行戦略には標準戦略のすべての機能が含まれており、スロットリングされていないリクエストとスロットリングされたリクエストの比率を測定するクライアント側のレートリミッターが追加されています。この戦略は、この計測値を使用してリクエストを減速させて安全な帯域幅内に収まるようにし、理想的にはスロットリングエラーをゼロに抑えます。

デフォルトでは、アダプティブ再試行戦略は以下を実行します。

概要: 再試行戦略のデフォルト値の比較

次の表は、各再試行戦略のプロパティのデフォルト値を示しています。

戦略を指定する

サービスクライアントの戦略を指定する方法は 4 つあります。

コードを使用する場合

クライアントを構築するときに、再試行戦略を使用して Lambda 式を設定できます。次のスニペットは、DynamoDB サービスクライアントでデフォルト値を使用する標準再試行戦略を設定します。

DynamoDbClient client = DynamoDbClient.builder()
        .overrideConfiguration(o -> o.retryStrategy(RetryMode.STANDARD))
        .build();

RetryMode.STANDARD の代わりに RetryMode.ADAPTIVE または RetryMode.LEGACY を指定できます。

プロファイル設定として

共有 AWS 設定ファイルにプロファイル設定として retry_mode を含めます。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();       

コードの代わりに外部設定を使用して、すべてのクライアントの最大試行回数を設定することもできます。この設定は、「戦略を指定する」セクションの説明に従って設定します。

再試行可能な例外のカスタマイズ

クライアントの構築中に、再試行をトリガーする追加の例外を設定できます。このカスタマイズは、再試行可能な例外のデフォルトセットに含まれていない例外がスローされるエッジケースに向けて使用できます。

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();

バックオフ戦略をカスタマイズする

バックオフ戦略を構築し、クライアントに提供できます。

次のコードは、デフォルトの標準戦略の指数関数的な遅延バックオフ戦略を置き換える 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 と同じ機能を提供しますが、作成と設定の方法は異なります。