本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 確保 Amazon EC2 API 請求中的冪等性
當您提出變動的 API 請求時，該請求一般會在操作的非同步工作流程完成之前傳回結果。即使請求已傳回結果，操作還是可能會在完成前就逾時或發生其他伺服器問題。這可能會讓您難以判斷請求是否成功，而且可能導致系統多次重試以確保操作能成功完成。但是，如果原始請求和後續的重試有成功，則操作會完成多次。這表示您可以建立比預期更多的資源。
等冪性**可確保 API 請求不會完成超過一次。使用等冪請求時，如果原始請求成功完成，則任何後續的重試都會成功完成，而不必執行任何進一步的動作。不過，結果可能包含更新的資訊，例如目前的建立狀態。
**Topics**
+ [Amazon EC2 中的冪等性](#client-tokens)
+ [RunInstances 等冪性](#run-instances-idempotency)
+ [範例](#Run_Instance_Idempotency_CLI)
+ [等冪請求的重試建議](#recommended-actions)
## Amazon EC2 中的冪等性
根據預設，下列 API 動作是等冪的，不需要額外的組態。根據預設，對應的 AWS CLI 命令也支援冪等性。
**依預設，無效**
+ AssociateAddress
+ CreateVpnConnection
+ DisassociateAddress
+ ReplaceNetworkAclAssociation
+ TerminateInstances
下列 API 動作可選擇性地使用*用戶端字符*支援冪等性。對應的 AWS CLI 命令也支援使用用戶端字符的冪等性。用戶端字符是唯一的區分大小寫字串，最多 64 個 ASCII 字元。若要使用其中一個動作提出等冪 API 請求，請在請求中指定用戶端字符。您不應該將相同的用戶端字符用於其他 API 請求。如果您重試使用相同用戶端字符和相同參數成功完成的請求，則重試會成功，而無需執行任何進一步的動作。如果您使用相同的用戶端字符重試成功的請求，但一或多個參數不同，但區域或可用區域除外，則重試會失敗並顯示`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**中指定相同的用戶端字符，則如果呼叫為 **AvailabilityZone** 參數指定不同的值，則呼叫會成功。
## RunInstances 等冪性
[RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) API 動作同時使用區域和區域冪等性。
使用的冪等性類型取決於您在 RunInstances API 請求中指定可用區域的方式。在下列情況下，請求使用**區域冪等性**：
+ 如果您使用**置放**資料類型中的 **AvailabilityZone** 參數明確指定可用區域
+ 如果您使用 **SubnetId** 參數隱含指定可用區域
如果您未明確或隱含指定可用區域，請求會使用**區域冪等性**。
### 區域冪等性
區域冪等性可確保區域中每個可用區域中的 RunInstances API 請求都冪等。這可確保具有相同用戶端字符的請求只能在區域中的每個可用區域內完成一次。不過，相同的用戶端字符可用於在 區域中的其他可用區域中啟動執行個體。
例如，如果您傳送等冪請求來啟動`us-east-1a`可用區域中的執行個體，然後在`us-east-1b`可用區域中的請求中使用相同的用戶端字符，我們會在每個可用區域中啟動執行個體。如果一或多個參數不同，則在這些可用區域中具有相同用戶端字符的後續重試會成功傳回，而不會執行任何進一步動作或失敗並發生錯誤`IdempotentParameterMismatch`。
### 區域冪等性
區域冪等性可確保區域中的 RunInstances API 請求具有冪等性。這可確保具有相同用戶端字符的請求只能在區域內完成一次。不過，具有相同用戶端字符的完全相同請求可用來啟動不同區域中的執行個體。
例如，如果您傳送等冪性請求以在 `us-east-1`區域中啟動執行個體，然後在 `eu-west-1`區域中的請求中使用相同的用戶端字符，我們會在每個區域中啟動執行個體。如果一或多個參數不同，則在這些區域中使用相同用戶端字符的後續重試會成功傳回，而不會執行任何進一步的動作，或失敗並發生錯誤`IdempotentParameterMismatch`。
**提示**
如果請求區域中的其中一個可用區域無法使用，則使用區域冪等性的 RunInstances 請求可能會失敗。若要利用 AWS 基礎設施提供的可用區域功能，建議您在啟動執行個體時使用區域冪等性。使用區域冪等性並將可用可用區域設為目標的 RunInstances 請求成功，即使請求區域中的其他可用區域無法使用。
## 範例
### AWS CLI 命令範例
若要讓 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 請求範例
若要讓 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
```
## 等冪請求的重試建議
下表顯示您可能會從等冪 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/zh_tw/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 伺服器端問題造成，通常是暫時性的。請使用適當的退避策略來重複請求。 |