本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
本主題說明 可能如何 AWS CLI 看到 AWS 服務呼叫因非預期問題而失敗。這些問題可能會發生在伺服器端，也可能會因為您嘗試呼叫的 AWS 服務受到速率限制而失敗。這些種類的失敗通常不需要特殊處理，因為通常在短暫的等待時間後會自動再次進行呼叫。 AWS CLI 提供許多功能，可協助用戶端在遇到這類錯誤或例外狀況時重試對 AWS 服務的呼叫。
可用的重試模式
傳統重試模式
傳統模式使用較舊的重試處理常式，其有限的功能包含：
-
預設值 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 的指數退避。
標準重試模式
標準模式是跨 AWS SDKs，其功能比舊版更多。此模式是 AWS CLI 第 2 版的預設模式。標準模式是針對第 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 秒。
自適應重試模式
警告
自適應模式是一種實驗模式，且功能及行為會隨時變更。
自適應重試模式是一種實驗性重試模式，其中包含標準模式的所有功能。除了標準模式功能之外，自適應模式還會透過使用字符儲存貯體和每次重試嘗試時會動態更新的速率限制變數，引進用戶端速率限制。此模式在用戶端重試中提供靈活性，以適應來自 AWS 服務的錯誤/例外狀態回應。
在每次新的重試嘗試時，適應性模式會根據 AWS 服務回應中呈現的錯誤、例外狀況或 HTTP 狀態碼來修改速率限制變數。之後，這些速率限制變數會用於計算用戶端的新呼叫速率。來自 AWS 服務的每個例外狀況/錯誤或非成功 HTTP 回應 (在上方清單中提供) 會在重試發生時更新速率限制變數，直到重試成功、字符儲存貯體用盡或達到設定嘗試數值的上限為止。
設定重試模式
AWS CLI 包含各種重試組態，以及建立用戶端物件時要考慮的組態方法。
可用組態方法
在 中 AWS CLI，使用者可以使用下列方式設定重試：
-
環境變數
-
AWS CLI 組態檔案
使用者可以自訂以下重試選項：
-
重試模式 - 指定 AWS CLI 使用的重試模式。如前所述，有三種可用的重試模式：傳統、標準及自適應。AWS CLI 2 是標準值。
-
最大嘗試次數 - 指定 AWS CLI 重試處理常式使用的最大重試次數值，其中初始呼叫會計入您提供的值。預設值取決於您的重試模式。
在環境變數中定義重試組態
若要定義 的重試組態 AWS CLI，請更新作業系統的環境變數。
重試環境變數是：
-
AWS_RETRY_MODE -
AWS_MAX_ATTEMPTS
如需環境變數的詳細資訊，請參閱 設定 的環境變數 AWS CLI。
在組態檔案中定義重試 AWS 組態
若要變更重試組態，請更新您的全域 AWS 組態檔案。 AWS 組態檔案的預設位置為 ~/.aws/config。
以下是 AWS 組態檔案的範例：
[default]
retry_mode = standard
max_attempts = 6如需有關組態檔案的詳細資訊，請參閱 中的組態和登入資料檔案設定 AWS CLI。
檢視重試嘗試的記錄
AWS CLI 使用 Boto3 的重試方法和記錄。您可以針對任何命令，使用 --debug 選項來接收偵錯記錄。如需如何使用 --debug 選項的相關資訊，請參閱 中的命令列選項 AWS CLI。
如果您在偵錯記錄中搜尋「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 儲存庫上的 _retry.json
