您在調用ROS API時，如果發生請求超時或服務器內部錯誤，客戶端可能會嘗試重發請求。您可以在請求中設置ClientToken參數避免多次重試帶來重復操作的問題。

什么是冪等性

在數學計算或者計算機科學中，冪等性（Idempotence）是指相同操作或資源在一次或多次請求中具有同樣效果的作用。冪等性在分布式系統設計中具有十分重要的地位。

保證冪等性

通常情況下，客戶端只需要在HTTP狀態碼返回500 Internal Server Error或503 Service Unavailable錯誤，或者無法獲取響應結果時重試。使用ROS API，您可以從客戶端生成一個參數值不超過64個ASCII字符的字符串，并將值賦予ClientToken，保證重試請求的冪等性。

ClientToken詳解

ClientToken參數的詳細信息如下：

  • ClientToken是一個由客戶端生成的唯一的、區分大小寫、不超過64個ASCII字符的字符串。例如：ClientToken=123e4567-e89b-12d3-a456-42665544****。
  • 如果您提供了一個已經使用過的ClientToken，但其他請求參數有變化，則ROS會返回InvalidIdempotenceParameter的錯誤代碼。
    說明 參數SignatureNonce、Timestamp和Signature在重試時是需要變化的。具體原因是ROS使用SignatureNonce防止重放攻擊，使用Timestamp標記每次請求時間。所以再次請求必須提供不同的SignatureNonce和Timestamp參數值，同時也會導致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"    
}