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

# Amazon ECS 任務縮減保護端點
<a name="task-scale-in-protection-endpoint"></a>

Amazon ECS 容器代理程式會自動將 `ECS_AGENT_URI` 環境變體注入 Amazon ECS 任務的容器中，以提供與容器代理程式 API 端點互動的方法。

我們建議將 Amazon ECS 容器代理程式端點，用於可自行判斷是否需要保護的任務。

當容器開始處理工作時，您可以從容器內透過任務縮減保護端點路徑 `$ECS_AGENT_URI/task-protection/v1/state` 來設定 `protectionEnabled` 屬性。

從容器內對此 URI 發送 PUT 請求，設定任務縮減保護。對此 URI 的 GET 請求將傳回任務的目前保護狀態。

## 任務縮減保護請求參數
<a name="task-scale-in-protection-request"></a>

您可以使用具有下列請求參數的 `${ECS_AGENT_URI}/task-protection/v1/state` 端點來設定任務縮減保護。

`ProtectionEnabled`  
指定 `true` 來標記任務以實現保護。指定 `false` 以移除保護，並讓任務符合終止資格。  
類型：布林值  
必要：是

`ExpiresInMinutes`  
任務受到保護的分鐘數。您可以指定最短 1 分鐘到最長 2,880 分鐘 (48 小時)。在此期間，您的任務不會因 Service Auto Scaling 或部署中的縮減事件而終止。在此時段過後，將 `protectionEnabled` 參數設為 `false`。  
如果您未指定時間，則會自動保護任務 120 分鐘 (2 小時)。  
類型：整數  
必要：否

下列範例示範如何設定具有不同時段的任務保護。

**如何使用預設時段保護任務的範例**

此範例示範如何保護預設時段為 2 小時的任務。

```
curl --request PUT --header 'Content-Type: application/json' ${ECS_AGENT_URI}/task-protection/v1/state --data '{"ProtectionEnabled":true}'
```

**60 分鐘保護任務的範例**

此範例示範如何使用 `expiresInMinutes` 參數保護任務 60 分鐘。

```
curl --request PUT --header 'Content-Type: application/json' ${ECS_AGENT_URI}/task-protection/v1/state --data '{"ProtectionEnabled":true,"ExpiresInMinutes":60}'      
```

**24 小時保護任務的範例**

此範例示範如何使用 `expiresInMinutes` 參數保護任務 24 小時。

```
curl --request PUT --header 'Content-Type: application/json' ${ECS_AGENT_URI}/task-protection/v1/state --data '{"ProtectionEnabled":true,"ExpiresInMinutes":1440}'      
```

**Windows 容器範例**

對於 Windows 容器，您可以使用 PowerShell 的 `Invoke-RestMethod` cmdlet 而非 curl。下列範例展示了與先前 curl 命令等效的 PowerShell 命令。

**使用預設時段保護 Windows 容器任務的範例**

此範例說明如何使用 PowerShell 以預設的 2 小時時段保護任務。

```
Invoke-RestMethod -Uri $env:ECS_AGENT_URI/task-protection/v1/state -Method Put -Body '{"ProtectionEnabled":true}' -ContentType 'application/json'
```

**60 分鐘保護 Windows 容器任務的範例**

此範例說明如何搭配 PowerShell 使用 `expiresInMinutes` 參數保護任務 60 分鐘。

```
Invoke-RestMethod -Uri $env:ECS_AGENT_URI/task-protection/v1/state -Method Put -Body '{"ProtectionEnabled":true,"ExpiresInMinutes":60}' -ContentType 'application/json'
```

**24 小時保護 Windows 容器任務的範例**

此範例說明如何搭配 PowerShell 使用 `expiresInMinutes` 參數保護任務 24 小時。

```
Invoke-RestMethod -Uri $env:ECS_AGENT_URI/task-protection/v1/state -Method Put -Body '{"ProtectionEnabled":true,"ExpiresInMinutes":1440}' -ContentType 'application/json'
```

PUT 請求將傳回以下回應。

```
{
  "protection": {
    "ExpirationDate": "2023-12-20T21:57:44.837Z",
    "ProtectionEnabled": true,
    "TaskArn": "arn:aws:ecs:us-west-2:111122223333:task/1234567890abcdef0"
  }
}
```

## 任務縮減保護回應參數
<a name="task-scale-in-protection-response"></a>

JSON 回應中的任務縮減保護端點 `${ECS_AGENT_URI}/task-protection/v1/state` 會傳回下列資訊。

`ExpirationDate`  
任務保護將到期的時間 (以 Epoch 時間表示)。如果任務未受到保護，則此值將為空。

`ProtectionEnabled`  
任務的保護狀態。如果已針對任務啟用縮減保護，則值為 `true`。否則為 `false`。

`TaskArn`  
容器所屬任務的完整 Amazon Resource Name (ARN)。

下列範例顯示了為受保護任務傳回的詳細資訊。

```
curl --request GET ${ECS_AGENT_URI}/task-protection/v1/state
```

對於 Windows 容器，請使用下列 PowerShell 命令來取得保護狀態：

```
Invoke-RestMethod -Uri $env:ECS_AGENT_URI/task-protection/v1/state -Method Get
```

```
{
    "protection":{
        "ExpirationDate":"2023-12-20T21:57:44Z",
        "ProtectionEnabled":true,
        "TaskArn":"arn:aws:ecs:us-west-2:111122223333:task/1234567890abcdef0"
    }
}
```

發生失敗時會傳回下列資訊。

`Arn`  
任務的完整 Amazon Resource Name (ARN)。

`Detail`  
與失敗相關的詳細資訊。

`Reason`  
失敗的原因。

下列範例顯示了為未保護任務傳回的詳細資訊。

```
{
    "failure":{
        "Arn":"arn:aws:ecs:us-west-2:111122223333:task/1234567890abcdef0",
        "Detail":null,
        "Reason":"TASK_NOT_VALID"
    }
}
```

發生例外狀況時會傳回下列資訊。

`requestID`  
造成例外狀況的 Amazon ECS API 呼叫 AWS 請求 ID。

`Arn`  
任務或服務的完整 Amazon Resource Name (ARN)。

`Code`  
錯誤代碼。

`Message`  
錯誤訊息。  
如果出現 `RequestError` 或 `RequestTimeout` 錯誤，則可能是聯網問題。嘗試對 Amazon ECS 使用 VPC 端點。

以下範例顯示了發生錯誤時傳回的詳細資訊。

```
{
    "requestID":"12345-abc-6789-0123-abc",
    "error":{
        "Arn":"arn:aws:ecs:us-west-2:555555555555:task/my-cluster-name/1234567890abcdef0",
        "Code":"AccessDeniedException",
        "Message":"User: arn:aws:sts::444455556666:assumed-role/my-ecs-task-role/1234567890abcdef0 is not authorized to perform: ecs:GetTaskProtection on resource: arn:aws:ecs:us-west-2:555555555555:task/test/1234567890abcdef0 because no identity-based policy allows the ecs:GetTaskProtection action"
    }    
}
```

如果 Amazon ECS 代理程式因為網路問題或 Amazon ECS 控制平面關閉等原因而無法從 Amazon ECS 端點獲得回應，則會出現下列錯誤。

```
{
  "error": {
    "Arn": "arn:aws:ecs:us-west-2:555555555555:task/my-cluster-name/1234567890abcdef0",
    "Code": "RequestCanceled",
    "Message": "Timed out calling Amazon ECS Task Protection API"
  }
}
```

當 Amazon ECS 代理程式從 Amazon ECS 中取得限流例外狀況時，會出現下列錯誤。

```
{
  "requestID": "12345-abc-6789-0123-abc",
  "error": {
    "Arn": "arn:aws:ecs:us-west-2:555555555555:task/my-cluster-name/1234567890abcdef0",
    "Code": "ThrottlingException",
    "Message": "Rate exceeded"
  }
}
```