Uso de AWS Lambda con Amazon API Gateway - AWS Lambda
Adición de un punto de conexión a la función de LambdaIntegración de proxyFormato de eventosFormato de respuestaPermisosAdministración de errores con una API de API GatewayElegir un tipo de APIAplicaciones de muestra

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

En esta sección se explica la información general sobre cómo elegir un tipo de API, agregar un punto de conexión a la función de Lambda e información sobre eventos, permisos, respuestas y gestión de errores.

Secciones

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

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

  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 desencadenador.

  4. Seleccione API Gateway.

  5. Seleccione Create an API (Crear una API) o Use an existing API (Usar una API existente).

    1. Nueva API: Para API type (Tipo de API), elija HTTP API (API HTTP). Para obtener más información, consulte API types (Tipos de API).

    2. API existente: Selecciona la API en el menú desplegable o introduce el ID de API (p. ej., r3pmxmplak).

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

  7. Elija Añadir.

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:

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

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. En el siguiente ejemplo, se muestra un evento proxy procedente de una API REST de API Gateway.

ejemplo event.json evento de proxy 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
  }

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.

ejemplo index.mjs: 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
  }

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.

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

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 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.mjs: 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 de Lambda:

  • API HTTP: API RESTful ligera de baja latencia.

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

  • WebSocket API: una API web que mantiene conexiones persistentes con los 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 en forma manual 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 las API HTTP y las API REST en la Guía para desarrolladores de API Gateway.

WebSocket Las API también utilizan la API API Gateway versión 2 y admiten un conjunto de funciones similar. Utilice una WebSocket API para las aplicaciones que se benefician de una conexión persistente entre el cliente y la API. WebSocket Las API proporcionan una comunicación dúplex completa, lo que significa que tanto el cliente como la API pueden enviar mensajes de forma continua 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 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 GitHub repositorio de esta guía proporciona el siguiente ejemplo de aplicación para 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 esquemas y plantillas que puede utilizar para crear una aplicación de API Gateway en la consola de Lambda.