Amazon EC2APIリクエストの冪等性の確保

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

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

Amazon の ID の容量 EC2

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

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

RunInstances 冪等性

このRunInstancesAPIアクションは、リージョンとゾーンの両方の冪等性を使用します。

使用される冪等性のタイプは、リクエストで 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: Idempotency

次の 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: Idempotency

次のAllocateHostsAPIリクエストでは、クライアントトークンが含まれているため、冪等性を使用します。

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 リージョンの冪等性

次のRunInstancesAPIリクエストは、クライアントトークンを含むが、アベイラビリティーゾーンを明示的または暗黙的に指定しないため、リージョンの冪等性を使用します。

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 ゾーンの冪等性

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

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リクエストに対して取得される可能性のある一般的なレスポンスの一部と、再試行に関する推奨事項を示しています。