AWS CLI 重试次数 - AWS Command Line Interface
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

AWS CLI 重试次数

本主题介绍在 AWS CLI 中,可能由于意外问题而导致 AWS 服务调用失败。这些问题可能发生在服务器端,也可能是由于您尝试调用的 AWS 服务存在速率限制而失败。这些类型的故障通常不需要特殊处理,并且通常在短暂的等待时间段后会自动重新发出调用。AWS CLI 提供了许多功能,在出现这些类型的错误或异常的情况下,帮助重试对 AWS 服务进行的客户端调用。

可用重试模式

AWS CLI 有多种模式可供选择,具体取决于您的版本:

传统重试模式

传统模式是 AWS CLI 版本 1 使用的默认模式。传统模式使用旧的重试处理程序,其功能有限,其中包括:

  • 最大重试次数的默认值为 4,总共可发出 5 次调用尝试。此值可通过 max_attempts 配置参数覆盖。

  • 重试以下有限数量的错误/异常:

    • 常规套接字/连接错误:

      • ConnectionError

      • ConnectionClosedError

      • ReadTimeoutError

      • EndpointConnectionError

    • 服务端限制错误和异常:

      • Throttling

      • ThrottlingException

      • ThrottledException

      • RequestThrottledException

      • ProvisionedThroughputExceededException

  • 对多个 HTTP 状态代码执行重试操作,包括 429、500、502、503、504 和 509。

  • 任何重试都将包含基准因子为 2 的指数回退。

标准重试模式

标准模式是一组跨 AWS 开发工具包的标准重试规则,其功能比传统模式更多。此模式是 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 版本 1 的默认值为传统模式,而 AWS CLI 版本 2 的默认值为标准模式。

  • 最大尝试次数 - 指定 AWS CLI 重试处理程序使用的最大重试次数值,其中初始调用会计入您提供的值。默认值是 5。

在环境变量中定义重试配置

要为 AWS CLI 定义您的重试配置,请更新操作系统的环境变量。

重试环境变量包括:

  • AWS_RETRY_MODE

  • AWS_MAX_ATTEMPTS

有关环境变量的更多信息,请参阅用于配置 AWS CLI 的环境变量

在 AWS 配置文件中定义重试配置

此功能仅适用于 AWS CLI 版本 2。

仅当您使用 AWS CLI 版本 2 时,以下功能才可用。如果您运行 AWS CLI 版本 1,则此功能不可用。有关如何安装版本 2 的信息,请参阅安装、更新和卸载 AWS CLI 版本 2

要更改重试配置,请更新您的全局 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