本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 請求 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 APIs 的 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 個 API 請求以耗盡儲存貯體，您可以繼續每秒提出 20 個 API 請求。只有在每秒提出少於 20 個 API 請求時，儲存貯體才能重新填充至最大容量。
## 請求權杖儲存貯體大小和補充費率
為了限制請求率，API 動作會分組為 類別。類別中的所有 API 動作都會共用相同的字符儲存貯體。例如， `DescribeClusters`和 `ListClusters` API 會共用*叢集讀取動作*儲存貯體，其中容量為 50，重新填充速率為 20。 APIs 這表示所有*叢集讀取動作*的 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_tw/AmazonECS/latest/developerguide/request-throttling.html) | 20 | 1 |
| 叢集讀取動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 任務定義修改動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 20 | 1 |
| 任務定義讀取動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 任務定義刪除動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 5 | 1 |
| 容量提供者修改動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 10 | 1 |
| 容量提供者讀取動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 標籤修改動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 20 | 10 |
| 標記讀取動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 設定修改動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 10 | 1 |
| 設定讀取動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 叢集資源修改動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 100 | 40 |
| 叢集資源讀取動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 100 | 20 |
| 客服人員修改動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 200 | 120 |
| 服務修改動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 5 |
| 服務讀取動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 100 | 20 |
| 服務部署動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 服務修訂動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 任務保護動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 200 | 80 |
| 叢集服務資源讀取動作 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/request-throttling.html) | 10 | 1 |
1 AWS Fargate 另外調節 Amazon ECS `RunTask` API 至 *Amazon ECS 開發人員指南*中[此處](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/throttling.html)列出的費率。
## 調整 API 限流配額
您可以請求提高 AWS 帳戶的 API 限流配額。若要請求調節配額，請聯絡 [AWS 支援 中心](https://console.aws.amazon.com/support/home#/)。
## 處理 API 限流
您可以實作錯誤重試和指數退避策略，以避免調節錯誤對工作負載的影響。如果您使用 AWS SDK，則自動重試邏輯已內建且可設定。如需詳細資訊，請參閱下列資源：
+ 《 AWS 一般參考指南》[中的錯誤重試和指數退避 AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)
+ [指數退避和抖動](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)部落格文章
+ Amazon Builder 程式庫中的[逾時、重試和退避抖動](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/)文章