使用 Lambda 元数据端点 - AWS Lambda
开始使用了解可用区 IDAPI 参考

使用 Lambda 元数据端点

Lambda 元数据端点允许您的函数发现它们在哪个可用区 (AZ) 中运行，从而使您能够通过路由到 Amazon ElastiCache 和 Amazon RDS 端点等相同可用区资源来优化延迟，并实施可用区感知弹性模式。

端点通过执行环境中的本地主机 HTTP API 以简单 JSON 格式返回元数据，运行时和扩展程序均可访问。

开始使用

Powertools for AWS Lambda 提供了一个实用工具，用于在 Python、TypeScript、Java 和.NET 中访问 Lambda 元数据端点。该实用程序会在第一次调用后缓存响应，并自动处理 SnapStart 缓存失效。

使用 Powertools for AWS Lambda 元数据实用程序或直接调用元数据端点

Python

安装 Powertools 软件包：

pip install "aws-lambda-powertools"

在处理程序中使用元数据实用程序：

例使用 Powertools (Python) 检索可用区 ID
from aws_lambda_powertools.utilities.lambda_metadata import get_lambda_metadata

def handler(event, context):
    metadata = get_lambda_metadata()
    az_id = metadata.availability_zone_id  # e.g., "use1-az1"

    return {"az_id": az_id}
TypeScript

安装 Powertools 软件包：

npm install @aws-lambda-powertools/commons

在处理程序中使用元数据实用程序：

例使用 owertools (TypeScript) 检索可用区 ID
import { getMetadata } from '@aws-lambda-powertools/commons/utils/metadata';

const metadata = await getMetadata();

export const handler = async () => {
  const { AvailabilityZoneID: azId } = metadata;
  return azId;
};
Java

将 Powertools 依赖项添加到 pom.xml：

<dependencies>
    <dependency>
        <groupId>software.amazon.lambda</groupId>
        <artifactId>powertools-lambda-metadata</artifactId>
        <version>2.10.0</version>
    </dependency>
</dependencies>

在处理程序中使用元数据客户端：

例使用 Powertools (Java) 检索可用区 ID
import software.amazon.lambda.powertools.metadata.LambdaMetadata;
import software.amazon.lambda.powertools.metadata.LambdaMetadataClient;

public class App implements RequestHandler<Object, String> {

    @Override
    public String handleRequest(Object input, Context context) {
        LambdaMetadata metadata = LambdaMetadataClient.get();
        String azId = metadata.getAvailabilityZoneId(); // e.g., "use1-az1"

        return "{\"azId\": \"" + azId + "\"}";
    }
}
.NET

安装 Powertools 软件包：

dotnet add package AWS.Lambda.Powertools.Metadata

在处理程序中使用元数据类：

例使用 Powertools (.NET) 检索可用区 ID
using AWS.Lambda.Powertools.Metadata;

public class Function
{
    public string Handler(object input, ILambdaContext context)
    {
        var azId = LambdaMetadata.AvailabilityZoneId;
        return $"Running in AZ: {azId}";
    }
}
All Runtimes

所有 Lambda 运行时都支持元数据端点，包括自定义运行时和容器映像。使用下面的示例，您可以使用 Lambda 在执行环境中自动设置的环境变量，直接从函数访问元数据 API。

例直接访问元数据端点
# Variables are automatically set by Lambda
METADATA_ENDPOINT="http://${AWS_LAMBDA_METADATA_API}/2026-01-15/metadata/execution-environment"

# Make the request
RESPONSE=$(curl -s -H "Authorization: Bearer ${AWS_LAMBDA_METADATA_TOKEN}" "$METADATA_ENDPOINT")

# Parse the AZ ID
AZ_ID=$(echo "$RESPONSE" | jq -r '.AvailabilityZoneID')

echo "Function is running in AZ ID: $AZ_ID"

了解可用区 ID

可用区 ID（例如 use1-az1）始终指所有 AWS 账户的相同物理位置，而可用区名称（例如 us-east-1a）可能映射到特定区域中每个 AWS 账户的不同物理基础设施。有关更多信息，请参阅跨账户一致性的可用区 ID。

将可用区 ID 转换为可用区名称：

要将可用区 ID 转换为可用区名称，请使用 Amazon EC2 DescribeAvailabilityZones API。要使用此 API，请将 ec2:DescribeAvailabilityZones 权限添加到函数的执行角色中。

API 参考

环境变量

Lambda 在每个执行环境中自动设置以下环境变量：

  • AWS_LAMBDA_METADATA_API–{ipv4_address}:{port} 元数据服务器地址的格式（例如，169.254.100.1:9001）。

  • AWS_LAMBDA_METADATA_TOKEN–当前执行环境的唯一身份验证令牌。Lambda 在初始化时会自动生成此令牌。将其包含在所有元数据 API 请求中。

端点

GET http://${AWS_LAMBDA_METADATA_API}/2026-01-15/metadata/execution-environment

请求

必需的标头：

  • Authorization–来自 AWS_LAMBDA_METADATA_TOKEN 环境变量的令牌值，使用 Bearer 方案：Bearer <token>。这种基于令牌的身份验证提供了针对服务器端请求伪造 (SSRF) 漏洞的深度防御。每个执行环境在初始化时都会收到一个随机生成的唯一令牌。

响应

状态： 200 OK

Content-Type: application/json

Cache-Control: private, max-age=43200, immutable

响应在执行环境中不可更改。客户端应缓存响应并遵守 Cache-Control TTL。对于 SnapStart 函数，TTL 会在初始化期间降低，因此当执行环境可能位于不同的可用区时，客户端可以在还原后刷新元数据。如果使用 Powertools，缓存和 SnapStart 失效会自动处理。

Body:

{
  "AvailabilityZoneID": "use1-az1"
}

AvailabilityZoneID 字段包含运行执行环境的可用区的唯一标识符。

注意

在将来的更新中，可能会在响应中添加其他字段。客户端应忽略未知字段，并且在出现新字段时不会失败。

错误响应

  • 401 未授权–Authorization 标头丢失或包含无效标记。验证您是否通过 Bearer ${AWS_LAMBDA_METADATA_TOKEN}。

  • 405 方法不允许–请求方法不是 GET。

  • 500 内部服务器错误–服务器端处理错误。