API de l'environnement d'exécution Lambda

AWS Lambda fournit une API HTTP pour les runtimes personnalisés afin de recevoir les événements d'invocations provenant de Lambda et de renvoyer des données de réponses au sein 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é.

Exemple Demande

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.

En-têtes de réponse

• Lambda-Runtime-Aws-Request-Id – ID de demande qui identifie la demande ayant déclenché l'invocation de la fonction.

  Par exemple, 8476a536-e9f4-11e8-9739-2dfe598c3fcd.

• Lambda-Runtime-Deadline-Ms – Date à laquelle la fonction expire, exprimée en millisecondes au format horaire Unix.

  Par exemple, 1542409706888.

• Lambda-Runtime-Invoked-Function-Arn – ARN de la fonction Lambda, de la version ou de l'alias spécifiés dans l'invocation.

  Par exemple, arn:aws:lambda:us-east-2:123456789012:function:custom-runtime.

• Lambda-Runtime-Trace-Id – En-tête de suivi AWS X-Ray.

  Par exemple, Root=1-5bef4de7-ad49b0e87f6ef6c87fc2e700;Parent=9a9197af755a6419;Sampled=1.

• Lambda-Runtime-Client-Context – Pour les invocations à partir du kit SDK AWS Mobile, données sur l'application et l'appareil clients.

• Lambda-Runtime-Cognito-Identity – Pour les invocations à partir du kit SDK AWS mobile, données sur le fournisseur d'identité Amazon Cognito.

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 amorce le runtime et celui où le runtime a un événement à renvoyer, le processus d'exécution peut être bloqué pendant plusieurs secondes.

L'ID de demande suit l'invocation au sein de Lambda. Utilisez-le pour spécifier l'invocation lorsque vous envoyez la réponse.

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 kit SDK X-Ray lit ceci pour obtenir les ID et déterminer l'opportunité 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.

Exemple demande d'opération réussie

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "SUCCESS"

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 – 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 :

• Durée d'exécution. NoSuchHandler

• Runtime.API KeyNotFound

• Durée d'exécution. ConfigInvalid

• Durée d'exécution. UnknownReason

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.

Exemple Erreur de fonction

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

Paramètres du corps de la réponse

• StatusResponse – String. Informations d'état, envoyées avec les codes de réponse 202.

• ErrorResponse – Informations supplémentaires sur l'erreur, envoyées avec les codes de réponse d'erreur. ErrorResponse contient un type d'erreur et un message d'erreur.

Codes de réponse

• 202 – Accepté

• 403 – Interdit

• 500 – Erreur de conteneur. État non récupérable. L'environnement d'exécution doit se terminer rapidement.

Exemple demande d'erreur d'initialisation

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 :

• Durée d'exécution. NoSuchHandler

• Runtime.API KeyNotFound

• Durée d'exécution. ConfigInvalid

• Durée d'exécution. UnknownReason

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.

Exemple Erreur de fonction

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

Paramètres du corps de la réponse

• StatusResponse – String. Informations d'état, envoyées avec les codes de réponse 202.

• ErrorResponse – Informations supplémentaires sur l'erreur, envoyées avec les codes de réponse d'erreur. ErrorResponse contient un type d'erreur et un message d'erreur.

Codes de réponse

• 202 – Accepté

• 400 – Demande erronée.

• 403 – Interdit

• 500 – Erreur de conteneur. État non récupérable. L'environnement d'exécution doit se terminer rapidement.

Exemple demande d'erreur

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"