Google Cloud ti offre 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 quando si completano gli intent dell'utente, la pipeline di Google Home Analytics registra l'errore in base alle tue metriche e pubblica un log degli errori nei log del progetto.
Per risolvere gli errori sono previsti due passaggi:
- Monitora lo stato dei tuoi progetti con le metriche della smart home.
- Analizza i problemi controllando le descrizioni dettagliate degli errori nei log degli errori.
Monitoraggio degli errori
Puoi usare gli elementi Google Cloud Monitoring dashboard per accedere alle metriche del progetto. Alcuni grafici chiave sono particolarmente utili per il monitoraggio della qualità e il debug:
- Il grafico Tasso di successo è il primo grafico da cui partire quando monitori l'affidabilità dei progetti. I rilasci in questo grafico possono indicare un'interruzione per una parte o l'intera base utenti. Ti consigliamo di monitorare attentamente questo grafico per rilevare eventuali irregolarità dopo ogni modifica o aggiornamento del progetto.
- Il grafico Latenza del 95° percentile è un indicatore importante del rendimento dell'azione per la smart home per gli utenti. Le fluttuazioni improvvise in questo grafico potrebbero indicare che i tuoi sistemi potrebbero non essere al passo con le richieste. Si consiglia di controllare periodicamente questo grafico per rilevare eventuali comportamenti imprevisti.
- I grafici Analisi degli errori sono più utili per la risoluzione dei problemi delle integrazioni. Per ogni errore evidenziato nel grafico della percentuale di successo, viene visualizzato un codice di errore nella suddivisione degli errori. Puoi visualizzare gli errori segnalati dal Google Home platform e come risolverli nella tabella seguente.
Codici di errore della piattaforma
Ecco alcuni codici di errore comuni che potresti vedere nei log del progetto per identificare i problemi rilevati da Google Home platform. Consulta la tabella seguente per informazioni sulla risoluzione dei problemi.
| Codice di errore | Descrizione |
|---|---|
BACKEND_FAILURE_URL_ERROR |
Google ha ricevuto dal tuo servizio un codice di errore HTTP 4xx diverso da 401.
Utilizza requestId in Google Cloud Logging per controllare i log dei servizi per la smart home.
|
BACKEND_FAILURE_URL_TIMEOUT |
La richiesta di Google è scaduta durante il tentativo di connessione al tuo servizio.
Verifica che il servizio sia online, accetti connessioni e che non abbia capacità eccessiva. 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 Google Cloud Logging per controllare i log dei servizi per la smart home.
|
DEVICE_NOT_FOUND |
Il dispositivo non esiste sul lato servizio del partner.
Di solito questo errore indica un errore nella sincronizzazione dei dati o una condizione di gara. |
GAL_BAD_3P_RESPONSE |
Google non può analizzare la risposta del servizio di collegamento dell'account a causa di formato o valori non validi nel payload.
Utilizza requestId in Google Cloud Logging per controllare i log degli errori
nel servizio di collegamento dell'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 percentuale di questo errore in Google Cloud 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 percentuale di questo errore in Google Cloud Logging, contattaci per ulteriori informazioni. |
GAL_NOT_FOUND |
I token di accesso e di aggiornamento dell'utente archiviati in Google sono stati 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 percentuale di questo errore in Google Cloud 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 percentuale di questo errore in Google Cloud 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.
Questo non è un problema e non è necessaria alcuna azione da parte tua. |
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 Logging di Google Cloud per controllare i log dei servizi per la smart home.
|
INVALID_JSON |
La risposta JSON non può essere analizzata o compresa.
Controlla che nella struttura della risposta JSON non siano presenti sintassi non valide, ad esempio parentesi non corrispondenti, virgole mancanti e 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 una maggiore frequenza di questo codice, controlla se noti anche un aumento della percentuale di errori relativi agli intent della 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 utilizzarne uno fornito dai nostri codici di errore supportati. |
PARTNER_RESPONSE_INVALID_PAYLOAD |
Il campo della risposta payload non può essere analizzato come oggetto
JSON.
Controlla se il campo del payload nella risposta alla richiesta contiene parentesi corrispondenti e se è strutturato correttamente come campo JSON. |
PARTNER_RESPONSE_INVALID_STATUS |
La risposta non indica uno stato o indica uno stato errato.
Le risposte alle richieste di evasione dell'intent devono indicare uno stato con SUCCESS, OFFLINE, ERROR, EXCEPTIONS. Scopri di più sulla
gestione di errori ed eccezioni.
|
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
Uno o più intent 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 relativo al payload nella risposta alla richiesta. Puoi scoprire di più su come creare correttamente una risposta di esecuzione. |
PARTNER_RESPONSE_NOT_OBJECT |
Impossibile analizzare la risposta come oggetto JSON.
Controlla che in tutti i campi della risposta alla richiesta non siano presenti 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 |
Errore durante l'elaborazione della richiesta.
Utilizza requestId in Google Cloud Logging per controllare i log dei servizi per la smart home.
|
RESPONSE_TIMEOUT |
Timeout della richiesta 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 evasione dell'intent devono essere strutturate in base ai documenti per la smart home e indicare lo stato. |
TRANSIENT_ERROR |
Un errore temporaneo è un errore che si risolve automaticamente.
In genere questi errori si manifestano come una connessione a un dispositivo o un servizio interrotto. Inoltre, se non è possibile aprire nuove connessioni a un server. |
Log di ricerca
Dopo aver acquisito 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 di tipo JSON con campi contenenti informazioni utili come ora, codice di errore e dettagli relativi all'intent della smart home di origine.
All'interno di Google Cloud esistono più sistemi che inviano sempre i log al tuo progetto. Devi scrivere query per filtrare i log e trovare quelli necessari. Le query possono essere basate su un intervallo di tempo, una risorsa, una gravità di 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. I log verranno filtrati e verranno visualizzati quelli che hanno origine nell'intervallo di tempo selezionato.
Per specificare una Risorsa, fai clic sul menu a discesa Risorsa, poi scegli Progetto di azioni dell'Assistente Google. In questo modo, nella query viene aggiunto un filtro per visualizzare i log che hanno origine dal progetto.
Utilizza il pulsante Gravità per filtrare in base ai livelli di log Emergenza, Informazioni, Debug e di altro tipo.
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 delle stringhe, sia tipi di query più avanzati, tra cui
comparatori (<, >=, !=) 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 query per trovare altri esempi per eseguire query sui log in modo efficace.
Correzioni dei test
Dopo aver identificato gli errori e applicato gli aggiornamenti per correggerli, ti consigliamo di testare a fondo le correzioni con Google Home Test Suite. Forniamo una guida dell'utente su come utilizzare Test Suite, che ti aiuterà a testare le tue modifiche in modo efficace.
Risorse didattiche
Questo documento fornisce i passaggi per risolvere gli errori nella tua azione per la smart home. Per saperne di più sul debug, puoi anche consultare i nostri codelab:
- Debug dell'integrazione nel cloud per la smart home: guida rapida al debug dell'integrazione nel cloud per la smart home.
- Debug codelab casa locale: guida rapida per eseguire il debug dell'integrazione locale per la smart home.