翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# Ensuring idempotency in Amazon EC2 API requests
<a name="ec2-api-idempotency"></a>

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

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

**Topics**
+ [

## Amazon EC2 のべき等性
](#client-tokens)
+ [

## RunInstances のべき等性
](#run-instances-idempotency)
+ [

## 例
](#Run_Instance_Idempotency_CLI)
+ [

## べき等リクエストの再試行の推奨事項
](#recommended-actions)

## Amazon EC2 のべき等性
<a name="client-tokens"></a>

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

**デフォルトでべき等**
+ AssociateAddress
+ CreateVpnConnection
+ DisassociateAddress
+ ReplaceNetworkAclAssociation
+ TerminateInstances

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

**クライアントトークンを使用したべき等性**
+ AllocateHosts
+ AllocateIpamPoolCidr
+ AssociateClientVpnTargetNetwork
+ AssociateIpamResourceDiscovery
+ AttachVerifiedAccessTrustProvider
+ AuthorizeClientVpnIngress
+ CopyFpgaImage
+ CopyImage
+ CreateCapacityReservation
+ CreateCapacityReservationFleet
+ CreateClientVpnEndpoint
+ CreateClientVpnRoute
+ CreateEgressOnlyInternetGateway
+ CreateFleet
+ CreateFlowLogs
+ CreateFpgaImage
+ CreateInstanceConnectEndpoint
+ CreateIpam
+ CreateIpamPool
+ CreateIpamResourceDiscovery
+ CreateIpamScope
+ CreateLaunchTemplate
+ CreateLaunchTemplateVersion
+ CreateManagedPrefixList
+ CreateNatGateway
+ CreateNetworkAcl
+ CreateNetworkInsightsAccessScope
+ CreateNetworkInsightsPath
+ CreateNetworkInterface
+ CreateReplaceRootVolumeTask
+ CreateReservedInstancesListing
+ CreateRouteTable
+ CreateTrafficMirrorFilter
+ CreateTrafficMirrorFilterRule
+ CreateTrafficMirrorSession
+ CreateTrafficMirrorTarget
+ CreateVerifiedAccessEndpoint
+ CreateVerifiedAccessGroup
+ CreateVerifiedAccessInstance
+ CreateVerifiedAccessTrustProvider
+ CreateVolume
+ CreateVpcEndpoint
+ CreateVpcEndpointConnectionNotification
+ CreateVpcEndpointServiceConfiguration
+ DeleteVerifiedAccessEndpoint
+ DeleteVerifiedAccessGroup
+ DeleteVerifiedAccessInstance
+ DeleteVerifiedAccessTrustProvider
+ DetachVerifiedAccessTrustProvider
+ ExportImage
+ ImportImage
+ ImportSnapshot
+ ModifyInstanceCreditSpecification
+ ModifyLaunchTemplate
+ ModifyReservedInstances
+ ModifyVerifiedAccessEndpoint
+ ModifyVerifiedAccessEndpointPolicy
+ ModifyVerifiedAccessGroup
+ ModifyVerifiedAccessGroupPolicy
+ ModifyVerifiedAccessInstance
+ ModifyVerifiedAccessInstanceLoggingConfiguration
+ ModifyVerifiedAccessTrustProvider
+ ProvisionIpamPoolCidr
+ PurchaseHostReservation
+ RequestSpotFleet
+ RequestSpotInstances
+ RunInstances
+ StartNetworkInsightsAccessScopeAnalysis
+ StartNetworkInsightsAnalysis

**べき等性のタイプ**
+ リージョン – リクエストは各リージョンでべき等です。ただし、同じクライアントトークンを含む同じリクエストを別のリージョンで使用できます。
+ ゾーン – リクエストは、リージョン内の各アベイラビリティーゾーンでべき等です。たとえば、同じリージョンの **AllocateHosts** への 2 回の呼び出しで同じクライアントトークンを指定した場合、**AvailabilityZone** パラメータに異なる値を指定すると、呼び出しは成功します。

## RunInstances のべき等性
<a name="run-instances-idempotency"></a>

[RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) API アクションは、リージョンとゾーンの両方のべき等性を使用します。

使用されるべき等性のタイプは、RunInstances API リクエストでアベイラビリティーゾーンを指定する方法によって異なります。リクエストは、次の場合に**ゾーンのべき等性**を使用します。
+ **プレイスメント**データ型で **AvailabilityZone** パラメータを使用してアベイラビリティーゾーンを明示的に指定する場合
+ **SubnetId** パラメータを使用して暗黙的にアベイラビリティーゾーンを指定する場合

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

### ゾーンのべき等性
<a name="zonal-idempotency"></a>

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

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

### リージョンのべき等性
<a name="regional-idempotency"></a>

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

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

**ヒント**  
リクエストされたリージョンのアベイラビリティーゾーンのいずれかが利用できない場合、リージョンのべき等性を使用する RunInstances リクエストは失敗する可能性があります。AWS インフラストラクチャが提供するアベイラビリティーゾーンの機能を活用するには、インスタンスの起動時にゾーンのべき等性を使用することをお勧めします。ゾーンのべき等性を使用し、利用可能なアベイラビリティーゾーンをターゲットとする RunInstances リクエストは、リクエストされたリージョン内の別のアベイラビリティーゾーンが利用できない場合でも成功します。

## 例
<a name="Run_Instance_Idempotency_CLI"></a>

### AWS CLI コマンドの例
<a name="cli-example"></a>

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

**例 1: べき等性**  
次の [allocate-hosts](https://docs.aws.amazon.com/cli/latest/reference/ec2/allocate-hosts.html) コマンドは、クライアントトークンを含むため、べき等性を使用します。

```
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](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) コマンドは、クライアントトークンを含むため、リージョンのべき等性を使用しますが、明示的にも暗黙的にもアベイラビリティーゾーンを指定しません。

```
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](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) コマンドは、クライアントトークンと明示的に指定されたアベイラビリティーゾーンを含むため、ゾーンのべき等性を使用します。

```
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 リクエストの例
<a name="api-example"></a>

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

**例 1: べき等性**  
次の [AllocateHosts](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_AllocateHosts.html) 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](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) 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](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) 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
```

## べき等リクエストの再試行の推奨事項
<a name="recommended-actions"></a>

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


| 応答 | 推奨事項 | コメント | 
| --- | --- | --- | 
|  200 (OK)  |  再試行しないでください  |  元のリクエストは正しく完了しています。それ以降に再試行しても正常に戻ります。  | 
|  400 シリーズ応答コード ([クライアントエラー](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/errors-overview.html#CommonErrors))  |  再試行しないでください  |  次のうち、リクエストに問題があります。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/ec2/latest/devguide/ec2-api-idempotency.html) リクエストに状態の変更処理中のリソースが含まれている場合、リクエストを再試行すると成功する可能性があります。  | 
|  500 シリーズ応答コード ([サーバーエラー](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/errors-overview.html#api-error-codes-table-server))  |  再試行  |  このエラーは AWS サーバー側の問題によって発生し、通常は一時的なものです。適切なバックオフ戦略でリクエストを繰り返してください。  |