Google Cloud ti fornisce gli strumenti per monitorare l'affidabilità dei tuoi progetti con Google Cloud Monitoring e per eseguire il debug dei problemi con i log degli errori di Google Cloud Logging. Ogni volta che si verifica un errore durante l'adempimento delle intenzioni degli utenti, la pipeline di Google Home Analytics registra l'errore nelle metriche e pubblica un log degli errori nei log del progetto.
Per risolvere i problemi, devi seguire due passaggi:
- Monitora lo stato dei tuoi progetti con le metriche per la 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 gli errori e le 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à e il debug:
- Il grafico Tasso di successo è il primo da cui iniziare quando monitori l'affidabilità dei tuoi progetti. I cali in questo grafico possono indicare un'interruzione del servizio per una parte o per la totalità della tua base utenti. Ti consigliamo di monitorare attentamente questo grafico per rilevare eventuali irregolarità dopo ogni modifica o aggiornamento del progetto.
- Il grafico Latenza (95° percentile) è un indicatore importante del rendimento della tua integrazione Cloud-to-cloud per gli utenti. Le fluttuazioni improvvise in questo grafico potrebbero indicare che i tuoi sistemi potrebbero non essere in grado di soddisfare le richieste. Ti consigliamo di controllare periodicamente questo grafico per rilevare eventuali comportamenti imprevisti.
- I grafici Analisi degli errori sono particolarmente utili per risolvere i problemi relativi alle integrazioni. Per ogni errore evidenziato nel grafico della percentuale di successo, viene visualizzato un codice di errore nella suddivisione degli errori. Puoi vedere gli errori segnalati da Google Home platform e come risolverli nella tabella seguente.
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.
Usa requestId in Log di Google Cloud per controllare i log dei servizi per la smart home.
|
BACKEND_FAILURE_URL_TIMEOUT |
La richiesta di Google ha superato il tempo di attesa durante il tentativo di raggiungere il tuo servizio.
Verifica che il servizio sia online, accetti le connessioni e non superi 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.
Usa requestId in Log di Google Cloud per controllare i log dei servizi per la smart home.
|
DEVICE_NOT_FOUND |
Il dispositivo non esiste sul lato del servizio del partner.
In genere, questo indica un errore nella sincronizzazione dei dati o una condizione di gara. |
GAL_BAD_3P_RESPONSE |
Google non riesce ad analizzare la risposta del servizio di collegamento dell'account
a causa di valori o formati non validi nel payload.
Utilizza requestId in Cloud Logging per controllare i log di errore
nel servizio di collegamento dell'account.
|
GAL_INTERNAL |
Si è verificato un errore interno di Google quando Google ha cercato di recuperare un
token di accesso.
Se noti un aumento della frequenza di questo errore in Log di Google Cloud, contattaci per ulteriori informazioni. |
GAL_INVALID_ARGUMENT |
Si è verificato un errore interno di Google quando Google ha cercato di recuperare un
token di accesso.
Se noti un aumento della frequenza di questo errore in Log di Google Cloud, contattaci per ulteriori informazioni. |
GAL_NOT_FOUND |
I token di accesso e i token 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 servizio.
Se noti un aumento della frequenza di questo errore in Log di Google Cloud, 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 Log di Google Cloud, contattaci per ulteriori informazioni. |
GAL_REFRESH_IN_PROGRESS |
Il token di accesso dell'utente è scaduto ed è già in corso un altro tentativo simultaneo di aggiornarlo.
Non si tratta di un problema e non è richiesta 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 servizio lo ha invalidato. Utilizza requestId in Log di Google Cloud per controllare i log dei servizi per la smart home.
|
INVALID_JSON |
La risposta JSON non può essere analizzata o compresa.
Verifica la presenza di sintassi non valida nella struttura della risposta JSON, 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, controlla 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 dei codici di errore supportati. |
PARTNER_RESPONSE_INVALID_PAYLOAD |
Il campo della risposta payload non può essere analizzato come oggetto JSON.
Verifica che il campo del payload nella risposta alla richiesta abbia parentesi di corrispondenza ed sia 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 adempimento dell'intento devono indicare uno stato con SUCCESS, OFFLINE, ERROR, EXCEPTIONS. Puoi trovare ulteriori informazioni sulla
gestione di errori ed eccezioni.
|
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
Nella risposta mancano uno o più intent presenti nella richiesta.
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 |
Nella risposta mancano uno o più dispositivi presenti nella richiesta.
Verifica che la risposta all'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 del 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 della risposta alla richiesta per verificare la presenza di caratteri indesiderati, 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 |
Impossibile elaborare la richiesta.
Utilizza requestId in Google Cloud Logging per controllare i log del servizio per la smart home.
|
RESPONSE_TIMEOUT |
La richiesta è scaduta durante l'attesa della risposta.
Il periodo di timeout per l'invio di una risposta è di 9 secondi dal momento in cui viene inviata la 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 adempimento dell'intento devono essere strutturate in base alla documentazione per la smart home e indicare lo stato. |
TRANSIENT_ERROR |
Un errore temporaneo è un errore che si risolve da solo.
In genere, questi errori si manifestano con l'interruzione della connessione a un dispositivo o 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 nella risoluzione di 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 per la smart home di origine.
In Google Cloud sono presenti più sistemi che inviano sempre log al progetto. Devi scrivere query per filtrare i log e trovare quelli di cui hai bisogno. Le query possono essere basate su un intervallo di tempo, su una risorsa, sulla gravità del log o su voci personalizzate.
Puoi utilizzare i pulsanti di query per creare i tuoi filtri personalizzati.
Per specificare un intervallo di tempo, fai clic sul pulsante di selezione dell'intervallo di tempo e scegli una delle opzioni disponibili. In questo modo, i log verranno filtrati e mostrati quelli che hanno origine nell'intervallo di tempo selezionato.
Per specificare una risorsa, fai clic sul menu a discesa Risorsa e poi scegli Progetto di azioni dell'Assistente Google. Viene aggiunto un filtro alla query per mostrare i log che provengono dal 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 le query di base come la corrispondenza di stringhe sia tipi di query più avanzati, inclusi i comparatori (<, >=, !=) e gli operatori booleani (AND, OR, NOT).
Ad esempio, la voce personalizzata riportata di seguito restituirà errori che provengono 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 per eseguire query sui log in modo efficace.
Correzioni dei test
Una volta identificati gli errori e applicati gli aggiornamenti per correggerli, ti consigliamo di testare attentamente le correzioni con Google Home Test Suite. Forniamo una guida utente su come utilizzare Test Suite, che illustra la procedura per testare efficacemente le modifiche.
Risorse didattiche
Questo documento illustra i passaggi per risolvere gli errori nell'azione per la smart home. Per scoprire di più sul debug, puoi anche consultare i nostri codelab:
- Codelab sul debug della smart home: guida rapida per eseguire il debug dell'integrazione della smart home con il cloud.
- Codelab di debug della casa locale: guida rapida per eseguire il debug dell'integrazione locale della smart home.