Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Panoramica della risoluzione dei problemi

Questa pagina fornisce informazioni generali sulla 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 Configurazione dell'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 esplicitamente 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 Configura l'ambiente di sviluppo.

Determinazione dell'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), potrebbe non essere chiaro dalla risposta stessa se l'errore proviene dal gateway o dal backend. Per determinarlo:

Vai alla pagina Esplora log e seleziona il tuo progetto.

Vai a Esplora log
Filtra in base alla 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 regione Google Cloud del gateway di cui è stato eseguito il deployment.
Trova la voce di log corrispondente alla risposta di errore HTTP che vuoi esaminare. Ad esempio, filtra in base a httpRequest.status.
Esamina i contenuti del campo jsonPayload.responseDetails.

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

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 dispone delle autorizzazioni associate ai ruoli concessi al service account che hai utilizzato durante la creazione della configurazione dell'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 durante la creazione della configurazione API per chiamare il servizio di backend.

Un'API di cui è stato eseguito il deployment dispone delle autorizzazioni associate ai ruoli concessi al service account che hai utilizzato durante la creazione della configurazione dell'API. Il account di servizio viene controllato per assicurarsi che esista e che possa essere utilizzato dall'API Gateway 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:

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.
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 del gateway API corrispondenti indicano che il account di servizio del gateway potrebbe non essere più attivo.

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

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

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 comunemente quando chiami un metodo per cui è configurata una quota, ma le metriche della quota non esistono più per l'API. Su un gateway gRPC, lo stesso errore viene restituito come codice di stato gRPC Internal.

Conferma la causa nei log del gateway

Vai alla pagina Esplora log e seleziona il tuo progetto.

Vai a Esplora log
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 valore responseDetails per ogni rifiuto della quota. Una richiesta che ha legittimamente superato la quota produce lo stesso valore con un httpRequest.status di 429.
Esamina i campi jsonPayload.apiConfig e jsonPayload.apiMethod di ogni voce corrispondente. Identificano la configurazione dell'API e il metodo la cui configurazione della quota non è valida.

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

Le metriche e i limiti delle quote vengono definiti in una configurazione API, ma API Gateway li applica all'intera API. Ogni volta che crei una configurazione API, le metriche e i limiti dichiarati 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 ciascun metodo sono definite nella configurazione API gestita dal gateway. Se un gateway esegue una configurazione API precedente, chiede a Service Control di allocare la quota in base a una metrica esistente nella propria configurazione, ma che potrebbe non esistere nell'API. Se la metrica non esiste, la chiamata di allocazione non va a buon fine e il gateway rifiuta la richiesta.

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

Crei la configurazione API config-v1, che dichiara la metrica quota-metric-v1, ed esegui il deployment in gateway-1.
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ù definito per l'API.

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

Ridenominazione o rimozione di una metrica.
Modifica della metrica a cui si applica un limite di quota.
Modifica della metrica denominata nei costi della quota per metodo (x-google-quota per i documenti OpenAPI o quota.metric_rules per le configurazioni dei servizi 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.

Confronta le configurazioni di quota di cui è stato eseguito il deployment

Elenca i gateway e la configurazione API che ciascuno gestisce:

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

Elenca le configurazioni API dell'API interessata, partendo 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 dell'API per cui vengono applicate le metriche e i limiti di quota per l'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.
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.
Esegui il comando del passaggio 3 per la configurazione API in cima all'elenco del passaggio 2, quindi per ciascuna delle altre configurazioni API che nel passaggio 1 risultano ancora di cui è stato eseguito il deployment in un gateway.
Confronta i risultati. Ogni metrica per cui una configurazione API precedente addebita i propri metodi deve essere definita anche nella configurazione API creata più di recente. Se una metrica non è presente nella configurazione, i gateway che gestiscono la configurazione API precedente non funzionano.

Ripristina una configurazione di quota valida

Controlla le metriche e i 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 Aggiorna 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 attuali.

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

Richieste API con latenza elevata

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

Se il problema persiste dopo il periodo iniziale di "warm up", controlla i log delle richieste dei servizio di backend che hai configurato 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 dei 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 servizi Google Cloud :

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

Per attivare i servizi richiesti:

Console Google Cloud

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

Vai alla libreria API
Nella pagina Libreria API, inserisci il nome dell'API richiesta nella barra di ricerca.
Nei risultati di ricerca, seleziona la pagina dell'API.
Nella pagina dell'API, fai clic su Abilita.
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 saperne di più sui servizi gcloud, consulta Servizi gcloud.