Utilisation du point de terminaison de métadonnées Lambda

Le point de terminaison de métadonnées Lambda permet à vos fonctions de découvrir dans quelle zone de disponibilité (AZ) elles s'exécutent, ce qui vous permet d'optimiser la latence en les acheminant vers des ressources de même zone, telles que les points de terminaison Amazon et ElastiCache Amazon RDS, et de mettre en œuvre des modèles de résilience compatibles avec l'AZ.

Le point de terminaison renvoie les métadonnées dans un format JSON simple via une API HTTP localhost au sein de l'environnement d'exécution et est accessible à la fois aux environnements d'exécution et aux extensions.

Prise en main

Powertools for AWS Lambda fournit un utilitaire permettant d'accéder au point de terminaison des métadonnées Lambda en Python TypeScript, Java et .NET. L'utilitaire met en cache la réponse après le premier appel et gère automatiquement l'invalidation SnapStart du cache.

Utilisez l'utilitaire de métadonnées Powertools for AWS Lambda ou appelez directement le point de terminaison des métadonnées

Python

Installez le package Powertools :

pip install "aws-lambda-powertools"

Utilisez l'utilitaire de métadonnées de votre gestionnaire :

Exemple Récupération d'un identifiant AZ avec 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

Installez le package Powertools :

npm install @aws-lambda-powertools/commons

Utilisez l'utilitaire de métadonnées de votre gestionnaire :

Exemple Récupération d'un identifiant AZ avec 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

Ajoutez la dépendance Powertools à votre pom.xml :

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

Utilisez le client de métadonnées dans votre gestionnaire :

Exemple Récupération d'un identifiant AZ avec 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

Installez le package Powertools :

dotnet add package AWS.Lambda.Powertools.Metadata

Utilisez la classe de métadonnées dans votre gestionnaire :

Exemple Récupération d'un identifiant AZ avec 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

Tous les environnements d'exécution Lambda prennent en charge le point de terminaison des métadonnées, y compris les environnements d'exécution personnalisés et les images de conteneur. Utilisez l'exemple suivant pour accéder à l'API de métadonnées directement depuis votre fonction à l'aide des variables d'environnement que Lambda définit automatiquement dans l'environnement d'exécution.

Exemple Accès direct au point de terminaison des métadonnées

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

Comprendre la zone de disponibilité IDs

AZ IDs (par exempleuse1-az1) fait toujours référence au même emplacement physique sur tous les AWS comptes, tandis que les noms AZ (par exemple,us-east-1a) peuvent correspondre à différentes infrastructures physiques de chaque AWS compte dans certaines régions. Pour plus d'informations, voir AZ IDs pour la cohérence entre comptes.

Conversion d'un ID AZ en nom AZ :

Pour convertir un ID AZ en nom AZ, utilisez l'API Amazon EC2. DescribeAvailabilityZones Pour utiliser cette API, ajoutez l'ec2:DescribeAvailabilityZonesautorisation au rôle d'exécution de votre fonction.

Référence des API

Variables d’environnement

Lambda définit automatiquement les variables d'environnement suivantes dans chaque environnement d'exécution :

• AWS_LAMBDA_METADATA_API— L'adresse du serveur de métadonnées au format {ipv4_address}:{port} (par exemple,169.254.100.1:9001).

• AWS_LAMBDA_METADATA_TOKEN— Un jeton d'authentification unique pour l'environnement d'exécution actuel. Lambda génère ce jeton automatiquement lors de l'initialisation. Incluez-le dans toutes les demandes d'API de métadonnées.

Endpoint

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

Demande

En-têtes obligatoires :

• Authorization— La valeur du jeton de la variable d'AWS_LAMBDA_METADATA_TOKENenvironnement avec le schéma Bearer :Bearer <token>. Cette authentification basée sur des jetons fournit une protection approfondie contre les vulnérabilités SSRF (Server-Side Request Forgery). Chaque environnement d'exécution reçoit un jeton unique généré aléatoirement lors de l'initialisation.

Réponse

État : 200 OK

Type de contenu : application/json

Contrôle du cache : private, max-age=43200, immutable

La réponse est immuable dans un environnement d'exécution. Les clients doivent mettre en cache la réponse et respecter le Cache-Control TTL. Pour les SnapStart fonctions, le TTL est réduit lors de l'initialisation afin que les clients actualisent les métadonnées après la restauration lorsque l'environnement d'exécution peut se trouver dans une zone de disponibilité différente. Si vous utilisez Powertools, la mise en cache et l' SnapStart invalidation sont gérées automatiquement.

Corps de texte:

{
  "AvailabilityZoneID": "use1-az1"
}

Le AvailabilityZoneID champ contient l'identifiant unique de la zone de disponibilité dans laquelle s'exécute l'environnement d'exécution.

Note

Des champs supplémentaires peuvent être ajoutés à la réponse lors de futures mises à jour. Les clients doivent ignorer les champs inconnus et ne pas échouer si de nouveaux champs apparaissent.

Réponses d'erreur

• 401 Non autorisé — L'Authorizationen-tête est manquant ou contient un jeton non valide. Vérifiez que vous êtes en train de réussirBearer ${AWS_LAMBDA_METADATA_TOKEN}.

• 405 Méthode non autorisée — La méthode de demande ne l'est pasGET.

• 500 Erreur interne du serveur — Erreur de traitement côté serveur.