Gestionar los errores de Lambda en API Gateway
Para las integraciones de Lambda personalizadas, debe asignar los errores devueltos por Lambda en la respuesta de integración a las respuestas de error de HTTP estándar para sus clientes. De lo contrario, los errores de Lambda se devuelven como respuestas 200 OK de forma predeterminada y el resultado no es intuitivo para los usuarios de la API.
Hay dos tipos de errores que Lambda puede devolver: errores estándar y errores personalizados. En la API, debe tratarlos de forma diferente.
Con la integración de proxy de Lambda, Lambda debe devolver una salida con el siguiente formato:
{ "isBase64Encoded" : "boolean", "statusCode": "number", "headers": { ... }, "body": "JSON string" }
En esta salida, statusCode es normalmente 4XX para un error del cliente y 5XX para un error del servidor. API Gateway trata estos errores asignando el error de Lambda a una respuesta de error HTTP, de acuerdo con el statusCode especificado. Para que API Gateway transmita el tipo de error (por ejemplo, InvalidParameterException), como parte de la respuesta al cliente, la función de Lambda debe incluir un encabezado (por ejemplo, "X-Amzn-ErrorType":"InvalidParameterException") en la propiedad headers.
Temas
Gestionar los errores de Lambda estándares en API Gateway.
Un error estándar de AWS Lambda tiene el siguiente formato:
{ "errorMessage": "<replaceable>string</replaceable>", "errorType": "<replaceable>string</replaceable>", "stackTrace": [ "<replaceable>string</replaceable>", ... ] }
Aquí, errorMessage es una expresión de cadena del error. errorType es un tipo de error o excepción dependiente del lenguaje. stackTrace es una lista de expresiones de cadena que indican la pila de rastreo que conduce a la aparición del error.
Por ejemplo, observe la siguiente función de Lambda en JavaScript (Node.js).
export const handler = function(event, context, callback) { callback(new Error("Malformed input ...")); };
Esta función devuelve el siguiente error de Lambda estándar, que contiene Malformed
input ... como el mensaje de error:
{ "errorMessage": "Malformed input ...", "errorType": "Error", "stackTrace": [ "export const handler (/var/task/index.js:3:14)" ] }
Asimismo, considere la siguiente función de Lambda de Python, que produce una Exception con el mismo mensaje de error Malformed input ....
def lambda_handler(event, context): raise Exception('Malformed input ...')
Esta función devuelve el siguiente error de Lambda estándar:
{ "stackTrace": [ [ "/var/task/lambda_function.py", 3, "lambda_handler", "raise Exception('Malformed input ...')" ] ], "errorType": "Exception", "errorMessage": "Malformed input ..." }
Tenga en cuenta que los valores de las propiedades errorType y stackTrace dependen del lenguaje. El error estándar también se aplica a cualquier objeto de error que sea una extensión del objeto Error o una subclase de la clase Exception.
Para asignar el error de Lambda estándar a una respuesta del método, primero debe decidir cuál es el código de estado HTTP para un error de Lambda determinado. Seguidamente, debe establecer un patrón de expresiones regulares en la propiedad selectionPattern del recurso IntegrationResponse asociado con el código de estado HTTP especificado. En la consola de API Gateway, este selectionPattern se denomina Expresión regular de error de Lambda en la sección Respuesta de integración, debajo de cada respuesta de integración.
nota
API Gateway utiliza expresiones regulares de estilo de patrón de Java para el mapeo de respuesta. Para obtener más información, consulte Pattern (Patrón)
Por ejemplo, para configurar una nueva expresión selectionPattern mediante la AWS CLI, llame al siguiente comando put-integration-response:
aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Malformed.*" --region us-west-2
Asegúrese de configurar también el código de error correspondiente (400) en la respuesta del método. De lo contrario, API Gateway produce una respuesta de error de configuración no válida en tiempo de ejecución.
nota
En el tiempo de ejecución, API Gateway coteja el errorMessage de error de Lambda con el patrón de la expresión regular en la propiedad selectionPattern. Si hay una coincidencia, API Gateway devuelve el error de Lambda como una respuesta HTTP del código de estado HTTP correspondiente. Si no hay ninguna coincidencia, API Gateway devuelve el error como una respuesta predeterminada o produce una excepción de configuración no válida si no se ha configurado una respuesta predeterminada.
Configurar el valor selectionPattern a .* para una determinada respuesta equivale a restablecer esta respuesta como la predeterminada. Esto se debe a que un patrón de solicitud de este tipo coincidirá con todos los mensajes de error, incluidos los nulos, es decir, cualquier mensaje de error no especificado. El mapeo resultante anula al predeterminado.
Para actualizar un valor de selectionPattern existente mediante la API REST de la AWS CLI, llame a la operación update-integration-response para reemplazar el valor de ruta de /selectionPattern por la expresión regular especificada con el patrón Malformed*.
Para establecer la expresión selectionPattern con la consola de API Gateway, escriba la expresión en el cuadro de texto Expresión regular de error de Lambda cuando configure o actualice una respuesta de integración de un código de estado HTTP especificado.
Gestionar los errores de Lambda personalizados en API Gateway
En lugar del error estándar descrito en la sección anterior, AWS Lambda le permite devolver un objeto de error personalizado como una cadena JSON. El error puede ser cualquier objeto JSON válido. Por ejemplo, la siguiente función de Lambda en JavaScript (Node.js) devuelve un error personalizado:
export const handler = (event, context, callback) => { ... // Error caught here: var myErrorObj = { errorType : "InternalServerError", httpStatus : 500, requestId : context.awsRequestId, trace : { "function": "abc()", "line": 123, "file": "abc.js" } } callback(JSON.stringify(myErrorObj)); };
Debe activar el objeto myErrorObj en una cadena JSON antes de llamar a callback para salir de la función. De lo contrario, myErrorObj se devuelve como una cadena de "[object Object]". Cuando un método de la API está integrado con la función API Gateway anterior, Lambda recibe una respuesta de integración con la siguiente carga:
{ "errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}" }
Al igual que con cualquier respuesta de integración, puede transferir esta respuesta de error tal como está a la respuesta del método. O puede usar una plantilla de mapeo para transformar la carga en un formato diferente. Considere, por ejemplo, la siguiente plantilla de asignación de cuerpo para una respuesta de método del código de estado 500:
{ errorMessage: $input.path('$.errorMessage'); }
Esta plantilla traduce el cuerpo de respuesta de la integración que contiene la cadena JSON del error personalizado en el siguiente cuerpo de respuesta del método. Este cuerpo de respuesta del método contiene el objeto JSON del error personalizado:
{ "errorMessage" : { errorType : "InternalServerError", httpStatus : 500, requestId : context.awsRequestId, trace : { "function": "abc()", "line": 123, "file": "abc.js" } } };
En función de los requisitos de la API, es posible que tenga que pasar algunas o todas las propiedades de errores personalizados como parámetros de encabezado de la respuesta del método. Para ello, puede aplicar asignaciones de errores personalizados desde el cuerpo de respuesta de integración a los encabezados de respuesta del método.
Por ejemplo, la siguiente extensión de OpenAPI define una asignación desde las propiedades errorMessage.errorType, errorMessage.httpStatus, errorMessage.trace.function y errorMessage.trace a error_type, error_status, error_trace_function y error_trace, respectivamente.
"x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function", "method.response.header.error_status": "integration.response.body.errorMessage.httpStatus", "method.response.header.error_type": "integration.response.body.errorMessage.errorType", "method.response.header.error_trace": "integration.response.body.errorMessage.trace" }, ... } } }
En tiempo de ejecución, API Gateway deserializa el parámetro integration.response.body cuando realiza mapeos de encabezado. Sin embargo, esta deserialización se aplica únicamente a los mapeos de cuerpo a encabezado para respuestas de errores personalizados de Lambda y no se aplica a los mapeos de cuerpo a cuerpo que utilizan $input.body. Con estas asignaciones de cuerpo a encabezado de errores personalizados, el cliente recibe los siguientes encabezados como parte de la respuesta del método, siempre que los encabezados error_status, error_trace, error_trace_function y error_type estén declarados en la solicitud del método.
"error_status":"500", "error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}", "error_trace_function":"abc()", "error_type":"InternalServerError"
La propiedad errorMessage.trace del cuerpo de respuesta de integración es una propiedad compleja. Se asigna al encabezado error_trace como una cadena JSON.
