Invocación asincrónica

Varios Servicios de AWS, como de Amazon Simple Storage Service (Amazon S3) y Amazon Simple Notification Service (Amazon SNS), invocan funciones de forma asíncrona para procesar eventos. Cuando se invoca una función de forma asíncrona, no se espera una respuesta del código de función. Se entrega el evento a Lambda, y Lambda se ocupa del resto. Puede configurar la forma en que Lambda gestiona los errores y enviar registros de invocaciones a un recurso posterior, como Amazon Simple Queue Service (Amazon SQS) o Amazon EventBridge (EventBridge), para encadenar los componentes de la aplicación.

Cómo maneja Lambda las invocaciones asíncronas

El siguiente diagrama muestra los clientes que invocan una función de Lambda de forma asíncrona. Lambda pone en cola los eventos antes de enviarlos a la función.

Para la invocación asíncrona, Lambda coloca el evento en una cola y devuelve una respuesta de “proceso realizado con éxito” sin información adicional. Un proceso independiente lee eventos de la cola y los envía a la función. Para invocar una función de forma asíncrona, establezca el parámetro de tipo de invocación en Event.

aws lambda invoke \
  --function-name my-function  \
  --invocation-type Event \
  --cli-binary-format raw-in-base64-out \
  --payload '{ "key": "value" }' response.json
  

La opción cli-binary-format es obligatoria si va a utilizar la versión 2 de la AWS CLI. Para que esta sea la configuración predeterminada, ejecute aws configure set cli-binary-format raw-in-base64-out. Para obtener más información, consulte Opciones de la línea de comandos globales compatibles con AWS CLI en la Guía del usuario de la AWS Command Line Interface versión 2.

{
    "StatusCode": 202
}

El archivo de salida (response.json) no contiene ninguna información, pero se crea al ejecutar este comando. Si Lambda no puede añadir el caso a la cola, el mensaje de error aparece en la salida del comando.

Lambda administra la cola de eventos asincrónica de la función y trata de reintentarlo en caso de errores. Si la función devuelve un error, Lambda intenta ejecutarla dos veces más, con una espera de un minuto entre los dos primeros intentos y dos minutos entre el segundo y el tercero. Los errores de la función incluyen errores devueltos por el código de la función y los errores devueltos por el tiempo de ejecución de la función, como, por ejemplo, los tiempos de espera.

Si la función no tiene disponible suficiente simultaneidad para procesar todos los eventos, se limitan las solicitudes adicionales. Para la limitación controlada de errores (429) y errores del sistema (serie 500), Lambda devuelve el evento a la cola e intenta ejecutar la función de nuevo durante un máximo de 6 horas. El intervalo de reintento aumenta exponencialmente desde 1 segundo después del primer intento hasta un máximo de 5 minutos. Si la cola contiene muchas entradas, Lambda aumenta el intervalo de reintento y reduce la velocidad a la que lee eventos de la cola.

Aunque la función no devuelva un error, es posible que reciba el mismo evento de Lambda varias veces, ya que la propia cola ofrece consistencia final. Si la función no es capaz de gestionar los eventos entrantes, podrían también eliminarse de la cola sin que se envíen a la función. Asegúrese de que el código de la función gestione sin problemas eventos duplicados y de que tenga simultaneidad suficiente disponible para gestionar todas las invocaciones.

Cuando la cola es muy larga, es posible que los nuevos eventos se agoten antes de que Lambda pueda enviarlos a la función. Cuando un evento caduca o todos los intentos de procesamiento fallan, Lambda lo descarga. Puede configurar la administración de errores de una función para reducir el número de reintentos que realiza Lambda o para descartar eventos no procesados más rápidamente.

También puede configurar Lambda para que envíe un registro de invocación a otro servicio. Lambda es compatible con los siguientes destinos para la invocación asíncrona. Tenga en cuenta que no se admiten las colas FIFO de SQS ni los temas FIFO de SNS.

• Amazon SQS: una cola de SQS estándar.

• Amazon SNS: un tema de SNS estándar.

• AWS Lambda: una función Lambda.

• Amazon EventBridge: el ARN de un bus de eventos de EventBridge.

El registro de invocación contiene detalles sobre la solicitud y la respuesta en formato JSON. Puede configurar destinos independientes en eventos que se procesan con éxito, y eventos que fallan todos los intentos de procesamiento. También puede configurar una cola de Amazon SQS estándar o un tema de Amazon SNS estándar como una cola de mensajes fallidos para eventos descartados. En las colas de mensajes fallidos, Lambda solo envía el contenido del evento, sin detalles sobre la respuesta.

Si Lambda no puede enviar un registro a un destino que haya configurado, envía una métrica DestinationDeliveryFailures a Amazon CloudWatch. Esto puede ocurrir si la configuración incluye un tipo de destino no admitido, como una cola FIFO de Amazon SQS o un tema FIFO de Amazon SNS. También pueden producirse errores de entrega debido a errores de permisos y límites de tamaño. Para obtener más información sobre las métricas de invocación de Lambda, consulte Métricas de invocación.

nota

Para evitar que una función se active, puede establecer la simultaneidad reservada de la función en cero. Cuando establece la simultaneidad reservada en cero para una función invocada de forma asíncrona, Lambda comienza a enviar nuevos eventos a la cola de mensajes fallidos configurada o al destino para eventos en caso de error, sin reintentos. Para procesar eventos que se enviaron mientras la simultaneidad reservada estaba establecida en cero, debe consumir los eventos de la cola de mensajes fallidos o el destino para eventos en caso de error.

Configuración de la gestión de errores para la invocación asincrónica

Utilice la consola de Lambda para configurar los ajustes de gestión de errores en una función, una versión o un alias.

Para configurar la gestión de errores

1. Abra la página de Funciones en la consola de Lambda.

2. Elija una función.

3. Elija Configuración y, a continuación, elija Invocación asíncrona.

4. En Asynchronous invocation (Invocación asincrónica), elija Edit (Editar).

5. Configure los siguientes ajustes.

   • Antigüedad máxima del evento: el período máximo de tiempo durante el que Lambda retiene un evento en la cola de evento asincrónico, hasta 6 horas.

   • Número de reintentos: número de reintentos que Lambda realiza cuando la función devuelve un error, entre 0 y 2.

6. Elija Guardar.

Cuando un evento de invocación supera la antigüedad máxima o no supera ningún reintento, Lambda lo descarta. Para conservar una copia de eventos descartados, configure un destino de eventos fallidos.

Configuración de destinos para invocación asincrónica

Para retener registros de invocaciones asincrónicas, agregue un destino a su función. Puede elegir enviar las invocaciones correctas o fallidas a un destino. Cada función puede tener varios destinos, por lo que puede configurar destinos independientes para los eventos correctos y los fallidos. Cada registro enviado al destino es un documento JSON con detalles sobre la invocación. Al igual que con los ajustes de gestión de errores, puede configurar los destinos en una función, versión de la función o alias.

nota

También puede retener los registros de las invocaciones fallidas para determinados tipos de asignación de orígenes de eventos. Para obtener más información, consulte Configuración de destinos para las invocaciones de asignación de orígenes de eventos

La siguiente table enumera los destinos admitidos para los registros de invocación asincrónica. Para que Lambda envíe correctamente los registros al destino elegido, asegúrese de que el rol de ejecución de la función también contenga los permisos pertinentes. En la tabla también se describe cómo cada tipo de destino recibe el registro de invocación de JSON.

Tipo de destino	Permiso necesario	Formato JSON específico del destino
Cola de Amazon SQS	sqs:SendMessage	Lambda pasa el registro de invocación como Message al destino.
Tema de Amazon SNS	sns:Publish	Lambda pasa el registro de invocación como Message al destino.
Función de Lambda	InvokeFunction	Lambda pasa el registro de invocación como carga útil a la función.
EventBridge	events:PutEvents	Lambda pasa el registro de invocación como detail en la llamada PutEvents. El valor del campo de eventos source es lambda. El valor del campo de eventos detail-type es “Resultado de la invocación de la función Lambda: éxito” o “Resultado de invocación de función de Lambda: error”. El campo de eventos resource contiene la función y el destino de Amazon Resource Names (ARN). Para ver otros campos de eventos, consulte Eventos de Amazon EventBridge.

El ejemplo siguiente muestra un registro de invocación para un evento que ha fallado tres intentos de procesamiento debido a un error de función. El registro de invocación contiene detalles sobre el evento, la respuesta y el motivo por el que se ha enviado el registro.

{
    "version": "1.0",
    "timestamp": "2019-11-14T18:16:05.568Z",
    "requestContext": {
        "requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function:$LATEST",
        "condition": "RetriesExhausted",
        "approximateInvokeCount": 3
    },
    "requestPayload": {
        "ORDER_IDS": [
            "9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
            "637de236-e7b2-464e-xmpl-baf57f86bb53",
            "a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
        ]
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "responsePayload": {
        "errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited before completing request"
    }
}

En los siguientes pasos se describe cómo configurar un destino para una función utilizando la consola de Lambda.

Configuración de un destino para registros de invocación asíncrona.

1. Abra la página de Funciones en la consola de Lambda.

2. Elija una función.

3. En Descripción general de la función, elija Agregar destino.

4. En Source (Origen), elija Asynchronous invocation (Invocación asincrónica).

5. En Condition (Condición) elija una de las siguientes opciones:

   • En caso de error: enviar un registro cuando el evento no supera los intentos de procesamiento o supera la antigüedad máxima.

   • Si es correcto: enviar un registro cuando la función procesa correctamente una invocación asincrónica.

6. En Destination type (Tipo de destino), elija el tipo de recurso que recibe el registro de invocación.

7. En Destination (Destino), elija un recurso.

8. Elija Guardar.

Cuando una invocación coincide con la condición, Lambda envía un documento JSON con detalles sobre la invocación al destino.

Formato JSON específico del destino

• Para Amazon SQS y Amazon SNS (SnsDestination y SqsDestination), el registro de invocación se pasa como Message al destino.

• Para Lambda (LambdaDestination), el registro de invocación se pasa como carga útil a la función.

• Para EventBridge (EventBridgeDestination), el registro de invocación se pasa como detail en la llamada PutEvents. El valor del campo de eventos source es lambda. El valor del campo de eventos detail-type es Resultado de la invocación de la función Lambda: éxito o Resultado de invocación de función Lambda: error. El campo de eventos resource contiene la función y el destino de Amazon Resource Names (ARN). Para ver otros campos de eventos, consulte Eventos de Amazon EventBridge.

El ejemplo siguiente muestra un registro de invocación para un evento que ha fallado tres intentos de procesamiento debido a un error de función.

ejemplo Registro de invocación

{
    "version": "1.0",
    "timestamp": "2019-11-14T18:16:05.568Z",
    "requestContext": {
        "requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function:$LATEST",
        "condition": "RetriesExhausted",
        "approximateInvokeCount": 3
    },
    "requestPayload": {
        "ORDER_IDS": [
            "9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
            "637de236-e7b2-464e-xmpl-baf57f86bb53",
            "a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
        ]
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "responsePayload": {
        "errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited before completing request"
    }
}

El registro de invocación contiene detalles sobre el evento, la respuesta y el motivo por el que se ha enviado el registro.

Seguimiento de solicitudes a destinos

Puede utilizar AWS X-Ray para ver una vista conectada de cada solicitud a medida que se pone en cola, la procesa una función de Lambda y se pasa al servicio de destino. Al activar el seguimiento de X-Ray para una función o un servicio que invoca una función, Lambda agrega un encabezado de X-Ray a la solicitud y lo pasa al servicio de destino. El seguimiento de los servicios anteriores se vincula automáticamente al seguimiento de las funciones de Lambda posteriores, lo que crea una vista integral de toda la aplicación. Para obtener más información sobre el seguimiento, consulte Uso de AWS Lambda con AWS X-Ray.

API de configuración de invocación asincrónica

Para administrar la configuración de invocación asincrónica con la AWS CLI o el SDK de AWS, utilice las siguientes operaciones de la API.

• PutFunctionEventInvokeConfig

• GetFunctionEventInvokeConfig

• UpdateFunctionEventInvokeConfig

• ListFunctionEventInvokeConfigs

• DeleteFunctionEventInvokeConfig

Para configurar la invocación asincrónica con la CLI de AWS CLI, utilice el comando put-function-event-invoke-config. En el ejemplo siguiente se configura una función con una antigüedad máxima de evento de 1 hora y sin reintentos.

aws lambda put-function-event-invoke-config --function-name error \
--maximum-event-age-in-seconds 3600 --maximum-retry-attempts 0

Debería ver los siguientes datos de salida:

{
    "LastModified": 1573686021.479,
    "FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:error:$LATEST",
    "MaximumRetryAttempts": 0,
    "MaximumEventAgeInSeconds": 3600,
    "DestinationConfig": {
        "OnSuccess": {},
        "OnFailure": {}
    }
}

El comando put-function-event-invoke-config sobrescribe cualquier configuración existente en la función, versión o alias. Para configurar una opción sin reiniciar otras, utilice update-function-event-invoke-config. En el siguiente ejemplo, se configura Lambda para enviar un registro a una cola de SQS estándar llamada destination cuando no se puede procesar un evento.

aws lambda update-function-event-invoke-config --function-name error \
--destination-config '{"OnFailure":{"Destination": "arn:aws:sqs:us-east-2:123456789012:destination"}}'

Debería ver los siguientes datos de salida:

{
    "LastModified": 1573687896.493,
    "FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:error:$LATEST",
    "MaximumRetryAttempts": 0,
    "MaximumEventAgeInSeconds": 3600,
    "DestinationConfig": {
        "OnSuccess": {},
        "OnFailure": {
            "Destination": "arn:aws:sqs:us-east-2:123456789012:destination"
        }
    }
}

Colas de mensajes fallidos

Como alternativa a un destino en caso de fallo, puede configurar su función con una cola de mensajes fallidos para guardar eventos descartados para su posterior procesamiento. Una cola de mensajes fallidos actúa igual que un destino en caso de error, ya que se utiliza cuando un evento falla todos los intentos de procesamiento o caduca sin ser procesado. Sin embargo, una cola de mensajes fallidos forma parte de la configuración específica de la versión de una función, por lo que se bloquea cuando se publica una versión. Los destinos en caso de error también admiten destinos adicionales e incluyen detalles sobre la respuesta de la función en el registro de invocación.

Para volver a procesar eventos en una cola de mensajes fallidos, puede configurarla como una fuente de eventos para su función de Lambda. También puede recuperar manualmente los eventos.

Puede elegir una cola de Amazon SQS estándar o un tema estándar de Amazon SNS para la cola de mensajes fallidos. No se admiten las colas FIFO ni los temas FIFO de Amazon SNS. Si no se dispone de una cola o tema, debe crearse. Elija el tipo de destino que coincida con su caso de uso.

• Cola de Amazon SQS: una cola que contiene eventos fallidos hasta que se recuperan. Elija una cola estándar de Amazon SQS si espera que una sola entidad, como una función de Lambda o una alarma de CloudWatch, procese el evento fallido. Para obtener más información, consulte Uso de Lambda con Amazon SQS.

  Cree una cola en la consola de Amazon SQS.

• Tema de Amazon SNS: un tema transmite eventos fallidos a uno o más destinos. Elija un tema estándar de Amazon SNS si espera que varias entidades actúen en un evento fallido. Por ejemplo, puede configurar un tema para enviar eventos a una dirección de correo electrónico, una función de Lambda o un punto de enlace HTTP. Para obtener más información, consulte Uso de AWS Lambda con Amazon SNS.

  Cree un tema en la consola de Amazon SNS.

Para enviar eventos a una cola o tema, la función necesita permisos adicionales. Añada una política con los permisos necesarios al rol de ejecución de la función.

• Amazon SQS: sqs:SendMessage

• Amazon SNS: sns:Publish

Si la cola o el tema de destino están cifrados con una clave administrada por el cliente, el rol de ejecución también debe ser un usuario en la política basada en recursos de la clave.

Después de crear el destino y actualizar el rol de ejecución de la función, añada la cola de mensajes fallidos a la función. Puede configurar varias funciones para enviar eventos al mismo destino.

Para configurar una cola de mensajes fallidos

1. Abra la página de Funciones en la consola de Lambda.

2. Elija una función.

3. Elija Configuración y, a continuación, elija Invocación asíncrona.

4. En Asynchronous invocation (Invocación asincrónica), elija Edit (Editar).

5. Establezca el Recurso de DLQ en Amazon SQS o Amazon SNS.

6. Elija la cola o el tema de destino.

7. Elija Guardar.

Para configurar una cola de mensajes fallidos con la AWS CLI, utilice el comando update-function-configuration.

aws lambda update-function-configuration --function-name my-function \
--dead-letter-config TargetArn=arn:aws:sns:us-east-2:123456789012:my-topic

Lambda envía el evento a la cola de mensajes fallidos tal y como está, con información adicional en atributos. Puede utilizar esta información para identificar el error que la función devuelve o correlacionar el evento con los registros o un rastro de AWS X-Ray.

Atributos de mensajes de cola de mensajes fallidos

• RequestID (cadena): el ID de la solicitud de invocación. Los ID de las solicitudes aparecen en los registros de la función. También puede usar el X-Ray SDK para registrar el ID de solicitud en un atributo del rastro. A continuación, puede buscar rastros por ID de solicitud en la consola de X-Ray. Consulte el ejemplo de procesador de errores para ver un ejemplo.

• ErrorCode (número): el código de estado de HTTP.

• ErrorMessage (cadena): el primer 1 KB del mensaje de error.

Si Lambda no puede enviar un mensaje a la cola de mensajes fallidos, elimina el evento y emite la métrica DeadLetterErrors. Esto puede ocurrir debido a la falta de permisos o si el tamaño total del mensaje supera el límite de la cola o tema de destino. Por ejemplo, supongamos que una notificación de Amazon SNS con un cuerpo cercano a los 256 KB activa una función que genera un error. En ese caso, los datos del evento que Amazon SNS agrega, junto con los atributos agregados por Lambda, pueden hacer que el mensaje supere el tamaño máximo permitido en la cola de mensajes fallidos.

Si está utilizando Amazon SQS como fuente de eventos, configure una cola de mensajes fallidos en la propia cola de Amazon SQS y no en la función de Lambda. Para obtener más información, consulte Uso de Lambda con Amazon SQS.