Come posso risolvere i problemi di integrazione di Gateway API con funzioni Lambda?

Risoluzione

Attiva la registrazione delle API

Completa i seguenti passaggi:

1. Apri la console Gateway API.
2. Nel pannello di navigazione, scegli API, quindi seleziona l'API.
3. Nel pannello di navigazione, scegli Fasi, quindi seleziona la fase.
4. Per Log e tracciamento, scegli Modifica.
5. Per CloudWatch Logs, seleziona un livello dal menu a discesa.
   Nota: per i log completi delle richieste e delle risposte, seleziona l'opzione Tracciamento dei dati con il livello di registrazione impostato su Log di errori e informazioni. È consigliabile non attivare Tracciamento dei dati per le API di produzione perché può registrare dati sensibili.
6. Scegli Metriche dettagliate.
7. In Registrazione accesso personalizzato, completa i seguenti passaggi:
   Seleziona Abilita la registrazione dell'accesso.
   In ARN di destinazione del log degli accessi, inserisci l'ARN di un gruppo di log di Amazon Data Firehose o di CloudWatch.
   Nota: solo le REST API supportano l'ARN di Firehose.
8. Inserisci un formato di log.
9. Scegli Salva.

Determina i tipi di integrazione, verifica gli errori e intraprendi i passaggi successivi per risolverli

Completa i seguenti passaggi:

1. Determina se in Gateway API è configurata un'integrazione proxy di Lambda o un'integrazione personalizzata di Lambda. Per verificare il tipo di integrazione, controlla il valore di Integrazione proxy Lambda in Richiesta di integrazione.

2. Verifica che gli errori in Gateway API corrispondano agli errori in Lambda. Esegui questa query di CloudWatch Logs Insights per individuare un codice di stato di errore in un arco di tempo specificato:

   parse @message '(*) *' as reqId, message
       | filter message like /Method completed with status: \d\d\d/
       | parse message 'Method completed with status: *' as status
       | filter status != 200
       | sort @timestamp asc
       | limit 50

3. Quindi esegui questa query di CloudWatch Logs Insights per cercare i log degli errori Lambda nello stesso arco di tempo:

   fields @timestamp, @message
       | filter @message like /(?i)(Exception|error|fail)/
       | sort @timestamp desc
       | limit 20

4. In base al tipo di errore che identifichi nei log, scegli una delle seguenti opzioni:
   Se ricevi il seguente errore, completa i passaggi riportati nella sezione Risolvi i problemi di concorrenza.

   (#####) Lambda invocation failed with status: 429. Lambda request id: ##########
   () Execution failed due to configuration error: Rate Exceeded.
   (#####) Method completed with status: 500

   Se ricevi uno dei seguenti errori, completa i passaggi riportati nella sezione Risolvi i problemi di timeout.
   Per un'integrazione personalizzata di Lambda:

   < Integration timeout:
   (#####) Method response body after transformations: {"errorMessage":"2019-08-14T02:45:14.133Z ########-####-####-####-############ Task timed out after ##.01 seconds"}
   > Integration timeout:
   (#####) Execution failed due to a timeout error

   Per un'integrazione proxy di Lambda:

   < Integration timeout:
   (#####) Endpoint response body before transformations: {"errorMessage":"2019-08-14T02:50:25.865Z ########-####-####-####-############ Task timed out after ##.01 seconds"}
   > Integration timeout:
   (#####) Execution failed due to a timeout error

   Se ricevi il seguente errore, completa i passaggi riportati nella sezione Risolvi gli errori della funzione.

   (#####) Execution failed due to configuration error: Malformed Lambda proxy response
   (#####) Method response body after transformations: {"errorMessage": "Syntax error in module 'lambda_function'"}

Risolvi i problemi di concorrenza

Ricevi errori di limitazione (della larghezza di banda della rete) 429 o errori 500 quando arrivano ulteriori richieste da Gateway API più velocemente di quanto la funzione Lambda possa scalare.

Per risolvere questi errori, analizza le seguenti metriche di CloudWatch: Count (Gateway API), Throttles (Lambda) e **ConcurrentExecutions ** (Lambda). Considera quanto segue:

• Count (Gateway API) corrisponde al numero totale di richieste API in un arco di tempo specificato.
• Throttles (Lambda) corrisponde al numero di richieste di invocazione limitate. Quando tutte le istanze della funzione elaborano richieste e non è disponibile concorrenza l'aumento verticale, Lambda rifiuta le ulteriori richieste con l'errore TooManyRequestsException. Le richieste limitate e altri errori di invocazione non contano come invocazioni o errori.
• ConcurrentExecutions (Lambda) corrisponde al numero di istanze della funzione che elaborano eventi. Se questo numero raggiunge la quota di esecuzioni concorrenti per la Regione AWS, le ulteriori richieste di invocazione vengono limitate. Lambda limita anche le richieste di invocazione quando il numero di istanze della funzione raggiunge il limite della concorrenza di riserva configurato per la funzione.

Nota: per ulteriori informazioni, consulta Metriche di Gateway API e Utilizzo delle metriche di CloudWatch Logs con Lambda.

Se imposti una concorrenza di riserva per la funzione Lambda, aumenta il valore della concorrenza di riserva. Oppure rimuovi il valore della concorrenza di riserva dalla funzione Lambda. La funzione attinge quindi dal pool di esecuzioni concorrenti senza riserva.

Se non imposti la concorrenza di riserva per la funzione Lambda, controlla la metrica ConcurrentExecutions per verificare l'utilizzo. Per ulteriori informazioni, consulta Quote di Lambda.

Risolvi i problemi di timeout

Il limite del timeout di integrazione predefinito è di 29 secondi per tutte le integrazioni di Gateway API. Puoi inviare una richiesta di aumento della quota per aumentare il timeout massimo di integrazione predefinito a più di 29 secondi per le API Regionali e private. Tuttavia, un aumento del timeout di integrazione potrebbe richiedere una riduzione della quota per la limitazione (della larghezza di banda della rete) a livello di Regione per l'account AWS.

Nota: se aumenti il timeout massimo di integrazione, assicurati di sostituire il valore del timeout predefinito di 29 secondi con il nuovo valore. Ad esempio, modifica il valore del timeout predefinito di 29 secondi nelle integrazioni in cui desideri applicare l'aumento. Quindi ridistribuisci l'API affinché il nuovo timeout massimo di integrazione abbia effetto.

Quando crei un'API di Gateway API con integrazione di Lambda, potresti riscontrare uno dei seguenti scenari:

• Il valore del timeout è inferiore al valore del timeout di integrazione.
• Il valore del timeout è superiore al valore di timeout di integrazione.

Se il timeout della funzione Lambda è inferiore a 29 secondi, controlla i log di Lambda per esaminare il problema. Se la funzione Lambda deve essere eseguita dopo 29 secondi, invocala in modo asincrono.

Per l'integrazione personalizzata dell'invocazione asincrona di Lambda, completa i seguenti passaggi:

1. Apri la console Gateway API.
2. Nel pannello di navigazione, scegli API, quindi seleziona l'API.
3. Scegli Risorse, quindi seleziona il metodo.
4. Scegli Richiesta di integrazione.
5. Scegli Richiesta metodo.
6. Espandi Intestazioni di richiesta HTTP.
7. Scegli Aggiungi intestazione.
8. In Nome, inserisci un nome per l'intestazione. Ad esempio: X-Amz-Invocation-Type
   Importante: devi mappare l'intestazione da 'Event'. Devi utilizzare virgolette singole.

Per l'integrazione proxy di Lambda, utilizza due funzioni Lambda: la funzione A e la funzione B. Gateway API invoca prima la funzione A in modo sincrono. Quindi la funzione A invoca in modo asincrono la funzione B. La funzione A può restituire una risposta corretta a Gateway API quando la funzione B è invocata in modo asincrono.

Se utilizzi un'integrazione proxy di Lambda, puoi modificare l'integrazione passando a un'integrazione personalizzata. Tuttavia, per trasformare la richiesta o la risposta nel formato specifico, devi configurare i modelli di mappatura. Per ulteriori informazioni, consulta Configurazione della chiamata asincrona della funzione Lambda di backend.

Nota: poiché una funzione Lambda asincrona viene eseguita in background, il client non può ricevere dati direttamente da una funzione Lambda. Devi disporre di un database intermedio per archiviare qualsiasi dato persistente.

Risolvere gli errori di funzione

Se ricevi un errore di funzione quando invochi l'API, controlla eventuali errori di sintassi nella funzione Lambda. L'errore viene visualizzato anche se la funzione Lambda non restituisce un oggetto JSON valido previsto da Gateway API per le integrazioni proxy.

Dai log di esecuzione di Gateway API, puoi esaminare il valore AWS Integration Endpoint RequestID nei log:

(#####) AWS Integration Endpoint RequestId : YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY

Quindi esegui questa query di CloudWatch Logs Insights per cercare i log degli errori di Lambda nello stesso arco di tempo:

fields @timestamp, @message, @requestId, @logStream
| filter @requestId = 'YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY'
| sort @timestamp asc

Per risolvere l'errore, completa i passaggi riportati nella sezione Attiva la registrazione per l'API e la fase.

Sostituisci le risposte con codice di stato della REST API errato

Se Gateway API restituisce un codice di stato errato, crea un modello di mappatura per sostituire il codice di stato errato con il codice di stato corretto. Puoi sostituire le risposte con codice di stato nelle integrazioni non proxy con REST API.

Nota: questa configurazione del modello di mappatura si applica solo alle REST API. Per le API HTTP, consulta How do I map the response status codes for API Gateway integrations in HTTP APIs? (Come posso mappare i codici di stato delle risposte per le integrazioni di Gateway API nelle API HTTP?)

Ad esempio, se Gateway API restituisce un codice di stato 200 anziché un 4## o 5## da una funzione Lambda, completa i seguenti passaggi:

1. Apri la console Gateway API e, nel pannello di navigazione, scegli API.

2. Scegli la REST API, quindi scegli la scheda Risposta di integrazione.

3. Per Impostazioni della risposta di integrazione, scegli ** Modifica**.

4. Espandi Modelli di mappatura, quindi scegli Aggiungi modello di mappatura.

5. In Content-Type, inserisci application/json.

6. Nell'editor dei modelli di mappatura, inserisci il seguente codice:

   #set($inputRoot = $input.path('$'))
   $input.json("$")
   #if($inputRoot.toString().contains("error"))
   #set($context.responseOverride.status = 400)
   #end

7. Scegli Salva.

Il parametro $context.responseOverride.status sostituisce il codice di stato con 400 anziché con la mappatura predefinita nel pannello della risposta di integrazione.

Per ulteriori informazioni, consulta Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per le REST API in Gateway API.

Configura le integrazioni delle REST API per restituire le intestazioni CORS richieste

Per restituire le intestazioni CORS richieste nella risposta, configura la funzione Lambda di backend o il server proxy HTTP. Devi includere i domini consentiti nel valore dell'intestazione Access-Control-Allow-Origin come elenco.

Per le integrazioni proxy non puoi impostare una risposta di integrazione in Gateway API per modificare i parametri di risposta restituiti dal backend dell’API. In un'integrazione proxy, Gateway API inoltra la risposta del backend direttamente al client. Devi configurare la funzione Lambda o l'integrazione HTTP per restituire le intestazioni CORS richieste.

Per le integrazioni non proxy, devi configurare manualmente una risposta di integrazione in Gateway API per restituire le intestazioni CORS richieste. Utilizza la console Gateway API per configurare CORS. La console aggiunge automaticamente le intestazioni CORS richieste alla risorsa configurata.

Per ulteriori informazioni, consulta Come posso risolvere gli errori CORS dalla mia API di Gateway API?

Integrazioni proxy di Lambda con payload binario

Un payload binario è qualcosa di diverso da un payload di testo. Ad esempio, un payload binario può essere un file .jpeg, un file .gzip e così via. Nel payload binario rientrano anche dati binari generici come, ad esempio, quelli provenienti da un'applicazione .pdf, da un'immagine .jpeg o da un'applicazione .zip.

Per gestire i payload binari nel caso delle integrazioni proxy di Lambda, devi codificare in base 64 la risposta della funzione e configurare i binaryMediaTypes per l'API.

Per gestire i payload binari nel caso delle integrazioni non proxy, devi aggiungere i tipi di media all'elenco binaryMediaTypes della risorsa RestApi.

Per ulteriori informazioni, consulta Tipi di supporti binari per REST API in Gateway API.

Informazioni correlate

Gestione degli errori di Lambda standard in Gateway API

Gestione degli errori di Lambda personalizzati in Gateway API