# 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 リクエスト送信のレートをリージョンごとに調べ、*持続*と*バースト*の 2 種類の API スロットリングクォータを適用します。持続レートは、 オペレーションで 1 秒あたりに許可される API リクエストの平均数です。バーストレートは、任意の 1 秒で許可される API リクエストの最大数です。バーストレートでは、持続レートよりも多くの API リクエストを定期的に作成できます。その後、Amazon ECS は、時間の経過とともに許可される API リクエストのレートが持続レートに安定するまで、後続の API リクエストをスロットリングします。トークンバケットアルゴリズムでは、*バケットの最大容量*はバーストレートを表します。*バケットリフィルレート*は持続レートです。これらの用語を使用して、次の例の Amazon ECS API リクエストスロットリングの図を紹介します。
実行する API リクエストの数でスロットリングされ、各リクエストはトークンバケットから 1 つのトークンを削除します。例えば、`DescribeClusters` API などの*クラスター読み取りアクション*のバケットサイズは 50 トークンであるため、1 秒間に最大 50 個の `DescribeClusters` リクエストを行うことができます。1 秒間に 50 リクエストを超えると、スロットリングされ、その秒以内の残りのリクエストは失敗します。
バケットは設定されたレートで自動的に補充されます。バケットが最大容量に達していない場合、最大容量に達するまで、設定した数のトークンが毎秒追加されます。リフィルトークンが到着したときにバケットが満杯である場合、リフィルトークンは破棄されます。バケットは最大数以上のトークンを保持できません。例えば、*クラスター読み取りアクション*のバケットサイズ (`DescribeClusters` API など) が 50 トークンで、リフィルレートが 1 秒あたり 20 トークンであるとします。1 秒間に 50 の `DescribeClusters` API リクエストを行うと、バケットはすぐにゼロトークンに削減されます。バケットは、最大容量の 50 トークンに達するまで、毎秒最大 20 トークン補充されます。つまり、以前空だったバケットは 2.5 秒後に最大容量に達します。
API リクエストを行う前に、バケットが完全にいっぱいになるまで待つ必要はありません。トークンはバケットに追加されるとすぐに使用できます。補充トークンをすぐに使用すると、バケットが最大容量に達することはありません。例えば、*クラスター読み取りアクション*のバケットサイズ (`DescribeClusters` API など) が 50 トークンで、リフィルレートが 1 秒あたり 20 トークンであるとします。1 秒あたり 50 個の API リクエストを行ってバケットを使い果たした場合、1 秒あたり 20 個の API リクエストを引き続き行うことができます。バケットは、1 秒あたり 20 個未満の API リクエストを行う場合のみ、最大容量に補充できます。
## リクエストトークンバケットのサイズとリフィルレート
リクエストレート制限の目的で、API アクションはカテゴリにグループ化されます。カテゴリ内のすべての API アクションは、同じトークンバケットを共有します。例えば、`DescribeClusters` と `ListClusters` API が、容量が 50、補充レートが 20 の*クラスター読み取りアクション*バケットを共有しているとします。この場合、すべての*クラスター読み取りアクション*の API リクエストの累積数は、50 件の API リクエストの同一バーストレートクォータによって調整されます。したがって、1 秒あたり 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/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 20 | 1 |
| クラスター読み取りアクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| タスク定義変更アクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 20 | 1 |
| タスク定義読み取りアクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| タスク定義削除アクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 5 | 1 |
| キャパシティプロバイダー変更アクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 10 | 1 |
| キャパシティプロバイダー読み取りアクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| タグ変更アクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 20 | 10 |
| タグ読み取りアクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| 変更アクションの設定 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 10 | 1 |
| 読み取りアクションの設定 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| クラスターリソース変更アクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 100 | 40 |
| クラスターリソース読み取りアクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 100 | 20 |
| エージェント変更アクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 200 | 120 |
| サービス変更アクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 5 |
| サービス読み取りアクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 100 | 20 |
| サービスデプロイアクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| サービスリビジョンアクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 50 | 20 |
| タスク保護アクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 200 | 80 |
| クラスターサービスリソース読み取りアクション | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/request-throttling.html) | 10 | 1 |
1 AWS Fargate は、「*Amazon ECS デベロッパーガイド*」の[こちら](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/throttling.html)に記載されているレートに Amazon ECS `RunTask` APIをさらにスロットリングします。
## 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 Builders' Library の「[ジッターを伴うタイムアウト、再試行、およびバックオフ](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/)」の記事