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 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 quando monitori 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 tenere il passo con le richieste. Ti consigliamo 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 da Google Home platform e come risolverli.
Codici di errore comuni 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. Per un elenco completo dei codici di errore, consulta Errori ed eccezioni.
| Codice di errore | Descrizione | Azione del partner |
|---|---|---|
ACTION_NOT_AVAILABLE |
Il comando non è valido per lo stato attuale del dispositivo (ad esempio,
"Imposta temperatura" mentre il dispositivo è spento).
Verifica le caratteristiche del dispositivo e la logica dello stato attuale nell'evasione. |
Sì |
AGENT_ISSUE |
Si è verificato un problema generale con l'agente cloud del partner.
Controlla la presenza di eccezioni non gestite o arresti anomali nei log di evasione. |
Sì |
AGENT_UNAVAILABLE_ERROR |
Google non è riuscito a raggiungere l'URL di evasione dell'ordine del partner.
Assicurati che il server sia online, che il firewall non blocchi Google e che l'URL sia corretto. |
Sì |
APP_LAUNCH_FAILED |
Impossibile avviare l'app di terze parti sul dispositivo di destinazione.
Verifica l'ID app e che l'app sia supportata sull'hardware di destinazione. |
Sì |
AUTH_EXPIRED |
Il token di accesso OAuth è scaduto e non può essere aggiornato.
Controlla la rotazione del token di aggiornamento e assicurati che l'utente non abbia revocato l'accesso. |
Sì |
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 Google Cloud Logging per controllare
i log del servizio di smart home.
|
|
CHANNEL_SWITCH_FAILED |
Il dispositivo non è riuscito a passare al canale multimediale richiesto.
Verifica i nomi/numeri dei canali e lo stato dell'abbonamento dell'utente. |
Sì |
CHARGER_ISSUE |
Il dispositivo segnala un problema hardware con il sistema di ricarica.
Il partner deve esaminare la telemetria a livello hardware e lo stato della batteria. |
Sì |
CHECK_PARTNER_APP |
L'errore richiede all'utente di aprire l'app del partner per la risoluzione.
Utilizza questo codice per gli errori che richiedono un'interazione complessa con la UI (ad esempio, aggiornamenti firmware). |
Sì |
COMMAND_FAILED |
Si è verificato un errore generico durante l'esecuzione di un comando.
Controlla i log di evasione per trovare il requestId specifico
e individuare la causa principale.
|
Sì |
COMMAND_INSERT_FAILED |
Google non è riuscito a mettere in coda o elaborare il comando per il dispositivo.
Analizza le prestazioni di scrittura del database o la logica di accodamento dei comandi interni. |
Sì |
DEVICE_NOT_FOUND |
L'ID dispositivo nella richiesta non esiste sul lato partner.
Assicurati che il cloud attivi un requestSync quando un utente
aggiunge o elimina dispositivi.
|
Sì |
ERROR_STATUS |
La risposta indicava uno stato "ERROR" non specifico senza un codice.
Includi sempre una stringa errorCode specifica per migliorare
i dati TTS e della dashboard degli utenti.
|
Sì |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google ha ricevuto un errore HTTP 4xx (diverso da 401) dal tuo
fulfillment.
Controlla i log del server web per le risposte 403, 404 o 400. |
Sì |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
L'URL di evasione è bloccato da robots.txt o dai filtri di sicurezza.
Assicurati che l'endpoint di evasione sia accessibile ai crawler/servizi di Google. |
Sì |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google ha ricevuto un errore HTTP 5xx dal tuo servizio di evasione.
Indaga su arresti anomali, timeout o errori 502/503 del gateway del server. |
Sì |
EXECUTION_BAILOUT_INVALID_RESPONSE |
La risposta JSON non era valida, pertanto l'elaborazione è stata interrotta.
Utilizza un validatore JSON per assicurarti che la risposta segua rigorosamente gli schemi di intent. |
Sì |
EXECUTION_GAL_BAD_3P_RESPONSE |
Il collegamento dell'account non è riuscito a causa di un formato non valido nella risposta del token.
Verifica che il formato della risposta del server OAuth corrisponda ai requisiti di Google. |
Sì |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
L'account dell'utente non dispone delle autorizzazioni necessarie per questa azione.
Controlla gli ambiti richiesti durante OAuth e assicurati che corrispondano ai tratti richiesti. |
Sì |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
La nuvola del partner indica che l'utente ha scollegato il proprio account.
Assicurati che il mapping agentUserId sia stabile e non sia
stato eliminato.
|
Sì |
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
L'integrazione è in stato di sola lettura da parte del partner.
Controlla se l'account dell'utente è sospeso o in modalità di manutenzione "sola visualizzazione". |
Sì |
EXECUTION_GAL_UNLINKED_BY_3P |
L'account è stato scollegato in modo proattivo dal servizio di terze parti.
Indaga sul motivo per cui l'utente è stato disconnesso (ad esempio, ripristino della sicurezza). |
Sì |
EXECUTION_INVALID_JSON |
Impossibile analizzare il payload della risposta JSON da parte di Google.
Controlla la presenza di errori di sintassi, parentesi mancanti o caratteri non validi nella risposta. |
Sì |
FAULTY_BATTERY |
L'hardware del dispositivo segnala che la batteria è guasta o scarica.
Chiedi all'utente di sostituire la batteria fisica utilizzando la sintesi vocale o l'app. |
Sì |
FUNCTION_NOT_SUPPORTED |
La modalità o la funzione richiesta non è supportata dal dispositivo.
Assicurati che la risposta SYNC rifletta con precisione le
funzionalità del dispositivo.
|
Sì |
HARD_ERROR |
Un errore non temporaneo che non si risolve senza intervento manuale.
Utilizza questo stato per guasti hardware permanenti o stati dell'account non recuperabili. |
Sì |
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 Google Cloud Logging per controllare i log del servizio per la smart home.
|
|
INVALID_JSON |
La struttura della risposta non è valida (ad esempio, mancano campi
obbligatori).
Convalida la risposta in base agli schemi JSON degli intent. |
Sì |
LOCK_FAILURE |
La serratura smart non è riuscita a passare allo stato richiesto.
Verifica la presenza di inceppamenti fisici, batteria scarica o guasti al motore della serratura. |
Sì |
MALFORMED_JSON |
La struttura JSON è danneggiata (ad esempio, stringhe o
oggetti non chiusi).
Assicurati che l'evasione utilizzi una libreria JSON standard per serializzare le risposte. |
Sì |
MISSING_STATE |
La risposta QUERY non conteneva lo stato del dispositivo richiesto.
Assicurati che tutte le caratteristiche definite in SYNC siano prese in considerazione in
ogni risposta QUERY.
|
Sì |
NETWORK_PROFILE_NOT_RECOGNIZED |
Il profilo di rete richiesto è sconosciuto al dispositivo.
Verifica che la stringa del nome del profilo corrisponda ai profili supportati nella risposta SYNC.
|
Sì |
NOT_IMPLEMENTED |
L'intent o la caratteristica richiesti non sono stati implementati dal partner.
Includi nella risposta SYNC solo le caratteristiche che hai
implementato completamente.
|
Sì |
OAUTH_RECONNECT_CALL_TO_ACTION |
Attiva una notifica per l'utente che deve ricollegare il proprio account.
Utilizza questa risposta predefinita quando la sessione di un utente viene invalidata e richiede una riautorizzazione OAuth manuale. |
Sì |
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 stringa errorCode restituita non è presente nell'elenco
supportato da Google.
Mappa gli errori interni con l'elenco ufficiale degli errori. |
Sì |
PARTNER_RESPONSE_INVALID_PAYLOAD |
Il campo payload nella risposta non è un oggetto JSON valido.
Verifica la struttura principale della risposta di evasione. |
Sì |
PARTNER_RESPONSE_INVALID_STATUS |
La risposta status non era SUCCESS, ERROR o OFFLINE.
Assicurati che ogni risultato del dispositivo nella risposta includa una stringa di stato valida. |
Sì |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
La risposta non includeva risultati per tutti i comandi/dispositivi
richiesti.
Ogni elemento dell'array commands della richiesta deve avere una voce di risposta corrispondente.
|
Sì |
PARTNER_RESPONSE_MISSING_DEVICE |
Un dispositivo specifico richiesto da Google è stato omesso dalla risposta.
Assicurati che la risposta includa ogni ID fornito nel
payload della richiesta.
|
Sì |
PARTNER_RESPONSE_MISSING_PAYLOAD |
Nella risposta manca il campo obbligatorio payload.
Assicurati che l'oggetto JSON di primo livello includa una chiave payload.
|
Sì |
PARTNER_RESPONSE_NOT_OBJECT |
L'intera risposta non è stata analizzata come oggetto JSON.
Controlla la presenza di caratteri finali o contenuti non JSON nel corpo della risposta HTTP. |
Sì |
PROTOCOL_ERROR |
Si è verificato un errore nel protocollo di comunicazione sottostante.
Esamina i problemi relativi all'intestazione HTTP o gli errori di handshake SSL/TLS. |
Sì |
RELINK_REQUIRED |
L'utente deve ricollegare il proprio account per continuare a utilizzare l'integrazione.
Assicurati che il server restituisca questo codice quando un token di aggiornamento non è più valido. |
Sì |
REQUEST_ID_NOT_FOUND |
Google non è riuscito a trovare l'ID monitoraggio interno per la richiesta.
In genere si tratta di un errore interno della piattaforma. Monitora i picchi e contatta l'assistenza. |
Sì |
RESOURCE_UNAVAILABLE |
La risorsa richiesta (dispositivo o caratteristica) non è disponibile.
Controlla se il dispositivo è "Occupato" o è stato disattivato temporaneamente. |
Sì |
RESPONSE_TIMEOUT |
Il servizio di evasione non ha risposto entro 9 secondi.
Ottimizza la latenza di backend; verifica la presenza di query DB lente o ritardi di rete regionali. |
Sì |
RESPONSE_UNAVAILABLE |
Nessuna risposta ricevuta dall'URL di evasione del partner.
Verifica che il servizio sia in esecuzione e che l'endpoint non vada in arresto anomalo. |
Sì |
SCENE_CANNOT_BE_APPLIED |
La scena richiesta non è stata attivata (ad esempio, dispositivi
mancanti).
Controlla lo stato interno delle scene dell'utente sul cloud del partner. |
Sì |
STREAM_UNPLAYABLE |
Impossibile avviare lo stream della videocamera o si è verificato un errore.
Verifica la segnalazione WebRTC/HLS e assicurati che l'URL dello stream sia valido. |
Sì |
TIMEOUT |
Si è verificato un timeout generale durante l'elaborazione dell'intent.
Controlla i log per i timeout del servizio interno tra il cloud e gli hub dei dispositivi. |
Sì |
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. |
|
UNABLE_TO_LOCATE_DEVICE |
Impossibile trovare il dispositivo utilizzando la caratteristica Locator (ad esempio,
ping non riuscito).
Controlla la connettività locale del dispositivo (Wi-Fi/Bluetooth). |
Sì |
UNABLE_TO_RING_DEVICE |
Il dispositivo è stato raggiunto, ma non è stato possibile attivare la funzione di suoneria/avviso.
Verifica lo stato di avviso/altoparlante e i livelli di volume dell'hardware. |
Sì |
UNABLE_TO_SILENCE_DEVICE |
Il dispositivo non è riuscito a interrompere l'avviso/la suoneria attivo.
Esamina gli errori di comunicazione tra il cloud e il dispositivo fisico. |
Sì |
UNEXPECTED_ERROR_CHECK_DEVICE_APP |
Si è verificato un errore imprevisto; l'utente deve controllare l'app partner.
Utilizza questo messaggio come soluzione generica per gli errori senza un equivalente specifico supportato da Google. |
Sì |
UNKNOWN_ERROR |
Un errore generico senza ulteriori dettagli.
L'obiettivo è sostituire questo codice con codici di errore più specifici per migliorare la risoluzione dei problemi. |
Sì |
UNLOCK_FAILURE |
La serratura smart non è riuscita a raggiungere lo stato "Aperta".
Indaga su inceppamenti hardware, batteria in esaurimento o inserimento di PIN non validi. |
Sì |
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. In questo modo, alla query viene aggiunto un filtro 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 per i log.
Test delle correzioni
Una volta identificati gli errori e applicati gli aggiornamenti per correggerli, ti consigliamo di testare a fondo le correzioni con Google Home Test Suite. Forniamo una guida per l'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 cloud della smart home.
- Codelab per il debug di Local Home: Guida rapida per il debug dell'integrazione locale della smart home.