# 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 SDK 的标准重试规则，其功能比传统模式更多，并且是 AWS CLI 的默认模式。标准模式为 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 秒。

### 传统重试模式
<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 版本 2 的默认值为标准模式。
+ 最大尝试次数 - 指定 AWS CLI 重试处理程序使用的最大重试次数值，其中初始调用会计入您提供的值。默认值基于您的重试模式。

### 在环境变量中定义重试配置
<a name="cli-usage-retries-configure-envvar"></a>

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

重试环境变量包括：
+ `AWS_RETRY_MODE`
+ `AWS_MAX_ATTEMPTS`

有关环境变量的更多信息，请参阅[为 AWS CLI 配置环境变量](cli-configure-envvars.md)。

### 在 AWS 配置文件中定义重试配置
<a name="cli-usage-retries-configure-file"></a>

要更改重试配置，请更新您的全局 AWS 配置文件。您的AWS配置文件的默认位置为 \$1/.aws/config。

下面是AWS配置文件的示例：

```
[default]
retry_mode = standard
max_attempts = 6
```

有关配置文件的更多信息，请参阅[AWS CLI 中的配置和凭证文件设置](cli-configure-files.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)。