Panoramica della risoluzione dei problemi

Questa pagina fornisce informazioni generali per la risoluzione dei problemi relativi ad API Gateway.

Impossibile eseguire i comandi "gcloud api-gateway"

Per eseguire i comandi gcloud api-gateway ..., devi aver aggiornato Google Cloud CLI e abilitato i servizi Google necessari. Per saperne di più, consulta Configurare l'ambiente di sviluppo.

Il comando "gcloud api-gateway api-configs create" indica che account di servizio non esiste

Se esegui il comando gcloud api-gateway api-configs create ... e ricevi un errore nel formato:

ERROR: (gcloud.api-gateway.api-configs.create) FAILED_PRECONDITION:
Service Account "projects/-/serviceAccounts/service_account_email" does not exist

Esegui di nuovo il comando, ma questa volta includi l'opzione --backend-auth-service-account per specificare in modo esplicito l'indirizzo email del service account da utilizzare:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

Assicurati di aver già assegnato le autorizzazioni necessarie al account di servizio come descritto in Configurare l'ambiente di sviluppo.

Determinare l'origine delle risposte di errore dell'API

Se le richieste all'API di cui hai eseguito il deployment generano un errore (codici di stato HTTP da 400 a 599), la risposta stessa potrebbe non indicare chiaramente se l'errore proviene dal gateway o dal backend. Per determinarlo:

  1. Vai alla pagina Esplora log e seleziona il tuo progetto.

    Vai a Esplora log

  2. Filtra la risorsa gateway pertinente utilizzando la seguente query di log:

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
resource.labels.location="GCP_REGION"

    Dove:

    • GATEWAY_ID specifica il nome del gateway.
    • GCP_REGION è la Google Cloud regione del gateway di cui è stato eseguito il deployment.

  3. Trova la voce di log che corrisponde alla risposta di errore HTTP che vuoi esaminare. Ad esempio, filtra per httpRequest.status.

  4. Esamina i contenuti del campo jsonPayload.responseDetails.

Se il valore del campo jsonPayload.responseDetails è "via_upstream", la risposta di errore proviene dal backend e dovrai risolvere i problemi direttamente nel backend. Se è un altro valore, la risposta di errore proviene dal gateway. Per ulteriori suggerimenti per la risoluzione dei problemi, consulta le sezioni seguenti di questo documento.

La richiesta API restituisce un errore HTTP 403

Se una richiesta a un'API di cui è stato eseguito il deployment restituisce un errore HTTP 403 al client API, significa che l'URL richiesto è valido, ma l'accesso è vietato per qualche motivo.

Un'API di cui è stato eseguito il deployment ha le autorizzazioni associate ai ruoli concessi al service account che hai utilizzato quando hai creato la configurazione API. In genere, il motivo dell'errore HTTP 403 è che il account di servizio non dispone delle autorizzazioni necessarie per accedere al servizio di backend.

Se hai definito l'API e il servizio di backend nello stesso progetto Google Cloud, assicurati che al account di servizio sia assegnato il ruolo Editor o il ruolo necessario per accedere al servizio di backend. Ad esempio, se il servizio di backend è implementato utilizzando Cloud Run Functions, assicurati che al account di servizio sia assegnato il ruolo Cloud Function Invoker.

La richiesta API restituisce un errore HTTP 401 o 500

Se una richiesta a un'API di cui è stato eseguito il deployment restituisce un errore HTTP 401 o 500 al client API, potrebbe esserci un problema con l'utilizzo del account di servizio utilizzato quando hai creato la configurazione API per chiamare il servizio di backend.

Un'API di cui è stato eseguito il deployment ha le autorizzazioni associate ai ruoli concessi al service account che hai utilizzato quando hai creato la configurazione API. Il account di servizio viene controllato per assicurarsi che esista e che possa essere utilizzato dal gateway API quando viene eseguito il deployment dell'API.

Se il account di servizio viene eliminato o disattivato dopo il deployment del gateway, potrebbe verificarsi la seguente sequenza di eventi:

  1. Subito dopo l'eliminazione o la disattivazione del account di servizio, potresti visualizzare risposte HTTP 401 nei log del gateway. Se il campo jsonPayload.responseDetails è impostato su "via_upstream" in jsonPayload della voce di log, significa che l'eliminazione o la disattivazione del account di servizio è la causa dell'errore.

  2. Potresti anche visualizzare un errore HTTP 500 senza alcuna voce di log corrispondente nei log di API Gateway. Se non ci sono richieste al gateway subito dopo l'eliminazione o la disattivazione del account di servizio, potresti non visualizzare le risposte HTTP 401, ma gli errori HTTP 500 senza i log di API Gateway corrispondenti indicano che il account di servizio del gateway potrebbe non essere più attivo.

Se il backend della richiesta non riuscita è un'altra Google Cloud API (ad esempio bigquery.googleapis.com), nei log del gateway verranno visualizzate risposte HTTP 401 con il campo jsonPayload.responseDetails impostato su "via_upstream". Questo perché API Gateway esegue l'autenticazione ai backend con un token ID mentre altre Google Cloud API richiedono un token di accesso.

La richiesta API restituisce un errore HTTP 500 per un metodo con quota applicata

Se ricevi il seguente errore, il gateway non è riuscito ad allocare la quota per la tua richiesta:

HTTP/2 500
{"code":500,"message":"Failed to call Service Control Quota."}

Questo errore si verifica in genere quando chiami un metodo per il quale è configurata una quota, ma le metriche relative alle quote non esistono più per l'API. Su un gateway gRPC, lo stesso errore viene restituito come codice di stato gRPC Internal.

Confermare la causa nei log del gateway

  1. Vai alla pagina Esplora log e seleziona il tuo progetto.

    Vai a Esplora log

  2. Esegui la seguente query di log:

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
jsonPayload.responseDetails="service_control_quota_error"
httpRequest.status=500

    Dove GATEWAY_ID specifica il nome del gateway.

    La query filtra in base al codice di stato e a jsonPayload.responseDetails perché API Gateway utilizza lo stesso responseDetails valore per ogni rifiuto della quota. Una richiesta che ha superato legittimamente la quota produce lo stesso valore con un httpRequest.status di 429.

  3. Esamina i campi jsonPayload.apiConfig e jsonPayload.apiMethod di qualsiasi voce corrispondente. Identificano la configurazione API e il metodo la cui configurazione della quota non è valida.

Perché una configurazione API può avere una configurazione della quota non valida

Definisci le metriche e i limiti delle quote in una configurazione API, ma API Gateway li applica all'intera API. Ogni volta che crei una configurazione API, le metriche e i limiti che dichiara sostituiscono quelli dichiarati dalle configurazioni API precedenti dell'API. Vengono applicati solo i valori della configurazione API creata più di recente.

Al contrario, le metriche utilizzate da ogni metodo sono definite nella configurazione API che il gateway pubblica. Se un gateway esegue una configurazione API precedente, chiede a Service Control di allocare la quota in base a una metrica che esiste nella sua configurazione, ma potrebbe non esistere nell'API. Se la metrica non esiste, la chiamata di allocazione non riesce e il gateway rifiuta la richiesta.

Ad esempio, la seguente sequenza lascia il primo gateway interrotto:

  1. Crei la configurazione API config-v1, che dichiara la metrica quota-metric-v1, ed esegui il deployment in gateway-1.
  2. Crei la configurazione API config-v2 per la stessa API, che dichiara la metrica quota-metric-v2, ed esegui il deployment in gateway-2.

gateway-2 funziona, ma le richieste ai metodi con quota applicata di gateway-1 iniziano a non riuscire perché quota-metric-v1 non è più definita per l'API.

Le seguenti modifiche possono causare errori per qualsiasi gateway di cui è ancora stato eseguito il deployment con una configurazione API precedente:

  • Rinominare o rimuovere una metrica.
  • Modificare la metrica a cui si applica un limite di quota.
  • Modificare la metrica denominata nei costi della quota per metodo (x-google-quota per i documenti OpenAPI o quota.metric_rules per le configurazioni del servizio gRPC).

La modifica del solo valore di un limite non causa errori. Tuttavia, poiché i limiti vengono applicati anche a livello API, il nuovo valore viene applicato a ogni gateway di quell'API, inclusi i gateway di cui è stato eseguito il deployment con una configurazione API precedente.

Confrontare le configurazioni delle quote di cui è stato eseguito il deployment

  1. Elenca i gateway e la configurazione API che ogni gateway pubblica:

    gcloud api-gateway gateways list \
 --format="table(name.basename(),apiConfig)"

  2. Elenca le configurazioni API dell'API interessata, a partire da quella creata più di recente:

    gcloud api-gateway api-configs list --api=API_ID \
 --format="table(name.basename(),createTime:sort=1:reverse)"

    La prima voce è la configurazione API le cui metriche e i cui limiti delle quote vengono applicati all'intera API. Ordina con il flag --format come mostrato: questo comando non supporta il flag --sort-by e non restituisce le configurazioni API in un ordine prevedibile.

  3. Visualizza la definizione dell'API da cui è stata creata una configurazione API:

    gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID \
 --view=FULL --format="value(openapiDocuments[0].document.contents)" \
 | tr '_-' '/+' | base64 --decode

    Il comando tr è obbligatorio perché il campo contents è codificato in base64url, che base64 --decode non può leggere direttamente.

    Per un'API gRPC, la configurazione della quota si trova nella configurazione del servizio anziché in un documento OpenAPI, quindi sostituisci openapiDocuments[0].document.contents con managedServiceConfigs[0].contents.

  4. Esegui il comando nel passaggio 3 per la configurazione API nella parte superiore dell'elenco del passaggio 2 e poi per ciascuna delle altre configurazioni API che il passaggio 1 mostra come ancora di cui è stato eseguito il deployment in un gateway.

  5. Confronta i risultati. Ogni metrica per cui una configurazione API precedente addebita i metodi deve essere definita anche nella configurazione API creata più di recente. Se una metrica non è presente in questa configurazione, i gateway che pubblicano la configurazione API precedente non funzionano.

Ripristinare una configurazione della quota valida

Esegui un audit delle metriche e dei limiti delle quote per assicurarti che siano coerenti in tutte le configurazioni attive. Per farlo, esegui una delle seguenti azioni:

  • Aggiorna ogni gateway dell'API in modo che utilizzi la configurazione API creata più di recente, come descritto in Aggiornare un gateway.
  • Crea una nuova configurazione API che dichiari ogni metrica utilizzata dalle configurazioni API di cui è ancora stato eseguito il deployment e mantieni i gateway esistenti nelle configurazioni API correnti.

Per evitare errori di allocazione, mantieni i nomi delle metriche coerenti nelle configurazioni API di un'API. Quando modifichi una quota, modifica il valore del limite anziché il nome della metrica.

Richieste API a latenza elevata

Come Cloud Run e Cloud Run Functions, API Gateway è soggetto alla latenza di "avvio a freddo". Se il gateway non ha ricevuto traffico per 15-20 minuti, le richieste effettuate al gateway nei primi 10-15 secondi dell'avvio a freddo subiranno una latenza di 3-5 secondi.

Se il problema persiste dopo il periodo di "riscaldamento" iniziale, controlla i log delle richieste dei servizio di backend configurati nella configurazione API. Ad esempio, se il servizio di backend è implementato utilizzando Cloud Run Functions, controlla le voci di Cloud Logging del log delle richieste di Cloud Function associato.

Impossibile visualizzare le informazioni di log

Se l'API risponde correttamente, ma i log non contengono dati, in genere significa che non hai abilitato tutti i servizi Google richiesti da API Gateway.

API Gateway richiede l'abilitazione dei seguenti Google Cloud servizi:

Nome Nome servizio
API API Gateway apigateway.googleapis.com
API Service Management servicemanagement.googleapis.com
API Service Control servicecontrol.googleapis.com

Per abilitare i servizi richiesti:

Google Cloud Console

  1. Nella Google Cloud console, vai alla pagina API e servizi > Libreria API.

    Vai alla libreria API

  2. Nella pagina Libreria API, inserisci il nome dell'API richiesta nella barra di ricerca.
  3. Nei risultati di ricerca, seleziona la pagina dell'API.
  4. Nella pagina dell'API, fai clic su Abilita.
  5. Ripeti questi passaggi per ciascuno dei servizi elencati nella tabella precedente.

Google Cloud CLI

Utilizza i seguenti comandi per abilitare i servizi:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Per ulteriori informazioni sui servizi gcloud, consulta gcloud servizi.