# Amazon ECS タスクスケールイン保護のエンドポイント
<a name="task-scale-in-protection-endpoint"></a>

Amazon ECS コンテナエージェントは、`ECS_AGENT_URI` 環境変数を Amazon ECS タスクのコンテナに自動的に挿入して、コンテナエージェント API エンドポイントとやり取りする方法を提供します。

保護の必要性を自己判断できるタスクには、Amazon ECS コンテナエージェントエンドポイントを使用することをお勧めします。

コンテナが処理を開始すると、コンテナ内からタスクスケールイン保護のエンドポイントパス「`protectionEnabled`」を使用して `$ECS_AGENT_URI/task-protection/v1/state` 属性を設定できます。

コンテナ内からこの 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 コンテナの場合、curl の代わりに PowerShell の `Invoke-RestMethod` コマンドレットを使用できます。次の例は、前の 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 時間保護する方法の例**

この例では、`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`  
タスクの保護が期限切れになるエポックタイム。タスクが保護されていない場合、この値は 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"
  }
}
```