Google Cloud fornisce gli strumenti per monitorare l'affidabilità dei progetti con Google Cloud Monitoring e per eseguire il debug dei problemi con i log degli errori Google Cloud Logging. Ogni volta che si verifica un errore durante il completamento degli intent dell'utente, la pipeline di Google Home Analytics registra l'errore nelle metriche e pubblica un log degli errori nei log del progetto.
Esistono due passaggi per risolvere gli errori:
- Monitora lo stato dei tuoi progetti con le metriche per la smart home.
- Esamina i problemi controllando le descrizioni dettagliate degli errori nei log.
Monitoraggio degli errori
Puoi utilizzare Google Cloud Monitoring dashboard per accedere alle metriche del progetto. Esistono alcuni grafici chiave particolarmente utili per il monitoraggio della qualità e il debug:
- Il grafico Tasso di successo è il primo grafico da cui iniziare il monitoraggio dell'affidabilità dei progetti. I cali in questo grafico possono indicare un'interruzione per una parte o tutta la tua base utenti. Ti consigliamo di monitorare attentamente questo grafico per individuare eventuali irregolarità dopo ogni modifica o aggiornamento del progetto.
- Il grafico della latenza del 95° percentile è un indicatore importante del rendimento dell'Azione per la smart home per i tuoi utenti. Le fluttuazioni improvvise in questo grafico potrebbero indicare che i tuoi sistemi potrebbero non essere in grado di recuperare le richieste. Ti consigliamo di controllare periodicamente questo grafico per individuare eventuali comportamenti imprevisti.
- I grafici di Analisi degli 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 nell'analisi degli errori. Puoi vedere gli errori segnalati da Google Home platform e scoprire come risolverli nella tabella riportata di seguito.
Codici di errore della piattaforma
Di seguito sono riportati alcuni codici di errore comuni che potresti vedere nei log di progetto per identificare i problemi rilevati da Google Home platform. Per informazioni sulla risoluzione dei problemi, consulta la seguente tabella.
| 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 nel logging di GCP per controllare i log dei servizi per la smart home.
|
BACKEND_FAILURE_URL_TIMEOUT |
La richiesta di Google è scaduta durante il tentativo di contattare il tuo servizio.
Verifica che il tuo servizio sia online, accetti connessioni e che 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 nel logging di GCP 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 race condition. |
GAL_BAD_3P_RESPONSE |
Google non può analizzare la risposta del servizio di collegamento dell'account
a causa di un formato o di valori non validi nel payload.
Utilizza requestId nel logging di GCP per controllare i log degli errori nel servizio di collegamento dell'account.
|
GAL_INTERNAL |
Si è verificato un errore interno di Google durante il tentativo di recupero di un token di accesso.
Se noti una frequenza maggiore di questo errore nel logging di Google Cloud, contattaci per ulteriori informazioni. |
GAL_INVALID_ARGUMENT |
Si è verificato un errore interno di Google durante il tentativo di recupero di un token di accesso.
Se noti una frequenza maggiore di questo errore nel logging di Google Cloud, contattaci per ulteriori informazioni. |
GAL_NOT_FOUND |
I token di accesso e i token di aggiornamento dell'utente archiviati in Google non sono più validi e non possono più essere aggiornati. L'utente deve
ricollegare il proprio account per continuare a utilizzare il servizio.
Se noti una frequenza maggiore di questo errore nel logging di Google Cloud, contattaci per ulteriori informazioni. |
GAL_PERMISSION_DENIED |
Si è verificato un errore interno di Google quando la condivisione del token non è autorizzata.
Se noti una frequenza maggiore di questo errore nel logging di Google Cloud, contattaci per ulteriori informazioni. |
GAL_REFRESH_IN_PROGRESS |
Il token di accesso dell'utente è scaduto e un altro tentativo simultaneo di aggiornarlo è già in corso.
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 nel logging di Google Cloud per controllare i log dei servizi per la smart home.
|
INVALID_JSON |
Impossibile analizzare o comprendere la risposta JSON.
Controlla che la struttura della tua risposta JSON non presenti sintassi non valide, ad esempio parentesi non corrispondenti, virgole mancanti o 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 frequenza maggiore 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 tua richiesta indica un errore, assicurati di utilizzarne uno fornito dai nostri codici di errore supportati. |
PARTNER_RESPONSE_INVALID_PAYLOAD |
Il campo payload della risposta non può essere analizzato come oggetto JSON.
Verifica 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 uno errato.
Le risposte alle richieste di evasione degli intent devono indicare uno stato con SUCCESS, OFFLINE, ERROR, EXCEPTIONS. Puoi trovare ulteriori informazioni sulla
gestione degli errori e delle 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 nella risposta siano presenti i risultati per tutti gli intent della richiesta. |
PARTNER_RESPONSE_MISSING_DEVICE |
Nella risposta mancano uno o più dispositivi presenti nella richiesta.
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. Scopri di più su come creare correttamente una risposta di esecuzione. |
PARTNER_RESPONSE_NOT_OBJECT |
Impossibile analizzare la risposta come oggetto JSON.
Controlla tutti i campi della risposta alla richiesta per verificare che non contengano caratteri indesiderati, parentesi non corrispondenti o errori di formattazione. Alcuni caratteri Unicode potrebbero non essere supportati. Assicurati inoltre che la risposta sia correttamente strutturata 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 dall'invio della richiesta. Assicurati di inviare una risposta entro questo periodo di tempo. |
RESPONSE_UNAVAILABLE |
Non viene ricevuta alcuna risposta oppure la risposta non indica lo stato.
Le risposte alle richieste di evasione degli 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 da solo.
Nella maggior parte dei casi, questi errori si manifestano come connessione a un dispositivo o servizio che viene interrotto. anche se non è possibile aprire nuove connessioni a un server. |
Log di ricerca
Una volta che hai acquisito 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 di tipo JSON con campi che contengono informazioni utili come ora, codice di errore e dettagli relativi all'intent per la smart home di origine.
All'interno di Google Cloud sono presenti più sistemi che inviano i log al tuo progetto in qualsiasi momento. Devi scrivere query per filtrare i log e trovare quelle che ti servono. Le query possono essere basate su intervallo di tempo, risorsa, gravità di log o voci personalizzate.
Puoi utilizzare i pulsanti di query per creare i filtri personalizzati.
Per specificare un intervallo di tempo, fai clic sul pulsante di selezione dell'intervallo di tempo e scegli una delle opzioni disponibili. 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 azione dell'Assistente Google. Questo aggiunge un filtro alla query per mostrare i log che hanno origine dal progetto.
Utilizza il pulsante Gravità per filtrare in base ai livelli di log di Emergenza, Informazioni, Debug e altri livelli di gravità.
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 i tipi più avanzati di query che includono i comparatori (<, >=, !=) e gli 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 delle query per trovare altri esempi di esecuzione di query efficaci sui log.
Test delle correzioni
Una volta identificati gli errori e applicati gli aggiornamenti per correggerli, ti consigliamo di testare accuratamente le correzioni con Google Home Test Suite. Forniamo una guida dell'utente su come utilizzare Test Suite, che ti accompagnerà in come testare le modifiche in modo efficace.
Risorse didattiche
Questo documento illustra i passaggi per risolvere gli errori nell'azione per la smart home. Puoi anche consultare i nostri codelab per scoprire di più sul debug:
- Debug del codelab per la smart home: guida rapida per eseguire il debug dell'integrazione cloud della smart home.
- Debug del codelab per la casa locale: Guida rapida per eseguire il debug dell'integrazione locale nella smart home.