refresh_date: 06-01-2023
Google Cloud fornisce gli strumenti per monitorare l'affidabilità dei progetti con Google Cloud Monitoring ed eseguire il debug dei problemi con i log degli errori Google Cloud Logging. Ogni volta che si verifica un errore quando vengono soddisfatti gli intent degli utenti, la pipeline di analisi di Google Home registra l'errore nelle metriche e pubblica un log degli errori nei log del progetto.
La procedura per la risoluzione degli 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.
Errori di monitoraggio
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 quando monitori l'affidabilità dei 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 individuare eventuali irregolarità dopo ogni modifica o aggiornamento del progetto.
- I grafici di Analisi degli errori sono più utili quando si tratta di risolvere i problemi delle integrazioni. Per ogni errore evidenziato nel grafico della percentuale di successo, viene visualizzato un codice di errore nell'analisi dettagliata degli errori. Puoi vedere gli errori segnalati da Google Home platform e come risolverli nella tabella riportata di seguito.
Codici di errore della piattaforma
Di seguito sono riportati alcuni codici di errore comuni che potresti visualizzare nei log di progetto per identificare i problemi rilevati da Google Home platform. Fai riferimento alla seguente tabella per informazioni sulla risoluzione dei problemi.
| 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 Google Cloud 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 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 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.
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 un formato o di valori non validi nel payload.
Utilizza requestId nel logging di Google Cloud 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 percentuale maggiore di questo errore nel logging di Google Cloud, contattaci per saperne di più. |
GAL_INVALID_ARGUMENT |
Si è verificato un errore interno di Google durante il tentativo di recupero di un token di accesso.
Se noti una percentuale maggiore di questo errore nel logging di Google Cloud, contattaci per saperne di più. |
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 una percentuale maggiore di questo errore nel logging di Google Cloud, contattaci per saperne di più. |
GAL_PERMISSION_DENIED |
Si è verificato un errore interno di Google quando la condivisione del token non è autorizzata.
Se noti una percentuale maggiore di questo errore nel logging di Google Cloud, contattaci per saperne di più. |
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. |
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 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.
Controlla se il campo payload nella risposta alla richiesta ha parentesi quadre corrispondenti e se è strutturato correttamente come campo JSON. |
PARTNER_RESPONSE_INVALID_STATUS |
La risposta non indica uno stato oppure uno stato errato.
Le risposte alle richieste di evasione degli intent 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 nella risposta siano presenti i risultati relativi a tutti gli intent della richiesta. |
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. Scopri di più su come creare correttamente una risposta di esecuzione. |
PARTNER_RESPONSE_NOT_OBJECT |
La risposta non può essere analizzata 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 nell'elaborazione della richiesta.
Utilizza requestId in Google Cloud Logging per controllare i log dei servizi per la smart home.
|
RESPONSE_TIMEOUT |
Timeout della richiesta in 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 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 risolverà 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 avrai preso dimestichezza con il monitoraggio delle integrazioni utilizzando le metriche, il passaggio successivo consisterà 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 della smart home di origine.
All'interno di Google Cloud sono presenti più sistemi che inviano 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à dei 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, quindi scegli Progetto di azione dell'Assistente Google. In questo modo viene aggiunto un filtro alla query per visualizzare i log che provengono dal progetto.
Utilizza il pulsante Gravità per filtrare in base a Emergenza, Informazioni, Debug e altri livelli di log 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 delle stringhe sia i tipi più avanzati di query, inclusi i comparatori (<, >=, !=) e gli operatori booleani (AND, OR, NOT).
Ad esempio, la voce personalizzata riportata di seguito restituisce 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 per eseguire in modo efficace query sui log.
Verifica delle correzioni
Dopo aver identificato gli errori e aver 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 guida attraverso come testare le modifiche in modo efficace.
Risorse didattiche
Questo documento illustra i passaggi per risolvere gli errori relativi all'azione per la smart home. Puoi anche consultare i nostri codelab per scoprire di più sul debug:
- Codelab sul debug per la smart home: guida rapida per il debug dell'integrazione cloud per la smart home.
- Debug del codelab per la casa locale: guida rapida per il debug dell'integrazione locale della smart home.