Google Cloud ti fornisce gli strumenti per monitorare l'affidabilità dei tuoi progetti con Google Cloud Monitoring ed eseguire il debug dei problemi con i log degli errori di Google Cloud Logging. Ogni volta che si verifica un errore durante l'esecuzione delle intenzioni dell'utente, la pipeline Google Home Analytics registra l'errore nelle metriche e pubblica un log degli errori nei log del progetto.
La risoluzione dei problemi relativi agli errori prevede due passaggi:
- Monitora lo stato dei tuoi progetti con le metriche della smart home.
- Esamina i problemi controllando le descrizioni dettagliate degli errori nei log degli errori.
Se vuoi, puoi testare l'azione condividendola con altri utenti. Assicurati di gestire errori ed eccezioni in modo appropriato.
Monitoraggio degli errori
Puoi utilizzare i Google Cloud Monitoring dashboard per accedere alle metriche del progetto. Esistono alcuni grafici chiave particolarmente utili per monitorare la qualità ed eseguire il debug:
- Il grafico Tasso di successo è il primo da cui iniziare a monitorare l'affidabilità dei tuoi progetti. I cali in questo grafico possono indicare un'interruzione per una parte o per tutta la tua base utenti. Ti consigliamo di monitorare attentamente questo grafico per rilevare eventuali irregolarità dopo ogni modifica o aggiornamento del progetto.
- Il grafico Latenza al 95° percentile è un indicatore importante di come l'integrazione di Cloud-to-cloud funziona per i tuoi utenti. Fluttuazioni improvvise in questo grafico potrebbero indicare che i tuoi sistemi non riescono a stare al passo con le richieste. Si consiglia di controllare periodicamente questo grafico per rilevare eventuali comportamenti imprevisti.
- I grafici Suddivisione errori sono più utili per la risoluzione dei problemi relativi alle integrazioni. Per ogni errore evidenziato nel grafico della percentuale di successo, viene visualizzato un codice di errore nella suddivisione degli errori. Nella tabella seguente puoi visualizzare gli errori segnalati dall'Google Home platform e come risolverli.
Codici di errore della piattaforma
Di seguito sono riportati alcuni codici di errore comuni che potresti visualizzare nei log del progetto per identificare i problemi rilevati da Google Home platform. Per informazioni sulla risoluzione dei problemi, consulta la tabella riportata di seguito.
| Codice di errore | Descrizione |
|---|---|
BACKEND_FAILURE_URL_ERROR |
Google ha ricevuto un codice di errore HTTP 4xx diverso da 401 dal tuo
servizio.
Utilizza requestId in GCP Logging per controllare i log del servizio
per la smart home.
|
BACKEND_FAILURE_URL_TIMEOUT |
La richiesta di Google è scaduta durante il tentativo di accesso al tuo servizio.
Verifica che il servizio sia online, accetti connessioni e non abbia superato la capacità. Inoltre, verifica che il dispositivo di destinazione sia acceso, online e sincronizzato. |
BACKEND_FAILURE_URL_UNREACHABLE |
Google ha ricevuto un codice di errore HTTP 5xx dal tuo servizio.
Utilizza requestId in GCP Logging per controllare i log del servizio
per la smart home.
|
DEVICE_NOT_FOUND |
Il dispositivo non esiste sul lato del servizio partner.
In genere, questo indica un errore di sincronizzazione dei dati o una condizione di competizione. |
GAL_BAD_3P_RESPONSE |
Google non può analizzare la risposta del tuo servizio di collegamento degli account
a causa di valori o formato non validi nel payload.
Utilizza requestId in GCP Logging per controllare i log degli errori
nel servizio di collegamento degli account.
|
GAL_INTERNAL |
Si è verificato un errore interno di Google quando Google ha tentato di recuperare un
token di accesso.
Se noti un aumento della frequenza di questo errore in GCP Logging, contattaci per ulteriori informazioni. |
GAL_INVALID_ARGUMENT |
Si è verificato un errore interno di Google quando Google ha tentato di recuperare un
token di accesso.
Se noti un aumento della frequenza di questo errore in GCP Logging, contattaci per ulteriori informazioni. |
GAL_NOT_FOUND |
I token di accesso e di aggiornamento dell'utente archiviati in Google
vengono invalidati e non possono più essere aggiornati. L'utente deve
ricollegare il proprio account per continuare a utilizzare il tuo servizio.
Se noti un aumento della frequenza di questo errore in GCP Logging, contattaci per ulteriori informazioni. |
GAL_PERMISSION_DENIED |
Si è verificato un errore interno di Google quando la condivisione dei token non è
autorizzata.
Se noti un aumento della frequenza di questo errore in GCP Logging, contattaci per ulteriori informazioni. |
GAL_REFRESH_IN_PROGRESS |
Il token di accesso dell'utente è scaduto ed è già in corso un altro tentativo simultaneo di
aggiornamento.
Non si tratta di un problema e non è necessaria alcuna azione. |
INVALID_AUTH_TOKEN |
Google ha ricevuto un codice di errore HTTP 401 dal tuo servizio.
Il token di accesso non è scaduto, ma il tuo servizio lo ha invalidato. Utilizza requestId in GCP Logging per controllare i log del servizio
per la smart home.
|
INVALID_JSON |
La risposta JSON non può essere analizzata o compresa.
Controlla la struttura della risposta JSON per individuare sintassi non valide, ad esempio parentesi non corrispondenti, virgole mancanti, caratteri non validi. |
OPEN_AUTH_FAILURE |
Il token di accesso dell'utente è scaduto e Google non è in grado di aggiornarlo,
oppure Google ha ricevuto un codice di errore HTTP 401 dal tuo servizio.
Se noti un aumento della frequenza di questo codice, verifica se noti anche un aumento della frequenza di errori relativi agli intent per la smart home o alle richieste di token di aggiornamento. |
PARTNER_RESPONSE_INVALID_ERROR_CODE |
La risposta indica un codice di errore non riconosciuto.
Se la risposta alla richiesta indica un errore, assicurati di utilizzare uno fornito dai nostri codici di errore supportati. |
PARTNER_RESPONSE_INVALID_PAYLOAD |
Il campo Response payload non può essere analizzato come oggetto JSON.
Controlla se il campo payload nella risposta alla richiesta ha parentesi corrispondenti ed è strutturato correttamente come campo JSON. |
PARTNER_RESPONSE_INVALID_STATUS |
La risposta non indica uno stato o ne indica uno errato.
Le risposte alle richieste di evasione dell'intent devono indicare uno stato con SUCCESS, OFFLINE, ERROR, EXCEPTIONS. Puoi
trovare maggiori informazioni sulla
gestione di errori ed eccezioni.
|
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
Uno o più intenti presenti nella richiesta non sono presenti nella
risposta.
Verifica che la risposta di esecuzione sia strutturata correttamente e che i risultati per tutti gli intent della richiesta siano presenti nella risposta. |
PARTNER_RESPONSE_MISSING_DEVICE |
Uno o più dispositivi presenti nella richiesta non sono presenti nella
risposta.
Verifica che la risposta di esecuzione sia strutturata correttamente e che tutti gli ID dispositivo della richiesta siano presenti nella risposta. |
PARTNER_RESPONSE_MISSING_PAYLOAD |
La risposta non contiene un campo payload.
Assicurati di includere un campo payload nella risposta alla richiesta. Puoi scoprire di più su come creare correttamente una risposta di esecuzione. |
PARTNER_RESPONSE_NOT_OBJECT |
La risposta non può essere analizzata come oggetto JSON.
Controlla tutti i campi nella risposta alla richiesta per verificare la presenza di caratteri non intenzionali, parentesi non corrispondenti o errori di formattazione. Alcuni caratteri Unicode potrebbero non essere supportati. Assicurati inoltre che la risposta sia strutturata correttamente come oggetto JSON. |
PROTOCOL_ERROR |
Errore durante l'elaborazione della richiesta.
Utilizza requestId in Google Cloud Logging per controllare i log del servizio di smart home.
|
RELINK_REQUIRED |
La risposta ha indicato un errore relinkRequired, che
invita l'utente a ricollegare i propri account Google e partner.
Per ulteriori informazioni, consulta i codici di errore supportati. |
RESPONSE_TIMEOUT |
La richiesta è scaduta durante l'attesa della risposta.
Il periodo di timeout per l'invio di una risposta è di 9 secondi dall'invio della richiesta. Assicurati di inviare una risposta entro questo periodo di tempo. |
RESPONSE_UNAVAILABLE |
Non viene ricevuta alcuna risposta o la risposta non indica lo stato.
Le risposte alle richieste di completamento dell'intent devono essere strutturate in base alla documentazione sulla smart home e indicare lo stato. |
TRANSIENT_ERROR |
Un errore temporaneo è un errore che si risolve da solo.
In genere questi errori si manifestano come interruzione della connessione a un dispositivo o a un servizio. Inoltre, se non è possibile aprire nuove connessioni a un server. |
Log di ricerca
Una volta acquisita familiarità con il monitoraggio delle integrazioni utilizzando le metriche, il passaggio successivo consiste nel risolvere errori specifici utilizzando Cloud Logging. Un log degli errori è una voce simile a JSON con campi contenenti informazioni utili come ora, codice di errore e dettagli relativi all'intent di smart home di origine.
Esistono più sistemi all'interno di Google Cloud che inviano log al tuo progetto in qualsiasi momento. Devi scrivere query per filtrare i log e trovare quelli che ti servono. Le query possono essere basate su un intervallo di tempo, una risorsa, una gravità del log o voci personalizzate.
Puoi utilizzare i pulsanti di query per creare filtri personalizzati.
Per specificare un intervallo di tempo, fai clic sul pulsante di selezione dell'intervallo di tempo e scegli una delle opzioni fornite. In questo modo, i log verranno filtrati e verranno mostrati quelli che hanno origine nell'intervallo di tempo selezionato.
Per specificare una risorsa, fai clic sul menu a discesa Risorsa, poi scegli Progetto di azione per l'Assistente Google. Viene aggiunto un filtro alla query per mostrare i log provenienti dal tuo progetto.
Utilizza il pulsante Gravità per filtrare in base a Emergenza, Informazioni, Debug e altri livelli di gravità dei log.
Puoi anche utilizzare il campo Query in Logs Explorer
per inserire voci personalizzate. Il motore di query utilizzato da questo campo supporta sia
query di base come la corrispondenza di stringhe, sia tipi di query più avanzati, inclusi
operatori di confronto (<, >=, !=) e operatori booleani (AND, OR, NOT).
Ad esempio, la voce personalizzata riportata di seguito restituirebbe errori
che hanno origine da un tipo di dispositivo LIGHT:
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
Visita la libreria di query per trovare altri esempi di query efficaci sui log.
Test delle correzioni
Una volta identificati gli errori e applicati gli aggiornamenti per correggerli, ti consigliamo di testare le correzioni in modo approfondito con Google Home Test Suite. Forniamo una guida utente su come utilizzare Test Suite, che ti guida nel test delle modifiche in modo efficace.
Risorse didattiche
Questo documento fornisce i passaggi per risolvere gli errori nell'azione per la smart home. Per saperne di più sul debug, puoi anche consultare i nostri codelab:
- Codelab per il debug della smart home: Guida rapida per il debug dell'integrazione del cloud della smart home.
- Codelab per il debug di Local Home: Guida rapida per il debug dell'integrazione locale della smart home.