Utilisation de l’API de l’environnement d’exécution Lambda pour des environnements d’exécution personnalisés

AWS Lambda fournit une API HTTP pour les exécutions personnalisées des fonctions d'événement Lambda afin de recevoir les événements d'invocation de Lambda et de renvoyer les données de réponse dans l'environnement d'exécution Lambda. Cette section contient la référence de l’API de l’environnement d’exécution Lambda.

La spécification OpenAPI pour la version d’API de l’exécution 2018-06-01 est disponible dans runtime-api.zip

Pour créer une URL de requête d’API, les exécutions obtiennent le point de terminaison de l’API à partir de la variable d’environnement AWS_LAMBDA_RUNTIME_API et ajoutent la version de l’API ainsi que le chemin d’accès de ressource souhaité.

curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"

Invocation suivante

Chemin – /runtime/invocation/next

Méthode – GET

L’exécution envoie ce message à Lambda pour demander un événement d’invocation. Le corps de la réponse contient la charge utile provenant de l’invocation, qui est un document JSON contenant les données d’événements du déclencheur de la fonction. Les en-têtes de la réponse contiennent des données supplémentaires sur l’invocation.

Ne définissez pas de délai d’expiration pour la demande GET, car la réponse peut être retardée. Entre le moment où Lambda démarre le moteur d'exécution et le moment où celui-ci doit renvoyer un événement, le processus d'exécution peut être gelé pendant plusieurs secondes.

Un ID de demande (Lambda-Runtime-Aws-Request-Id) identifie un événement unique. Les identifiants de demande sont fournis par des sources d'événements ou générés automatiquement par Lambda lors de l'ingestion. Utilisez l'ID de demande indiqué dans le chemin de l'URL lors de l'envoi de la réponse ou de l'erreur.

Un ID d'appel (Lambda-Runtime-Invocation-Id) représente une tentative d'invocation unique pour un événement. Un identifiant de demande unique peut entraîner plusieurs tentatives d'invocation, chacune ayant son propre identifiant d'appel unique. Lambda utilise chaque ID d'appel une seule fois et ne le réutilise jamais. Réactivez cette valeur /response et /error appelez. L'en-tête est facultatif pour des raisons de rétrocompatibilité avec les environnements d'exécution existants ; son omission ne déclenche pas de rejet. Lambda rejette uniquement with 400 InvalidInvocationId lorsque l'en-tête est présent mais que sa valeur ne correspond pas à l'invocation active.

L’en-tête de suivi contient l’ID de suivi, l’ID parent et la décision d’échantillonnage. Si la demande est échantillonnée, elle a été échantillonnée par Lambda ou un service en amont. Le runtime doit définir l’_X_AMZN_TRACE_ID avec la valeur de l’en-tête. Le X-Ray SDK le lit pour obtenir les identifiants et déterminer s'il convient de suivre la demande.

Réponse d’invocation

Chemin – /runtime/invocation/AwsRequestId/response

Méthode – POST

Une fois l’exécution de la fonction terminée, le runtime envoie une réponse à l’invocation à Lambda. Pour les invocations synchrones, Lambda envoie la réponse au client.

En-têtes de demandes

Lambda-Runtime-Invocation-Id— Renvoie la valeur reçue de/next. Lambda rejette la demande 400 InvalidInvocationId si la valeur ne correspond pas à l'invocation active.

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
INVOCATION_ID=<value from Lambda-Runtime-Invocation-Id response header>
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "SUCCESS" --header "Lambda-Runtime-Invocation-Id: $INVOCATION_ID"

Erreur d’initialisation

Si la fonction renvoie une erreur ou si le runtime rencontre une erreur lors de l’initialisation, le runtime utilise cette méthode pour signaler l’erreur à Lambda.

Chemin – /runtime/init/error

Méthode – POST

En-têtes

Lambda-Runtime-Function-Error-Type : le type d’erreur que l’exécution a rencontré. Cet en-tête est facultatif. Lambda accepte n'importe quelle valeur de chaîne ; nous vous recommandons d'utiliser le format <Category.Reason> dans lequel Category est Runtime ou Function et Reason commence par une lettre majuscule. Par exemple :

Les valeurs qui ne correspondent pas à ce modèle sont normalisées à Runtime.Unknown ouFunction.Unknown.

Paramètres de corps

ErrorRequest : informations sur l’erreur. Requis : non.

Ce champ est un objet JSON avec la structure suivante :

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Notez que Lambda accepte n’importe quelle valeur pour errorType.

L’exemple suivant montre un message d’erreur de fonction Lambda indiquant que la fonction n’a pas pu analyser les données d’événement fournies dans l’invocation.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

ERROR="{\"errorMessage\" : \"Failed to load function.\", \"errorType\" : \"InvalidFunctionException\"}"
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/init/error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"

Erreur d’invocation

Si la fonction renvoie une erreur ou si le runtime rencontre une erreur, le runtime utilise cette méthode pour signaler l’erreur à Lambda.

Chemin – /runtime/invocation/AwsRequestId/error

Méthode – POST

En-têtes

Lambda-Runtime-Function-Error-Type – Type d’erreur que l’environnement d’exécution a rencontré. Requis : non.

Cet en-tête se compose d’une valeur de chaîne. Lambda accepte n’importe quelle chaîne, mais nous recommandons le format <category.reason>. Par exemple :

Lambda-Runtime-Invocation-Id— Renvoie la valeur reçue de/next. Lambda rejette la demande 400 InvalidInvocationId si la valeur ne correspond pas à l'invocation active.

Paramètres de corps

ErrorRequest : informations sur l’erreur. Requis : non.

Ce champ est un objet JSON avec la structure suivante :

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Notez que Lambda accepte n’importe quelle valeur pour errorType.

L’exemple suivant montre un message d’erreur de fonction Lambda indiquant que la fonction n’a pas pu analyser les données d’événement fournies dans l’invocation.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
ERROR="{\"errorMessage\" : \"Error parsing event data.\", \"errorType\" : \"InvalidEventDataException\"}"
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"

After-Restore (applicable uniquement pour SnapStart)

Chemin – /runtime/restore/next

Méthode – GET

Une fois les hooks antérieurs à la capture d'écran terminés, le moteur d'exécution appelle. GET /runtime/restore/next Il s'agit d'un appel de blocage de type itérateur, similaire à/runtime/invocation/next, qui indique à Lambda que le moteur d'exécution est prêt pour la capture instantanée de l'environnement d'exécution. La requête est bloquée jusqu'à ce que Lambda restaure l'environnement d'exécution à partir d'un instantané, puis renvoie une réponse HTTP 200 avec un corps vide.

En-têtes

Aucun en-tête n'est requis.

Syntaxe de demande

GET /2018-06-01/runtime/restore/next HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}

Syntaxe de réponse

HTTP/1.1 200 OK
Content-Length: 0

Erreur de restauration (applicable uniquement pour SnapStart)

Si un hook après restauration échoue ou si le moteur d'exécution rencontre une erreur lors de la restauration, le moteur d'exécution utilise cette méthode pour signaler l'erreur à Lambda. Lambda échoue à l'invocation en vol et détruit l'environnement d'exécution.

Chemin – /runtime/restore/error

Méthode – POST

En-têtes

Lambda-Runtime-Function-Error-Type : le type d’erreur que l’exécution a rencontré. Cet en-tête est facultatif. Lambda accepte n'importe quelle valeur de chaîne ; nous vous recommandons d'utiliser le format <Category.Reason> dans lequel Category est Runtime ou Function et Reason commence par une lettre majuscule (par exemple,). Runtime.AfterRestoreError Les valeurs qui ne correspondent pas à ce modèle sont normalisées à Runtime.Unknown ouFunction.Unknown.

Syntaxe de demande

POST /2018-06-01/runtime/restore/error HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}
Lambda-Runtime-Function-Error-Type: Runtime.AfterRestoreError

Syntaxe de réponse

HTTP/1.1 202 Accepted
Content-Type: application/json

{"status":"OK"}