べき等性の確保

変更オペレーションを実行すると、リソースが変更された後にタイムアウトやサーバーの問題が発生するため、例外が表示されることがあります。これにより、ミューテーションが発生したかどうかを判断することが難しくなり、複数回の再試行につながる場合があります。ただし、元のオペレーションとその後の再試行が実際にミューテーションを実行した場合、スタックの変更を適用したか、意図したよりも多くのリソースを作成している可能性があります。べき等性により、 オペレーションはリソースを 1 回しか変更しません。べき等性リクエストでは、元のリクエストが変更された場合、その後の再試行は追加のミューテーションを実行することなく正しく完了します。

Amazon ECS のべき等性

次の API アクションは、オプションでクライアントトークンを使用したべき等性をサポートしています。対応する AWS CLI コマンドも、クライアントトークンを使用したべき等性をサポートしています。クライアントトークンは、大文字と小文字を区別する一意の文字列です。これらのアクションのいずれかを使用してべき等 API リクエストを行うには、リクエストでクライアントトークンを指定します。同じクライアントトークンを他の API リクエストに再利用しないでください。同じクライアントトークンと同じパラメータを使用して正常に完了したリクエストを再試行すると、それ以上のアクションを実行せずに再試行が成功します。

RunTask のべき等性

RunTask API は、クライアントトークンを使用したべき等性に対応しています。クライアントトークンは、API リクエストを行うときに指定する一意の文字列です。API リクエストが正常に完了した後で、同じクライアントトークンと同じリクエストパラメータを使用して API リクエストを再試行すると、元のリクエストの結果が返されます。同じクライアントトークンを使用して成功したリクエストを再試行しても、リージョンまたはアベイラビリティーゾーン以外の 1 つ以上のパラメータが異なる場合、再試行は ConflictException で失敗します。独自のクライアントトークンを指定しない場合、AWS SDK および AWS Command Line Interface はリクエストのクライアントトークンを自動生成し、それがべき等性であることを確認します。クライアントトークンには、33～126 (含む) の範囲の最大 64 文字の ASCII 文字を含む任意の文字列を指定できます。

RunTask クライアントトークンの有効期限 (TTL) は 24 時間です。同じクライアントトークンを異なるリクエストに再利用しないでください。クライアントトークンの最大 TTL は、次の 2 つの値のいずれか低い方に対して有効です。

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 コマンドは、クライアントトークンを含むため、べき等性を使用します。

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 コマンドは、クライアントトークンを含むため、べき等性を使用します。

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 コマンドは、クライアントトークンを含むため、べき等性を使用します。

aws ecs run-task \
    --cluster MyCluster \
    --task-definition MyTaskDefinition:2 \
    --client-token 550e8400-e29b-41d4-a716-446655440000

API リクエストの例

API リクエストをべき等にするには、clientToken パラメータを追加します。

例: CreateService

次の CreateService 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 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 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 リクエストに対して返される一般的な応答と、再試行の推奨事項を示しています。