本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

確保冪等性

當您執行變動操作時，您可能會因為資源變動後發生的逾時或伺服器問題而看到例外狀況。這可能會導致難以判斷變動是否發生，並可能導致多次重試。不過，如果原始操作和後續重試確實執行了變動，您可能已套用堆疊變更或建立比您預期更多的資源。等冪性可確保 操作不會變更資源超過一次。使用等冪請求時，如果原始請求成功變動，任何後續重試都會成功完成，而不會執行任何進一步的變動。

Amazon ECS 中的冪等性

下列 API 動作可選擇性地使用用戶端字符支援冪等性。對應的 AWS CLI 命令也支援使用用戶端字符的冪等性。用戶端字符是唯一的區分大小寫字串。若要使用其中一個動作提出等冪 API 請求，請在請求中指定用戶端字符。您不應該在其他 API 請求中重複使用相同的用戶端字符。如果您重試使用相同用戶端字符和相同參數成功完成的請求，則重試會成功，而無需執行任何進一步的動作。

RunTask 的冪等性

RunTask API 支援使用用戶端字符的冪等性。用戶端標記是您在提出 API 請求時指定的唯一字串。如果您在成功完成後使用相同的用戶端標記和相同的請求參數重試 API 請求，則會傳回原始請求的結果。如果您使用相同的用戶端字符重試成功請求，但一或多個參數不同於區域或可用區域，則重試會失敗並顯示 ConflictException。如果您未指定自己的用戶端字符， AWS SDK 和 AWS Command Line Interface 會自動為請求產生用戶端字符，以確保其具有等冪性。用戶端字符可以是包含 33-126 （包含） 範圍內最多 64 個 ASCII 字元的任何字串。

RunTask 用戶端字符的存留時間 (TTL) 為 24 小時。您不應該為不同的請求重複使用相同的用戶端字符。用戶端字符最大 TTL 對以下兩個值中的任一個值都有效：

RunTask 重試規則和回應

當您因為收到 5xx 例外狀況而重試請求時，重試的成功回應通常會包含原始請求傳回的所有資訊。在一小時內停止的任務僅包含任務 ARN、最後狀態和所需狀態。

以下是當有一個執行中的任務、一個已停止的任務和一個無法啟動的任務時，重試的回應程式碼片段範例。

{
  "failures": [
    {
      "arn": "arn:aws:ecs:us-east-1:123456789012:container/4df26bb4-f057-467b-a079-961675296e64",
      "reason": "RESOURCE:MEMORY"
    }
  ],
  "tasks": [
    {
      "desiredStatus": "RUNNING",
      "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/default/fdf2c302-468c-4e55-b884-5331d816e7fb",
      ...
    },
    {
      "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/default/fdf2c302-468c-4e55-b884-5331d819999",
      "lastStatus": "STOPPED",
      ...
     }
  ]
}

超過一小時的故障只會包含失敗的任務數量。

範例

AWS CLI 命令範例

若要讓 AWS CLI 命令成為等冪，請新增 --client-token選項。

範例：create-service

下列 create-service 命令使用冪等性，因為它包含用戶端字符。

aws ecs create-service \
    --cluster MyCluster \
    --service MyService \
    --task-definition MyTaskDefinition:2 \
    --desired-count 2 \
    --launch-type FARGATE \
    --platform-version LATEST \
    --network-configuration "awsvpcConfiguration={subnets=["subnet-12344321"],securityGroups=["sg-12344321"],assignPublicIp="ENABLED"}" \
    --client-token 550e8400-e29b-41d4-a716-44665544

範例：create-task-set

下列 create-task-set 命令使用冪等性，因為它包含用戶端字符。

aws ecs create-task-set \
    --cluster MyCluster \
    --service MyService \
    --task-definition MyTaskDefinition:2 \
    --network-configuration "awsvpcConfiguration={subnets=["subnet-12344321"],securityGroups=["sg-12344321"]}" \
    --client-token 550e8400-e29b-41d4-a716-44665544

範例：run-task

下列 run-task 命令使用冪等性，因為它包含用戶端字符。

aws ecs run-task \
    --cluster MyCluster \
    --task-definition MyTaskDefinition:2 \
    --client-token 550e8400-e29b-41d4-a716-446655440000

API 請求範例

若要讓 API 請求具有等冪性，請新增 clientToken 參數。

範例：CreateService

下列 CreateService API 請求使用冪等性，因為它包含用戶端字符。

POST / HTTP/1.1
Host: ecs.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 87
X-Amz-Target: AmazonEC2ContainerServiceV20141113.CreateService
X-Amz-Date: 20150429T170125Z
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS

{
  "serviceName": "MyService",
  "taskDefinition": "MyTaskDefinition:2",
  "desiredCount": 10,
   "capacityProviderStrategy": [ 
      { 
         "base": "number",
         "capacityProvider": "FARGATE",
         "weight": 1
      }
   ],
   "capacityProviderStrategy": [ 
      { 
         "base": "number",
         "capacityProvider": "FARGATE_SPOT",
         "weight": 1
      }
   ],
   "clientToken": "550e8400-e29b-41d4-a716-44665544"
}

範例：CreateTaskSet

下列 CreateTaskSet API 請求使用冪等性，因為它包含用戶端字符。

POST / HTTP/1.1
Host: ecs.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 87
X-Amz-Target: AmazonEC2ContainerServiceV20141113.CreateTaskSet
X-Amz-Date: 20150429T170125Z
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS

{
  "serviceName": "MyService",
  "taskDefinition": "mytask:1",
  "desiredCount": 1,
   "capacityProviderStrategy": [ 
      { 
         "base": "number",
         "capacityProvider": "FARGATE",
         "weight": 1
      }
   ],
   "capacityProviderStrategy": [ 
      { 
         "base": "number",
         "capacityProvider": "FARGATE_SPOT",
         "weight": 1
      }
   ],
    "clientToken": "550e8400-e29b-41d4-a716-44665544" 
}

範例：RunTask

下列 RunTask API 請求使用冪等性，因為它包含用戶端字符。

POST / HTTP/1.1
Host: ecs.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 45
X-Amz-Target: AmazonEC2ContainerServiceV20141113.RunTask
X-Amz-Date: 20161121T215740Z
User-Agent: aws-cli/1.11.13 Python/2.7.12 Darwin/16.1.0 botocore/1.4.66
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS

{
  "count": 1,
  "taskDefinition": "mytask:1",
  "clientToken": "550e8400-e29b-41d4-a716-446655440000" 
}

等冪請求的重試建議

下表顯示您可能會從等冪 API 請求得到的一些常見回應，並提供重試建議。