Elegir un tipo de API Adición de un punto de conexión a la función de Lambda Integración de proxy Formato de eventos Formato de respuesta Permisos Aplicación de muestra

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.

Secciones

Elegir un tipo de API
Adición de un punto de conexión a la función de Lambda
Integración de proxy
Formato de eventos
Formato de respuesta
Permisos
Aplicación de muestra
Tutorial: Uso de Lambda con API Gateway
Manejo de los errores en Lambda con una API de API Gateway

Elegir un tipo de API

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

API HTTP: una API de RESTful ligera de baja latencia.
API de REST: una API de RESTful personalizable con gran variedad de características.
API de WebSocket: una 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 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.

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

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

Abra la página de Funciones en la consola de Lambda.
Elija una función.
En Descripción general de la función, elija Agregar desencadenador.
Seleccione API Gateway.
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).
En Security (Seguridad), elija Open (Abrir).
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.

Para obtener más información, consulte Configuración de las integraciones del 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. 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 de AWS 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.

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.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Alexa

Tutorial