# Usar o endpoint de metadados Lambda
<a name="configuration-metadata-endpoint"></a>

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.

**Topics**
+ [

## Introdução
](#metadata-endpoint-getting-started)
+ [

## Sobre IDs de zonas de disponibilidade
](#metadata-endpoint-az-ids)
+ [

## Referência de API
](#metadata-endpoint-api-reference)

## Introdução
<a name="metadata-endpoint-getting-started"></a>

[O Powertools para AWS Lambda](https://docs.aws.amazon.com/powertools/) 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:

**Example 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:

**Example 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:

**Example 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:

**Example 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.

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

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](https://docs.aws.amazon.com/global-infrastructure/latest/regions/az-ids.html).

**Converter o ID da AZ em nome da AZ:**

Para converter um ID de AZ em um nome de AZ, utilize a API [DescribeAvailabilityZones](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeAvailabilityZones.html) 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
<a name="metadata-endpoint-api-reference"></a>

### Variáveis de ambiente
<a name="metadata-endpoint-env-vars"></a>

O Lambda define automaticamente as seguintes variáveis de ambiente em todos os ambientes de execução:
+ `AWS_LAMBDA_METADATA_API`: o endereço do servidor de metadados no formato `{ipv4_address}:{port}` (por exemplo, `169.254.100.1:9001`).
+ `AWS_LAMBDA_METADATA_TOKEN`: um token de autenticação exclusivo para o ambiente de execução atual. O Lambda gera esse token automaticamente na inicialização. Inclua-o em todas as solicitações da API de metadados.

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

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

### Solicitação
<a name="metadata-endpoint-request"></a>

**Cabeçalhos obrigatórios:**
+ `Authorization`: o valor do token da variável de ambiente `AWS_LAMBDA_METADATA_TOKEN` com o esquema Bearer: `Bearer <token>`. Essa autenticação baseada em token oferece proteção em camadas contra vulnerabilidades de falsificação de solicitação do lado do servidor (SSRF). Cada ambiente de execução recebe um token único, gerado aleatoriamente, durante a inicialização.

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

**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.

**nota**  
Campos adicionais podem ser adicionados à resposta em atualizações futuras. Os clientes devem ignorar campos desconhecidos e não falhar se novos campos aparecerem.

### Respostas de erro
<a name="metadata-endpoint-errors"></a>
+ **401 Não autorizado**: o cabeçalho `Authorization` está ausente ou contém um token inválido. Verifique se você está passando `Bearer ${AWS_LAMBDA_METADATA_TOKEN}`.
+ **405 Método não permitido**: o método de solicitação não é `GET`.
+ **500 Erro interno do servidor**: erro de processamento no lado do servidor.