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

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

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 SDK 之間的一組標準重試規則，其功能比傳統模式更多。此模式是 AWS CLI 第 2 版的預設模式。標準模式轉為 AWS CLI 第 2 版建立，並可回溯到 AWS CLI 第 1 版。標準模式的功能包含：

  • 預設值 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 會使用 Boto3 的重試方法及記錄。您可以針對任何命令，使用 --debug 選項來接收偵錯記錄。如需如何使用 --debug 選項的相關資訊，請參閱 命令列選項。

如果您在偵錯記錄中搜尋「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。