# べき等性の確保
変更オペレーションを実行すると、リソースが変更された後にタイムアウトやサーバーの問題が発生するため、例外が表示されることがあります。これにより、ミューテーションが発生したかどうかを判断することが難しくなり、複数回の再試行につながる場合があります。ただし、元のオペレーションとその後の再試行が実際にミューテーションを実行した場合、スタックの変更を適用したか、意図したよりも多くのリソースを作成している可能性があります。べき等性により、 オペレーションはリソースを 1 回しか変更しません。べき等性リクエストでは、元のリクエストが変更された場合、その後の再試行は追加のミューテーションを実行することなく正しく完了します。
**Topics**
+ [Amazon ECS のべき等性](#client-tokens)
+ [RunTask のべき等性](#RunTaskIdempotency)
+ [例](#Run_Task_Idempotency_CLI)
+ [べき等リクエストの再試行の推奨事項](#recommended-actions)
## Amazon ECS のべき等性
次の API アクションは、オプションで*クライアントトークン*を使用したべき等性をサポートしています。対応する AWS CLI コマンドも、クライアントトークンを使用したべき等性をサポートしています。クライアントトークンは、大文字と小文字を区別する一意の文字列です。これらのアクションのいずれかを使用してべき等 API リクエストを行うには、リクエストでクライアントトークンを指定します。同じクライアントトークンを他の API リクエストに再利用しないでください。同じクライアントトークンと同じパラメータを使用して正常に完了したリクエストを再試行すると、それ以上のアクションを実行せずに再試行が成功します。
**クライアントトークンを使用したべき等性**
+ CreateService
クライアントトークンは、33～126 (含む) の範囲の最大 36 文字の ASCII 文字です。
+ CreateTaskSet
クライアントトークンは、33～126 (含む) の範囲の最大 36 文字の ASCII 文字です。
+ RunTask
クライアントトークンは、33～126 (含む) の範囲の最大 64 文字の ASCII 文字です。
**べき等性のタイプ**
+ クラスター – 同じクラスターに同じトークンを持つリクエストはべき等性です。例えば、ClientToken A は、クラスター X の `RunTask` リクエストに対して 1 回のみリクエストパラメータとして使用できます。他のクラスターへの `RunTask` リクエストは、別のリクエストと見なされます。したがって、クラスター Y の `RunTask` リクエストに ClientToken A を使用できます。
## RunTask のべき等性
`RunTask` API は、クライアントトークンを使用したべき等性に対応しています。クライアントトークンは、API リクエストを行うときに指定する一意の文字列です。API リクエストが正常に完了した後で、同じクライアントトークンと同じリクエストパラメータを使用して API リクエストを再試行すると、元のリクエストの結果が返されます。同じクライアントトークンを使用して成功したリクエストを再試行しても、リージョンまたはアベイラビリティーゾーン以外の 1 つ以上のパラメータが異なる場合、再試行は `ConflictException` で失敗します。独自のクライアントトークンを指定しない場合、AWS SDK および AWS Command Line Interface はリクエストのクライアントトークンを自動生成し、それがべき等性であることを確認します。クライアントトークンには、33～126 (含む) の範囲の最大 64 文字の ASCII 文字を含む任意の文字列を指定できます。
`RunTask` クライアントトークンの有効期限 (TTL) は 24 時間です。同じクライアントトークンを異なるリクエストに再利用しないでください。クライアントトークンの最大 TTL は、次の 2 つの値のいずれか低い方に対して有効です。
+ 24 時間
+ リソースの有効期間 \+ 1 時間
リソースの有効期間は、タスクが作成されたタイムスタンプから、最後のステータス (`lastStatus`) が `STOPPED` に移行したタイムスタンプです。`RunTask` を使用して 1 つ以上のタスクを起動する場合、リソースの有効期間は、`STOPPED` に移行した最後のタスクの有効期間と等しくなります。
### RunTask 再試行ルールとレスポンス
5xx 例外を受け取ったためにリクエストを再試行すると、再試行された成功レスポンスには通常、元のリクエストが返すすべての情報が含まれます。1 時間以内に停止されたタスクには、タスク ARN、最終ステータス、目的のステータスのみが含まれます。
次に示すのは、実行中のタスクが 1 つ、停止したタスクが 1 つ、起動に失敗したタスクが 1 つある場合の再試行からのレスポンスのスニペットの例です。
```
{
"failures": [
{
"arn": "arn:aws:ecs:us-east-1:123456789012:container/4df26bb4-f057-467b-a079-961675296e64",
"reason": "RESOURCE:MEMORY"
}
],
"tasks": [
{
"desiredStatus": "RUNNING",
"taskArn": "arn:aws:ecs:us-east-1:123456789012:task/default/fdf2c302-468c-4e55-b884-5331d816e7fb",
...
},
{
"taskArn": "arn:aws:ecs:us-east-1:123456789012:task/default/fdf2c302-468c-4e55-b884-5331d819999",
"lastStatus": "STOPPED",
...
}
]
}
```
1 時間以上経過したエラーには、失敗したタスクの数のみが含まれます。
## 例
### AWS CLI コマンドの例
AWS CLI コマンドをべき等にするには、`--client-token` オプションを追加します。
**例: create-service**
次の [create-service](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-service.html#examples) コマンドは、クライアントトークンを含むため、べき等性を使用します。
```
aws ecs create-service \
--cluster MyCluster \
--service MyService \
--task-definition MyTaskDefinition:2 \
--desired-count 2 \
--launch-type FARGATE \
--platform-version LATEST \
--network-configuration "awsvpcConfiguration={subnets=["subnet-12344321"],securityGroups=["sg-12344321"],assignPublicIp="ENABLED"}" \
--client-token 550e8400-e29b-41d4-a716-44665544
```
**例: create-service**
次の [create-service](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-task-set.html#examples) コマンドは、クライアントトークンを含むため、べき等性を使用します。
```
aws ecs create-task-set \
--cluster MyCluster \
--service MyService \
--task-definition MyTaskDefinition:2 \
--network-configuration "awsvpcConfiguration={subnets=["subnet-12344321"],securityGroups=["sg-12344321"]}" \
--client-token 550e8400-e29b-41d4-a716-44665544
```
**例: run-task**
次の [run-task](https://docs.aws.amazon.com/cli/latest/reference/ecs/run-task.html#examples) コマンドは、クライアントトークンを含むため、べき等性を使用します。
```
aws ecs run-task \
--cluster MyCluster \
--task-definition MyTaskDefinition:2 \
--client-token 550e8400-e29b-41d4-a716-446655440000
```
### API リクエストの例
API リクエストをべき等にするには、`clientToken` パラメータを追加します。
**例: CreateService**
次の [CreateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html) API リクエストは、クライアントトークンを含むため、べき等性を使用します。
```
POST / HTTP/1.1
Host: ecs.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 87
X-Amz-Target: AmazonEC2ContainerServiceV20141113.CreateService
X-Amz-Date: 20150429T170125Z
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{
"serviceName": "MyService",
"taskDefinition": "MyTaskDefinition:2",
"desiredCount": 10,
"capacityProviderStrategy": [
{
"base": "number",
"capacityProvider": "FARGATE",
"weight": 1
}
],
"capacityProviderStrategy": [
{
"base": "number",
"capacityProvider": "FARGATE_SPOT",
"weight": 1
}
],
"clientToken": "550e8400-e29b-41d4-a716-44665544"
}
```
**例: CreateTaskSet**
次の [CreateTaskSet](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateTaskSet.html) API リクエストは、クライアントトークンを含むため、べき等性を使用します。
```
POST / HTTP/1.1
Host: ecs.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 87
X-Amz-Target: AmazonEC2ContainerServiceV20141113.CreateTaskSet
X-Amz-Date: 20150429T170125Z
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{
"serviceName": "MyService",
"taskDefinition": "mytask:1",
"desiredCount": 1,
"capacityProviderStrategy": [
{
"base": "number",
"capacityProvider": "FARGATE",
"weight": 1
}
],
"capacityProviderStrategy": [
{
"base": "number",
"capacityProvider": "FARGATE_SPOT",
"weight": 1
}
],
"clientToken": "550e8400-e29b-41d4-a716-44665544"
}
```
**例: RunTask**
次の [RunTask](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html) API リクエストは、クライアントトークンを含むため、べき等性を使用します。
```
POST / HTTP/1.1
Host: ecs.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 45
X-Amz-Target: AmazonEC2ContainerServiceV20141113.RunTask
X-Amz-Date: 20161121T215740Z
User-Agent: aws-cli/1.11.13 Python/2.7.12 Darwin/16.1.0 botocore/1.4.66
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{
"count": 1,
"taskDefinition": "mytask:1",
"clientToken": "550e8400-e29b-41d4-a716-446655440000"
}
```
## べき等リクエストの再試行の推奨事項
次の表は、べき等 API リクエストに対して返される一般的な応答と、再試行の推奨事項を示しています。
| 応答 | 推奨事項 | コメント |
| --- | --- | --- |
| 200 (OK) | 再試行しないでください | 元のリクエストは正しく完了しています。それ以降に再試行しても正常に戻ります。 |
| 400 シリーズ応答コード ([クライアントエラー](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/errors-overview.html#CommonErrors)) | 再試行しないでください | 次のうち、リクエストに問題があります。[See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/ECS_Idempotency.html)
リクエストに状態の変更処理中のリソースが含まれている場合、リクエストを再試行すると成功する可能性があります。 |
| 500 シリーズ応答コード ([サーバーエラー](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/errors-overview.html#api-error-codes-table-server)) | 再試行 | このエラーは AWS サーバー側の問題によって発生し、通常は一時的なものです。適切なバックオフ戦略を使用してリクエストを繰り返してください。 |