**本文件 AWS CLI 僅適用於 第 1 版。**

我們已宣布即將end-of-support。 AWS CLI 我們建議您遷移至 第 2 AWS CLI 版。如需日期、其他詳細資訊和如何遷移的資訊，請參閱 [公告](https://aws.amazon.com/blogs/developer/cli-v1-maintenance-mode-announcement/)。如需 第 2 版的相關文件 AWS CLI，請參閱 第 [2 版使用者指南](https://docs.aws.amazon.com/cli/latest/userguide/)。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# AWS CLI 中的重試次數 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 SDKs，具有比舊版更多的功能，預設模式是 的預設模式 AWS CLI。標準模式是針對第 2 AWS CLI 版建立的，並回溯到第 1 AWS CLI 版。標準模式的功能包含：
+ 預設值 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。
+ 任何重試嘗試都會包含基本係數為 2 的指數退避，且退避時間最長為 20 秒。

### 舊式重試模式 (預設)
<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`
+ 數個 HTTP 狀態碼 (包括 429、500、502、503、504 及 509) 上的重試嘗試次數。
+ 任何重試嘗試都會包含基本係數為 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 使用的重試模式。如前所述，有三種可用的重試模式：傳統、標準及自適應。AWS CLI 第 1 版的預設值為 Legacyversion值。
+ 最大嘗試次數 - 指定 AWS CLI 重試處理常式使用的最大重試次數值，其中初始呼叫會計入您提供的值。預設值取決於您的重試模式。

### 在環境變數中定義重試組態
<a name="cli-usage-retries-configure-envvar"></a>

若要定義 的重試組態 AWS CLI，請更新作業系統的環境變數。

重試環境變數是：
+ `AWS_RETRY_MODE`
+ `AWS_MAX_ATTEMPTS`

如需環境變數的詳細資訊，請參閱 [設定 的環境變數 AWS CLI](cli-configure-envvars.md)。

## 檢視重試嘗試的記錄
<a name="cli-usage-retries-validate"></a>

 AWS CLI 使用 Boto3 的重試方法和記錄。您可以針對任何命令，使用 `--debug` 選項來接收偵錯記錄。如需如何使用 `--debug` 選項的相關資訊，請參閱 [中的命令列選項 AWS CLI](cli-configure-options.md)。

如果您在偵錯記錄中搜尋「retry」，就能找到所需的重試資訊。重試嘗試的用戶端記錄項目視您已啟用的重試模式而定。

**傳統模式：**

 重試訊息會由 botocore.retryhandler 產生。您會看到以下三條訊息中的某一條：
+ `No retry needed`
+ `Retry needed, action of: <action_name>`
+ `Reached the maximum number of retry attempts: <attempt_number>`

**標準或自適應模式：**

 重試訊息會由 botocore.retries.standard 產生。您會看到以下三條訊息中的某一條：
+ `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)。