Tutorial: Uso de Lambda con API Gateway

En este tutorial, se crea una API de REST a través la cual invoca una función de Lambda mediante una solicitud HTTP. Su función de Lambda realizará operaciones de creación, lectura, actualización y eliminación (CRUD) en una tabla de DynamoDB. Se proporciona esta función a modo de demostración, pero aprenderá a configurar una API de REST de API Gateway que pueda invocar cualquier función de Lambda.

El uso de API Gateway proporciona a los usuarios un punto de conexión seguro en HTTP para invocar la función de Lambda y puede ayudar a gestionar grandes volúmenes de llamadas a su función al limitar el tráfico, validar y autorizar automáticamente las llamadas a la API. API Gateway también proporciona controles de seguridad flexibles mediante AWS Identity and Access Management (IAM) y Amazon Cognito. Esto resulta útil para los casos de uso en los que se requiere una autorización previa para las llamadas a la aplicación.

Para completar este tutorial, pasará por las siguientes etapas:

1. Cree y configure una función de Lambda en Python o Node.js para realizar operaciones en una tabla de DynamoDB.

2. Cree una API de REST en API Gateway para conectarse a la función de Lambda.

3. Cree una tabla de DynamoDB y pruébela con la función de Lambda en la consola.

4. Despliegue su API y pruebe la configuración completa con curl en una terminal.

Al completar estas etapas, aprenderá a utilizar API Gateway para crear un punto de conexión en HTTP que pueda invocar de forma segura una función de Lambda a cualquier escala. También aprenderá a implementar su API, a probarla en la consola y a enviar una solicitud HTTP mediante una terminal.

Requisitos previos

Registro para obtener una Cuenta de AWS

Si no dispone de una Cuenta de AWS, siga estos pasos para crear una.

Cómo registrarse para una Cuenta de AWS

1. Abra https://portal.aws.amazon.com/billing/signup.

2. Siga las instrucciones que se le indiquen.

   Parte del procedimiento de registro consiste en recibir una llamada telefónica e indicar un código de verificación en el teclado del teléfono.

   Al registrarse en una Cuenta de AWS, se crea un Usuario raíz de la cuenta de AWS. El usuario raíz tendrá acceso a todos los Servicios de AWS y recursos de esa cuenta. Como práctica recomendada de seguridad, asigne acceso administrativo a un usuario administrativo y utilice únicamente el usuario raíz para realizar tareas que requieran acceso de usuario raíz.

AWS le enviará un correo electrónico de confirmación después de completar el proceso de registro. Puede ver la actividad de la cuenta y administrar la cuenta en cualquier momento entrando en https://aws.amazon.com/ y seleccionando Mi cuenta.

Crear un usuario administrativo

Después de registrarse para obtener una Cuenta de AWS, proteja su Usuario raíz de la cuenta de AWS, habilite AWS IAM Identity Center y cree un usuario administrativo para no utilizar el usuario raíz en las tareas cotidianas.

Protección de su Usuario raíz de la cuenta de AWS

1. Inicie sesión en AWS Management Console como propietario de cuenta eligiendo Usuario raíz e introduzca el correo electrónico de su Cuenta de AWS. En la siguiente página, escriba su contraseña.

   Para obtener ayuda para iniciar sesión con el usuario raíz, consulte Iniciar sesión como usuario raíz en la Guía del usuario de AWS Sign-In.

2. Active la autenticación multifactor (MFA) para el usuario raíz.

   Para obtener instrucciones, consulte Habilitar un dispositivo MFA virtual para el usuario raíz Cuenta de AWS (consola) en la Guía del usuario de IAM.

Creación de un usuario administrativo

1. Activar IAM Identity Center

   Para conocer las instrucciones, consulte Habilitar AWS IAM Identity Center en la Guía del usuario de AWS IAM Identity Center.

2. En IAM Identity Center, otorga acceso administrativo a un usuario administrativo.

   Para ver un tutorial sobre el uso de Directorio de IAM Identity Center como origen de identidad, consulte Configurar el acceso de los usuarios con la configuración predeterminada de Directorio de IAM Identity Center en la Guía del usuario de AWS IAM Identity Center.

Cómo iniciar sesión como usuario administrativo

• Para iniciar sesión con el usuario del Centro de identidades de IAM, utilice la URL de inicio de sesión que se envió a la dirección de correo electrónico cuando creó el usuario del IAM Identity Center.

  Para obtener ayuda para iniciar sesión con un usuario del IAM Identity Center, consulte Iniciar sesión en el portal de acceso de AWS en la Guía del usuario de AWS Sign-In.

Instalar la AWS Command Line Interface

Si aún no ha instalado AWS Command Line Interface, siga los pasos que se indican en Instalación o actualización de la versión más reciente de AWS CLI para instalarlo.

El tutorial requiere un intérprete de comandos o un terminal de línea de comando para ejecutar los comandos. En Linux y macOS, use su administrador de intérprete de comandos y paquetes preferido.

nota

En Windows, algunos comandos de la CLI de Bash que se utilizan habitualmente con Lambda (por ejemplo, zip) no son compatibles con los terminales integrados del sistema operativo. Para obtener una versión de Ubuntu y Bash integrada con Windows, instale el subsistema de Windows para Linux.

Crear una política de permisos

Para poder crear un rol de ejecución para la función de Lambda, primero debe crear una política de permisos que permita a la función acceder a los recursos de AWS necesarios. En este tutorial, la política permite a Lambda realizar operaciones CRUD en una tabla de DynamoDB y escribirlas en Amazon Logs. CloudWatch

Para crear la política de

1. Abra la página de Policies (Políticas) de la consola de IAM.

2. Seleccione Crear política.

3. Elija la pestaña JSON y pegue la siguiente política personalizada en el editor JSON.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "Stmt1428341300017",
         "Action": [
           "dynamodb:DeleteItem",
           "dynamodb:GetItem",
           "dynamodb:PutItem",
           "dynamodb:Query",
           "dynamodb:Scan",
           "dynamodb:UpdateItem"
         ],
         "Effect": "Allow",
         "Resource": "*"
       },
       {
         "Sid": "",
         "Resource": "*",
         "Action": [
           "logs:CreateLogGroup",
           "logs:CreateLogStream",
           "logs:PutLogEvents"
         ],
         "Effect": "Allow"
       }
     ]
   }

4. Elija Siguiente: Etiquetas.

5. Elija Siguiente: Revisar.

6. En Review policy (Revisar política), para el Name (Nombre) de la política, ingrese lambda-apigateway-policy.

7. Elija Crear política.

Creación de un rol de ejecución

Un rol de ejecución es un rol de AWS Identity and Access Management (IAM) que concede a la función de Lambda permiso para acceder a servicios y recursos de AWS. Para permitir que la función realice operaciones en una tabla de DynamoDB, adjuntará la política de permisos que creó en el paso anterior.

Para crear una función de ejecución y adjuntar su política de permisos personalizada

1. Abra la página Roles en la consola de IAM.

2. Elija Crear rol.

3. Para el tipo de entidad de confianza, seleccione Servicio de AWS y, para el caso de uso, elija Lambda.

4. Seleccione Siguiente.

5. En el cuadro de búsqueda de políticas, escriba lambda-apigateway-policy.

6. En los resultados de búsqueda, seleccione la política que ha creado (lambda-apigateway-policy), y luego Next (Siguiente).

7. En Role details (Detalles del rol), introduzca lambda-apigateway-role en Role name (Nombre del rol) y, luego, elija Create role (Crear rol).

Más adelante en el tutorial, necesitará el nombre de recurso de Amazon (ARN) del rol que acaba de crear. En la página Roles (Roles) de la consola de IAM, seleccione el nombre de su rol (lambda-apigateway-role) y copie el Role ARN (ARN del rol) que aparece en la página Summary (Resumen).

Creación de la función

El siguiente ejemplo de código recibe una entrada de evento de API Gateway en la que se especifica la operación que se debe realizar en la tabla de DynamoDB que creará y algunos datos de carga. Si los parámetros que recibe la función son válidos, realice la operación solicitada en la tabla.

Node.js

ejemplo index.mjs

console.log('Loading function');

import { DynamoDBDocumentClient, PutCommand, GetCommand, 
         UpdateCommand, DeleteCommand} from "@aws-sdk/lib-dynamodb";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

const ddbClient = new DynamoDBClient({ region: "us-west-2" });
const ddbDocClient = DynamoDBDocumentClient.from(ddbClient);

// Define the name of the DDB table to perform the CRUD operations on
const tablename = "lambda-apigateway";

/**
 * Provide an event that contains the following keys:
 *
 *   - operation: one of 'create,' 'read,' 'update,' 'delete,' or 'echo'
 *   - payload: a JSON object containing the parameters for the table item
 *              to perform the operation on
 */
export const handler = async (event, context) => {
   
     const operation = event.operation;
   
     if (operation == 'echo'){
          return(event.payload);
     }
     
    else { 
        event.payload.TableName = tablename;
        
        switch (operation) {
          case 'create':
               await ddbDocClient.send(new PutCommand(event.payload));
               break;
          case 'read':
               var table_item = await ddbDocClient.send(new GetCommand(event.payload));
               console.log(table_item);
               break;
          case 'update':
               await ddbDocClient.send(new UpdateCommand(event.payload));
               break;
          case 'delete':
               await ddbDocClient.send(new DeleteCommand(event.payload));
               break;
          default:
            return ('Unknown operation: ${operation}');
          }
    }
};

nota

En este ejemplo, el nombre de la tabla de DynamoDB se define como una variable en el código de la función. En la aplicación real, la mejor práctica es pasar este parámetro como variable de entorno y evitar codificar el nombre de la tabla. Para obtener más información, consulte Uso de variables de entorno de AWS Lambda.

Cómo crear la función

1. Guarde el ejemplo de código como un archivo denominado index.mjs y, si es necesario, edite la región AWS especificada en el código. La región especificada en el código debe ser la misma que la región en la que se crea la tabla de DynamoDB más adelante en el tutorial.

2. Cree un paquete de despliegue utilizando el siguiente comando zip.

   zip function.zip index.mjs

3. Cree una función de Lambda con el comando create-function de la AWS CLI. Para el parámetro role, introduzca el nombre de recurso de Amazon (ARN) del rol de ejecución que copió anteriormente.

   aws lambda create-function --function-name LambdaFunctionOverHttps \
   --zip-file fileb://function.zip --handler index.handler --runtime nodejs18.x \
   --role arn:aws:iam::123456789012:role/service-role/lambda-apigateway-role

Python 3

ejemplo LambdaFunctionOverHttps.py

import boto3
import json

# define the DynamoDB table that Lambda will connect to
tableName = "lambda-apigateway"

# create the DynamoDB resource
dynamo = boto3.resource('dynamodb').Table(tableName)

print('Loading function')

def handler(event, context):
    '''Provide an event that contains the following keys:

      - operation: one of the operations in the operations dict below
      - payload: a JSON object containing parameters to pass to the 
                 operation being performed
    '''
    
    # define the functions used to perform the CRUD operations
    def ddb_create(x):
        dynamo.put_item(**x)

    def ddb_read(x):
        dynamo.get_item(**x)

    def ddb_update(x):
        dynamo.update_item(**x)
        
    def ddb_delete(x):
        dynamo.delete_item(**x)

    def echo(x):
        return x

    operation = event['operation']

    operations = {
        'create': ddb_create,
        'read': ddb_read,
        'update': ddb_update,
        'delete': ddb_delete,
        'echo': echo,
    }

    if operation in operations:
        return operations[operation](event.get('payload'))
    else:
        raise ValueError('Unrecognized operation "{}"'.format(operation))

nota

En este ejemplo, el nombre de la tabla de DynamoDB se define como una variable en el código de la función. En la aplicación real, la mejor práctica es pasar este parámetro como variable de entorno y evitar codificar el nombre de la tabla. Para obtener más información, consulte Uso de variables de entorno de AWS Lambda.

Cómo crear la función

1. Guarde el código de ejemplo como un archivo denominado LambdaFunctionOverHttps.py.

2. Cree un paquete de despliegue utilizando el siguiente comando zip.

   zip function.zip LambdaFunctionOverHttps.py

3. Cree una función de Lambda con el comando create-function de la AWS CLI. Para el parámetro role, introduzca el nombre de recurso de Amazon (ARN) del rol de ejecución que copió anteriormente.

   aws lambda create-function --function-name LambdaFunctionOverHttps \
   --zip-file fileb://function.zip --handler LambdaFunctionOverHttps.handler --runtime python3.9 \
   --role arn:aws:iam::123456789012:role/service-role/lambda-apigateway-role

Invoque la función de utilizando el comando de AWS CLI.

Antes de integrar la función con API Gateway, confirme que la ha implementado de forma correcta. Cree un evento de prueba que contenga los parámetros que la API de API Gateway enviará a Lambda y utilice el comando de la AWS CLI invoke para ejecutar la función.

Para invocar la función de Lambda con el comando AWS CLI.

1. Guarde el siguiente JSON como un archivo denominado input.txt.

   {
       "operation": "echo",
       "payload": {
           "somekey1": "somevalue1",
           "somekey2": "somevalue2"
       }
   }

2. Ejecute el siguiente comando AWS CLI de la invoke.

   aws lambda invoke --function-name LambdaFunctionOverHttps \
   --payload file://input.txt outputfile.txt --cli-binary-format raw-in-base64-out

   La opción cli-binary-format es obligatoria si va a utilizar la versión 2 de la AWS CLI. Para que esta sea la configuración predeterminada, ejecute aws configure set cli-binary-format raw-in-base64-out. Para obtener más información, consulte Opciones de la línea de comandos globales compatibles con AWS CLI en la Guía del usuario de la AWS Command Line Interface versión 2.

   Debería ver la siguiente respuesta:

   {
   "StatusCode": 200,
   "ExecutedVersion": "LATEST"
   }
   

3. Confirme que la función ha realizado la operación echo que especificó en el evento de prueba de JSON. Inspeccione el archivo outputfile.txt y compruebe que contiene lo siguiente:

   {"somekey1": "somevalue1", "somekey2": "somevalue2"}

Creación de una API REST mediante API Gateway

En este paso, crea la API de REST de API Gateway que utilizará para invocar la función de Lambda.

Para crear la API

1. Abra la consola de API Gateway.

2. Seleccione Create API (Crear API).

3. En el cuadro REST API (API de REST), elija Build (Crear).

4. En Detalles de la API, deje seleccionada la opción Nueva API y, en Nombre de la API, ingrese DynamoDBOperations.

5. Seleccione Create API (Crear API).

Creación de un recurso en su API de REST.

Para agregar un método HTTP a su API, primero debe crear un recurso para que funcione ese método. Aquí, se crea el recurso para administrar la tabla de DynamoDB.

Para crear el recurso

1. En la consola de puerta de enlace de API, en la página Recursos de su API, seleccione Crear recurso.

2. En Detalles del recurso, ingrese el nombre del recursoDynamoDBManager.

3. Elija Create Resource (Crear recurso).

Creación de un método HTTP POST.

En este paso, creará un método (POST) para su recurso DynamoDBManager. Debe vincular este método POST a la función de Lambda para que cuando el método reciba una solicitud HTTP, API Gateway invoca la función de Lambda.

nota

A los efectos de este tutorial, se utiliza un método HTTP (POST) para invocar una única función de Lambda que lleva a cabo todas las operaciones de la tabla de DynamoDB. En una aplicación real, la práctica recomendada es utilizar una función de Lambda y un método HTTP diferente para cada operación. Para obtener más información, consulte The Lambda monolith en Serverless Land.

Para crear el método POST

1. En la página Eecursos de su API, asegúrese de que el recurso /DynamoDBManager esté resaltado. A continuación, en el panel Métodos, seleccione Crear método.

2. En Tipo de método, elija POST.

3. En Tipo de integración, seleccione función de Lambda.

4. Para la función de Lambda, elija el nombre de recurso de Amazon (ARN) para la función (LambdaFunctionOverHttps).

5. Elija Crear método.

Creación de una tabla de DynamoDB

Cree una tabla de DynamoDB vacía en la que la función de Lambda realizará operaciones CRUD.

Creación de la tabla de DynamoDB

1. Abra la página Tables (Tablas) en la consola de DynamoDB.

2. Elija Crear tabla.

3. En Table details (Detalles de la tabla), haga lo siguiente:

   1. En Nombre de la tabla, introduzca lambda-apigateway.

   2. En Partition key (Clave de partición), ingrese id y mantenga el tipo de datos establecido como String (Cadena).

4. En Settings (Configuración), mantenga los valores predeterminados en Default settings (Configuración predeterminada).

5. Elija Crear tabla.

Pruebe la integración de API Gateway, Lambda y DynamoDB.

Ya está listo para probar la integración del método de API de API Gateway con la función de Lambda y la tabla de DynamoDB. Con la consola de API Gateway, envíe las solicitudes directamente a su método POST mediante la función de prueba de la consola. En este paso, primero use una operación create para agregar un nuevo elemento a la tabla de DynamoDB y, a continuación, use una operación update para modificar el elemento.

Prueba 1: Crear un nuevo elemento en la tabla de DynamoDB

1. En la consola de API Gateway, elija su API (DynamoDBOperations).

2. Elija el método POST en el DynamoDBManager recurso.

   

3. Elija la pestaña Prueba. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.

4. En Método de prueba, deje vacías las cadenas de consulta y los encabezados. En Cuerpo de la solicitud, pegue el siguiente JSON:

   {
     "operation": "create",
     "payload": {
       "Item": {
         "id": "1234ABCD",
         "number": 5
       }
     }
   }

5. Seleccione Probar.

   Los resultados que se muestran al finalizar la prueba deben mostrar el estado 200. Este código de estado indica que la operación create se ha realizado correctamente.

   Para confirmarlo, verifique que ahora su tabla de DynamoDB contenga un nuevo elemento.

6. Abra la página Tables (Tablas) en la consola de DynamoDB y elija la tabla lambda-apigateway.

7. Elija Explore table items (Explorar elementos de la tabla). En el panel Items returned (Devolución de elementos), debería ver un elemento con el id1234ABCD y el número de 5.

Prueba 2: Actualización del elemento de la tabla de DynamoDB

1. En la consola de la puerta de enlace de API, vuelva a la pestaña Prueba del método POST.

2. En Método de prueba, deje vacías las cadenas de consulta y los encabezados. En Cuerpo de la solicitud, pegue el siguiente JSON:

   {
       "operation": "update",
       "payload": {
           "Key": {
               "id": "1234ABCD"
           },
           "AttributeUpdates": {
               "number": {
                   "Value": 10
               }
           }
       }
   }

3. Seleccione Probar.

   Los resultados que se muestran cuando finaliza la prueba deben mostrar el estado 200. Este código de estado indica que la operación de update se ha realizado correctamente.

   Para confirmarlo, compruebe que el elemento de la tabla de DynamoDB se haya modificado.

4. Abra la página Tables (Tablas) en la consola de DynamoDB y elija la tabla lambda-apigateway.

5. Elija Explore table items (Explorar elementos de la tabla). En el panel Items returned (Devolución de elementos), debería ver un elemento con el id1234ABCD y el número de 10.

Implementar la API

Para que un cliente llame a la API, debe crear una implementación y una etapa asociada. La etapa representa una imagen instantánea de su API, incluidos sus métodos e integraciones.

Para implementar la API

1. Abra la página API de la consola de API Gateway y seleccione la API de DynamoDBOperations.

2. En la página Recursos de su API, seleccione Implementar la API.

3. Para la Etapa de implementación, seleccione *Nueva etapa* y, en Nombre de etapa, introduzca test.

4. Elija Implementar.

5. En el panel Editor de etapas de prueba, copie la URL de invocación. Lo utilizará en el siguiente paso para invocar su función mediante una solicitud HTTP.

Utilice curl para invocar tu función mediante solicitudes HTTP.

Ahora puede invocar la función de Lambda al emitir una solicitud HTTP a la API. En este paso, creará un elemento nuevo en la tabla de DynamoDB y, a continuación, lo eliminará.

Para invocar la función de Lambda mediante curl

1. Ejecute el siguiente comando curl por medio de la URL de invocación que copió en el paso anterior. Cuando use el curl con la opción -d (data), utilice automáticamente el método HTTP POST.

   curl https://l8togsqxd8.execute-api.us-west-2.amazonaws.com/test/DynamoDBManager \
   -d '{"operation": "create", "payload": {"Item": {"id": "5678EFGH", "number": 15}}}'

2. Para verificar que la operación de creación se realizó correctamente, haga lo siguiente:

   1. Abra la página Tables (Tablas) en la consola de DynamoDB y elija la tabla lambda-apigateway.

   2. Elija Explore table items (Explorar elementos de la tabla). En el panel Items returned (Devolución de elementos), debería ver un elemento con el id5678EFGH y el número15.

3. Si lo desea, ejecute el siguiente comando para eliminar el curl que ha creado. Utilice su propia URL de invocación.

   curl https://l8togsqxd8.execute-api.us-west-2.amazonaws.com/test/DynamoDBManager \
   -d '{"operation": "delete", "payload": {"Key": {"id": "5678EFGH"}}}'

4. Confirme que la operación de eliminación se ha realizado correctamente. En el panel Elementos devueltos de la página Explorar elementos de la consola de DynamoDB, verifique que el elemento con id 5678EFGH ya no se encuentre en la tabla.

Elimine sus recursos (opcional)

A menos que desee conservar los recursos que creó para este tutorial, puede eliminarlos ahora. Si elimina los recursos de AWS que ya no utiliza, evitará gastos innecesarios en su cuenta de AWS.

Cómo eliminar la función de Lambda

1. Abra la página de Funciones en la consola de Lambda.

2. Seleccione la función que ha creado.

3. Elija Acciones, Eliminar.

4. Escriba delete en el campo de entrada de texto y elija Delete(Eliminar).

Cómo eliminar el rol de ejecución

1. Abra la página Roles en la consola de IAM.

2. Seleccione el rol de ejecución que creó.

3. Elija Eliminar.

4. Si desea continuar, escriba el nombre del rol en el campo de entrada de texto y elija Delete (Eliminar).

Para eliminar la API

1. Abra la página API de la consola de API Gateway.

2. Seleccione la API que ha creado.

3. Elija Actions (Acciones), Delete (Eliminar).

4. Elija Eliminar.

Para eliminar una tabla de DynamoDB

1. Abra la página Tables (Tablas) en la consola de DynamoDB.

2. Seleccione la tabla que ha creado.

3. Elija Eliminar.

4. Escriba delete en el cuadro de texto.

5. Elija Delete table (Eliminar tabla).