Come posso utilizzare i log di Gateway Amazon API per risolvere i problemi relativi alle API?

Breve descrizione

Per risolvere i problemi relativi a una REST API o a un'API WebSocket di Gateway API, attiva i log di esecuzione, quindi utilizza Amazon CloudWatch Logs per accedervi. Assicurati di collegare tutte le autorizzazioni richieste al ruolo AWS Identity and Access Management (AWS IAM) Gateway API. Per istruzioni, consulta Come posso attivare CloudWatch Logs per risolvere i problemi della mia REST API o API WebSocket di Gateway API?

Nota: le API HTTP supportano solo la registrazione degli accessi. Per ulteriori informazioni sulla configurazione della registrazione per queste API, consulta Configurare la registrazione per le API HTTP in Gateway API.

Risoluzione

Dopo aver attivato la registrazione, Gateway API crea automaticamente un gruppo di log in CloudWatch denominato API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}. Utilizza questo gruppo per risolvere ulteriormente i problemi. Per ulteriori informazioni, consulta Formati dei log di CloudWatch per Gateway API.

Verifica la presenza di errori di autorizzazione

Se attivi i sistemi di autorizzazione AWS Lambda per l'API, i log indicano se la richiesta è autorizzata e includono gli ID del sistema di autorizzazione e della richiesta.

Esempi di log autorizzati:

Starting authorizer: 62mgrc for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0
Successfully completed authorizer execution

Esempi di log non autorizzati:

Starting authorizer: 62mgrc for request: fd443056-60d0-425f-874e-e93e5d61351e  
Unauthorized request: fd443056-60d0-425f-874e-e93e5d61351e

Per ulteriori informazioni, consulta Perché ricevo errori 401 di autorizzazione negata di Gateway API dopo aver creato un sistema di autorizzazione Lambda?

Aggiorna la configurazione del piano di utilizzo

Dopo i log del sistema di autorizzazione Lambda, Gateway API verifica il piano di utilizzo per la richiesta API. Se non hai configurato un piano di utilizzo, le richieste API non vengono conteggiate ai fini delle soglie per la limitazione (della larghezza di banda della rete).

Esempi di log del piano di utilizzo:

Verifying Usage Plan for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0. API Key: API Stage: <api_id>/<stage>
API Key authorized because method 'GET /' does not require API Key. Request will not contribute to throttle or quota limits
Usage Plan check succeeded for API Key and API Stage <api_id>/<stage>

Se configuri le API con chiavi API e manca l'intestazione X-API-key, i log restituiscono un errore simile al seguente:

"API Key not authorized because method 'GET /' requires API Key and API Key is not associated with a Usage Plan for API Stage <api_id>/<stage>: API Key was required but not present"

Per risolvere il problema, esamina la configurazione dell'API. Devi associare la chiave API al piano di utilizzo richiesto e includere la chiave nella richiesta come intestazione X-API-KEY con il valore corretto.

Se aggiungi la chiave API corretta nell'intestazione e Gateway API limita la richiesta, i log restituiscono un errore simile al seguente:

"API Key **FGQes7 exceeded throttle limit for API Stage <api_id>/<stage>: Key throttle limit exceeded for Usage Plan ID iwuzkt. Limit: 5.00 Burst: 0
Method completed with status: 429"

Per risolvere il problema, completa la procedura descritta in Come posso risolvere gli errori "429 Too Many Requests" (429 Troppe richieste) o "Limit Exceeded" (Limite superato) per la mia API con Gateway API?

Tipi di log delle richieste

Quando attivi il tracciamento dei dati e i log degli errori e informativi, i log di Gateway API contengono maggiori dettagli per aiutarti a risolvere i problemi. Per individuare dove la richiesta API Gateway ha esito negativo, consulta i seguenti tipi di log per ulteriori informazioni.

Nota: per i log delle richieste, devi scegliere Errori e log informativi dal menu a discesa dei log di CloudWatch. Quindi attiva Tracciamento dei dati per i log di esecuzione. È consigliabile non attivare Tracciamento dei dati per le API di produzione perché può registrare dati sensibili.

Log delle richieste del metodo

I log delle richieste del metodo includono informazioni dettagliate ricevute da una richiesta API, tra cui il percorso della richiesta, il parametro della query, l'intestazione della richiesta e il corpo della richiesta.

Esempio di log delle richieste del metodo:

(####) Method request path: {...}
(####) Method request query string: {...}
(####) Method request headers: {User-Agent=...}
(####) Method request body before transformations: ...

Log delle richieste dell'endpoint

I log delle richieste dell'endpoint includono informazioni dettagliate ricevute da una richiesta API, inclusi l'URI, le intestazioni della richiesta e il corpo della richiesta.

Esempio di log delle richieste dell'endpoint:

(####) Endpoint request URI: ...
(####) Endpoint request headers: {...}
(####) Endpoint request body after transformations: {...}

I dati inclusi nelle richieste dell'endpoint vengono inviati all'integrazione del backend per un'ulteriore elaborazione.

Log delle risposte dell'endpoint

I log delle risposte dell'endpoint includono i dati restituiti dalle integrazioni del backend, inclusi il codice di stato, le intestazioni, il corpo e la latenza dell'integrazione.

Esempio di log delle risposte dell'endpoint:

(####) Received response. Status: YYY, Integration latency: ZZZ ms
(####) Endpoint response headers: {...}
(####) Endpoint response body before transformations: {...}

Log delle risposte del metodo

I log delle risposte del metodo includono le intestazioni e il corpo inviati al client dopo la trasformazione.

Esempio di log delle risposte del metodo:

(####) Method response body after transformations: ...
(####) Method response headers: {...}

Importante: Gateway API limita gli eventi di log a 1.024 byte. Gateway API tronca gli eventi di log di dimensioni superiori a 1.024 byte, ad esempio i corpi della richiesta e della risposta, prima che i log vengano inviati a CloudWatch Logs.

Informazioni correlate

Come posso risolvere i problemi relativi ai log di CloudWatch mancanti per le REST API di Gateway API?

Configurazione della registrazione dei log CloudWatch per REST API in Gateway API

Monitoraggio dell'esecuzione della REST API con le metriche Amazon CloudWatch

Monitoraggio dell'esecuzione dell'API WebSocket con le metriche CloudWatch

Troubleshooting Amazon API Gateway with enhanced observability variables (Risoluzione dei problemi di Gateway Amazon API con variabili di osservabilità avanzate)