Ensuring idempotency in Amazon EC2 API requests

当您发出变更 API 请求时，该请求通常会在操作的异步工作流完成之前返回结果。即使请求已经返回结果，操作在完成之前也可能会超时或遇到其他服务器问题。这样就很难确定请求是否成功，并且会导致进行多次重试以确保操作成功完成。但是，如果原始请求和后续重试成功，则会多次完成操作。这意味着您可能会创建超过预期数量的资源。

幂等性确保 API 请求完成不超过一次。对于幂等性请求，如果原始请求成功完成，则后续重试也会成功完成，而不会执行任何后续操作。不过，结果中可能包含更新后的信息，例如当前的创建状态。

Amazon EC2 中的幂等性

以下 API 操作默认具备幂等性，无需额外配置。对应的 AWS CLI 命令也默认支持幂等性。

以下 API 操作通过客户端令牌来支持幂等性（可选）。对应的 AWS CLI 命令同样支持通过客户端令牌实现幂等性。客户端令牌是一个由最多 64 个 ASCII 字符组成、区分大小写的唯一字符串。要让这些操作的 API 请求具备幂等性，请在请求中指定一个客户端令牌。您不应将同一个客户端令牌用于其他 API 请求。如果您使用相同的客户端令牌并保持所有参数一致来重试一个已成功完成的请求，该重试会直接成功，而不会执行任何额外操作。如果您在重试成功的请求时使用了相同的客户端令牌，但一个或多个参数发生变化（区域或可用区除外），重试将失败，并返回 IdempotentParameterMismatch 错误。

RunInstances 的幂等性

RunInstances API 操作同时采用区域级和可用区级幂等性。

具体采用哪种幂等性，取决于您在 RunInstances API 请求中如何指定可用区。在以下情况中，请求会使用可用区级幂等性：

您既没有显式也没有隐式指定可用区，则请求会使用区域级幂等性。

可用区级幂等性

可用区级幂等性确保 RunInstances API 请求在同一区域内的每个可用区中都是幂等的。这保证了在同一区域内，使用相同客户端令牌的请求在每个可用区中只能成功执行一次。然而，您仍然可以使用同一个客户端令牌在该区域的其他可用区中启动实例。

例如，如果您发送一个在 us-east-1a 可用区启动实例的幂等请求，然后在 us-east-1b 可用区再次使用相同的客户端令牌发起请求，我们会在这些可用区中分别启动实例。如果后续重试中的一个或多个参数发生变化，那么在这些可用区内使用相同客户端令牌进行的重试要么会成功返回但不执行任何操作，要么会因参数不匹配而报告 IdempotentParameterMismatch 错误。

区域级幂等性

区域级幂等性确保 RunInstances API 请求在同一区域内是幂等的。这保证了在同一区域内，使用相同客户端令牌的请求只能成功执行一次。然而，您可以使用完全相同的请求（包括相同的客户端令牌）在其他区域中启动实例。

例如，如果您发送一个在 us-east-1 区域启动实例的幂等请求，然后在 eu-west-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 请求可能获得的一些常见响应，并提供了重试建议。