# 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 小时）。在这段时间内，您的任务不会因来自服务自动扩缩或部署的横向缩减事件而终止。在这段时间过后，`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'
```

**如何保护 Windows 容器任务 60 分钟的示例**

此示例显示了如何在 PowerShell 中使用 `expiresInMinutes` 参数保护任务 60 分钟。

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

**如何保护 Windows 容器任务 24 小时的示例**

此示例显示了如何在 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 时间。如果任务未受到保护，则此值为 null。

`ProtectionEnabled`  
任务的保护状态。如果为任务启用了横向缩减保护，则值为 `true`。否则为 `false`。

`TaskArn`  
容器所属的任务的完整 Amazon 资源名称（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 资源名称（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 资源名称（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"
  }
}
```