Tutorial: uso di Lambda con Amazon API Gateway

In questo tutorial, viene creata una REST API tramite la quale viene richiamata una funzione Lambda utilizzando una richiesta HTTP. La funzione Lambda eseguirà operazioni di creazione, aggiornamento ed eliminazione (CRUD) su una tabella DynamoDB. Questa funzione viene fornita qui a scopo dimostrativo, ma imparerai a configurare una REST API di Gateway API in grado di richiamare qualsiasi funzione Lambda.

L'utilizzo di Gateway API fornisce agli utenti un endpoint HTTP sicuro per richiamare la funzione Lambda e può aiutare a gestire grandi volumi di chiamate alla funzione limitando il traffico e convalidando e autorizzando automaticamente le chiamate API. API Gateway fornisce anche controlli di sicurezza flessibili utilizzando AWS Identity and Access Management (IAM) e Amazon Cognito. Ciò è utile nei casi d'uso in cui è richiesta un'autorizzazione preventiva per le chiamate all'applicazione.

Per completare questo tutorial, saranno completate le seguenti fasi:

1. Crea e configura una funzione Lambda in Python o Node.js per eseguire operazioni su una tabella DynamoDB.

2. Crea una REST API in Gateway API per connetterti alla funzione Lambda.

3. Crea una tabella DynamoDB e testala con la funzione Lambda nella console.

4. Implementa la tua API e testa la configurazione completa usando curl in un terminale.

Completando queste fasi, imparerai come utilizzare Gateway API per creare un endpoint HTTP in grado di richiamare in modo sicuro una funzione Lambda su qualsiasi scala. Imparerai anche come distribuire la tua API e come testarla nella console e inviando una richiesta HTTP tramite un terminale.

Prerequisiti

Registrati per un Account AWS

Se non ne hai uno Account AWS, completa i seguenti passaggi per crearne uno.

Per iscriverti a un Account AWS

1. Apri la pagina all'indirizzo https://portal.aws.amazon.com/billing/signup.

2. Segui le istruzioni online.

   Nel corso della procedura di registrazione riceverai una telefonata, durante la quale sarà necessario inserire un codice di verifica attraverso la tastiera del telefono.

   Quando ti iscrivi a un Account AWS, Utente root dell'account AWSviene creato un. L'utente root dispone dell'accesso a tutte le risorse e tutti i Servizi AWS nell'account. Come procedura consigliata in materia di sicurezza, assegnate l'accesso amministrativo a un utente e utilizzate solo l'utente root per eseguire attività che richiedono l'accesso da parte dell'utente root.

AWS ti invia un'e-mail di conferma dopo il completamento della procedura di registrazione. È possibile visualizzare l'attività corrente dell'account e gestire l'account in qualsiasi momento accedendo all'indirizzo https://aws.amazon.com/ e selezionando Il mio account.

Crea un utente con accesso amministrativo

Dopo esserti registrato Account AWS, proteggi Utente root dell'account AWS AWS IAM Identity Center, abilita e crea un utente amministrativo in modo da non utilizzare l'utente root per le attività quotidiane.

Proteggi i tuoi Utente root dell'account AWS

1. Accedi AWS Management Consolecome proprietario dell'account scegliendo Utente root e inserendo il tuo indirizzo Account AWS email. Nella pagina successiva, inserisci la password.

   Per informazioni sull'accesso utilizzando un utente root, consulta la pagina Signing in as the root user della Guida per l'utente di Accedi ad AWS .

2. Abilita l'autenticazione a più fattori (MFA) per l'utente root.

   Per istruzioni, consulta Abilitare un dispositivo MFA virtuale per l'utente Account AWS root (console) nella Guida per l'utente IAM.

Crea un utente con accesso amministrativo

1. Abilita Centro identità IAM.

   Per istruzioni, consulta Abilitazione di AWS IAM Identity Center nella Guida per l'utente di AWS IAM Identity Center .

2. In IAM Identity Center, concedi l'accesso amministrativo a un utente.

   Per un tutorial sull'utilizzo di IAM Identity Center directory come fonte di identità, consulta Configurare l'accesso utente con le impostazioni predefinite IAM Identity Center directory nella Guida per l'AWS IAM Identity Center utente.

Accedi come utente con accesso amministrativo

• Per accedere con l'utente IAM Identity Center, utilizza l'URL di accesso che è stato inviato al tuo indirizzo e-mail quando hai creato l'utente IAM Identity Center.

  Per informazioni sull'accesso utilizzando un utente IAM Identity Center, consulta AWS Accedere al portale di accesso nella Guida per l'Accedi ad AWS utente.

Assegna l'accesso ad altri utenti

1. In IAM Identity Center, crea un set di autorizzazioni che segua la migliore pratica di applicazione delle autorizzazioni con privilegi minimi.

   Per istruzioni, consulta Creare un set di autorizzazioni nella Guida per l'utente.AWS IAM Identity Center

2. Assegna gli utenti a un gruppo, quindi assegna l'accesso Single Sign-On al gruppo.

   Per istruzioni, consulta Aggiungere gruppi nella Guida per l'utente.AWS IAM Identity Center

Installa il AWS Command Line Interface

Se non l'hai ancora installato AWS Command Line Interface, segui i passaggi indicati in Installazione o aggiornamento della versione più recente di AWS CLI per installarlo.

Per eseguire i comandi nel tutorial, sono necessari un terminale a riga di comando o una shell (interprete di comandi). In Linux e macOS, utilizza la shell (interprete di comandi) e il gestore pacchetti preferiti.

Nota

Su Windows, alcuni comandi della CLI Bash utilizzati comunemente con Lambda (ad esempio, zip) non sono supportati dai terminali integrati del sistema operativo. Per ottenere una versione integrata su Windows di Ubuntu e Bash, installa il sottosistema Windows per Linux.

Creazione di una policy di autorizzazione

Prima di poter creare un ruolo di esecuzione per la tua funzione Lambda, devi prima creare una politica di autorizzazioni per concedere alla funzione il permesso di accedere alle risorse richieste. AWS Per questo tutorial, la policy consente a Lambda di eseguire operazioni CRUD su una tabella DynamoDB e scrivere su Amazon Logs. CloudWatch

Come creare la policy

1. Apri la pagina Policies (Policy) nella console IAM.

2. Scegliere Create Policy (Crea policy).

3. Scegliere la scheda JSON e quindi incollare la seguente policy personalizzata nell'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. Scegliere Next: Tags (Successivo: Tag).

5. Scegliere Next:Review (Successivo: Rivedi).

6. In Rivedi policy, per Nome della policy inserisci lambda-apigateway-policy.

7. Scegli Crea policy.

Creazione di un ruolo di esecuzione

Un ruolo di esecuzione è un ruolo AWS Identity and Access Management (IAM) che concede a una funzione Lambda l'autorizzazione ad AWS accedere a servizi e risorse. Per consentire alla funzione di eseguire operazioni su una tabella DynamoDB, collega la policy di autorizzazione che hai creato nella fase precedente.

Creazione di un ruolo di esecuzione e collegamento di una policy di autorizzazione personalizzata

1. Aprire la pagina Roles (Ruoli) della console IAM.

2. Scegliere Create role (Crea ruolo).

3. Per il tipo di entità attendibile, scegli Servizio AWS , quindi per il caso d'uso seleziona Lambda.

4. Seleziona Successivo.

5. Nella casella di ricerca delle policy, immettere lambda-apigateway-policy.

6. Nei risultati della ricerca, seleziona la policy creata (lambda-apigateway-policy), quindi scegli Next (Successivo).

7. In Role details (Dettagli del ruolo), per Role name (Nome del ruolo), specifica lambda-apigateway-role, quindi scegli Create role (Crea ruolo).

Più avanti nel tutorial sarà necessario il nome della risorsa Amazon (ARN) del ruolo appena creato. Nella pagina Roles (Ruoli) della console IAM, scegli il nome del ruolo (lambda-apigateway-role) e copia l'ARN del ruolo visualizzato nella pagina Summary (Riepilogo).

Creazione della funzione

Il seguente esempio di codice riceve un input di evento da Gateway API che specifica un'operazione da eseguire sulla tabella DynamoDB che verrà creata e alcuni dati del payload. Se i parametri ricevuti dalla funzione sono validi, l'operazione richiesta viene eseguita sulla tabella.

Node.js

Esempio 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

In questo esempio, il nome della tabella DynamoDB è definito come variabile nel codice della funzione. In un'applicazione reale, la best practice consiste nell'inviare questo parametro come variabile d'ambiente ed evitare di codificare il nome della tabella. Per ulteriori informazioni, consulta Utilizzo delle variabili di AWS Lambda ambiente.

Creazione della funzione

1. Salvate l'esempio di codice come file denominato index.mjs e, se necessario, modificate l' AWS area specificata nel codice. La regione specificata nel codice deve essere la stessa regione in cui verrà creata la tabella DynamoDB più avanti nel tutorial.

2. Crea un pacchetto di implementazione utilizzando il seguente comando zip.

   zip function.zip index.mjs

3. Crea una funzione Lambda utilizzando il create-function AWS CLI comando. Per il parametro role, immetti il nome della risorsa Amazon (ARN) del ruolo di esecuzione copiato in precedenza.

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

Python 3

Esempio 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 lambda_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

In questo esempio, il nome della tabella DynamoDB è definito come variabile nel codice della funzione. In un'applicazione reale, la best practice consiste nell'inviare questo parametro come variabile d'ambiente ed evitare di codificare il nome della tabella. Per ulteriori informazioni, vedere Utilizzo delle variabili di AWS Lambda ambiente.

Creazione della funzione

1. Salva l'esempio di codice come un file denominato LambdaFunctionOverHttps.py.

2. Crea un pacchetto di implementazione utilizzando il seguente comando zip.

   zip function.zip LambdaFunctionOverHttps.py

3. Crea una funzione Lambda utilizzando il create-function AWS CLI comando. Per il parametro role, immetti il nome della risorsa Amazon (ARN) del ruolo di esecuzione copiato in precedenza.

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

Richiamate la funzione utilizzando il AWS CLI

Prima di integrare la tua funzione con Gateway API, verifica di aver implementato correttamente la funzione. Crea un evento di test contenente i parametri che l'API API Gateway invierà a Lambda e usa il AWS CLI invoke comando per eseguire la funzione.

Per richiamare la funzione Lambda con AWS CLI

1. Salva il seguente JSON come un file denominato input.txt.

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

2. Eseguire il seguente comando invoke AWS CLI .

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

   L'cli-binary-formatopzione è obbligatoria se si utilizza la AWS CLI versione 2. Per rendere questa impostazione come predefinita, esegui aws configure set cli-binary-format raw-in-base64-out. Per ulteriori informazioni, consulta la pagina AWS CLI supported global command line options nella Guida per l'utente di AWS Command Line Interface versione 2.

   Dovrebbe essere visualizzata la seguente risposta:

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

3. Verifica che la tua funzione abbia eseguito l'operazione echo specificata nell'evento di test JSON. Analizza il file outputfile.txt e verifica che contenga quanto segue:

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

Creazione di una REST API utilizzando API Gateway

In questa fase, viene creata la REST API di Gateway API che sarà utilizzata per richiamare la funzione Lambda.

Per creare l'API

1. Apri la console API Gateway.

2. Seleziona Create API (Crea API).

3. Nella casella REST API, scegliere Build.

4. In Dettagli API, lasciare selezionata Nuova API e per Nome API, inserire DynamoDBOperations.

5. Seleziona Create API (Crea API).

Creazione di una risorsa sulla REST API

Per aggiungere un metodo HTTP all'API, è necessario prima creare una risorsa su cui quel metodo possa operare. Qui viene creata la risorsa per gestire la tabella DynamoDB.

Per creare la risorsa

1. Nella console API Gateway, nella pagina Risorse dell'API, scegliere Crea risorsa.

2. In Dettagli risorsa, per Nome risorsa, inserire DynamoDBManager.

3. Scegliere Create Resource (Crea risorsa).

Creazione di un metodo HTTP POST

In questa fase, viene creato un metodo (POST) per la risorsa DynamoDBManager. Il metodo POST viene collegato alla funzione Lambda in modo che quando il metodo riceve una richiesta HTTP, Gateway API richiama la funzione Lambda.

Nota

Ai fini di questo tutorial, viene utilizzato un metodo HTTP (POST) per richiamare una singola funzione Lambda che esegue tutte le operazioni sulla tabella DynamoDB. In un'applicazione reale, la best practice consiste nell'utilizzare una funzione Lambda e un metodo HTTP diversi per ogni operazione. Per ulteriori informazioni, consulta Il monolite Lambda in Serverless Land.

Creazione del metodo POST

1. Nella pagina Risorse dell'API, assicurarsi che la risorsa /DynamoDBManager sia evidenziata. Nel riquadro Metodi, scegliere Crea metodo.

2. Per Metodo HTTP scegliere POST.

3. Per Tipo di integrazione lasciare selezionato Funzione Lambda.

4. Per la funzione Lambda, scegliere nome della risorsa Amazon (ARN) per la funzione (LambdaFunctionOverHttps).

5. Scegli Crea metodo.

Creazione di una tabella DynamoDB

Crea una tabella DynamoDB vuota su cui la funzione Lambda eseguirà le operazioni CRUD.

Creare la tabella DynamoDB

1. Aprire la pagina Tables (Tabelle) della console DynamoDB.

2. Scegliere Create table (Crea tabella).

3. In Table details (Dettagli tabella), effettuare le seguenti operazioni:

   1. Nel campo Table name (Nome tabella) immetti lambda-apigateway.

   2. Per Partition key (Chiave di partizione), immettere id e mantenere il tipo di dati impostato come String (Stringa).

4. In Table settings (Impostazioni tabella), mantieni le impostazioni predefinite.

5. Scegliere Create table (Crea tabella).

Test dell'integrazione di Gateway API, Lambda e DynamoDB

A questo punto sei pronto per testare l'integrazione del metodo API di Gateway API con la funzione Lambda e la tabella DynamoDB. Utilizzando la console di Gateway API, invii le richieste direttamente al metodo POST utilizzando la funzione di test della console. In questo passaggio, viene utilizzata prima un'operazione create per aggiungere un nuovo elemento alla tabella DynamoDB, quindi viene utilizzata un'operazione update per modificare l'elemento.

Test 1: creazione di un nuovo elemento nella tabella DynamoDB

1. Nella console di Gateway API, scegli l'API (DynamoDBOperations).

2. Scegli il metodo POST sotto la DynamoDBManager risorsa.

   

3. Seleziona la scheda Test. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.

4. In Metodo di prova, lasciare vuote le stringhe di query e le intestazioni. Per Corpo della richiesta, incollare il file JSON seguente:

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

5. Scegli Test (Esegui test).

   I risultati visualizzati al termine del test devono mostrare lo stato 200. Questo codice di stato indica che l'operazione create è riuscita.

   Come verifica, controlla che la tabella DynamoDB contenga il nuovo elemento.

6. Apri la pagina Tables (Tabelle) della console DynamoDB e scegli la tabella lambda-apigateway.

7. Scegli Explore table items (Esplora elementi della tabella). Nel riquadro Items returned (Elementi restituiti), dovresti vedere un elemento con l'id 1234ABCD e il numero 5.

Test 2: aggiornamento dell'elemento nella tabella DynamoDB

1. Nella Console API Gateway, tornare alla scheda Test del metodo POST.

2. In Metodo di prova, lasciare vuote le stringhe di query e le intestazioni. Per Corpo della richiesta, incollare il file JSON seguente:

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

3. Scegli Test (Esegui test).

   I risultati visualizzati al termine del test devono mostrare lo stato 200. Questo codice di stato indica che l'operazione update è riuscita.

   Per confermare, controlla che l'elemento nella tua tabella DynamoDB sia stato modificato.

4. Apri la pagina Tables (Tabelle) della console DynamoDB e scegli la tabella lambda-apigateway.

5. Scegli Explore table items (Esplora elementi della tabella). Nel riquadro Items returned (Elementi restituiti), dovresti vedere un elemento con l'id 1234ABCD e il numero 10.

Distribuzione dell'API

Per consentire al client di chiamare l'API, è necessario creare una implementazione e una fase associata. Una fase rappresenta un'istantanea dell'API, inclusi i suoi metodi e le sue integrazioni.

Per distribuire l'API

1. Apri la pagina APIs (API) della console Gateway API quindi scegli l'API DynamoDBOperations.

2. Nella pagina Risorse per la tua API, scegliere Distribuzione dell'API.

3. Per Fase, scegliere *Nuova fase* quindi per Nome fase specificare test.

4. Seleziona Deploy (Implementa).

5. Nel riquadro Editor fase (Editor fasi) del test, copia l'URL di richiamo. Questo verrà utilizzato nella fase successiva per richiamare la tua funzione utilizzando una richiesta HTTP.

Uso di curl per richiamare la funzione tramite le richieste HTTP

A questo punto è possibile richiamare la funzione Lambda inviando una richiesta HTTP all'API. In questo passaggio, verrà creato un nuovo elemento nella tabella DynamoDB e poi sarà eliminato.

Richiamo della funzione Lambda tramite curl

1. Esegui il comando curl riportato utilizzando l'URL di richiamo che hai copiato nel passaggio precedente. Quando si utilizza curl con l'opzione -d (dati), viene utilizzato automaticamente il metodo HTTP POST.

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

2. Per verificare che l'operazione di creazione è andata a buon fine, procedi come segue:

   1. Apri la pagina Tables (Tabelle) della console DynamoDB e scegli la tabella lambda-apigateway.

   2. Scegli Explore table items (Esplora elementi della tabella). Nel riquadro Items returned (Elementi restituiti), dovresti vedere un elemento con l'id 5678EFGH e il numero 15.

3. Esegui il comando curl riportato per eliminare l'elemento appena creato. Utilizzo dei propri URL di richiamo

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

4. Verifica che l'operazione di eliminazione è andata a buon fine. Nel riquadro Items returned (Elementi restituiti) della pagina Explore items (Esplora elementi) della console DynamoDB, verifica che l'elemento con id 5678EFGH non sia più presente nella tabella.

Pulizia delle risorse (facoltativo)

Ora è possibile eliminare le risorse create per questo tutorial, a meno che non si voglia conservarle. Eliminando AWS le risorse che non utilizzi più, eviti addebiti inutili ai tuoi Account AWS.

Per eliminare la funzione Lambda

1. Aprire la pagina Functions (Funzioni) della console Lambda.

2. Selezionare la funzione creata.

3. Scegliere Operazioni, Elimina.

4. Inserisci delete nel campo di immissione del testo, quindi scegli Elimina.

Come eliminare il ruolo di esecuzione

1. Aprire la pagina Ruoli della console IAM.

2. Selezionare il ruolo di esecuzione creato.

3. Scegliere Elimina.

4. Inserisci il nome del ruolo nel campo di immissione testo e seleziona Delete (Elimina).

Per eliminare l'API

1. Aprire la pagina API della console API Gateway.

2. Selezionare l'API creata.

3. Scegliere Actions (Operazioni), Delete (Elimina).

4. Scegliere Delete (Elimina).

Per eliminare la tabella DynamoDB

1. Aprire la pagina Tables (Tabelle) della console DynamoDB.

2. Selezionare la tabella creata.

3. Scegliere Delete (Elimina).

4. Immettere delete nella casella di testo.

5. Seleziona Delete Table (Elimina tabella).