本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 中設定重試行為 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 作為 AWS整體工作的一部分推出，以統一 SDKs 核心元件的界面和行為。
適用於 Java 的 SDK 2.x 有三種內建重試策略：標準、傳統和適應性。所有三個重試策略都會預先設定為在一組可重試的例外狀況上重試。可重試錯誤的範例包括通訊端逾時、服務端調節、並行或樂觀鎖定失敗，以及暫時性服務錯誤。
### 標準重試策略
對於正常使用案例，建議`RetryStrategy`實作[標準重試策略](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/StandardRetryStrategy.html)。與 不同`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 毫秒），而限流例外狀況不會影響字符儲存貯體狀態。
內部大規模使用此策略的經驗 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)`。
+ 使用以下游資源目前負載為基礎的動態退避延遲。
+ 發生大量下游故障時，執行電路中斷 （停用重試）。電路中斷可能會阻止在中斷情況下的第二次嘗試來保護下游服務。
**警告**
自適應重試策略假設用戶端針對單一資源 （例如，一個 DynamoDB 資料表或一個 Amazon S3 儲存貯體） 運作。
如果您將單一用戶端用於多個資源，當用戶端存取所有其他資源時，與一個資源相關聯的限流或中斷會導致延遲增加和失敗。當您使用自適應重試策略時，我們建議您為每個資源使用單一用戶端。
我們也建議您在所有用戶端針對資源使用自適應重試策略的情況下使用此策略。
**重要**
Java 開發套件 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_V2`模式行為，方法是將 模式設定為`adaptive`使用環境變數、系統屬性或設定檔設定。這些設定沒有`adaptive_v2`值。如需如何設定 模式，請參閱下[指定策略](#retry-strategies-specify)一節。
使用者可以使用 在程式碼中設定 模式，以取得先前的行為`RetryMode.ADAPTIVE`。
### 摘要：重試策略預設值的比較
下表顯示每個重試策略屬性的預設值。
| 策略 | 最大嘗試次數 | 非調節錯誤的基本延遲 | 調節錯誤的基本延遲 | 權杖儲存貯體大小 | 每個非限流重試的字符成本 | 每次限流重試的字符成本 |
| --- | --- | --- | --- | --- | --- | --- |
| 標準 | 3 | 100 毫秒 | 1000 毫秒 | 500 | 5 | 5 |
| 傳統 | 4 | 100 毫秒 | 500 毫秒 | 500 | 5 | 0 |
| 自適應 | 3 | 100 毫秒 | 100 毫秒 | 500 | 5 | 5 |
**注意**
DynamoDB 用戶端對所有重試策略使用預設的重試計數上限 8，這高於其他 AWS 服務 用戶端上表所示的值。
## 指定策略
您可以透過四種方式為您的服務用戶端指定策略。
### 在程式碼中
建置用戶端時，您可以使用重試策略設定 lambda 表達式。下列程式碼片段會設定在 DynamoDB 服務用戶端上使用預設值的標準重試策略。
```
DynamoDbClient client = DynamoDbClient.builder()
.overrideConfiguration(o -> o.retryStrategy(RetryMode.STANDARD))
.build();
```
您可以指定 `RetryMode.LEGACY`或 `RetryMode.ADAPTIVE` 來取代 `RetryMode.STANDARD`。
### 作為設定檔設定
在[共用 AWS 組態檔案中](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)包含 `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");
...
}
```
### 使用環境變數
您也可以使用值為 `standard`、 `legacy`或 `AWS_RETRY_MODE`的環境變數`adaptive`。如同設定檔設定或 JVM 系統屬性，環境變數會將所有服務用戶端設定為指定的重試模式，除非您在程式碼中設定用戶端。
下列命令會將目前 shell 工作階段`standard`的重試模式設定為 。
```
export AWS_RETRY_MODE=standard
```
## 自訂策略
您可以透過設定可重試的最大嘗試次數、退避策略和例外狀況來自訂任何重試策略。您可以在建置重試策略或使用覆寫建置器來建立用戶端時自訂 ，以允許進一步精簡設定的策略。
### 自訂最大嘗試次數
您可以在用戶端建構期間設定最大嘗試次數，如下列陳述式所示。下列陳述式會將用戶端的預設重試策略自訂為最多 5 次嘗試 - 第一次嘗試加上 4 次重試。
```
DynamoDbClient client = DynamoDbClient.builder()
.overrideConfiguration(o -> o.retryStrategy(b -> b.maxAttempts(5)))
.build();
```
或者，您可以建置策略並將其提供給用戶端，如下列程式碼範例所示。下列程式碼以 10 取代標準最多 3 次嘗試，並使用自訂策略設定 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 的預設重試功能。
如果 SDK 擲回直接例外狀況，或如果例外狀況被包裝為另一個例外狀況中的原因，則 `retryOnExceptionOrCause`方法會新增可重試的例外狀況。
下列程式碼片段顯示您用來自訂重試例外狀況的方法 --`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 開發套件會適應 `RetryStrategy`。新的重試策略界面提供與 相同的功能，`RetryPolicy`但會以不同的方式建立和設定。