Uso de AWS Lambda con Amazon API Gateway - AWS Lambda

Uso de AWS Lambda con Amazon API Gateway

Puede crear una API web con un punto de enlace HTTP para la función Lambda utilizando Amazon API Gateway. API Gateway dispone de herramientas para crear y documentar API web que enrutan solicitudes HTTP a funciones Lambda. Puede proteger el acceso a la API con controles de autenticación y autorización. Las API pueden atender el tráfico a través de Internet o estar accesibles exclusivamente en la VPC.

Para agregar un punto de enlace público a la función Lambda

  1. Abra la Página de funciones en la consola de Lambda.

  2. Elija una función.

  3. En Functional overview (Descripción general de la función), elija Add trigger (Agregar disparador).

  4. Seleccione API Gateway.

  5. En API, elija Create an API (Crear una API).

  6. En Security (Seguridad), elija Open (Abrir).

  7. Elija Add (Añadir).

Las API de API Gateway se componen de etapas, recursos, métodos e integraciones. La etapa y el recurso determinan la ruta del punto de enlace:

Formato de la ruta de las API

  • /prod/: etapa prod y recurso raíz.

  • /prod/user: etapa prod y recurso user.

  • /dev/{proxy+}: cualquier ruta de la etapa dev.

  • /: (API HTTP) etapa predeterminada y recurso raíz.

La integración de Lambda asigna una combinación de ruta y método HTTP a una función Lambda. Puede configurar API Gateway para pasar el cuerpo de la solicitud HTTP tal cual (integración personalizada) o para encapsular el cuerpo de la solicitud en un documento que incluya toda la información de la solicitud, incluidos los encabezados, los recursos, la ruta y el método.

Amazon API Gateway invoca la función sincrónicamente con un evento que contiene una representación JSON de la solicitud HTTP. En las integraciones personalizadas, el evento es el cuerpo de la solicitud. En las integraciones de proxy, el evento tiene una estructura definida. En el siguiente ejemplo, se muestra un evento proxy procedente de una API REST de API Gateway.

ejemplo event.json: evento de proxy de API Gateway (REST API).

{ "resource": "/", "path": "/", "httpMethod": "GET", "requestContext": { "resourcePath": "/", "httpMethod": "GET", "path": "/Prod/", ... }, "headers": { "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "accept-encoding": "gzip, deflate, br", "Host": "70ixmpl4fl.execute-api.us-east-2.amazonaws.com", "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.132 Safari/537.36", "X-Amzn-Trace-Id": "Root=1-5e66d96f-7491f09xmpl79d18acf3d050", ... }, "multiValueHeaders": { "accept": [ "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9" ], "accept-encoding": [ "gzip, deflate, br" ], ... }, "queryStringParameters": null, "multiValueQueryStringParameters": null, "pathParameters": null, "stageVariables": null, "body": null, "isBase64Encoded": false }

En este ejemplo, se muestra un evento de una solicitud GET en la ruta raíz de la etapa Prod de una API REST. La forma y el contenido del evento varían según el tipo de API y la configuración.

API Gateway espera una respuesta de la función y transmite el resultado a la persona que llama. En las integraciones personalizadas, debe definir una respuesta de integración y una respuesta de método para convertir la salida de la función en una respuesta HTTP. En las integraciones de proxy, la función debe responder con una representación de la respuesta en un formato específico.

En el ejemplo siguiente, se muestra un objeto response de una función Node.js. El objeto response representa una respuesta HTTP correcta que contiene un documento JSON.

ejemplo index.js:– objeto de respuesta de integración de proxy (Node.js).

var response = { "statusCode": 200, "headers": { "Content-Type": "application/json" }, "isBase64Encoded": false, "multiValueHeaders": { "X-Custom-Header": ["My value", "My other value"], }, "body": "{\n \"TotalCodeSize\": 104330022,\n \"FunctionCount\": 26\n}" }

El tiempo de ejecución de Lambda serializa el objeto response en un archivo JSON y lo envía a la API. La API analiza la respuesta y la utiliza para crear una respuesta HTTP, que luego envía al cliente que realizó la solicitud original.

ejemplo Respuesta HTTP

< HTTP/1.1 200 OK < Content-Type: application/json < Content-Length: 55 < Connection: keep-alive < x-amzn-RequestId: 32998fea-xmpl-4268-8c72-16138d629356 < X-Custom-Header: My value < X-Custom-Header: My other value < X-Amzn-Trace-Id: Root=1-5e6aa925-ccecxmplbae116148e52f036 < { "TotalCodeSize": 104330022, "FunctionCount": 26 }

Los recursos de la API definen uno o varios métodos, como GET o POST. Los métodos tienen una integración que enruta las solicitudes a una función Lambda o a otro tipo de integración. Puede definir cada recurso y cada método de manera individual, o utilizar tipos de recursos y métodos especiales para que coincidan con todas las solicitudes que se ajustan a un patrón. Un recurso proxy captura todas las rutas que hay debajo de un recurso. El método ANY captura todos los métodos HTTP.

Permisos

Amazon API Gateway necesita permiso para invocar la función desde la política basada en recursos de la función. Puede conceder permiso de invocación a toda una API o conceder acceso limitado a una etapa, un recurso o un método.

Cuando agrega una API a la función utilizando la consola de Lambda, la consola de API Gateway o una plantilla de AWS SAM, la política basada en recursos de la función se actualiza automáticamente. En el ejemplo siguiente, se muestra la política de una función con una instrucción agregada mediante una plantilla de AWS SAM.

ejemplo política de funciones

{ "Version": "2012-10-17", "Id": "default", "Statement": [ { "Sid": "nodejs-apig-functiongetEndpointPermissionProd-BWDBXMPLXE2F", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:us-east-2:123456789012:function:nodejs-apig-function-1G3MXMPLXVXYI", "Condition": { "ArnLike": { "AWS:SourceArn": "arn:aws:execute-api:us-east-2:123456789012:ktyvxmpls1/*/GET/" } } } ] }

Confirme la política de la función en la pestaña Permissions (Permisos) de la consola de Lambda.

Puede administrar manualmente los permisos de las políticas de funciones con las siguientes operaciones de API:

Para conceder permiso de invocación a una API existente, utilice el comando add-permission.

aws lambda add-permission --function-name my-function \ --statement-id apigateway-get --action lambda:InvokeFunction \ --principal apigateway.amazonaws.com \ --source-arn "arn:aws:execute-api:us-east-2:123456789012:mnh1xmpli7/default/GET/"

Debería ver los siguientes datos de salida:

{ "Statement": "{\"Sid\":\"apigateway-test-2\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"apigateway.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource\":\"arn:aws:lambda:us-east-2:123456789012:function:my-function\",\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:execute-api:us-east-2:123456789012:mnh1xmpli7/default/GET\"}}}" }
nota

Si la función y la API se encuentran en regiones diferentes, el identificador de región en el ARN del origen debe coincidir con la región de la función, no la región de la API. Cuando API Gateway invoca una función, utiliza el ARN de un recurso que se basa en el ARN de la API, pero que se ha modificado para que coincida con la región de la función.

El ARN de origen de este ejemplo concede permiso a una integración del método GET del recurso raíz en la etapa predeterminada de una API, con el ID mnh1xmpli7. Puede utilizar un asterisco en el ARN de origen para conceder permisos a varias etapas, métodos o recursos.

Patrones de recursos

  • mnh1xmpli7/*/GET/*: método GET de todos los recursos en todas las etapas.

  • mnh1xmpli7/prod/ANY/user: método ANY del recurso user en la etapa prod.

  • mnh1xmpli7/*/*/*: cualquier método de todos los recursos en todas las etapas.

Para obtener información detallada acerca de cómo ver la política y quitar instrucciones, consulte Limpieza de políticas basadas en recursos.

Administración de errores con una API de API Gateway

API Gateway trata todos los errores de las invocaciones y las funciones como errores internos. Si la API de Lambda rechaza la solicitud de invocación, API Gateway devuelve un código de error 500. Si la función se ejecuta pero devuelve un error o devuelve una respuesta con un formato incorrecto, API Gateway muestra un error 502. En ambos casos, el cuerpo de la respuesta de API Gateway es {"message": "Internal server error"}.

nota

API Gateway no vuelve a intentar ninguna invocación de Lambda. Si Lambda devuelve un error, API Gateway devuelve una respuesta de error al cliente.

En el ejemplo siguiente, se muestra un mapa de seguimiento de X-Ray de una solicitud que generó un error de función y un error 502 de API Gateway. El cliente recibirá el mensaje de error genérico.


        Mapa de seguimiento de un error de función con API Gateway.

Para personalizar la respuesta del error, debe detectar errores en el código y elaborar una respuesta en el formato que desee.

ejemplo index.js:– error de formato.

var formatError = function(error){ var response = { "statusCode": error.statusCode, "headers": { "Content-Type": "text/plain", "x-amzn-ErrorType": error.code }, "isBase64Encoded": false, "body": error.code + ": " + error.message } return response }

API Gateway convierte esta respuesta en un error HTTP con un código de estado y un cuerpo personalizados. En el mapa de seguimiento, el nodo de la función es verde porque el error se administró correctamente.


        Mapa de seguimiento de un error al que se le aplicó formato con API Gateway.

Elegir un tipo de API

API Gateway admite tres tipos de API que invocan funciones Lambda:

  • API HTTP: API RESTful ligera de baja latencia.

  • API REST: API RESTful personalizable con gran variedad de características.

  • API WebSocket : API web que mantiene conexiones persistentes con clientes para una comunicación dúplex completa.

Las API HTTP y REST son API RESTful que procesan solicitudes HTTP y devuelven respuestas. Las API HTTP son más recientes y se construyen con la API de la versión 2 de API Gateway. Las siguientes características son nuevas en las API HTTP:

Características de las API HTTP

  • Implementaciones automáticas: cuando se modifican rutas o integraciones, los cambios se implementan automáticamente en etapas que tienen habilitada la implementación automática.

  • Etapa predeterminada: puede crear una etapa predeterminada ($default) para atender las solicitudes en la ruta raíz de la URL de la API. En las etapas con nombre asignado, debe incluir el nombre de la etapa al principio de la ruta.

  • Configuración CORS: puede configurar la API para agregar encabezados CORS a las respuestas salientes, en lugar de agregarlos manualmente en el código de función.

Las API REST son las API RESTful clásicas que API Gateway admite desde su lanzamiento. En la actualidad, las API REST tienen más características de personalización, integración y administración.

Características de las API REST

  • Tipos de integración: las API REST son compatibles con las integraciones de Lambda personalizadas. Con una integración personalizada, puede enviar solo el cuerpo de la solicitud a la función o aplicar una plantilla de transformación al cuerpo de la solicitud antes de enviarla a la función.

  • Control de acceso: las API REST admiten más opciones de autenticación y autorización.

  • Monitoreo y seguimiento: la API REST admiten el seguimiento de AWS X-Ray y otras opciones de registro.

Para ver una comparativa detallada, consulte Elección entre HTTP API y REST API en la Guía para desarrolladores de API Gateway.

Las API de WebSocket también usan la API de la versión 2 de API Gateway y admiten un conjunto de características similares. Utilice una API de WebSocket para las aplicaciones que se benefician de una conexión persistente entre el cliente y la API. Las API de WebSocket proporcionan comunicación dúplex completa, lo que significa que tanto el cliente como la API pueden enviar mensajes continuamente sin esperar una respuesta.

Las API HTTP admiten un formato de evento simplificado (versión 2.0). En el ejemplo siguiente, se muestra el evento de una API HTTP.

ejemplo event-v2.json:– evento de proxy de API Gateway (API HTTP).

{ "version": "2.0", "routeKey": "ANY /nodejs-apig-function-1G3XMPLZXVXYI", "rawPath": "/default/nodejs-apig-function-1G3XMPLZXVXYI", "rawQueryString": "", "cookies": [ "s_fid=7AABXMPL1AFD9BBF-0643XMPL09956DE2", "regStatus=pre-register" ], "headers": { "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "accept-encoding": "gzip, deflate, br", ... }, "requestContext": { "accountId": "123456789012", "apiId": "r3pmxmplak", "domainName": "r3pmxmplak.execute-api.us-east-2.amazonaws.com", "domainPrefix": "r3pmxmplak", "http": { "method": "GET", "path": "/default/nodejs-apig-function-1G3XMPLZXVXYI", "protocol": "HTTP/1.1", "sourceIp": "205.255.255.176", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.132 Safari/537.36" }, "requestId": "JKJaXmPLvHcESHA=", "routeKey": "ANY /nodejs-apig-function-1G3XMPLZXVXYI", "stage": "default", "time": "10/Mar/2020:05:16:23 +0000", "timeEpoch": 1583817383220 }, "isBase64Encoded": true }

Para obtener más información, consulte este artículo sobre las integraciones de AWS Lambda en la Guía para desarrolladores de API Gateway.

Aplicaciones de muestra

El repositorio de GitHub para esta guía incluye la siguiente aplicación de ejemplo de API Gateway.

  • API Gateway con Node.js: función con una plantilla de AWS SAM que crea una API REST que tiene el seguimiento de AWS X-Ray habilitado. Incluye scripts para implementar, invocar la función, probar la API y limpiar.

Lambda también dispone de proyectos y plantillas que puede utilizar para crear una aplicación de API Gateway en la consola de Lambda.