# Amazon ECS 작업 메타데이터 엔드포인트 버전 4
<a name="task-metadata-endpoint-v4"></a>

Amazon ECS 컨테이너 에이전트가 *태스크 메타데이터 엔드포인트*라고 하는 각 컨테이너에 환경 변수를 주입합니다. 이 컨테이너는 다양한 태스크 메타데이터와 [Docker 통계](https://docs.docker.com/engine/api/v1.30/#operation/ContainerStats)를 컨테이너에 제공합니다.

태스크 메타데이터와 네트워크 속도 통계는 CloudWatch Container Insights로 전송되고 AWS Management Console에서 확인할 수 있습니다. 자세한 정보는 [관찰성이 향상된 Container Insights를 사용하여 Amazon ECS 컨테이너 모니터링](cloudwatch-container-insights.md)을 참조하세요.

**참고**  
Amazon ECS는 이전 버전의 태스크 메타데이터 엔드포인트를 제공합니다. 나중에 새 태스크 메타데이터 엔드포인트 버전을 생성할 필요가 없도록 버전 4 출력에 메타데이터를 추가할 수 있습니다. 기존 메타데이터를 제거하거나 메타데이터 필드 이름을 변경하지 않습니다.

환경 변수는 기본적으로 Amazon ECS 컨테이너 에이전트 버전 `1.39.0` 이상을 실행하는 Amazon EC2 Linux 인스턴스에서 시작된 Amazon ECS 태스크의 컨테이너에 주입됩니다. `awsvpc` 네트워크 모드를 사용하는 Amazon EC2 Windows 인스턴스의 경우, Amazon ECS 컨테이너 에이전트 버전이 `1.54.0` 이상이어야 합니다. 자세한 내용은 [Amazon ECS Linux 컨테이너 인스턴스 관리](manage-linux.md) 섹션을 참조하세요.

**참고**  
에이전트를 최신 버전으로 업데이트하여 이전 버전의 Amazon ECS 컨테이너 인스턴스를 사용하여 Amazon EC2 인스턴스에서 이 기능에 대한 지원을 추가할 수 있습니다. 자세한 내용은 [Amazon ECS 컨테이너 에이전트 업데이트](ecs-agent-update.md) 섹션을 참조하세요.

태스크 메타데이터 예제 출력은 [Amazon ECS 작업 메타데이터 v4 예제](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint-v4-examples.html)를 참조하세요.

## 태스크 메타데이터 엔드포인트 버전 4 경로
<a name="task-metadata-endpoint-v4-paths"></a>

다음의 태스크 메타데이터 엔드포인트 경로를 컨테이너에 사용할 수 있습니다.

`${ECS_CONTAINER_METADATA_URI_V4}`  
이 경로는 컨테이너에 대한 메타데이터를 반환합니다.

`${ECS_CONTAINER_METADATA_URI_V4}/task`  
이 경로는 태스크와 연결된 모든 컨테이너의 컨테이너 ID 및 이름 목록을 포함하여 작업에 대한 메타데이터를 반환합니다. 이 엔드포인트의 응답에 대한 자세한 내용은 [Amazon ECS 작업 메타데이터 V4 JSON 응답](task-metadata-endpoint-v4-response.md) 섹션을 참조하세요.

`${ECS_CONTAINER_METADATA_URI_V4}/taskWithTags`  
이 경로는 `ListTagsForResource` API를 사용하여 검색할 수 있는 태스크와 컨테이너 인스턴스 태그 외에도 `/task` 엔드포인트에 포함된 태스크에 대한 메타데이터를 반환합니다. 태그 메타데이터를 검색하면서 수신한 오류는 응답의 `Errors` 필드에 포함됩니다.  
`Errors` 필드는 컨테이너 에이전트 버전`1.50.0` 이상을 실행하는 Amazon EC2 Linux 인스턴스에서 호스팅되는 태스크에 대한 응답에만 포함됩니다. `awsvpc` 네트워크 모드를 사용하는 Amazon EC2 Windows 인스턴스의 경우, Amazon ECS 컨테이너 에이전트 버전이 `1.54.0` 이상이어야 합니다.  
이 엔드포인트에는 `ecs.ListTagsForResource` 권한이 필요합니다.
`${ECS_CONTAINER_METADATA_URI_V4}/taskWithTags` 엔드포인트를 사용하는 경우 직접 호출할 때마다 `ecs:ListTagsForResource`에 대한 최대 2번의 API 요청(컨테이너 인스턴스 태그 및 태스크 태그에 한 번씩)을 수행하고 태스크의 사이드카 컨테이너는 사용자를 대신해 이 직접 호출을 수행합니다. 엔드포인트 직접 호출이 잦으면 API 스로틀링이 발생할 수 있습니다.  
특히 트래픽이 높은 애플리케이션에서 직접 호출 빈도를 줄이기 위해 캐싱이나 배치 처리 전략을 구현하고 AWS CloudTrail을 사용해 API 스로틀링을 디버깅하는 방법을 고려하세요. `ListTagsForResource` API의 스로틀링 제한에 대한 자세한 내용은 *Amazon Elastic Container Service API 참조*의 [Request throttling for the Amazon ECS API](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/request-throttling.html)를 참조하세요. AWS CloudTrail을 사용해 Amazon ECS API 직접 호출을 디버깅하는 방법에 대한 자세한 내용은 [AWS CloudTrail을 사용하여 Amazon ECS API 직접 호출 로깅](logging-using-cloudtrail.md) 섹션을 참조하세요.

`${ECS_CONTAINER_METADATA_URI_V4}/stats`  
이 경로는 특정 Docker 컨테이너에 대한 Docker 통계를 반환합니다. 반환된 각 통계에 대한 자세한 내용은 Docker API 설명서의 [ContainerStats](https://docs.docker.com/engine/api/v1.30/#operation/ContainerStats)를 참조하세요.  
컨테이너 에이전트 버전 `1.43.0` 이상을 실행하는 Amazon EC2 Linux 인스턴스에서 호스팅되고 `awsvpc` 또는 `bridge` 네트워크 모드를 사용하는 Amazon ECS 태스크의 경우, 응답에 추가적 네트워크 속도 통계가 포함됩니다. 그 외에 다른 모든 태스크는 응답에 누적 네트워크 통계만 포함됩니다.

`${ECS_CONTAINER_METADATA_URI_V4}/task/stats`  
이 경로는 태스크와 연결된 모든 컨테이너에 대한 Docker 통계를 반환합니다. 사이드카 컨테이너에서 네트워크 지표를 추출하는 데 사용할 수 있습니다. 반환된 각 통계에 대한 자세한 내용은 Docker API 설명서의 [ContainerStats](https://docs.docker.com/engine/api/v1.30/#operation/ContainerStats)를 참조하세요.  
컨테이너 에이전트 버전 `1.43.0` 이상을 실행하는 Amazon EC2 Linux 인스턴스에서 호스팅되고 `awsvpc` 또는 `bridge` 네트워크 모드를 사용하는 Amazon ECS 태스크의 경우, 응답에 추가적 네트워크 속도 통계가 포함됩니다. 그 외에 다른 모든 태스크는 응답에 누적 네트워크 통계만 포함됩니다.