Ensuring idempotency in Amazon EC2 API requests

変異する API リクエストを行うと、通常、リクエストはオペレーションの非同期ワークフローが完了する前に結果を返します。リクエストが既に結果を返している場合でも、操作が完了する前にタイムアウトしたり、その他のサーバーの問題が発生したりすることもあります。これにより、リクエストが成功したかどうかを判断するのが難しくなり、操作を正常に完了するために複数回の再試行が行われることがあります。ただし、元のリクエストとその後の再試行が成功すると、操作は複数回完了します。つまり、意図したよりも多くのリソースが作成される可能性があります。

冪等性とは、API リクエストが 1 回だけ完了することを保証するものです。冪等性リクエストでは、元のリクエストが正常に完了した場合、その後の再試行は追加のアクションを実行せずに正しく完了します。ただし、結果には、現在の作成ステータスなどの更新された情報が含まれる場合があります。

Amazon EC2 のべき等性

以下の API アクションはデフォルトでべき等であり、追加の設定は必要ありません。対応する AWS CLI コマンドも、デフォルトでべき等性をサポートしています。

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

RunInstances のべき等性

RunInstances API アクションは、リージョンとゾーンの両方のべき等性を使用します。

使用されるべき等性のタイプは、RunInstances API リクエストでアベイラビリティーゾーンを指定する方法によって異なります。リクエストは、次の場合にゾーンのべき等性を使用します。

アベイラビリティーゾーンを明示的または暗黙的に指定しない場合、リクエストではリージョンのべき等性を使用します。

ゾーンのべき等性

ゾーンのべき等性により、RunInstances API リクエストがリージョン内の各アベイラビリティーゾーンでべき等であることが保証されます。これにより、同じクライアントトークンを使用するリクエストは、リージョン内の各アベイラビリティーゾーン内で 1 回だけ完了できます。ただし、同じクライアントトークンを使用して、リージョン内の他のアベイラビリティーゾーンでインスタンスを起動できます。

たとえば、べき等リクエストを送信して us-east-1a アベイラビリティーゾーンでインスタンスを起動し、us-east-1b アベイラビリティーゾーンのリクエストで同じクライアントトークンを使用する場合、それらの各アベイラビリティーゾーンでインスタンスを起動します。1 つ以上のパラメータが異なる場合、それらのアベイラビリティーゾーンで同じクライアントトークンを使用した後続の再試行は、それ以上のアクションを実行せずに正常に返されるか、IdempotentParameterMismatch エラーで失敗します。

リージョンのべき等性

リージョンのべき等性により、RunInstances API リクエストがリージョンでべき等であることが保証されます。これにより、同じクライアントトークンを使用するリクエストは、リージョン内で 1 回のみ完了できます。ただし、同じクライアントトークンを使用するまったく同じリクエストを使用して、別のリージョンでインスタンスを起動できます。

たとえば、us-east-1 リージョンでインスタンスを起動するべき等リクエストを送信し、次に eu-west-1 リージョンのリクエストで同じクライアントトークンを使用する場合、それらの各リージョンでインスタンスを起動します。1 つ以上のパラメータが異なる場合、それらのリージョンで同じクライアントトークンを使用した後続の再試行は、それ以上のアクションを実行せずに正常に返されるか、IdempotentParameterMismatch エラーで失敗します。

例

AWS CLI コマンドの例

AWS CLI コマンドをべき等にするには、--client-token オプションを追加します。

例 1: べき等性

次の allocate-hosts コマンドは、クライアントトークンを含むため、べき等性を使用します。

aws ec2 allocate-hosts  --instance-type m5.large  --availability-zone eu-west-1a  --auto-placement on  --quantity 1 --client-token 550e8400-e29b-41d4-a716-446655440000

例 2: run-instances リージョンのべき等性

次の run-instances コマンドは、クライアントトークンを含むため、リージョンのべき等性を使用しますが、明示的にも暗黙的にもアベイラビリティーゾーンを指定しません。

aws ec2 run-instances --image-id ami-b232d0db --count 1 --key-name my-key-pair --client-token 550e8400-e29b-41d4-a716-446655440000

例 3: run-instances ゾーンのべき等性

次の run-instances コマンドは、クライアントトークンと明示的に指定されたアベイラビリティーゾーンを含むため、ゾーンのべき等性を使用します。

aws ec2 run-instances  --placement "AvailabilityZone=us-east-1a" --image-id ami-b232d0db --count 1 --key-name my-key-pair --client-token 550e8400-e29b-41d4-a716-446655440000

API リクエストの例

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

例 1: べき等性

次の AllocateHosts API リクエストは、クライアントトークンを含むためべき等性を使用します。

https://ec2.amazonaws.com/?Action=AllocateHosts
&AvailabilityZone=us-east-1b
&InstanceType=m5.large
&Quantity=1
&AutoPlacement=off
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

例 2: RunInstances リージョンのべき等性

次の RunInstances API リクエストは、クライアントトークンを含むため、リージョンのべき等性を使用しますが、明示的にも暗黙的にもアベイラビリティーゾーンを指定しません。

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-3ac33653
&MaxCount=1
&MinCount=1
&KeyName=my-key-pair
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

例 3: RunInstances ゾーンのべき等性

次の RunInstances API リクエストでは、クライアントトークンと明示的に指定されたアベイラビリティーゾーンが含まれているため、ゾーンのべき等性を使用します。

https://ec2.amazonaws.com/?Action=RunInstances
&Placement.AvailabilityZone=us-east-1d
&ImageId=ami-3ac33653
&MaxCount=1
&MinCount=1
&KeyName=my-key-pair
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

べき等リクエストの再試行の推奨事項

次の表は、べき等 API リクエストに対して返される一般的な応答と、再試行の推奨事項を示しています。