Usar o endpoint de metadados Lambda

O endpoint de metadados do Lambda permite que suas funções do Lambda identifiquem em qual Zona de Disponibilidade (AZ) estão sendo executadas, possibilitando a otimização da latência por meio do roteamento para recursos na mesma AZ, como o Amazon ElastiCache e os endpoints do Amazon RDS, além de permitir a implementação de padrões de resiliência que levam em conta a AZ.

O endpoint retorna metadados em um formato JSON simples por meio de uma API HTTP no localhost dentro do ambiente de execução e está acessível tanto aos runtimes quanto às extensões.

Introdução

O Powertools para AWS Lambda fornece um utilitário para acessar o endpoint de metadados do Lambda em Python, TypeScript, Java e .NET. O utilitário armazena a resposta em cache após a primeira chamada e lida com a invalidação do cache do SnapStart automaticamente.

Use o utilitário de metadados Powertools para AWS Lambda ou chame o endpoint de metadados diretamente

Python

Instale o pacote Powertools:

pip install "aws-lambda-powertools"

Use o utilitário de metadados em seu manipulador:

exemplo Recuperação do ID de AZ com o Powertools (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

Instale o pacote Powertools:

npm install @aws-lambda-powertools/commons

Use o utilitário de metadados em seu manipulador:

exemplo Recuperação do ID de AZ com o Powertools (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

Adicione a dependência Powertools ao seu pom.xml:

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

Utilize o cliente de metadados no seu manipulador:

exemplo Recuperação do ID de AZ com o Powertools (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

Instale o pacote Powertools:

dotnet add package AWS.Lambda.Powertools.Metadata

Utilize a classe de metadados no seu manipulador:

exemplo Recuperação do ID de AZ com o Powertools (.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

Todos os runtimes do Lambda oferecem suporte ao endpoint de metadados, incluindo runtimes personalizados e imagens de contêiner. Utilize o exemplo a seguir para acessar a API de metadados diretamente a partir da sua função do Lambda, utilizando as variáveis de ambiente que o Lambda define automaticamente no ambiente de execução.

exemplo Acessar diretamente o endpoint de metadados

# 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"

Sobre IDs de zonas de disponibilidade

Os IDs de AZ (por exemplo, use1-az1) sempre se referem à mesma localização física em todas as contas da AWS, enquanto os nomes de AZ (por exemplo,us-east-1a) podem ser mapeados para diferentes infraestruturas físicas em cada conta da AWS em determinadas regiões. Para obter mais informações, consulte IDs de AZ para garantir a consistência entre contas.

Converter o ID da AZ em nome da AZ:

Para converter um ID de AZ em um nome de AZ, utilize a API DescribeAvailabilityZones do Amazon EC2. Para usar essa API, adicione a permissão ec2:DescribeAvailabilityZones ao perfil de execução da sua função.

Referência de API

Variáveis de ambiente

O Lambda define automaticamente as seguintes variáveis de ambiente em todos os ambientes de execução:

Endpoint

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

Solicitação

Cabeçalhos obrigatórios:

Resposta

Status: 200 OK

Content-Type: application/json

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

A resposta é imutável em um ambiente de execução. Os clientes devem armazenar a resposta em cache e respeitar o TTL Cache-Control. No caso das funções SnapStart, o TTL é reduzido durante a inicialização para que os clientes atualizem os metadados após a restauração, quando o ambiente de execução estiver em uma zona de disponibilidade diferente. Se você usa o Powertools, o armazenamento em cache e a invalidação do SnapStart são gerenciados automaticamente.

Corpo:

{
  "AvailabilityZoneID": "use1-az1"
}

O campo AvailabilityZoneID contém o identificador exclusivo da zona de disponibilidade onde o ambiente de execução está sendo executado.

Respostas de erro