AWS CLI 中的重試 AWS CLI - AWS Command Line Interface
可用的重試模式設定重試模式檢視重試嘗試的記錄

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

AWS CLI 中的重試 AWS CLI

本主題說明 可能如何 AWS CLI 看到 因非預期問題而呼叫 AWS 服務失敗。這些問題可能會發生在伺服器端，也可能會因為您嘗試呼叫的 AWS 服務受到速率限制而失敗。這些種類的失敗通常不需要特殊處理，因為通常在短暫的等待時間後會自動再次進行呼叫。 AWS CLI 提供許多功能，可在遇到這類錯誤或例外狀況時，協助重試用戶端對 AWS 服務的呼叫。

可用的重試模式

AWS CLI 有多種模式可供選擇，取決於您的版本：

傳統重試模式

傳統模式使用較舊的重試處理常式，其有限的功能包含：

  • 預設值 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 重試處理常式使用的最大重試次數值，其中初始呼叫會計入您提供的值。預設值為 5。

在環境變數中定義重試組態

若要定義 的重試組態 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。