Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅
中国的 Amazon Web Services 服务入门
(PDF)。
Lambda 元数据端点允许您的函数发现它们在哪个可用区 (AZ) 中运行，从而使您能够通过路由到 Amazon ElastiCache 和 Amazon RDS 端点等相同可用区资源来优化延迟，并实施可用区感知弹性模式。
端点通过执行环境中的本地主机 HTTP API 以简单 JSON 格式返回元数据，运行时和扩展程序均可访问。
Powertools for Amazon Lambda 提供了一个实用工具，用于在 Python、TypeScript、Java 和.NET 中访问 Lambda 元数据端点。该实用程序会在第一次调用后缓存响应，并自动处理 SnapStart 缓存失效。
使用 Powertools for Amazon 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（例如 use1-az1）始终指所有 Amazon 账户的相同物理位置，而可用区名称（例如 us-east-1a）可能映射到特定区域中每个 Amazon 账户的不同物理基础设施。有关更多信息，请参阅跨账户一致性的可用区 ID。
将可用区 ID 转换为可用区名称：
要将可用区 ID 转换为可用区名称，请使用 Amazon EC2 DescribeAvailabilityZones API。要使用此 API，请将 ec2:DescribeAvailabilityZones 权限添加到函数的执行角色中。
Lambda 在每个执行环境中自动设置以下环境变量：
GET http://${AWS_LAMBDA_METADATA_API}/2026-01-15/metadata/execution-environment
必需的标头：
状态： 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 字段包含运行执行环境的可用区的唯一标识符。
在将来的更新中，可能会在响应中添加其他字段。客户端应忽略未知字段，并且在出现新字段时不会失败。