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

# 使用 EventBridge 自動化因應 Amazon ECS 錯誤
<a name="cloudwatch_event_stream"></a>

使用 Amazon EventBridge，您可以自動化您的 AWS 服務，並自動回應系統事件，例如應用程式可用性問題或資源變更。 AWS 服務的事件會以接近即時的方式傳送到 EventBridge。您可編寫簡單的規則，來指示您在意的事件，以及當事件符合規則時所要自動執行的動作。可以自動設定的動作如下︰
+ 將事件新增至 CloudWatch Logs 中的日誌群組
+ 叫用 AWS Lambda 函數
+ 調用 Amazon EC2 執行命令
+ 將事件轉傳至 Amazon Kinesis Data Streams
+ 啟用 AWS Step Functions 狀態機器
+ 通知 Amazon SNS 主題或 Amazon Simple Queue Service (Amazon SQS) 佇列

如需詳細資訊，請參閱 *《Amazon EventBridge 使用者指南》*中的 [Amazon EventBridge 入門](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html)。

您可以使用適用於 EventBridge 的 Amazon ECS 事件，接收有關您的 Amazon ECS 叢集目前狀態的近乎即時通知。如果任務使用的是 EC2，則可檢視容器執行個體的狀態，以及這些容器執行個體上所有執行中任務的目前狀態。如果任務使用的是 Fargate，則可檢視容器執行個體的狀態。

您可以使用 EventBridge，在 Amazon ECS 上建置自訂排程器，而自訂排程器負責協調叢集之間的任務，並以近乎即時的方式監控叢集狀態。您不需要排定和監控持續輪詢 Amazon ECS 服務以處理狀態變更的程式碼，而是改為使用任意 EventBridge 目標，以非同步的方式處理 Amazon ECS 狀態變更。目標可能包括 AWS Lambda Amazon Simple Queue Service、Amazon Simple Notification Service 或 Amazon Kinesis Data Streams。

Amazon ECS 事件資料流可確保每個事件會至少交付一次。如果傳送重複的事件，則事件會提供足夠的資訊來識別重複項目。如需詳細資訊，請參閱[因應 Amazon ECS 事件](ecs_cwet_handling.md)。

由於事件的排序具有相對性，因此您可以清楚得知事件發生的時間 (相對於其他事件)。

**Topics**
+ [Amazon ECS 事件](ecs_cwe_events.md)
+ [因應 Amazon ECS 事件](ecs_cwet_handling.md)

# Amazon ECS 事件
<a name="ecs_cwe_events"></a>

Amazon ECS 會追蹤每個任務和服務的狀態。如果任務或服務的狀態變更，就會產生事件並將事件傳送到 Amazon EventBridge。系統會將這些事件分類為任務狀態變更事件和服務動作事件。下列各節將更詳細地說明這些事件及其可能原因。

Amazon ECS 會產生下列類型的事件並將其傳送至 EventBridge：
+ 容器執行個體狀態變更
+ 任務狀態變更
+ Deployment state change (部署狀態變更)
+ 服務動作

**注意**  
Amazon ECS 日後可能會新增其他事件類型、來源與詳細資訊。如果透過程式碼將事件 JSON 資料反序列化，請確保應用程式已準備好處理不明屬性，避免日後新增這些額外屬性時出現問題。

在某些情況下，會針對相同的活動產生多個事件。例如，在容器執行個體開始任務時，即會為新的任務產生任務狀態變更事件。系統會針對容器執行個體上可用資源 (例如，CPU、記憶體和可用連接埠) 中的變更，對帳戶產生容器執行個體狀態變更事件。同樣地，如果終止容器執行個體，則會針對容器執行個體、容器代理連線狀態以及在容器執行個體上執行的每個任務產生事件。

容器狀態變更和任務狀態變更事件包含兩個 `version` 欄位：一個位於事件本體，另一個位於事件的 `detail` 物件中。以下說明這兩個欄位之間的差異：
+ 事件本體的 `version` 欄位在所有事件中皆設為 `0`。如需有關 EventBridge 參數的詳細資訊，請參閱 *Amazon EventBridge User Guide* 中的 [AWS service event metadata](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events-structure.html)。
+ 事件之 `detail` 物件中的 `version` 欄位說明相關資源的版本。每次資源變更狀態時，此版本都會遞增。因為事件可以傳送多次，所以此欄位可讓您識別重複的事件。重複事件在 `detail` 物件中具有相同版本。如果您使用 EventBridge 複寫 Amazon ECS 容器執行個體和任務狀態，您可以將 Amazon ECS APIs 回報的資源版本與 EventBridge 中回報的資源版本 （在 `detail` 物件內） 進行比較，以確認事件串流中的版本為最新版本。

服務動作事件只包含本體中的 `version` 欄位。

服務動作事件會透過 2 個不同欄位標明所屬服務：
+ 對於由 `create-service` 產生的事件，服務位於 `serviceName` 欄位中。
+ 對於由 `update-service` 產生的事件，服務位於 `service` 欄位中。

如果您針對服務事件使用自動化工具，則需要為這兩個欄位編寫程式碼。

如需有關如何建立服務動作事件規則的資訊，請參閱 [Amazon ECS 服務動作事件](ecs_service_events.md)。

如需有關如何整合 Amazon ECS 與 EventBridge 的其他資訊，請參閱[整合 Amazon EventBridge 與 Amazon ECS](https://aws.amazon.com/blogs/compute/integrating-amazon-eventbridge-and-amazon-ecs/)。

# Amazon ECS 容器執行個體狀態變更事件
<a name="ecs_container_instance_events"></a>

下列案例會引發容器執行個體狀態變更事件：

您可以呼叫 `StartTask`、`RunTask` 或 `StopTask` API 操作 (可直接或使用 AWS 管理主控台 或軟體開發套件執行此動作)。  
在容器執行個體上放置或停用任務會修改容器執行個體上的可用資源 (例如 CPU、記憶體和可用連接埠)。

Amazon ECS 服務排程器會啟動或停止任務。  
在容器執行個體上放置或停用任務會修改容器執行個體上的可用資源 (例如 CPU、記憶體和可用連接埠)。

Amazon ECS 容器代理程式會呼叫 `SubmitTaskStateChange` API 操作取得所需狀態為 `RUNNING` 之任務的 `STOPPED` 狀態。  
Amazon ECS 容器代理程式會監控容器執行個體上的任務狀態，並報告任何狀態變更。如果應為 `RUNNING` 的任務轉換為 `STOPPED`，則代理程式會釋出配給至已停止任務的資源 (例如 CPU、記憶體和可用連接埠)。

您可以直接使用 `DeregisterContainerInstance` API 操作或使用 或 AWS 管理主控台 SDKs 取消註冊容器執行個體。  
取消登錄容器代理程式會變更容器執行個體的狀態以及 Amazon ECS 容器代理程式的連線狀態。

在 EC2 執行個體停止時，任務即停止。  
當您停止容器執行個體時，在其上執行的任務會轉換為 `STOPPED` 狀態。

Amazon ECS 容器代理程式第一次登錄容器執行個體。  
Amazon ECS 容器代理程式第一次登錄容器執行個體時 (在啟動時，或手動初次執行時)，這會建立執行個體的狀態變更事件。

Amazon ECS 容器代理會與 Amazon ECS 連線或中斷連線。  
Amazon ECS 容器代理程式與 Amazon ECS 後端連線或中斷連線時，會變更容器執行個體的 `agentConnected` 狀態。  
Amazon ECS 容器代理程式在正常操作的過程中，每小時會中斷連線並重新連線數次，因此應預期會發生代理程式連線事件。這些事件並不表示容器代理程式或容器執行個體發生問題。

升級執行個體上的 Amazon ECS 容器代理程式。  
容器執行個體詳細資訊包含容器代理版本的物件。如果您升級代理，則此版本資訊會變更並產生事件。

**Example 容器執行個體狀態變更事件**  
容器執行個體狀態變更事件以下列格式交付。以下 `detail` 區段類似於從 *Amazon Elastic Container Service API 參考*中的 [DescribeContainerInstances](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeContainerInstances.html) API 操作所返回的 [ContainerInstance](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerInstance.html) 物件。如需有關 EventBridge 參數的詳細資訊，請參閱 *Amazon EventBridge User Guide* 中的 [AWS service event metadata](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events-structure.html)。  

```
{
  "version": "0",
  "id": "8952ba83-7be2-4ab5-9c32-6687532d15a2",
  "detail-type": "ECS Container Instance State Change",
  "source": "aws.ecs",
  "account": "111122223333",
  "time": "2016-12-06T16:41:06Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:ecs:us-east-1:111122223333:container-instance/b54a2a04-046f-4331-9d74-3f6d7f6ca315"
  ],
  "detail": {
    "agentConnected": true,
    "attributes": [
      {
        "name": "com.amazonaws.ecs.capability.logging-driver.syslog"
      },
      {
        "name": "com.amazonaws.ecs.capability.task-iam-role-network-host"
      },
      {
        "name": "com.amazonaws.ecs.capability.logging-driver.awslogs"
      },
      {
        "name": "com.amazonaws.ecs.capability.logging-driver.json-file"
      },
      {
        "name": "com.amazonaws.ecs.capability.docker-remote-api.1.17"
      },
      {
        "name": "com.amazonaws.ecs.capability.privileged-container"
      },
      {
        "name": "com.amazonaws.ecs.capability.docker-remote-api.1.18"
      },
      {
        "name": "com.amazonaws.ecs.capability.docker-remote-api.1.19"
      },
      {
        "name": "com.amazonaws.ecs.capability.ecr-auth"
      },
      {
        "name": "com.amazonaws.ecs.capability.docker-remote-api.1.20"
      },
      {
        "name": "com.amazonaws.ecs.capability.docker-remote-api.1.21"
      },
      {
        "name": "com.amazonaws.ecs.capability.docker-remote-api.1.22"
      },
      {
        "name": "com.amazonaws.ecs.capability.docker-remote-api.1.23"
      },
      {
        "name": "com.amazonaws.ecs.capability.task-iam-role"
      }
    ],
    "clusterArn": "arn:aws:ecs:us-east-1:111122223333:cluster/default",
    "containerInstanceArn": "arn:aws:ecs:us-east-1:111122223333:container-instance/b54a2a04-046f-4331-9d74-3f6d7f6ca315",
    "ec2InstanceId": "i-f3a8506b",
    "registeredResources": [
      {
        "name": "CPU",
        "type": "INTEGER",
        "integerValue": 2048
      },
      {
        "name": "MEMORY",
        "type": "INTEGER",
        "integerValue": 3767
      },
      {
        "name": "PORTS",
        "type": "STRINGSET",
        "stringSetValue": [
          "22",
          "2376",
          "2375",
          "51678",
          "51679"
        ]
      },
      {
        "name": "PORTS_UDP",
        "type": "STRINGSET",
        "stringSetValue": []
      }
    ],
    "remainingResources": [
      {
        "name": "CPU",
        "type": "INTEGER",
        "integerValue": 1988
      },
      {
        "name": "MEMORY",
        "type": "INTEGER",
        "integerValue": 767
      },
      {
        "name": "PORTS",
        "type": "STRINGSET",
        "stringSetValue": [
          "22",
          "2376",
          "2375",
          "51678",
          "51679"
        ]
      },
      {
        "name": "PORTS_UDP",
        "type": "STRINGSET",
        "stringSetValue": []
      }
    ],
    "status": "ACTIVE",
    "version": 14801,
    "versionInfo": {
      "agentHash": "aebcbca",
      "agentVersion": "1.13.0",
      "dockerVersion": "DockerVersion: 1.11.2"
    },
    "updatedAt": "2016-12-06T16:41:06.991Z"
  }
}
```

# Amazon ECS 任務狀態變更事件
<a name="ecs_task_events"></a>

下列案例會引發任務狀態變更事件：

您可以呼叫 `StartTask`、`RunTask` 或 `StopTask` API 操作 (可直接或使用 AWS 管理主控台、 AWS CLI或軟體開發套件執行此動作)。  
啟動或停止任務會建立新的任務資源，或修改現有任務資源的狀態。

Amazon ECS 服務排程器會啟動或停止任務。  
啟動或停止任務會建立新的任務資源，或修改現有任務資源的狀態。

Amazon ECS 容器代理程序會呼叫 `SubmitTaskStateChange` API 操作。  
若使用的是 EC2，Amazon ECS 容器代理程式會監控容器執行個體上任務的狀態。Amazon ECS 容器代理程式會回報所有狀態變更。狀態變更可能包括從 `PENDING` 到 `RUNNING` 或從 `RUNNING` 到 `STOPPED` 的變更。

您可以使用 `DeregisterContainerInstance` API 操作和 `force`旗標，直接或使用 或 AWS 管理主控台 SDKs，強制取消基礎容器執行個體的註冊。  
取消登錄容器代理程式會變更容器執行個體的狀態以及 Amazon ECS 容器代理程式的連線狀態。如果任務是在容器執行個體上執行，則必須將 `force` 旗標設定為允許取消登錄。這會停止執行個體上的所有任務。

停止或終止基礎容器執行個體。  
當您停止或終止容器執行個體時，在其上執行的任務會轉換為 `STOPPED` 狀態。

任務中的容器變更狀態。  
Amazon ECS 容器代理程序會監控任務內的容器狀態。例如，如果任務內的執行容器停止，則此容器狀態變更會產生事件。

使用 Fargate Spot 容量提供者的任務會收到終止通知。  
當任務使用 `FARGATE_SPOT` 容量提供者且因 Spot 中斷而停止時，會產生任務狀態變更事件。

**Example 任務狀態變更事件**  
任務狀態變更事件以下列格式交付。請注意下列關於欄位的事項：  
+ 任務狀態變更事件中不提供事件的運作狀態。如果您需要任務的運作狀態，可以執行 [describe-tasks](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html)。
+ 當容器使用 Amazon ECR 託管的映像時，會傳回 `imageDigest` 欄位。
+ `createdAt`、`connectivityAt`、`pullStartedAt`、`startedAt`、`pullStoppedAt` 與 `updatedAt` 欄位的值為 ISO 字串時間戳記。
+ `detail-type` 值為「ECS 任務狀態變更」。
+ 當為已停止的任務產生事件時，`stoppedReason` 與 `stopCode` 欄位會提供有關任務停止原因的其他資訊 (例如「使用者啟動」)。
如需有關 EventBridge 參數的詳細資訊，請參閱 *Amazon EventBridge Events Reference* 中的 [AWS service event metadata](https://docs.aws.amazon.com/eventbridge/latest/ref/events-structure.html)。  
如需有關如何設定 Amazon EventBridge 事件規則 (僅擷取因任務的一個必要容器已終止而導致任務停止執行的任務事件) 的資訊，請參閱[針對 Amazon ECS 任務停止事件傳送 Amazon Simple Notification Service 提醒](ecs_cwet2.md)  

```
{
    "version": "0",
    "id": "105f6bb1-4da6-c630-4965-35383018cbca",
    "detail-type": "ECS Task State Change",
    "source": "aws.ecs",
    "account": "123456789012",
    "time": "2025-05-06T11:02:34Z",
    "region": "us-east-1",
    "resources": [
        "arn:aws:ecs:us-east-1:123456789012:task/example-cluster/a1173316d40a45dea9"
    ],
    "detail": {
        "attachments": [
            {
                "id": "fe3a9a46-6a47-40ee-afd9-7952ae90a75a",
                "type": "eni",
                "status": "ATTACHED",
                "details": [
                    {
                        "name": "subnetId",
                        "value": "subnet-0d0eab1bb38d5ca64"
                    },
                    {
                        "name": "networkInterfaceId",
                        "value": "eni-0103a2f01bad57d71"
                    },
                    {
                        "name": "macAddress",
                        "value": "0e:50:d1:c1:77:81"
                    },
                    {
                        "name": "privateDnsName",
                        "value": "ip-10-0-1-163.ec2.internal"
                    },
                    {
                        "name": "privateIPv4Address",
                        "value": "10.0.1.163"
                    }
                ]
            }
        ],
        "attributes": [
            {
                "name": "ecs.cpu-architecture",
                "value": "x86_64"
            }
        ],
        "availabilityZone": "us-east-1b",
        "capacityProviderName": "FARGATE",
        "clusterArn": "arn:aws:ecs:us-east-1:123456789012:cluster/example-cluster",
        "connectivity": "CONNECTED",
        "connectivityAt": "2025-05-06T11:02:17.19Z",
        "containers": [
            {
                "containerArn": "arn:aws:ecs:us-east-1:123456789012:container/example-cluster/a1173316d40a45dea9/a0a99b87-baa8-4bf6-b9f1-a9a95917a635",
                "lastStatus": "RUNNING",
                "name": "web",
                "image": "nginx",
                "imageDigest": "sha256:c15da6c91de8d2f436196f3a768483ad32c258ed4e1beb3d367a27ed67253e66",
                "runtimeId": "a1173316d40a45dea9-0265927825",
                "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example-cluster/a1173316d40a45dea9",
                "networkInterfaces": [
                    {
                        "attachmentId": "fe3a9a46-6a47-40ee-afd9-7952ae90a75a",
                        "privateIpv4Address": "10.0.1.163"
                    }
                ],
                "cpu": "99",
                "memory": "100"
            },
            {
                "containerArn": "arn:aws:ecs:us-east-1:123456789012:container/example-cluster/a1173316d40a45dea9/a2010e2d-ba7c-4135-8b79-e0290ff3cd8c",
                "lastStatus": "RUNNING",
                "name": "aws-guardduty-agent-nm40lC",
                "imageDigest": "sha256:bf9197abdf853607e5fa392b4f97ccdd6ca56dd179be3ce8849e552d96582ac8",
                "runtimeId": "a1173316d40a45dea9-2098416933",
                "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example-cluster/a1173316d40a45dea9",
                "networkInterfaces": [
                    {
                        "attachmentId": "fe3a9a46-6a47-40ee-afd9-7952ae90a75a",
                        "privateIpv4Address": "10.0.1.163"
                    }
                ],
                "cpu": "null"
            },
            {
                "containerArn": "arn:aws:ecs:us-east-1:123456789012:container/example-cluster/a1173316d40a45dea9/dccf0ca2-d929-471f-a5c3-98006fd4379e",
                "lastStatus": "RUNNING",
                "name": "aws-otel-collector",
                "image": "public.ecr.aws/aws-observability/aws-otel-collector:v0.32.0",
                "imageDigest": "sha256:7a1b3560655071bcacd66902c20ebe9a69470d5691fe3bd36baace7c2f3c4640",
                "runtimeId": "a1173316d40a45dea9-4027662657",
                "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example-cluster/a1173316d40a45dea9",
                "networkInterfaces": [
                    {
                        "attachmentId": "fe3a9a46-6a47-40ee-afd9-7952ae90a75a",
                        "privateIpv4Address": "10.0.1.163"
                    }
                ],
                "cpu": "0"
            }
        ],
        "cpu": "256",
        "createdAt": "2025-05-06T11:02:13.877Z",
        "desiredStatus": "RUNNING",
        "enableExecuteCommand": false,
        "ephemeralStorage": {
            "sizeInGiB": 20
        },
        "group": "family:webserver",
        "launchType": "FARGATE",
        "lastStatus": "RUNNING",
        "memory": "512",
        "overrides": {
            "containerOverrides": [
                {
                    "name": "web"
                },
                {
                    "environment": [
                        {
                            "name": "CLUSTER_NAME",
                            "value": "example-cluster"
                        },
                        {
                            "name": "REGION",
                            "value": "us-east-1"
                        },
                        {
                            "name": "HOST_PROC",
                            "value": "/host_proc"
                        },
                        {
                            "name": "AGENT_RUNTIME_ENVIRONMENT",
                            "value": "ecsfargate"
                        },
                        {
                            "name": "STAGE",
                            "value": "prod"
                        }
                    ],
                    "memory": 128,
                    "name": "aws-guardduty-agent-nm40lC"
                },
                {
                    "name": "aws-otel-collector"
                }
            ]
        },
        "platformVersion": "1.4.0",
        "pullStartedAt": "2025-05-06T11:02:24.162Z",
        "pullStoppedAt": "2025-05-06T11:02:33.493Z",
        "startedAt": "2025-05-06T11:02:34.325Z",
        "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example-cluster/a1173316d40a45dea9",
        "taskDefinitionArn": "arn:aws:ecs:us-east-1:123456789012:task-definition/webserver:5",
        "updatedAt": "2025-05-06T11:02:34.325Z",
        "version": 3
    }
}
```

**Example**  
以下是 EC2 任務狀態變更事件的範例。  

```
{
    "version": "0",
    "id": "a65cf262-f104-0dd5-ceda-4b09ba71a441",
    "detail-type": "ECS Task State Change",
    "source": "aws.ecs",
    "account": "123456789012",
    "time": "2025-05-12T13:12:06Z",
    "region": "us-east-1",
    "resources": [
        "arn:aws:ecs:us-east-1:123456789012:task/example/c1ffa94f19a540ed8d9f7e1d2a5d"
    ],
    "detail": {
        "attachments": [
            {
                "id": "52333e3b-b812-41a8-b057-9ed184bbe5e1",
                "type": "eni",
                "status": "ATTACHED",
                "details": [
                    {
                        "name": "subnetId",
                        "value": "subnet-0d0eab1bb38d5ca64"
                    },
                    {
                        "name": "networkInterfaceId",
                        "value": "eni-0ea90f746500773a4"
                    },
                    {
                        "name": "macAddress",
                        "value": "0e:d5:9b:ce:49:fb"
                    },
                    {
                        "name": "privateDnsName",
                        "value": "ip-10-0-1-37.ec2.internal"
                    },
                    {
                        "name": "privateIPv4Address",
                        "value": "10.0.1.37"
                    }
                ]
            }
        ],
        "attributes": [
            {
                "name": "ecs.cpu-architecture",
                "value": "x86_64"
            }
        ],
        "availabilityZone": "us-east-1b",
        "capacityProviderName": "Infra-ECS-Cluster-example-fa84e0cc-AsgCapacityProvider-OseQJU9pizmp",
        "clusterArn": "arn:aws:ecs:us-east-1:123456789012:cluster/example",
        "connectivity": "CONNECTED",
        "connectivityAt": "2025-05-12T13:11:44.98Z",
        "containerInstanceArn": "arn:aws:ecs:us-east-1:123456789012:container-instance/example/d1d84798400f49f3b21cb61610c1e",
        "containers": [
            {
                "containerArn": "arn:aws:ecs:us-east-1:123456789012:container/example/c1ffa94f19a540ed8d9f7e1d2a5d3626/197d0994-5367-4a6d-9f9a-f075e4a6",
                "lastStatus": "RUNNING",
                "name": "aws-otel-collector",
                "image": "public.ecr.aws/aws-observability/aws-otel-collector:v0.32.0",
                "imageDigest": "sha256:7a1b3560655071bcacd66902c20ebe9a69470d5691fe3bd36baace7c2f3c4640",
                "runtimeId": "8e926f0ccd8fe2b459926f49584ba6d33a3d9f61398dbabe944ee6a13a8ff3a1",
                "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example/c1ffa94f19a540ed8d9f7e1d2a5d",
                "networkInterfaces": [
                    {
                        "attachmentId": "52333e3b-b812-41a8-b057-9ed184bbe5e1",
                        "privateIpv4Address": "10.0.1.37"
                    }
                ],
                "cpu": "0"
            },
            {
                "containerArn": "arn:aws:ecs:us-east-1:123456789012:container/example/c1ffa94f19a540ed8d9f7e1d2a5d3626/cab39ef0-9c50-459d-844b-b9d51d73d",
                "lastStatus": "RUNNING",
                "name": "web",
                "image": "nginx",
                "imageDigest": "sha256:c15da6c91de8d2f436196f3a768483ad32c258ed4e1beb3d367a27ed67253e66",
                "runtimeId": "9f1c73f0094f051541d9e5c2ab1e172d83c4eb5171bcc857c4504b02770ff3b8",
                "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example/c1ffa94f19a540ed8d9f7e1d2a5d",
                "networkInterfaces": [
                    {
                        "attachmentId": "52333e3b-b812-41a8-b057-9ed184bbe5e1",
                        "privateIpv4Address": "10.0.1.37"
                    }
                ],
                "cpu": "99",
                "memory": "100"
            }
        ],
        "cpu": "256",
        "createdAt": "2025-05-12T13:11:44.98Z",
        "desiredStatus": "RUNNING",
        "enableExecuteCommand": false,
        "group": "family:webserver",
        "launchType": "EC2",
        "lastStatus": "RUNNING",
        "memory": "512",
        "overrides": {
            "containerOverrides": [
                {
                    "name": "aws-otel-collector"
                },
                {
                    "name": "web"
                }
            ]
        },
        "pullStartedAt": "2025-05-12T13:11:59.491Z",
        "pullStoppedAt": "2025-05-12T13:12:05.896Z",
        "startedAt": "2025-05-12T13:12:06.053Z",
        "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example/c1ffa94f19a540ed8d9f7e1d2a5d",
        "taskDefinitionArn": "arn:aws:ecs:us-east-1:123456789012:task-definition/webserver",
        "updatedAt": "2025-05-12T13:12:06.053Z",
        "version": 4
    }
}
```

# Amazon ECS 服務動作事件
<a name="ecs_service_events"></a>

Amazon ECS 會傳送具有 **ECS Service Action** (ECS 服務動作) 詳細類型的服務動作事件。與容器執行個體和任務狀態變更事件不同，服務動作事件不會在 `details` 回應欄位中包含版本號碼。以下這個事件模式會用來建立 Amazon ECS 服務動作事件的 EventBridge 規則。如需詳細資訊，請參閱 *Amazon EventBridge User Guide* 中的 [Getting started with EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html)。

```
{
    "source": [
        "aws.ecs"
    ],
    "detail-type": [
        "ECS Service Action"
    ]
}
```

Amazon ECS 會傳送具有 `INFO`、`WARN` 和 `ERROR` 事件類型的事件。以下是服務動作事件。

## 具有 `INFO` 事件類型的服務動作事件
<a name="ecs_service_events_info_type"></a>

`SERVICE_STEADY_STATE`  
服務運作狀況良好且有所需的任務數量，因而達到穩定狀態。服務排程器會定期報告狀態，因此您可能會多次收到此訊息。

`TASKSET_STEADY_STATE`  
任務集運作狀況良好且有所需的任務數量，因而達到穩定的狀態。

`CAPACITY_PROVIDER_STEADY_STATE`  
與服務相關聯的容量提供者會達到穩定狀態。

`SERVICE_DESIRED_COUNT_UPDATED`  
服務排程器更新適用於服務或任務集的計算所需計數時。當使用者手動更新所需的計數時，不會傳送此事件。

`TASKS_STOPPED`  
服務已停止執行中的任務。

`SERVICE_DEPLOYMENT_IN_PROGRESS`  
一項服務部署正在進行中。服務部署可為復原作業，也可為新的服務修訂版。

`SERVICE_DEPLOYMENT_COMPLETED`  
服務部署處於穩定狀態且已完成。服務部署可為復原作業，也可為部署更新後的服務修訂版。

## 具有 `WARN` 事件類型的服務動作事件
<a name="ecs_service_events_warn_type"></a>

`SERVICE_TASK_START_IMPAIRED`  
此服務無法成功持續啟動任務。

`SERVICE_DISCOVERY_INSTANCE_UNHEALTHY`  
使用服務探索的服務包含運作狀況不良的任務。服務排程器會偵測到服務登錄中的任務運作狀況不良。

`VPC_LATTICE_TARGET_UNHEALTHY`  
使用 VPC Lattice 的服務偵測到 VPC Lattice 某一個目標的運作狀態不良。

## 具有 `ERROR` 事件類型的服務動作事件
<a name="ecs_service_events_error_type"></a>

`SERVICE_DAEMON_PLACEMENT_CONSTRAINT_VIOLATED`  
使用 `DAEMON` 服務排程器策略的服務中的任務不再符合此服務的放置限制策略。

`ECS_OPERATION_THROTTLED`  
由於 Amazon ECS API 限流限制，服務排程器已經受到限流控管。

`SERVICE_DISCOVERY_OPERATION_THROTTLED`  
由於 AWS Cloud Map API 限流限制，服務排程器已調節。這可能會在設定為使用服務探索的服務上發生。

`SERVICE_TASK_PLACEMENT_FAILURE`  
服務排程器無法放置任務。原因的描述位於 `reason` 欄位中。  
產生此服務事件的常見原因是因為叢集缺乏放置任務的資源。例如，可用的容器執行個體沒有足夠的 CPU 或記憶體容量，或沒有可用的容器執行個體。另一個常見原因是，若容器執行個體上的 Amazon ECS 容器代理程式連線中斷，會造成排程器無法放置任務。

`SERVICE_TASK_CONFIGURATION_FAILURE`  
由於組態錯誤，服務排程器無法放置任務。原因的描述位於 `reason` 欄位中。  
產生此服務事件的常見原因是因為標籤正在套用至服務，但使用者或角色尚未在區域中選擇使用新的 Amazon Resource Name (ARN) 格式。如需詳細資訊，請參閱[Amazon Resource Name (ARN) 和 ID](ecs-account-settings.md#ecs-resource-ids)。另一個常見的原因是 Amazon ECS 無法擔任所提供的任務 IAM 角色。

`SERVICE_HEALTH_UNKNOWN`  
服務無法描述任務的運作狀態資料。

`SERVICE_DEPLOYMENT_FAILED`  
服務部署未達到穩定狀態。當 CloudWatch 被觸發或斷路器偵測到服務部署失敗時，就會發生這種情況。

**Example 服務穩定狀態事件**  
任務穩定狀態事件以下列格式交付。如需有關 EventBridge 參數的詳細資訊，請參閱 *Amazon EventBridge User Guide* 中的 [Events in EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html)。  

```
{
    "version": "0",
    "id": "af3c496d-f4a8-65d1-70f4-a69d52e9b584",
    "detail-type": "ECS Service Action",
    "source": "aws.ecs",
    "account": "111122223333",
    "time": "2019-11-19T19:27:22Z",
    "region": "us-west-2",
    "resources": [
        "arn:aws:ecs:us-west-2:111122223333:service/default/servicetest"
    ],
    "detail": {
        "eventType": "INFO",
        "eventName": "SERVICE_STEADY_STATE",
        "clusterArn": "arn:aws:ecs:us-west-2:111122223333:cluster/default",
        "createdAt": "2019-11-19T19:27:22.695Z"
    }
}
```

**Example 容量提供者穩定狀態事件**  
容量提供者穩定狀態事件以下列格式交付。  

```
{
    "version": "0",
    "id": "b9baa007-2f33-0eb1-5760-0d02a572d81f",
    "detail-type": "ECS Service Action",
    "source": "aws.ecs",
    "account": "111122223333",
    "time": "2019-11-19T19:37:00Z",
    "region": "us-west-2",
    "resources": [
        "arn:aws:ecs:us-west-2:111122223333:service/default/servicetest"
    ],
    "detail": {
        "eventType": "INFO",
        "eventName": "CAPACITY_PROVIDER_STEADY_STATE",
        "clusterArn": "arn:aws:ecs:us-west-2:111122223333:cluster/default",
        "capacityProviderArns": [
            "arn:aws:ecs:us-west-2:111122223333:capacity-provider/ASG-tutorial-capacity-provider"
        ],
        "createdAt": "2019-11-19T19:37:00.807Z"
    }
}
```

**Example 服務任務啟動受損事件**  
服務任務啟動受損事件以下列格式交付。  

```
{
    "version": "0",
    "id": "57c9506e-9d21-294c-d2fe-e8738da7e67d",
    "detail-type": "ECS Service Action",
    "source": "aws.ecs",
    "account": "111122223333",
    "time": "2019-11-19T19:55:38Z",
    "region": "us-west-2",
    "resources": [
        "arn:aws:ecs:us-west-2:111122223333:service/default/servicetest"
    ],
    "detail": {
        "eventType": "WARN",
        "eventName": "SERVICE_TASK_START_IMPAIRED",
        "clusterArn": "arn:aws:ecs:us-west-2:111122223333:cluster/default",
        "createdAt": "2019-11-19T19:55:38.725Z"
    }
}
```

**Example 服務任務放置失敗事件**  
服務任務放置失敗事件以下列格式交付。如需詳細資訊，請參閱 *Amazon EventBridge User Guide* 中的 [Events in EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html)。  
在下列範例中，此任務嘗試使用 `FARGATE_SPOT` 容量提供者，但服務排程器無法取得任何 Fargate Spot 容量。  

```
{
    "version": "0",
    "id": "ddca6449-b258-46c0-8653-e0e3a6d0468b",
    "detail-type": "ECS Service Action",
    "source": "aws.ecs",
    "account": "111122223333",
    "time": "2019-11-19T19:55:38Z",
    "region": "us-west-2",
    "resources": [
        "arn:aws:ecs:us-west-2:111122223333:service/default/servicetest"
    ],
    "detail": {
        "eventType": "ERROR",
        "eventName": "SERVICE_TASK_PLACEMENT_FAILURE",
        "clusterArn": "arn:aws:ecs:us-west-2:111122223333:cluster/default",
        "capacityProviderArns": [
            "arn:aws:ecs:us-west-2:111122223333:capacity-provider/FARGATE_SPOT"
        ],
        "reason": "RESOURCE:FARGATE",
        "createdAt": "2019-11-06T19:09:33.087Z"
    }
}
```
在下列 EC2 範例中，嘗試在容器執行個體 `2dd1b186f39845a584488d2ef155c131` 上啟動任務，但由於 CPU 不足，服務排程器無法置放任務。  

```
{
  "version": "0",
  "id": "ddca6449-b258-46c0-8653-e0e3a6d0468b",
  "detail-type": "ECS Service Action",
  "source": "aws.ecs",
  "account": "111122223333",
  "time": "2019-11-19T19:55:38Z",
  "region": "us-west-2",
  "resources": [
    "arn:aws:ecs:us-west-2:111122223333:service/default/servicetest"
  ],
  "detail": {
    "eventType": "ERROR",
    "eventName": "SERVICE_TASK_PLACEMENT_FAILURE",
    "clusterArn": "arn:aws:ecs:us-west-2:111122223333:cluster/default",
    "containerInstanceArns": [
    "arn:aws:ecs:us-west-2:111122223333:container-instance/default/2dd1b186f39845a584488d2ef155c131"
    ],
    "reason": "RESOURCE:CPU",
    "createdAt": "2019-11-06T19:09:33.087Z"
  }
}
```

# Amazon ECS 服務部署狀態變更事件
<a name="ecs_service_deployment_events"></a>

Amazon ECS 會傳送具有 **ECS Deployment State Change** (ECS 部署狀態變更) 詳細類型的服務部署變更狀態事件。以下這個事件模式會用來建立 Amazon ECS 服務部署狀態變更事件的 EventBridge 規則。如需有關建立 EventBridge 規則的詳細資訊，請參閱 *Amazon EventBridge User Guide* 中的 [Getting started with Amazon EventBridge ](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html)。

```
{
    "source": [
        "aws.ecs"
    ],
    "detail-type": [
        "ECS Deployment State Change"
    ]
}
```

Amazon ECS 會傳送具有 `INFO` 和 `ERROR` 事件類型的事件。如需詳細資訊，請參閱[Amazon ECS 服務動作事件](ecs_service_events.md)

以下是服務部署狀態變更事件。

`SERVICE_DEPLOYMENT_IN_PROGRESS`  
服務部署正在進行。此事件會被傳送用於初始部署和回復部署。

`SERVICE_DEPLOYMENT_COMPLETED`  
服務部署完成。一旦服務在部署後達到穩定狀態，此事件將被傳送。

`SERVICE_DEPLOYMENT_FAILED`  
服務部署失敗。此事件會被傳送用於開啟部署斷路器邏輯的服務。

**Example 服務部署正在進行事件**  
服務部署正在進行事件會在初始和回復部署均已開始時交付。兩者之間的區別位於 `reason` 欄位。如需有關 EventBridge 參數的詳細資訊，請參閱 *Amazon EventBridge User Guide* 中的 [AWS service event metadata](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events-structure.html)。  
下列顯示初始部署開始的輸出範例。  

```
{
   "version": "0",
   "id": "ddca6449-b258-46c0-8653-e0e3a6EXAMPLE",
   "detail-type": "ECS Deployment State Change",
   "source": "aws.ecs",
   "account": "111122223333",
   "time": "2020-05-23T12:31:14Z",
   "region": "us-west-2",
   "resources": [ 
        "arn:aws:ecs:us-west-2:111122223333:service/default/servicetest"
   ],
   "detail": {
        "eventType": "INFO", 
        "eventName": "SERVICE_DEPLOYMENT_IN_PROGRESS",
        "deploymentId": "ecs-svc/123",
        "updatedAt": "2020-05-23T11:11:11Z",
        "reason": "ECS deployment deploymentId in progress."
   }
}
```
下列顯示回復部署開始的輸出範例。`reason` 欄位提供服務轉返至的部署 ID。  

```
{
   "version": "0",
   "id": "ddca6449-b258-46c0-8653-e0e3aEXAMPLE",
   "detail-type": "ECS Deployment State Change",
   "source": "aws.ecs",
   "account": "111122223333",
   "time": "2020-05-23T12:31:14Z",
   "region": "us-west-2",
   "resources": [ 
        "arn:aws:ecs:us-west-2:111122223333:service/default/servicetest"
   ],
   "detail": {
        "eventType": "INFO", 
        "eventName": "SERVICE_DEPLOYMENT_IN_PROGRESS",
        "deploymentId": "ecs-svc/123",
        "updatedAt": "2020-05-23T11:11:11Z",
        "reason": "ECS deployment circuit breaker: rolling back to deploymentId deploymentID."
   }
}
```

**Example 服務部署完成事件**  
任務部署完成狀態事件以下列格式交付。如需詳細資訊，請參閱[透過取代任務來部署 Amazon ECS 服務](deployment-type-ecs.md)。  

```
{
   "version": "0",
   "id": "ddca6449-b258-46c0-8653-e0e3aEXAMPLE",
   "detail-type": "ECS Deployment State Change",
   "source": "aws.ecs",
   "account": "111122223333",
   "time": "2020-05-23T12:31:14Z",
   "region": "us-west-2",
   "resources": [ 
        "arn:aws:ecs:us-west-2:111122223333:service/default/servicetest"
   ],
   "detail": {
        "eventType": "INFO", 
        "eventName": "SERVICE_DEPLOYMENT_COMPLETED",
        "deploymentId": "ecs-svc/123",
        "updatedAt": "2020-05-23T11:11:11Z",
        "reason": "ECS deployment deploymentID completed."
   }
}
```

**Example 服務部署失敗事件**  
任務部署失敗狀態事件以下列格式交付。服務部署失敗狀態事件只會被傳送用於開啟部署斷路器邏輯的服務。如需詳細資訊，請參閱[透過取代任務來部署 Amazon ECS 服務](deployment-type-ecs.md)。  

```
{
   "version": "0",
   "id": "ddca6449-b258-46c0-8653-e0e3aEXAMPLE",
   "detail-type": "ECS Deployment State Change",
   "source": "aws.ecs",
   "account": "111122223333",
   "time": "2020-05-23T12:31:14Z",
   "region": "us-west-2",
   "resources": [ 
        "arn:aws:ecs:us-west-2:111122223333:service/default/servicetest"
   ],
   "detail": {
        "eventType": "ERROR", 
        "eventName": "SERVICE_DEPLOYMENT_FAILED",
        "deploymentId": "ecs-svc/123",
        "updatedAt": "2020-05-23T11:11:11Z",
        "reason": "ECS deployment circuit breaker: task failed to start."
   }
}
```

# 因應 Amazon ECS 事件
<a name="ecs_cwet_handling"></a>

Amazon ECS 會傳送事件*至少一次*。這表示您可能會收到指定事件的多個副本。此外，可能不會依事件發生順序將事件交付至事件接聽程式。

為了正確排序事件，每個事件的 `detail` 區段都會包含 `version` 屬性。每次資源變更狀態時，此 `version` 都會遞增。重複事件在 `detail` 物件中具有相同的 `version`。如果您使用 EventBridge 複寫 Amazon ECS 容器執行個體和任務狀態，您可以將 Amazon ECS APIs 回報的資源版本與 EventBridge 中`version`回報的資源版本進行比較，以驗證事件串流中的版本是否為最新版本。較高版本屬性編號的事件應該視為比較低版本編號的事件晚發生。

## 範例：處理 AWS Lambda 函數中的事件
<a name="ecs_cwet_handling_example"></a>

下列範例顯示使用 Python 3.9 撰寫的 Lambda 函數，以同時擷取任務和容器執行個體狀態變更事件，並將其儲存至兩個 Amazon DynamoDB 資料表中的其中一個：
+ *ECSCtrInstanceState*：存放容器執行個體的最新狀態。資料表 ID 是容器執行個體的 `containerInstanceArn` 值。
+ *ECSTaskState*：存放任務的最新狀態。資料表 ID 是任務的 `taskArn` 值。

```
import json
import boto3

def lambda_handler(event, context):
    id_name = ""
    new_record = {}

    # For debugging so you can see raw event format.
    print('Here is the event:')
    print((json.dumps(event)))

    if event["source"] != "aws.ecs":
       raise ValueError("Function only supports input from events with a source type of: aws.ecs")

    # Switch on task/container events.
    table_name = ""
    if event["detail-type"] == "ECS Task State Change":
        table_name = "ECSTaskState"
        id_name = "taskArn"
        event_id = event["detail"]["taskArn"]
    elif event["detail-type"] == "ECS Container Instance State Change":
        table_name = "ECSCtrInstanceState"
        id_name =  "containerInstanceArn"
        event_id = event["detail"]["containerInstanceArn"]
    else:
        raise ValueError("detail-type for event is not a supported type. Exiting without saving event.")

    new_record["cw_version"] = event["version"]
    new_record.update(event["detail"])

    # "status" is a reserved word in DDB, but it appears in containerPort
    # state change messages.
    if "status" in event:
        new_record["current_status"] = event["status"]
        new_record.pop("status")


    # Look first to see if you have received a newer version of an event ID.
    # If the version is OLDER than what you have on file, do not process it.
    # Otherwise, update the associated record with this latest information.
    print("Looking for recent event with same ID...")
    dynamodb = boto3.resource("dynamodb", region_name="us-east-1")
    table = dynamodb.Table(table_name)
    saved_event = table.get_item(
        Key={
            id_name : event_id
        }
    )
    if "Item" in saved_event:
        # Compare events and reconcile.
        print(("EXISTING EVENT DETECTED: Id " + event_id + " - reconciling"))
        if saved_event["Item"]["version"] < event["detail"]["version"]:
            print("Received event is a more recent version than the stored event - updating")
            table.put_item(
                Item=new_record
            )
        else:
            print("Received event is an older version than the stored event - ignoring")
    else:
        print(("Saving new event - ID " + event_id))

        table.put_item(
            Item=new_record
        )
```

下列範例顯示使用 Python 3.9 撰寫的 Lambda 函式，其功能為擷取任務狀態變更事件，並將這些事件儲存至下列 Amazon DynamoDB 資料表：

```
import json
import boto3

def lambda_handler(event, context):
    id_name = ""
    new_record = {}

    # For debugging so you can see raw event format.
    print('Here is the event:')
    print((json.dumps(event)))

    if event["source"] != "aws.ecs":
       raise ValueError("Function only supports input from events with a source type of: aws.ecs")

    # Switch on task/container events.
    table_name = ""
    if event["detail-type"] == "ECS Task State Change":
        table_name = "ECSTaskState"
        id_name = "taskArn"
        event_id = event["detail"]["taskArn"]
    else:
        raise ValueError("detail-type for event is not a supported type. Exiting without saving event.")

    new_record["cw_version"] = event["version"]
    new_record.update(event["detail"])

    # "status" is a reserved word in DDB, but it appears in containerPort
    # state change messages.
    if "status" in event:
        new_record["current_status"] = event["status"]
        new_record.pop("status")


    # Look first to see if you have received a newer version of an event ID.
    # If the version is OLDER than what you have on file, do not process it.
    # Otherwise, update the associated record with this latest information.
    print("Looking for recent event with same ID...")
    dynamodb = boto3.resource("dynamodb", region_name="us-east-1")
    table = dynamodb.Table(table_name)
    saved_event = table.get_item(
        Key={
            id_name : event_id
        }
    )
    if "Item" in saved_event:
        # Compare events and reconcile.
        print(("EXISTING EVENT DETECTED: Id " + event_id + " - reconciling"))
        if saved_event["Item"]["version"] < event["detail"]["version"]:
            print("Received event is a more recent version than the stored event - updating")
            table.put_item(
                Item=new_record
            )
        else:
            print("Received event is an older version than the stored event - ignoring")
    else:
        print(("Saving new event - ID " + event_id))

        table.put_item(
            Item=new_record
        )
```