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 environnements d'exécution personnalisés afin de recevoir des é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 bloqué pendant plusieurs secondes.

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

Un ID d'invocation (Lambda-Runtime-Invocation-Id) représente une seule tentative d'invocation pour un événement. Un seul identifiant de demande peut entraîner plusieurs tentatives d'invocation, chacune ayant son propre identifiant d'appel unique. Lambda utilise chaque identifiant d'appel exactement une fois et ne le réutilise jamais. Réactivez cette valeur /response et lancez les /error appels. L'en-tête est facultatif pour des raisons de compatibilité descendante avec les environnements d'exécution existants. Son omission n'entraîne pas de rejet. Lambda rejette uniquement 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 lit ceci pour obtenir les identifiants et déterminer s'il faut 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'appel actif.

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>, où Category est Runtime ou Function et Reason commence par une 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'appel actif.

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 appelleGET /runtime/restore/next. Il s'agit d'un appel de blocage de type itérateur, similaire à/runtime/invocation/next, qui signale à Lambda que le moteur d'exécution est prêt pour la capture instantanée de l'environnement d'exécution. La requête se bloque 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>, où Category est Runtime ou Function et Reason commence par une majuscule (par exemple,Runtime.AfterRestoreError). Les valeurs qui ne correspondent pas à ce modèle sont normalisées à Runtime.Unknown ouFunction.Unknown.

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

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

{"status":"OK"}