Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Integrazioni proxy Lambda in Gateway API

La sezione seguente illustra come utilizzare un'integrazione proxy Lambda.

Informazioni sull'integrazione proxy Lambda di API Gateway

L'integrazione proxy Lambda di Amazon API Gateway è un sistema semplice, potente e agile per creare un'API con una configurazione di un singolo metodo API. Permette al client di chiamare una singola funzione Lambda nel back-end. La funzione accede a molte risorse o funzionalità di altri AWS servizi, inclusa la chiamata ad altre funzioni Lambda.

Nell'integrazione proxy Lambda, quando un client invia una richiesta API, API Gateway passa alla funzione Lambda integrata un oggetto evento, ad eccezione del fatto che non viene mantenuto l'ordine dei parametri della richiesta. Questi dati di richiesta includono intestazioni di richiesta, parametri delle stringhe di query, variabili di percorso URL, payload e dati di configurazione API. I dati di configurazione possono includere il nome della fase di distribuzione corrente, variabili di fasi, identità utente o contesto di autorizzazione (se presente). La funzione Lambda back-end analizza i dati delle richieste in entrata per stabilire la risposta da restituire. Perché API Gateway possa passare l'output Lambda come risposta API al client, la funzione Lambda deve restituire il risultato in questo formato.

Poiché API Gateway non interviene in modo significativo tra il client e la funzione Lambda back-end per l'integrazione proxy Lambda, il client e la funzione Lambda integrata possono adattarsi alle modifiche reciproche senza alterare la configurazione di integrazione esistente dell'API. Per consentirlo, il client deve seguire i protocolli di applicazione attuati dalla funzione Lambda back-end.

Puoi configurare un'integrazione proxy Lambda per qualsiasi metodo API. Tuttavia un'integrazione proxy Lambda è più potente quando viene configurata per un metodo API che coinvolge una risorsa proxy generica. La risorsa proxy generica può essere indicata dalla speciale variabile di percorso preconfigurata {proxy+}, dal segnaposto del metodo catch-all ANY o da entrambi. Il client può passare l'input alla funzione Lambda back-end nella richiesta in entrata come parametri di richiesta o payload applicabile. I parametri di richiesta includono intestazioni, variabili di percorso URL, parametri delle stringhe di query e il payload applicabile. La funzione Lambda integrata verifica tutte le sorgenti di input prima di elaborare la richiesta e rispondere al client con messaggi di errore significativi, se manca qualcuno degli input richiesti.

Quando si chiama un metodo API integrato con il metodo HTTP generico ANY e la risorsa generica {proxy+}, il client invia una richiesta con un metodo HTTP specifico al posto di ANY. Il client inoltre specifica un particolare percorso URL al posto di {proxy+} e include eventuali intestazioni, parametri delle stringhe di query o payload applicabile necessari.

L'elenco di seguito riepiloga i comportamenti di runtime di diversi metodi API con l'integrazione proxy Lambda:

La risorsa proxy {proxy+} e quella personalizzata {custom} sono entrambe espresse come variabili di percorso preconfigurate. Tuttavia {proxy+} può fare riferimento a qualsiasi risorsa in una gerarchia di percorso, mentre {custom} fa riferimento solo a un segmento di percorso specifico. Ad esempio, un negozio di generi alimentari potrebbe organizzare il proprio inventario di prodotti online in base ai nomi dei reparti, alle categorie di produzione e ai tipi di prodotto. Il sito Web del negozio potrebbe quindi rappresentare i prodotti disponibili in base alle seguenti variabili di percorso preconfigurate di risorse personalizzate: /{department}/{produce-category}/{product-type}. Ad esempio le mele sono rappresentate da /produce/fruit/apple e le carote da /produce/vegetables/carrot. Può anche usare /{proxy+} per rappresentare qualsiasi reparto, categoria di produzione o tipo di prodotto che un cliente può cercare quando fa acquisti nel negozio online. Ad esempio, /{proxy+} può fare riferimento a uno qualsiasi degli articoli seguenti:

Per permettere ai clienti di cercare i prodotti disponibili, la categoria di produzione e il reparto del negozio associato, puoi esporre un singolo metodo GET /{proxy+} con autorizzazioni di sola lettura. Analogamente, per consentire a un superiore di aggiornare l'inventario del reparto produce, puoi impostare un altro metodo singolo PUT /produce/{proxy+} con autorizzazioni di lettura/scrittura. Per permettere a un cassiere di aggiornare la quantità complessiva di un tipo di ortaggio, puoi configurare un metodo POST /produce/vegetables/{proxy+} con autorizzazioni di lettura/scrittura. Per permettere a un responsabile di negozio di eseguire tutte le operazioni possibili per tutti i prodotti disponibili, lo sviluppatore di negozi online può esporre il metodo ANY /{proxy+} con autorizzazioni di lettura/scrittura. In ogni caso, al runtime il cliente o il dipendente deve selezionare un prodotto specifico di un determinato tipo in un reparto scelto, una particolare categoria di produzione in un reparto scelto o un reparto specifico.

Per ulteriori informazioni sull'impostazione delle integrazioni proxy di API Gateway, consulta Configurazione di un'integrazione proxy mediante una risorsa proxy.

Per l'integrazione proxy è necessario che il client abbia una conoscenza più dettagliata dei requisiti del back-end. Pertanto, per garantire prestazioni dell'app e un'esperienza utente ottimali, lo sviluppatore di back-end deve comunicare chiaramente allo sviluppatore del client i requisiti del back-end e fornire un sistema solido di notifica degli errori quando i requisiti non vengono soddisfatti.

Supporto per le intestazioni multi-valore e i parametri di stringa di query

API Gateway ora supporta più intestazioni e parametri di stringa di query con lo stesso nome. Le intestazioni multi-valore, quelle con valore singolo e le intestazioni di valore e parametri possono essere combinati nelle stesse richieste e risposte. Per ulteriori informazioni, consulta Formato di input di una funzione Lambda per l'integrazione proxy e Formato di output di una funzione Lambda per l'integrazione proxy.

Formato di input di una funzione Lambda per l'integrazione proxy

Con l'integrazione proxy Lambda, API Gateway mappa l'intera richiesta client al parametro di input event della funzione Lambda di back-end. Nell'esempio seguente viene illustrata la struttura di un evento che API Gateway invia a un'integrazione proxy Lambda.

{
  "resource": "/my/path",
  "path": "/my/path",
  "httpMethod": "GET",
  "headers": {
    "header1": "value1",
    "header2": "value1,value2"
  },
  "multiValueHeaders": {
    "header1": [
      "value1"
    ],
    "header2": [
      "value1",
      "value2"
    ]
  },
  "queryStringParameters": {
    "parameter1": "value1,value2",
    "parameter2": "value"
  },
  "multiValueQueryStringParameters": {
    "parameter1": [
      "value1",
      "value2"
    ],
    "parameter2": [
      "value"
    ]
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "id",
    "authorizer": {
      "claims": null,
      "scopes": null
    },
    "domainName": "id.execute-api.us-east-1.amazonaws.com",
    "domainPrefix": "id",
    "extendedRequestId": "request-id",
    "httpMethod": "GET",
    "identity": {
      "accessKey": null,
      "accountId": null,
      "caller": null,
      "cognitoAuthenticationProvider": null,
      "cognitoAuthenticationType": null,
      "cognitoIdentityId": null,
      "cognitoIdentityPoolId": null,
      "principalOrgId": null,
      "sourceIp": "IP",
      "user": null,
      "userAgent": "user-agent",
      "userArn": null,
      "clientCert": {
        "clientCertPem": "CERT_CONTENT",
        "subjectDN": "www.example.com",
        "issuerDN": "Example issuer",
        "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
        "validity": {
          "notBefore": "May 28 12:30:02 2019 GMT",
          "notAfter": "Aug  5 09:36:04 2021 GMT"
        }
      }
    },
    "path": "/my/path",
    "protocol": "HTTP/1.1",
    "requestId": "id=",
    "requestTime": "04/Mar/2020:19:15:17 +0000",
    "requestTimeEpoch": 1583349317135,
    "resourceId": null,
    "resourcePath": "/my/path",
    "stage": "$default"
  },
  "pathParameters": null,
  "stageVariables": null,
  "body": "Hello from Lambda!",
  "isBase64Encoded": false
}

Nell'input per la funzione Lambda back-end l'oggetto requestContext è una mappa di coppie chiave/valore. In ogni coppia la chiave è il nome di una proprietà della variabile $context e il valore è il valore della proprietà. Gateway API potrebbe aggiungere nuove chiavi alla mappa.

A seconda delle funzionalità abilitate, la mappa requestContext può variare in base all'API. Ad esempio, nell'esempio precedente non è specificato alcun tipo di autorizzazione e di conseguenza non è presente alcuna proprietà $context.authorizer.* o $context.identity.*. Quando è specificato un tipo di autorizzazione, API Gateway passa informazioni sugli utenti autorizzati all'endpoint di integrazione in un oggetto requestContext.identity nel modo seguente:

Formato di output di una funzione Lambda per l'integrazione proxy

Nell'integrazione proxy Lambda, API Gateway richiede la funzione Lambda back-end per restituire l'output in base al seguente formato JSON:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": "..."
}

Nell'output:

Per abilitare CORS per l'integrazione proxy Lambda, devi aggiungere Access-Control-Allow-Origin:domain-name all'output headers. domain-name può essere * per qualsiasi nome di dominio. Viene eseguito il marshalling del parametro body di output al front-end come payload di risposta del metodo. Se body è un BLOB binario, puoi codificarlo come stringa con codifica Base64 impostando isBase64Encoded su true e configurando */* come Binary Media Type (Tipo multimediale binario). In caso contrario, puoi impostarlo su false o lasciarlo non specificato.

Se l'output della funzione ha un formato diverso, API Gateway restituisce una risposta di errore 502 Bad Gateway.

Per restituire una risposta in una funzione Lambda in Node.js, è possibile utilizzare comandi come i seguenti:

In una funzione Lambda async in Node.js, la sintassi equivalente è la seguente: