使用 Lambda 中繼資料端點

Lambda 中繼資料端點可讓您的函數探索他們在哪個可用區域 (AZ) 中執行，讓您能夠透過路由至 Amazon ElastiCache 和 Amazon RDS 端點等相同可用區域資源來最佳化延遲，並實作可用區域感知彈性模式。

端點會透過執行環境中的 localhost 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 擷取 AZ ID (Python)

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

在處理常式中使用中繼資料公用程式：

範例使用 Powertools 擷取 AZ ID (TypeScript)

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 擷取 AZ ID (Java)

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 擷取 AZ ID (.NET)

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"

了解可用區域 IDs

AZ IDs （例如，use1-az1) 一律在所有 AWS 帳戶中參考相同的實體位置，而 AZ 名稱 （例如，us-east-1a) 可能會映射到特定區域中每個 AWS 帳戶中的不同實體基礎設施。如需詳細資訊，請參閱 AZ IDs以取得跨帳戶一致性。

將 AZ ID 轉換為 AZ 名稱：

若要將 AZ ID 轉換為 AZ 名稱，請使用 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 請求中。

Endpoint

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

請求

必要標頭：

• Authorization – 來自具有 Bearer 結構描述之AWS_LAMBDA_METADATA_TOKEN環境變數的字符值：Bearer <token>。此字符型身分驗證可針對伺服器端請求偽造 (SSRF) 漏洞提供深度防禦。每個執行環境都會在初始化時收到唯一的隨機產生字符。

回應

狀態： 200 OK

Content-Type： application/json

快取控制： private, max-age=43200, immutable

回應在執行環境中是不可變的。用戶端應快取回應並遵循 Cache-Control TTL。對於 SnapStart 函數，TTL 會在初始化期間減少，因此當執行環境可能位於不同的可用區域中時，用戶端會在還原後重新整理中繼資料。如果您使用 Powertools，會自動處理快取和 SnapStart 無效。

本文：

{
  "AvailabilityZoneID": "use1-az1"
}

AvailabilityZoneID 欄位包含執行環境執行所在可用區域的唯一識別符。

注意

其他欄位可能會新增至未來更新的回應。用戶端應該忽略未知欄位，如果出現新欄位，則不會失敗。

錯誤回應

• 401 未授權 – Authorization標頭遺失或包含無效的字符。驗證您正在傳遞 Bearer ${AWS_LAMBDA_METADATA_TOKEN}。

• 405 不允許的方法 – 請求方法不是 GET。

• 500 內部伺服器錯誤 – 伺服器端處理錯誤。