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 mostra come utilizzare un'integrazione proxy Lambda.

Comprendi l'integrazione del API proxy Gateway Lambda

L'integrazione del proxy Amazon API Gateway Lambda è un meccanismo semplice, potente e agile per creare un proxy API con una configurazione di un unico 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 con proxy Lambda, quando un client invia una API richiesta, API Gateway passa alla funzione Lambda integrata un oggetto evento, tranne per il fatto che l'ordine dei parametri della richiesta non viene mantenuto. Questi dati di richiesta includono le intestazioni della richiesta, i parametri della stringa di query, le variabili di URL percorso, il payload e i 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. Affinché API Gateway passi l'output Lambda come API risposta al client, la funzione Lambda deve restituire il risultato in questo formato.

Poiché API Gateway non interviene molto tra il client e la funzione Lambda di backend per l'integrazione del proxy Lambda, il client e la funzione Lambda integrata possono adattarsi alle modifiche reciproche senza interrompere la configurazione di integrazione esistente di. 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 API metodo. Tuttavia, l'integrazione del proxy Lambda è più potente quando è configurata per un API metodo 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 URL percorso, parametri della stringa 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 API metodo integrato con il HTTP metodo generico di ANY e la risorsa generica di{proxy+}, il client invia una richiesta con un HTTP metodo particolare al posto di. ANY Il client specifica inoltre un URL percorso particolare anziché e include tutte le intestazioni richieste{proxy+}, i parametri della stringa di query o un payload applicabile.

L'elenco seguente riassume i comportamenti di runtime dei diversi API metodi con l'integrazione del 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 sulla configurazione delle integrazioni proxy 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

APIGateway supporta più intestazioni e parametri di stringhe 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

Nell'integrazione del proxy Lambda, API Gateway mappa l'intera richiesta del client al event parametro di input della funzione Lambda di backend. L'esempio seguente mostra 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à. APIGateway potrebbe aggiungere nuove chiavi alla mappa.

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

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

Nell'integrazione del proxy Lambda, API Gateway richiede la funzione Lambda di backend per restituire l'output secondo il seguente formato: JSON

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

Nell'output:

CORSPer abilitare l'integrazione del proxy Lambda, è necessario aggiungere Access-Control-Allow-Origin:domain-name all'output. headers domain-namepuò 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 502 Bad Gateway di errore.

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: