更新时间:2022-09-22 GMT+08:00

请求幂等性说明

当您调用ECS API操作资源时,操作可能在完成之前超时或遇到其他服务器问题,客户端可能会尝试重试请求。如果原始请求和后续重试请求都成功执行,则操作将多次完成。这意味着您可能会创建比预期更多的资源。

为了解决这种问题,引入了请求幂等标识,通过针对幂等请求标识的一系列判断检查,服务端将识别当前请求是否为重试请求,进而进行下一步处理。

什么是请求幂等性

请求幂等性,指的是同样的请求被执行一次与连续执行多次的效果是一样的。换句话说就是,幂等方法不应该具有副作用(统计用途除外)。

如何保证请求幂等性

客户端在发送请求时,可以在HTTP请求消息头中增加X-Client-Token作为幂等性标识,字段描述参见表1

表1 幂等标识消息头

名称

描述

是否必选

示例

X-Client-Token

保证客户端请求幂等性的标识。

该标识为32位UUID格式,由客户端生成,且需确保不同请求之间该标识具有唯一性。

46436810-d999-454c-bd85-e515fd258600

通常情况下,客户端只需要在服务端内部异常、连接超时等响应状态码为5xx的错误,或者无法获取响应结果重试请求。重试请求仍然使用相同的幂等标识和请求参数,则服务端会返回与第一次请求相同的请求结果。

幂等标识的详细信息如下所示:

  • 幂等标识是一个大小写敏感的32位UUID,其格式为:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12),其中每个 x 是 0-9 或 a-f 范围内的一个十六进制的数字。如果您提供了一个非UUID格式的标识,则服务端会返回Ecs.0123错误码。
  • 幂等标识需要具有唯一性,如果您提供了一个已经使用过的标识,但请求参数有变化,则服务端会返回Ecs.0122错误码。
  • 幂等标识具有时效性(8小时),如果您提供了一个已经失效的标识,则服务端会返回Ecs.0124错误码。
  • 使用幂等标识后:
    • 返回结果状态码为2xx时,重试后客户端可以得到与上次相同的结果,但对您的服务端状态没有影响。
    • 返回结果状态码为4xx时,重试不会成功。您需要根据错误信息排查问题后再重试请求。

支持幂等设置的API列表

以下API支持设置X-Client-Token请求头,保证请求幂等性。