Questa pagina è stata tradotta dall'API Cloud Translation.

Panoramica della risoluzione dei problemi

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

Impossibile eseguire i comandi "gcloud api-gateway"

Per eseguire i comandi gcloud api-gateway ..., devi aver aggiornato Google Cloud CLI e aver attivato 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 Configurazione dell'ambiente di sviluppo.

Determinare l'origine delle risposte di errore dell'API

Se le richieste alla tua API di cui è stato eseguito il deployment generano un errore (codici di stato HTTP da 400 a 599), potrebbe non essere chiaro dalla risposta stessa se l'errore ha origine dal gateway o dal backend. Per determinarlo:

Vai alla pagina Esplora log e seleziona il tuo progetto.

Vai a Esplora log
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.
Trova la voce di log corrispondente alla risposta di errore HTTP che vuoi esaminare. Ad esempio, filtra per httpRequest.status.
Controlla i contenuti del campo jsonPayload.responseDetails.

Se il valore del campo jsonPayload.responseDetails è "via_upstream", la risposta di errore ha origine dal backend e dovrai risolvere i problemi del backend direttamente. Se è 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 all'account di servizio che hai utilizzato quando hai creato la 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 all'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. L'account di servizio viene controllato per assicurarsi che esista e possa essere utilizzato dal gateway API quando l'API viene implementata.

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

Subito dopo l'eliminazione o la disattivazione dell'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 vengono inviate richieste al gateway immediatamente dopo l'eliminazione o la disattivazione dell'account di servizio, potresti non visualizzare le risposte HTTP 401, ma gli errori HTTP 500 senza log del gateway API corrispondenti indicano che l'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 esegue l'autenticazione ai backend con un token ID, mentre altre API Google Cloud richiedono un token di accesso.

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 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 iniziale di "riscaldamento", controlla i log delle richieste deiservizio di backendd 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 del log

Se la tua API risponde correttamente, ma i log non contengono dati, in genere significa che non hai attivato tutti i servizi Google richiesti da API Gateway.

API Gateway richiede l'abilitazione dei seguenti servizi Google:

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

Utilizza i seguenti comandi per abilitare questi 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.