Uso del punto de conexión de metadatos de Lambda

El punto de conexión de metadatos de Lambda permite que sus funciones identifiquen en qué zona de disponibilidad (AZ) se ejecutan, de manera que puede optimizar la latencia al enrutar hacia recursos en la misma AZ, como puntos de conexión de Amazon ElastiCache y Amazon RDS, y aplicar patrones de resiliencia con reconocimiento de AZ.

El punto de conexión devuelve metadatos en un formato JSON simple mediante una API de HTTP en localhost dentro del entorno de ejecución y está disponible tanto para tiempos de ejecución como para extensiones.

Introducción

Powertools para AWS Lambda proporciona una utilidad para acceder al punto de conexión de metadatos de Lambda en Python, TypeScript, Java y .NET. La utilidad almacena en caché la respuesta después de la primera llamada y gestiona automáticamente la invalidación de caché de SnapStart.

Utilice la utilidad de metadatos Powertools para AWS Lambda o llame directamente al punto de conexión de metadatos.

Python

Instale el paquete de Powertools:

pip install "aws-lambda-powertools"

Utilice la utilidad de metadatos en su controlador:

ejemplo Obtención del identificador de AZ con 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 el paquete de Powertools:

npm install @aws-lambda-powertools/commons

Utilice la utilidad de metadatos en su controlador:

ejemplo Obtención del identificador de AZ con 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

Agregue la dependencia de Powertools a su pom.xml:

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

Utilice el cliente de metadatos en su controlador:

ejemplo Obtención del identificador de AZ con 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 el paquete de Powertools:

dotnet add package AWS.Lambda.Powertools.Metadata

Utilice la clase de metadatos en su controlador:

ejemplo Obtención del identificador de AZ con 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 los tiempos de ejecución de Lambda admiten el punto de conexión de metadatos, incluidos los tiempos de ejecución personalizados y las imágenes de contenedor. Guíese con el siguiente ejemplo para acceder directamente a la API de metadatos desde su función mediante las variables de entorno que Lambda configura automáticamente en el entorno de ejecución.

ejemplo Acceso directo al punto de conexión de metadatos

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

Explicación sobre los identificadores de zona de disponibilidad

Los identificadores de AZ (por ejemplo, use1-az1) siempre hacen referencia a la misma ubicación física en todas las cuentas de AWS, mientras que los nombres de AZ (por ejemplo, us-east-1a) pueden asignarse a infraestructuras físicas diferentes en cada cuenta de AWS en determinadas regiones. Para obtener más información, consulte Identificadores de AZ para coherencia entre cuentas.

Convertir un identificador de AZ en un nombre de AZ:

Para convertir un identificador de AZ en un nombre de AZ, utilice la API DescribeAvailabilityZones de Amazon EC2. Para usar esta API, agregue el permiso de ec2:DescribeAvailabilityZones al rol de ejecución de su función.

Referencia de la API

Variables de entorno

Lambda configura automáticamente las siguientes variables de entorno en cada entorno de ejecución:

Punto de conexión

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

Solicitud

Encabezados obligatorios:

Respuesta

Estado: 200 OK

Content-Type: application/json

Cache-Control (Control de caché): private, max-age=43200, immutable

La respuesta es inmutable dentro de un entorno de ejecución. Los clientes deben almacenar la respuesta en caché y respetar el Cache-Control TTL. En el caso de las funciones con SnapStart, el TTL se reduce durante la inicialización para que los clientes actualicen los metadatos después de la restauración cuando el entorno de ejecución pueda estar en una AZ diferente. Si utiliza Powertools, el almacenamiento en caché y la invalidación de SnapStart se gestionan automáticamente.

Body (Cuerpo):

{
  "AvailabilityZoneID": "use1-az1"
}

El campo AvailabilityZoneID contiene el identificador único de la zona de disponibilidad en la que se ejecuta el entorno de ejecución.

Respuestas de error