# Amazon ECS API 的请求节流
Amazon Elastic Container Service 会在每个 AWS 账户按区域对所有 API 请求实施节流。我们这样做是为了保证性能稳定，并确保所有 Amazon ECS 用户都能公平使用。通过节流，可确保对 Amazon ECS API 的调用不超过 Amazon ECS 及其集成的其他 AWS 服务允许的 API 最大请求配额。无论 API 调用来自以下哪些来源，都会受到请求配额的约束：
+ 第三方应用程序
+ 命令行工具
+ Amazon ECS 控制台
如果您超过 API 节流配额，则会收到`ThrottlingException`错误代码。
```
An error occurred (ThrottlingException) when calling the DescribeClusters operation (reached max retries: 4): Rate exceeded.
com.amazonaws.services.ecs.model.AmazonECSException: Rate exceeded (Service: AmazonECS; Status Code: 400; Error
Code: ThrottlingException; Request ID: 5ed90669-e454-464d-9b2f-6523bc86f537; Proxy: null)
```
## 如何应用节流
Amazon ECS 使用[令牌存储桶算法](https://en.wikipedia.org/wiki/Token_bucket)实施 API 节流。使用此算法，您的账户拥有一个持有特定数量的*令牌*的*存储桶*。存储桶中的令牌数表示您在任何给定秒钟的节流配额。
Amazon ECS 会按区域检查您账户中所有 Amazon ECS API 的 API 请求提交速率，并应用以下两种类型的 API 节流配额：*持续*和*突发*。持续速率是指在一段时间内，某项操作每秒允许的平均 API 请求数。突发速率是指任何一秒内允许的最大 API 请求数。使用突发速率，您可以定期发出比持续速率更高的 API 请求数。之后，Amazon ECS 会对后续 API 请求进行节流，直到允许的 API 请求速率在一段时间内稳定至持续速率。在令牌存储桶算法中，*存储桶的最大容量*表示突发速率，*存储桶重填速率*指持续速率。在以下示例中，我们将使用这些术语举例说明 Amazon ECS API 请求节流。
您发出的 API 请求数会被节流，并且每发出一个请求将会从令牌存储桶中删除一个令牌。例如，*集群读取操作*（例如 `DescribeClusters` API）的存储桶大小为 50 个令牌，因此您在一秒内最多可以发出 50 个 `DescribeClusters` 请求。如果您在一秒钟内发出的请求超过 50 个，则会被节流，同时该秒内剩余的请求将会失败。
存储桶会以设定的速率自动填充。如果存储桶的容量低于其最大容量，则每秒都会向其添加一定数量的令牌，直到其达到最大容量。如果重填令牌到达时存储桶已满，额外的令牌会被丢弃。存储桶中的令牌数量不能超过其最大数量。例如，*集群读取操作*（比如 `DescribeClusters` API）的存储桶容量为 50 个令牌，重填速率为每秒 20 个令牌。如果您在一秒钟内发出 50 个 `DescribeClusters` API 请求，存储桶会立即减少到零个令牌。之后，存储桶会以每秒 20 个的速度重填令牌，直到重新达到 50 个的最大容量。这意味着，之前为空的存储桶需要 2.5 秒的时间才能重新填满。
您无需等存储桶完全填满才能继续发起 API 请求。您可以在令牌被添加到存储桶时使用这些令牌。如果您立即使用重填令牌，存储桶就不会达到最大容量。例如，*集群读取操作*（比如 `DescribeClusters` API）的存储桶容量为 50 个令牌，重填速率为每秒 20 个令牌。如果您在一秒内用掉存储桶中的全部 50 个令牌，随后仍可每秒发起 20 次 API 请求。只有当您每秒发起的请求少于 20 次时，存储桶才有机会重新填满。
## 请求令牌存储桶的容量与重填速率
API 操作分为若干类别来实施请求速率限制。一个类别的所有 API 操作将共享同一个令牌存储桶。例如，`DescribeClusters` 和 `ListClusters` API 共享*集群读取操作*存储桶，其容量为 50，重填速率为 20。这意味着，所有*集群读取操作*的累计 API 请求数受同一个突发速率配额（即 50 个 API 请求）的节流。因此，您可以在一秒钟内发出 25 个 `DescribeClusters` 和 25 个 `ListClusters` API 请求，或者发出 30 个 `DescribeClusters` 和 20 个 `ListClusters` 请求，或 50 个 `DescribeClusters` 和 0 个 `ListClusters` 请求，或 0 个 `DescribeClusters` 和 50 个 `ListClusters` 请求，但不能同时发出 50 个 `DescribeClusters` 和 50 个 `ListClusters` 请求。同样，持续速率以累计方式应用于存储桶内的所有 API 请求。
下表显示了所有 AWS区域的存储桶容量（或突发速率）和重填速率（或持续速率）。所有 API 操作类别根据区域对每个 AWS 账户强制执行速率配额。
| API 操作类别 | 操作 | 存储桶最大容量（或突发速率） | 存储桶重填速率（或持续速率） |
| --- | --- | --- | --- |
| 集群修改操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 20 | 1 |
| 集群读取操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 任务定义修改操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 20 | 1 |
| 任务定义读取操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 任务定义删除操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 5 | 1 |
| 容量提供程序修改操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 10 | 1 |
| 容量提供程序读取操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 标签修改操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 20 | 10 |
| 标签读取操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 设置修改操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 10 | 1 |
| 设置读取操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 集群资源修改操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 100 | 40 |
| 集群资源读取操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 100 | 20 |
| 代理修改操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 200 | 120 |
| 服务修改操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 5 |
| 服务读取操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 100 | 20 |
| 服务部署操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 服务修订操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 任务保护操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 200 | 80 |
| 集群服务资源读取操作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/request-throttling.html) | 10 | 1 |
1 AWS Fargate 还将 Amazon ECS `RunTask` API 节流为[此处](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/throttling.html)列出的速率，参见《Amazon ECS 开发人员指南》**。
## 调整 API 节流配额
您可以请求增加您的 AWS 账户的 API 限制配额。要请求配额调整，请联系 [AWS 支持 中心](https://console.aws.amazon.com/support/home#/)。
## 处理 API 节流
您可以实施错误重试和指数退避策略，以免节流错误对工作负载造成影响。如果使用 AWS 开发工具包，自动重试逻辑已内置其中且可配置。有关更多详细信息，可参阅以下资源：
+ 《AWS 一般参考指南》中 [AWS 中的错误重试和指数回退](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)
+ [指数回退和抖动](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)博客文章
+ Amazon Builders' Library 中的[超时、重试和抖动回退](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/)文章