Invocación de una función de Lambda mediante un punto de conexión de 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 de 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.

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.

Elegir un tipo de API

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

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:

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.

Para ver una comparativa detallada, consulte Elección entre las API de REST y las API de HTTP 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). Para ver un ejemplo de un evento de una API de HTTP, consulte Creación de integraciones proxy de AWS Lambda para la API de HTTP en API Gateway.

Para obtener más información, consulte Creación de integraciones de proxy de AWS Lambda Lambda para las API de HTTP en API Gateway.

Adición de un punto de conexión a la función de Lambda

Integración de proxy

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:

La integración de Lambda asigna una combinación de ruta y método HTTP a una función de 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.

Para obtener más información, consulte Integraciones de proxy de Lambda en API Gateway.

Formato de eventos

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. Para ver un ejemplo de un evento de proxy de una API de REST de API Gateway, consulte Formato de entrada de una función de Lambda para la integración de proxy en la Guía para desarrolladores de API Gateway.

Formato de respuesta

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.

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.

< 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
  }

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. A continuación se muestra una política de función de ejemplo.

{
  "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:111122223333:function:nodejs-apig-function-1G3MXMPLXVXYI",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "111122223333"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:execute-api:us-east-2:111122223333:ktyvxmpls1/*/GET/"
        }
      }
    }
  ]
}

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. Ejemplo:

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\"}}}"
}

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.

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

Aplicación de muestra

La aplicación de muestra API Gateway con Node.js incluye una función con una plantilla de SAM AWS SAM que crea una API de REST que tiene el seguimiento de AWS X-Ray habilitado. También incluye scripts para implementar, invocar la función, probar la API y limpiar.