Scelta di un tipo di API Aggiunta di un endpoint alla funzione Lambda Integrazione proxy Formato dell'evento Formato della risposta Autorizzazioni Applicazione di esempio

Richiamo di una funzione Lambda utilizzando un endpoint Amazon API Gateway

È possibile creare un'API web con un endpoint HTTP per la funzione Lambda utilizzando Amazon API Gateway. API Gateway fornisce strumenti per la creazione e la documentazione di API Web che indirizzano le richieste HTTP alle funzioni Lambda. È possibile proteggere l'accesso all'API con controlli di autenticazione e autorizzazione. Le API possono servire il traffico via Internet o possono essere accessibili solo all'interno del VPC.

Le risorse nell'API definiscono uno o più metodi, ad esempio GET o POST. I metodi hanno un'integrazione che instrada le richieste a una funzione Lambda o a un altro tipo di integrazione. È possibile definire ogni risorsa e metodo singolarmente oppure utilizzare tipi di risorse e metodi speciali per soddisfare tutte le richieste che si adattano a un modello. Una risorsa proxy cattura tutti i percorsi sottostanti una risorsa. Il metodo ANY cattura tutti i metodi HTTP.

Sections

Scelta di un tipo di API
Aggiunta di un endpoint alla funzione Lambda
Integrazione proxy
Formato dell'evento
Formato della risposta
Autorizzazioni
Applicazione di esempio
Tutorial: uso di Lambda con Amazon API Gateway
Gestione degli errori Lambda con un'API Gateway API

Scelta di un tipo di API

API Gateway supporta tre tipi di API che richiamano le funzioni Lambda:

API HTTP: un'API RESTful leggera e a bassa latenza.
API REST: un'API RESTful personalizzabile e ricca di funzionalità.
WebSocket API: un'API Web che mantiene connessioni persistenti con i client per comunicazioni full-duplex.

Le API HTTP e le REST API sono entrambe API RESTful che elaborano richieste HTTP e restituiscono risposte. Le API HTTP sono più recenti e vengono create con la versione 2 di API Gateway. Le seguenti funzionalità sono nuove per le API HTTP:

Funzionalità API HTTP

Distribuzioni automatiche: quando si modificano routing o integrazioni, le modifiche vengono distribuite automaticamente alle fasi in cui è abilitata la distribuzione automatica.
Fase predefinita: è possibile creare una fase predefinita ($default) che invii le richieste nel percorso root dell'URL dell'API. Per le fasi denominate, è necessario includere il nome dello stage all'inizio del percorso.
Configurazione CORS: è possibile configurare l'API in modo da aggiungere intestazioni CORS alle risposte in uscita, invece di aggiungerle manualmente nel codice della funzione.

Le REST API sono le API RESTful classiche supportate da API Gateway dall'avvio. Le REST API dispongono attualmente di più funzionalità di personalizzazione, integrazione e gestione.

Funzionalità REST API

Tipi di integrazione: le REST API supportano le integrazioni Lambda personalizzate. Con un'integrazione personalizzata, è possibile inviare solo il corpo della richiesta alla funzione, o applicare un modello di trasformazione al corpo della richiesta prima di inviarlo alla funzione.
Controllo degli accessi: le REST API supportano più opzioni per l'autenticazione e l'autorizzazione.
Monitoraggio e tracciamento: le API REST supportano opzioni di AWS X-Ray tracciamento e registrazione aggiuntive.

Per un confronto dettagliato, consultare Scelta tra le API HTTP e le REST API nella Guida per gli sviluppatori di API Gateway.

WebSocket Le API utilizzano anche l'API API Gateway versione 2 e supportano un set di funzionalità simile. Utilizza un' WebSocket API per le applicazioni che traggono vantaggio da una connessione persistente tra il client e l'API. WebSocket Le API forniscono una comunicazione full-duplex, il che significa che sia il client che l'API possono inviare messaggi in modo continuo senza attendere una risposta.

Le API HTTP supportano un formato di evento semplificato (versione 2.0). L'esempio seguente mostra un evento da un'API HTTP.

Esempio event-v2.json - evento proxy di API Gateway (HTTP API)


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

Per ulteriori informazioni, consultare Integrazioni di AWS Lambda nella Guida per gli sviluppatori di API Gateway.

Aggiunta di un endpoint alla funzione Lambda

Per aggiungere un endpoint pubblico alla funzione Lambda

Aprire la pagina Funzioni della console Lambda.
Scegliere una funzione.
In Function overview (Panoramica delle funzioni), scegliere Add trigger (Aggiungi trigger).
Selezionare API Gateway.
Scegliere Create an API (Crea una nuova API) o Use an existing API (Usa un'API esistente).
1. Nuova API: per API type (Tipo di API), scegliere HTTP API (API HTTP). Per ulteriori informazioni, consultare API types (Tipi di API).
2. API esistente: selezionare l'API dal menu a discesa o inserire l'ID API (ad esempio, r3pmxmplak).
Per Security (Sicurezza), scegliere Open (Apri).
Scegliere Add (Aggiungi).

Integrazione proxy

Le API di API Gateway sono costituite da fasi, risorse, metodi e integrazioni. La fase e la risorsa determinano il percorso dell'endpoint:

Formato del percorso API

/prod/: la fase e la risorsa radice di prod.
/prod/user: la fase di prod e la risorsa di user.
/dev/{proxy+} – Qualunque routing della fase dev.
/: (API HTTP) la fase e la risorsa radice predefinite.

Un'integrazione Lambda mappa una combinazione di percorso e metodo HTTP a una funzione Lambda. È possibile configurare API Gateway in modo da passare il corpo della richiesta HTTP così com'è (integrazione personalizzata), o da incapsulare il corpo della richiesta in un documento che include tutte le informazioni sulla richiesta, incluse intestazioni, risorsa, percorso e metodo.

Per ulteriori informazioni, consulta Configurare le integrazioni del proxy Lambda in API Gateway.

Formato dell'evento

Amazon API Gateway richiama la funzione in modo sincrono con un evento che contiene una rappresentazione JSON della richiesta HTTP. Per un'integrazione personalizzata, l'evento è il corpo della richiesta. Per un'integrazione proxy, l'evento ha una struttura definita. L'esempio seguente mostra un evento proxy da una REST API di API Gateway.

Esempio Evento proxy event.json di 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 della risposta

API Gateway attende una risposta dalla funzione e inoltra il risultato al chiamante. Per un'integrazione personalizzata, è possibile definire una risposta di integrazione e una risposta al metodo per convertire l'output dalla funzione a una risposta HTTP. Per un'integrazione proxy, la funzione deve rispondere con una rappresentazione della risposta in un formato specifico.

L'esempio seguente mostra un oggetto risposta da una funzione Node.js. L'oggetto risposta rappresenta una risposta HTTP riuscita che contiene un documento JSON.

Esempio index.mjs: oggetto risposta di integrazione 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}"
    }

Il tempo di esecuzione Lambda serializza l'oggetto di risposta in JSON e lo invia all'API. L'API analizza la risposta e la utilizza per creare una risposta HTTP, che quindi la invia al client che ha effettuato la richiesta originale.

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

Autorizzazioni

Amazon API Gateway ottiene l'autorizzazione a richiamare la funzione dalla policy basata su risorse della funzione. È possibile concedere l'autorizzazione a un'intera API o concedere un accesso limitato a una fase, una risorsa o un metodo.

Quando aggiungi un'API alla funzione utilizzando la console Lambda, la console API Gateway o in un modello AWS SAM , la policy basata su risorse della funzione viene aggiornata automaticamente. Di seguito è riportata una policy di funzioni di esempio.

Esempio Policy di funzione


{
  "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/"
        }
      }
    }
  ]
}

È possibile gestire manualmente le autorizzazioni delle policy di funzione con le seguenti operazioni API:

Per concedere l'autorizzazione di chiamata a un'API esistente, utilizzare il 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/"

Verrà visualizzato l'output seguente:


{
    "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

Se la funzione e l'API sono diverse Regioni AWS, l'identificatore di regione nell'ARN di origine deve corrispondere alla regione della funzione, non alla regione dell'API. Quando API Gateway richiama una funzione, utilizza un ARN di risorsa basato sull'ARN dell'API, ma modificato in modo che corrisponda alla regione della funzione.

L'ARN di origine in questo esempio concede l'autorizzazione a un'integrazione nel metodo GET della risorsa root nella fase predefinita di un'API, con ID mnh1xmpli7. È possibile utilizzare un asterisco nell'ARN di origine per concedere autorizzazioni a più fasi, metodi o risorse.

Modelli di risorse

mnh1xmpli7/*/GET/*: metodo GET su tutte le risorse in tutte le fasi.
mnh1xmpli7/prod/ANY/user: metodo ANY sulla risorsa user nella fase prod.
mnh1xmpli7/*/*/*: qualsiasi metodo su tutte le risorse in tutte le fasi.

Per informazioni dettagliate sulla visualizzazione delle policy e sulla rimozione delle istruzioni, vedere Pulizia delle policy basate sulle risorse.

Applicazione di esempio

L'app di esempio API Gateway with Node.js include una funzione con un AWS SAM modello che crea un'API REST con AWS X-Ray tracciamento abilitato. Include anche script per la distribuzione, il richiamo della funzione, il test dell'API e la pulizia.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Alexa

Tutorial