Uso de la API de tiempo de ejecución de Lambda para tiempos de ejecución personalizados

AWS Lambda proporciona una API HTTP para que los tiempos de ejecución personalizados puedan recibir eventos de invocación desde Lambda y enviar los datos de respuesta dentro del entorno de ejecución de Lambda. Esta sección contiene la referencia de la API para la API de tiempo de ejecución de Lambda.

La especificación de OpenAPI para la versión de la API de tiempo de ejecución 2018-06-01 está disponible en: runtime-api.zip.

Para crear una URL de solicitud de API, los tiempos de ejecución obtienen el punto de enlace de la API de la variable de entorno AWS_LAMBDA_RUNTIME_API; agregue la versión de la API y la ruta de recurso deseada.

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

Siguiente invocación

Ruta – /runtime/invocation/next

Método: GET

El tiempo de ejecución envía este mensaje a Lambda para solicitar un evento de invocación. El cuerpo de la respuesta contiene la carga a partir de la invocación, la cual es un documento JSON que contiene datos de eventos del desencadenador de la función. Los encabezados de la respuesta contienen datos adicionales sobre la invocación.

No establezca un tiempo de espera en la solicitud GET, ya que la respuesta puede retrasarse. Entre el momento en que Lambda arranca el tiempo de ejecución y el momento en que el tiempo de ejecución tiene un evento para devolver, el proceso de tiempo de ejecución podría congelarse durante varios segundos.

Un ID de solicitud (Lambda-Runtime-Aws-Request-Id) identifica un evento único. Los orígenes de eventos proporcionan los ID de solicitud o Lambda los genera automáticamente al ingerirlos. Use el ID de solicitud en la ruta URL al enviar la respuesta o el error.

Un ID de invocación (Lambda-Runtime-Invocation-Id) representa un único intento de invocación para un evento. Un único ID de solicitud puede provocar varios intentos de invocación, cada uno con su propio ID de invocación único. Lambda usa cada ID de invocación exactamente una vez y nunca lo reutiliza. Vuelva a enviar este valor en las llamadas /response y /error. El encabezado es opcional para garantizar la compatibilidad con versiones anteriores de los tiempos de ejecución existentes; omitirlo no provoca un rechazo. Lambda solo rechaza con 400 InvalidInvocationId cuando el encabezado está presente, pero su valor no coincide con la invocación activa.

El encabezado de rastreo contiene el ID de rastreo, el ID principal y la decisión de muestreo. Si se muestrea la solicitud, lo hace Lambda o un servicio ascendente. El tiempo de ejecución deberá definir el valor _X_AMZN_TRACE_ID con el valor del encabezado. El X-Ray SDK lee esto para obtener los ID y determinar si hay que rastrear la solicitud.

Respuesta de la invocación

Ruta – /runtime/invocation/AwsRequestId/response

Método: POST

Después de que la función se ha ejecutado hasta su finalización, el tiempo de ejecución envía una respuesta de invocación a Lambda. En el caso de invocaciones síncronas, Lambda envía la respuesta al cliente.

Encabezados de solicitudes

Lambda-Runtime-Invocation-Id: reproduce el valor recibido de /next. Lambda rechaza la solicitud con 400 InvalidInvocationId si el valor no coincide con la invocación activa.

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"

Error de inicialización

Si la función devuelve un error o el tiempo de ejecución encuentra un error durante la inicialización, el tiempo de ejecución utiliza este método para informar del error a Lambda.

Ruta – /runtime/init/error

Método: POST

Encabezados

Lambda-Runtime-Function-Error-Type: el tipo de error que encontró el tiempo de ejecución. Este encabezado es opcional. Lambda acepta cualquier valor de cadena; se recomienda usar el formato <Category.Reason>, donde Category es Runtime o Function y Reason comienza con una letra mayúscula. Por ejemplo:

Los valores que no coinciden con este patrón se normalizan a Runtime.Unknown o Function.Unknown.

Body parameters (Parámetros del cuerpo

ErrorRequest: información sobre el error. Obligatorio: no

Este campo es un objeto JSON con la siguiente estructura:

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

Tenga en cuenta que Lambda acepta cualquier valor para errorType.

En el ejemplo siguiente, se muestra un mensaje de error de función de Lambda en el que la función no pudo analizar los datos de evento proporcionados en la invocación.

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

Error de invocación

Si la función devuelve un error o el tiempo de ejecución encuentra un error, el tiempo de ejecución utiliza este método para informar del error a Lambda.

Ruta – /runtime/invocation/AwsRequestId/error

Método: POST

Encabezados

Lambda-Runtime-Function-Error-Type: tipo de error que encontró el tiempo de ejecución. Obligatorio: no

Este encabezado consta de un valor de cadena. Lambda acepta cualquier cadena, pero recomendamos un formato de <category.reason>. Por ejemplo:

Lambda-Runtime-Invocation-Id: reproduce el valor recibido de /next. Lambda rechaza la solicitud con 400 InvalidInvocationId si el valor no coincide con la invocación activa.

Body parameters (Parámetros del cuerpo

ErrorRequest: información sobre el error. Obligatorio: no

Este campo es un objeto JSON con la siguiente estructura:

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

Tenga en cuenta que Lambda acepta cualquier valor para errorType.

En el ejemplo siguiente, se muestra un mensaje de error de función de Lambda en el que la función no pudo analizar los datos de evento proporcionados en la invocación.

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

Después de la restauración (solo aplicable a SnapStart)

Ruta – /runtime/restore/next

Método: GET

Una vez completados los enlaces previos a la instantánea, el tiempo de ejecución llama a GET /runtime/restore/next. Se trata de una llamada de bloqueo de tipo iterador, similar a /runtime/invocation/next, que indica a Lambda que el tiempo de ejecución está preparado para que se tome una instantánea del entorno de ejecución. La solicitud se bloquea hasta que Lambda restablece el entorno de ejecución a partir de una instantánea y, a continuación, devuelve una respuesta HTTP 200 con el cuerpo vacío.

Encabezados

No se requieren encabezados.

Sintaxis de la solicitud

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

Sintaxis de la respuesta

HTTP/1.1 200 OK
Content-Length: 0

Restauración del error (solo aplicable a SnapStart)

Si un enlace posterior a la restauración falla o el tiempo de ejecución encuentra un error durante la restauración, el tiempo de ejecución utiliza este método para informar del error a Lambda. Lambda produce un error en la invocación en curso y destruye el entorno de ejecución.

Ruta – /runtime/restore/error

Método: POST

Encabezados

Lambda-Runtime-Function-Error-Type: el tipo de error que encontró el tiempo de ejecución. Este encabezado es opcional. Lambda acepta cualquier valor de cadena; se recomienda usar el formato <Category.Reason>, donde Category es Runtime o Function y Reason comienza con una letra mayúscula (por ejemplo, Runtime.AfterRestoreError). Los valores que no coinciden con este patrón se normalizan a Runtime.Unknown o Function.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"}