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

で再試行する AWS SDK for Kotlin

を呼び出すと、予期しない例外が返される AWS のサービス ことがあります。呼び出しを再試行すると、スロットリングや一時的なエラーなど、特定のタイプのエラーが成功する可能性があります。

このページでは、 が自動的に再試行 AWS SDK for Kotlin を処理する方法と、アプリケーションの再試行動作をカスタマイズする方法について説明します。

再試行動作について

以下のセクションでは、SDK がリクエストを再試行するタイミングを決定する方法と、再試行可能と見なされる例外について説明します。

デフォルトの再試行設定

デフォルトでは、すべてのサービスクライアントは標準の再試行戦略で自動的に設定されます。デフォルト設定では、最大 3 回失敗する呼び出しを試行します (最初の試行と 2 回の再試行）。各呼び出し間の介入遅延は、再試行ストームを回避するために、エクスポネンシャルバックオフとランダムジッターで設定されます。この設定は、ほとんどのユースケースで機能しますが、高スループットシステムなどの状況では適さない場合があります。

SDK は、再試行可能なエラーに対してのみ再試行を試みます。再試行可能なエラーの例としては、ソケットタイムアウト、サービス側のスロットリング、同時実行またはオプティミスティックロックの失敗、一時的なサービスエラーなどがあります。欠落または無効なパラメータ、認証/セキュリティエラー、設定ミスの例外は再試行可能と見なされません。

最大試行回数、遅延とバックオフ、トークンバケットの設定を設定することで、標準の再試行戦略をカスタマイズできます。

どの例外を再試行できますか?

は、再試行可能な例外を決定する事前設定された再試行ポリシー AWS SDK for Kotlin を使用します。サービスクライアント設定には、再試行に適用されるポリシーを指定するretryPolicyプロパティがあります。カスタム値を指定しない場合、デフォルト値は AwsRetryPolicy です。

以下の例外は、 によって再試行可能であると判断されますAwsRetryPolicy。

エラーコードで再試行可能

sdkErrorMetadata.errorCode 以下の ServiceExceptionを持つ :

HTTP ステータスコードで再試行可能

sdkErrorMetadata.statusCode 以下の ServiceExceptionを持つ :

エラータイプで再試行可能

sdkErrorMetadata.errorType 以下の ServiceExceptionを持つ 。

SDK メタデータで再試行可能

以下のSdkBaseException場合:

各サービスクライアントによってスローされる可能性のある例外の完全なリストについては、サービス固有の API リファレンスドキュメントを参照してください。

例外が再試行可能かどうかを確認します。

SDK が例外を再試行可能と見なすかどうかを判断するには、キャッチされた例外の isRetryableプロパティを確認します。

try {
    dynamoDbClient.putItem {
        tableName = "MyTable"
        item = mapOf("id" to AttributeValue.S("123"))
    }
} catch (e: SdkBaseException) {
    println("Exception occurred: ${e.message}")
    
    if (e.sdkErrorMetadata.isRetryable) {
        println("This exception is retryable - SDK will automatically retry")
        println("If you're seeing this, retries may have been exhausted")
    } else {
        println("This exception is not retryable - fix the underlying issue")
        
        // Common non-retryable scenarios.
        when {
            e.message?.contains("ValidationException") == true -> 
                println("Check your request parameters")
            e.message?.contains("AccessDenied") == true -> 
                println("Check your IAM permissions")
            e.message?.contains("ResourceNotFound") == true -> 
                println("Verify the resource exists")
        }
    }
}

再試行が失敗した場合にコードに到達する例外

SDK の再試行メカニズムが問題を解決できない場合、例外はアプリケーションコードにスローされます。これらの例外タイプを理解することで、適切なエラー処理を実装できます。これらは再試行をトリガーする例外ではなく、 SDK によって内部的に処理されます。

再試行が枯渇または無効になると、コードは次のタイプの例外をキャッチします。

アプリケーションでこれらの例外を処理するには、次のパターンを使用します。

try {
    s3Client.getObject { 
        bucket = "amzn-s3-demo-bucket"
        key = "my-key" 
    }
} catch (e: AwsServiceException) {
    // Service-side errors that persisted through all retries.
    println("Service error after retries: ${e.errorDetails?.errorCode} - ${e.message}")
    
    // Handle specific service errors that couldn't be resolved.
    if (e.errorDetails?.errorCode == "ServiceQuotaExceededException" || 
        e.errorDetails?.errorCode == "ThrottlingException") {
        println("Rate limiting persisted - consider longer delays or quota increase")
    }
} catch (e: ClientException) {
    // Client-side errors (persistent network issues, DNS resolution failures, etc.)
    println("Client error after retries: ${e.message}")
}

再試行動作のカスタマイズ

以下のセクションでは、特定のユースケースに合わせて SDK の再試行動作をカスタマイズする方法を示します。

最大試行回数を設定する

クライアントの構築中に retryStrategyDSL ブロックのデフォルトの最大試行回数 (3) をカスタマイズできます。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        maxAttempts = 5
    }
}

前のスニペットで示した DynamoDB サービスクライアントでは、SDK は最大 5 回失敗する API コールを試行します (最初の試行と 4 回の再試行）。

次のスニペットに示すように、最大試行回数を 1 に設定することで、自動再試行を完全に無効にできます。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        maxAttempts = 1  // The SDK makes no retries.
    }
}

遅延とバックオフを設定する

再試行が必要な場合、デフォルトの再試行戦略は後続の試行を行う前に待機します。最初の再試行の遅延は小さいですが、後の再試行では指数関数的に増加します。最大遅延量は、大きくなりすぎないように制限されます。

最後に、すべての試行間の遅延にランダムジッターが適用されます。ジッターは、再試行ストームを引き起こす可能性のある大規模なフリートの影響を軽減するのに役立ちます。(エクスポネンシャルバックオフとジッターの詳細については、このAWS アーキテクチャブログの投稿を参照してください）。

遅延パラメータは delayProviderDSL ブロックで設定できます。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        delayProvider {
            initialDelay = 100.milliseconds
            maxBackoff = 5.seconds
        }
    }
}

前のスニペットに示されている設定では、クライアントは最初の再試行を最大 100 ミリ秒遅延します。再試行間の最大時間は 5 秒です。

遅延とバックオフの調整には、次のパラメータを使用できます。

再試行トークンバケットを設定する

デフォルトのトークンバケット設定を調整することで、標準の再試行戦略の動作をさらに変更できます。再試行トークンバケットは、成功する可能性が低い再試行や、タイムアウトやスロットリングの失敗など、解決に時間がかかる再試行を減らすのに役立ちます。

再試行するたびに (オプションで最初の試行を含む）、トークンバケットから一部の容量が減少します。減少する量は、試行のタイプによって異なります。例えば、一時的なエラーを再試行すると安くなりますが、タイムアウトまたはスロットリングエラーを再試行するとコストが高くなる可能性があります。

試行が成功すると、バケットに容量が返されます。バケットは最大容量を超えて増分したり、ゼロ未満に減らしたりすることはできません。

useCircuitBreakerMode 設定の値に応じて、 は容量をゼロ未満に減らそうとすると、次のいずれかの結果になります。

トークンバケットパラメータは tokenBucketDSL ブロックで設定できます。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        tokenBucket {
            maxCapacity = 100
            refillUnitsPerSecond = 2
        }
    }
}

再試行トークンバケットのチューニングには、次のパラメータを使用できます。

サーキットブレーカーの例外など、再試行シナリオ中にスローされる例外タイプの詳細については、「」を参照してください再試行が失敗した場合にコードに到達する例外。

アダプティブ再試行を設定する

標準の再試行戦略の代わりに、アダプティブ再試行戦略は、スロットリングエラーを最小限に抑えるための理想的なリクエストレートを求める高度なアプローチです。

アダプティブ再試行には、標準再試行のすべての機能が含まれています。これにより、スロットリングされていないリクエストと比較したスロットリングされたリクエストのレートを測定するクライアント側のレートリミッターが追加されます。また、トラフィックが安全な帯域幅内にとどまるように制限し、スロットリングエラーが発生するのが理想的です。

レートは、サービス条件やトラフィックパターンの変化にリアルタイムで適応し、それに応じてトラフィックのレートを増減する可能性があります。クリティカルなことに、レートリミッターはトラフィックの多いシナリオでの最初の試行を遅らせる可能性があります。

retryStrategy メソッドに追加のパラメータを指定して、アダプティブ再試行戦略を選択します。レートリミッターパラメータは rateLimiterDSL ブロックで設定できます。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy(AdaptiveRetryStrategy) {
        maxAttempts = 10
        rateLimiter {
            minFillRate = 1.0
            smoothing = 0.75
        }
    }
}