本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 確保冪等性
當您執行變動操作時，您可能會因為資源變動後發生的逾時或伺服器問題而看到例外狀況。這可能會導致難以判斷變動是否發生，並可能導致多次重試。不過，如果原始操作和後續重試確實執行了變動，您可能已套用堆疊變更或建立比您預期更多的資源。等冪性可確保 操作不會變更資源超過一次。使用等冪請求時，如果原始請求成功變動，任何後續重試都會成功完成，而不會執行任何進一步的變動。
**Topics**
+ [Amazon ECS 中的冪等性](#client-tokens)
+ [RunTask 的冪等性](#RunTaskIdempotency)
+ [範例](#Run_Task_Idempotency_CLI)
+ [等冪請求的重試建議](#recommended-actions)
## Amazon ECS 中的冪等性
下列 API 動作可選擇性地使用*用戶端字符*支援冪等性。對應的 AWS CLI 命令也支援使用用戶端字符的冪等性。用戶端字符是唯一的區分大小寫字串。若要使用其中一個動作提出等冪 API 請求，請在請求中指定用戶端字符。您不應該在其他 API 請求中重複使用相同的用戶端字符。如果您重試使用相同用戶端字符和相同參數成功完成的請求，則重試會成功，而無需執行任何進一步的動作。
**使用用戶端字符的等冪**
+ CreateService
用戶端字符最多可以有 36 個 ASCII 字元，範圍為 33-126 （含）。
+ CreateTaskSet
用戶端字符最多可以有 36 個 ASCII 字元，範圍為 33-126 （含）。
+ RunTask
用戶端字符最多可以有 64 個 ASCII 字元，範圍為 33-126 （含）。
**等冪的類型**
+ 叢集 – 相同叢集中具有相同字符的請求是等冪的。例如，ClientToken A 只能作為叢集 X 中`RunTask`請求的請求參數使用一次。對其他叢集的`RunTask`請求會被視為單獨的請求。因此，您可以使用 ClientToken A 來`RunTask`請求叢集 Y。
## RunTask 的冪等性
`RunTask` API 支援使用用戶端字符的冪等性。用戶端標記是您在提出 API 請求時指定的唯一字串。如果您在成功完成後使用相同的用戶端標記和相同的請求參數重試 API 請求，則會傳回原始請求的結果。如果您使用相同的用戶端字符重試成功請求，但一或多個參數不同於區域或可用區域，則重試會失敗並顯示 `ConflictException`。如果您未指定自己的用戶端字符， AWS SDK 和 AWS Command Line Interface 會自動為請求產生用戶端字符，以確保其具有等冪性。用戶端字符可以是包含 33-126 （包含） 範圍內最多 64 個 ASCII 字元的任何字串。
`RunTask` 用戶端字符的存留時間 (TTL) 為 24 小時。您不應該為不同的請求重複使用相同的用戶端字符。用戶端字符最大 TTL 對以下兩個值中的任一個值都有效：
+ 24 小時
+ 資源的生命週期加上一小時
資源的生命週期是建立任務的時間戳記，轉換為最後一個狀態 (`lastStatus`) 轉換為 的時間戳記`STOPPED`。當您使用 `RunTask`啟動多個任務時，資源的生命週期等於轉換為 的最後一個任務的生命週期`STOPPED`。
### 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](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-service.html#examples) 命令使用冪等性，因為它包含用戶端字符。
```
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](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-task-set.html#examples) 命令使用冪等性，因為它包含用戶端字符。
```
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](https://docs.aws.amazon.com/cli/latest/reference/ecs/run-task.html#examples) 命令使用冪等性，因為它包含用戶端字符。
```
aws ecs run-task \
--cluster MyCluster \
--task-definition MyTaskDefinition:2 \
--client-token 550e8400-e29b-41d4-a716-446655440000
```
### API 請求範例
若要讓 API 請求具有等冪性，請新增 `clientToken` 參數。
**範例：CreateService**
下列 [CreateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html) 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](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateTaskSet.html) 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](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html) 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 請求得到的一些常見回應，並提供重試建議。
| 回應 | 建議 | 說明 |
| --- | --- | --- |
| 200 (OK) | 請勿重試 | 原始請求已成功完成。任何後續的重試都會成功傳回。 |
| 400 系列回應代碼 ([用戶端錯誤](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/errors-overview.html#CommonErrors)) | 請勿重試 | 請求有下列方面的問題：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonECS/latest/developerguide/ECS_Idempotency.html)
如果請求涉及處於變更狀態過程的資源，則重試請求有可能會成功。 |
| 500 系列回應代碼 ([伺服器錯誤](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/errors-overview.html#api-error-codes-table-server)) | 重試 | 錯誤是由 AWS 伺服器端問題造成，通常是暫時性的。使用適當的退避策略重複請求。 |