您在调用ROS API时,如果发生请求超时或服务器内部错误,客户端可能会尝试重发请求。您可以在请求中设置ClientToken参数避免多次重试带来重复操作的问题。

什么是幂等性

在数学计算或者计算机科学中,幂等性(Idempotence)是指相同操作或资源在一次或多次请求中具有同样效果的作用。幂等性在分布式系统设计中具有十分重要的地位。

保证幂等性

通常情况下,客户端只需要在HTTP状态码返回500 Internal Server Error503 Service Unavailable错误,或者无法获取响应结果时重试。使用ROS API,您可以从客户端生成一个参数值不超过64个ASCII字符的字符串,并将值赋予ClientToken,保证重试请求的幂等性。

ClientToken详解

ClientToken参数的详细信息如下:

  • ClientToken是一个由客户端生成的唯一的、区分大小写、不超过64个ASCII字符的字符串。例如:ClientToken=123e4567-e89b-12d3-a456-42665544****
  • 如果您提供了一个已经使用过的ClientToken,但其他请求参数有变化,则ROS会返回InvalidIdempotenceParameter的错误代码。
    说明 参数 SignatureNonceTimestampSignature在重试时是需要变化的。具体原因是ROS使用 SignatureNonce防止重放攻击,使用 Timestamp标记每次请求时间。所以再次请求必须提供不同的 SignatureNonceTimestamp参数值,同时也会导致 Signature值的变化。
  • 添加了ClientToken参数后:
    • HTTP状态码返回200 OK时,重试后客户端可以得到与上次相同的结果,但对您的服务端状态没有影响。
    • HTTP状态码返回请求错误(例如400 Bad Request)时,如果错误信息没有表明try it later类似的信息,重试不会成功。您需要根据错误信息排查问题后再重试请求。

幂等请求示例

以调用CreateStack创建资源栈为例,如果您使用同一个ClientToken值,其他请求参数相同时,则服务端只会返回同一个StackId。如果您不使用ClientToken,在报错重试时,可能会创建多个资源栈。

请求示例

http(s)://ros.aliyuncs.com/?Action=CreateStack
&RegionId=cn-hangzhou
&StackName=MyStack
&TemplateBody={"ROSTemplateFormatVersion": "2015-09-01"}
&ClientToken=123e4567-e89b-12d3-a456-42665544****
&<公共请求参数>

返回示例

{
    "StackId": "4a6c9851-3b0f-4f5f-b4ca-a14bf691****",
    "RequestId": "B288A0BE-D927-4888-B0F7-B35EF84B6E6F"    
}