# Amazon ECS 任务元数据端点版本 4
<a name="task-metadata-endpoint-v4"></a>

Amazon ECS 容器代理会向每个容器注入一个环境变量，称为*任务元数据端点*，它提供了各种任务元数据和 [Docker 统计信息](https://docs.docker.com/engine/api/v1.30/#operation/ContainerStats)添加到容器中。

任务元数据和联网速率统计数据将发送到 CloudWatch 容器洞察，并可在 AWS 管理控制台 中查看。有关更多信息，请参阅 [使用具有增强型可观测性的 Container Insights 监控 Amazon ECS 容器](cloudwatch-container-insights.md)。

**注意**  
Amazon ECS 提供较早版本的任务元数据端点。为避免将来需要创建新的任务元数据端点版本，可能会将其他元数据添加到版本 4 输出中。我们不会删除任何现有元数据或更改元数据字段名称。

原定设置情况下，环境变量会注入到运行至少版本的 Amazon EC2 Linux 实例上启动的 Amazon ECS 任务的容器中 `1.39.0` 的 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` 发出两个 API 请求（一个用于容器实例标签，一个用于任务标签），并且任务中的 Sidecar 容器可以代表您进行这些调用。频繁的端点调用可能会导致 API 节流。  
考虑实施缓存或批处理策略来降低调用频率，尤其是在高流量应用程序中，并使用 AWS CloudTrail 调试 API 节流问题。有关 `ListTagsForResource` API 节流限制的信息，请参阅《Amazon Elastic Container Service API 参考》**中的[请求对 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 API 文档中的 [ContainerStats](https://docs.docker.com/engine/api/v1.30/#operation/ContainerStats)。  
对于使用 `awsvpc` 或 `bridge` 版本托管在运行至少版本 `1.43.0` 的容器代理的Amazon EC2 Linux 实例上的或网络模式的Amazon ECS任务，响应中将包含其他网络速率统计信息。对于所有其他任务，响应将仅包含累积网络统计信息。

`${ECS_CONTAINER_METADATA_URI_V4}/task/stats`  
此路径返回与任务相关的所有容器的 Docker 统计数据 。附加容器可以使用此路径提取网络指标。有关每个返回的统计信息的更多信息，请参阅 Docker API 文档中的 [ContainerStats](https://docs.docker.com/engine/api/v1.30/#operation/ContainerStats)。  
对于使用 `awsvpc` 或 `bridge` 版本托管在运行至少版本 `1.43.0` 的容器代理的Amazon EC2 Linux 实例上的或网络模式的Amazon ECS任务，响应中将包含其他网络速率统计信息。对于所有其他任务，响应将仅包含累积网络统计信息。