# 使用 Lambda 元数据端点
<a name="configuration-metadata-endpoint"></a>

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

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

**Topics**
+ [开始使用](#metadata-endpoint-getting-started)
+ [了解可用区 ID](#metadata-endpoint-az-ids)
+ [API 参考](#metadata-endpoint-api-reference)

## 开始使用
<a name="metadata-endpoint-getting-started"></a>

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

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

------
#### [ Python ]

安装 Powertools 软件包：

```
pip install "aws-lambda-powertools"
```

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

**Example 使用 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
```

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

**Example 使用 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>
```

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

**Example 使用 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
```

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

**Example 使用 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。

**Example 直接访问元数据端点**  

```
# 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
<a name="metadata-endpoint-az-ids"></a>

可用区 ID（例如 `use1-az1`）始终指所有 AWS 账户的相同物理位置，而可用区名称（例如 `us-east-1a`）可能映射到特定区域中每个 AWS 账户的不同物理基础设施。有关更多信息，请参阅[跨账户一致性的可用区 ID](https://docs.aws.amazon.com/global-infrastructure/latest/regions/az-ids.html)。

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

要将可用区 ID 转换为可用区名称，请使用 Amazon EC2 [DescribeAvailabilityZones](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeAvailabilityZones.html) API。要使用此 API，请将 `ec2:DescribeAvailabilityZones` 权限添加到函数的执行角色中。

## API 参考
<a name="metadata-endpoint-api-reference"></a>

### 环境变量
<a name="metadata-endpoint-env-vars"></a>

Lambda 在每个执行环境中自动设置以下环境变量：
+ `AWS_LAMBDA_METADATA_API`–`{ipv4_address}:{port}` 元数据服务器地址的格式（例如，`169.254.100.1:9001`）。
+ `AWS_LAMBDA_METADATA_TOKEN`–当前执行环境的唯一身份验证令牌。Lambda 在初始化时会自动生成此令牌。将其包含在所有元数据 API 请求中。

### 端点
<a name="metadata-endpoint-url"></a>

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

### 请求
<a name="metadata-endpoint-request"></a>

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

### 响应
<a name="metadata-endpoint-response"></a>

**状态：** `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` 字段包含运行执行环境的可用区的唯一标识符。

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

### 错误响应
<a name="metadata-endpoint-errors"></a>
+ **401 未授权**–`Authorization` 标头丢失或包含无效标记。验证您是否通过 `Bearer ${AWS_LAMBDA_METADATA_TOKEN}`。
+ **405 方法不允许**–请求方法不是 `GET`。
+ **500 内部服务器错误**–服务器端处理错误。