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 Configurare l'ambiente di sviluppo.
Il comando "gcloud api-gateway api-configs create" indica che l'account di servizio non esiste
Se esegui il comando gcloud api-gateway api-configs create ...
e ricevi un messaggio di errore nel seguente 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 dell'account di servizio da utilizzare:
gcloud api-gateway api-configs create CONFIG_ID \ --api=API_ID --openapi-spec=API_DEFINITION \ --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
Assicurati di aver già assegnato le autorizzazioni necessarie all'account di servizio come descritto in Configurazione dell'ambiente di sviluppo.
Determinare l'origine delle risposte di errore dell'API
Se le richieste all'API di cui è stato eseguito il deployment generano un errore (codici di stato HTTP da 400
a 599
), dalla risposta stessa potrebbe non essere chiaro se l'errore proviene dal gateway o dal backend.
Per determinare questo:
Vai alla pagina Esplora log e seleziona il tuo progetto.
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 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 in base a
httpRequest.status
.Controlla 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 direttamente i problemi relativi al backend. 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 ha le autorizzazioni associate ai ruoli concessi all'account di servizio utilizzato per creare la configurazione dell'API. In genere, il motivo dell'errore HTTP403
è che l'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 stato assegnato il ruolo Editor
o il ruolo necessario per accedere al servizio di backend. Ad esempio, se il servizio di backend è implementato utilizzando le funzioni Cloud Run, assicurati che all'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 dell'account di servizio utilizzato quando hai creato la configurazione dell'API per chiamare il servizio di backend.
Un'API di cui è stato eseguito il deployment dispone delle autorizzazioni associate ai ruoli concessi all'account di servizio che hai utilizzato per creare la configurazione dell'API. L'account di servizio viene controllato per verificare che esista e possa essere utilizzato da API Gateway quando viene eseguita il deployment dell'API.
Se l'account di servizio viene eliminato o disattivato dopo il deployment del gateway, potrebbe verificarsi la seguente sequenza di eventi:
Immediatamente dopo l'eliminazione o la disattivazione dell'account di servizio, potresti visualizzare risposte HTTP 401 nei log del gateway. Se il campo
response_code_details
è impostato su"via_upstream"
injsonPayload
della voce del log, significa che l'eliminazione o la disattivazione dell'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 subito dopo l'eliminazione o la disattivazione dell'account servizio, potresti non vedere le risposte HTTP 401, ma gli errori HTTP500
senza i log del gateway API corrispondenti indicano che l'account servizio del gateway potrebbe non essere più attivo.
Richieste API con latenza elevata
Come Cloud Run e le funzioni Cloud Run, 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 del cold start avranno una latenza di 3-5 secondi.
Se il problema persiste dopo il periodo di "preparazione" iniziale, controlla i log delle richieste del servizio o dei servizi di backend configurati nella configurazione API. Ad esempio, se il servizio di backend è implementato utilizzando le funzioni Cloud Run, 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 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 |
Per verificare che i servizi richiesti siano abilitati:
gcloud services list
Se non vedi i servizi richiesti nell'elenco, attivali:
gcloud services enable apigateway.googleapis.comgcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
Per ulteriori informazioni sui servizi gcloud
, consulta
Servizi gcloud
.