Risoluzione degli errori di integrazione della pratica

refresh_date: 2023-01-06

Google Cloud ti fornisce gli strumenti per monitorare l'affidabilità dei tuoi progetti con Google Cloud Monitoring e risolvere i problemi con Google Cloud Logging log degli errori. Ogni volta che si verifica un errore durante l'esecuzione degli intent utente, 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 relativi agli errori, segui questi due passaggi:

  1. Monitora lo stato dei tuoi progetti con le metriche per la smart home.
  2. Esamina i problemi controllando le descrizioni dettagliate degli errori nei log degli errori.

Monitorare gli errori

Puoi utilizzare Google Cloud Monitoring dashboards per accedere alle metriche del progetto. Di seguito sono riportati alcuni grafici chiave particolarmente utili per monitorare la qualità e risolvere i problemi:

  • Il grafico della percentuale di successo è il primo da consultare quando monitori l'affidabilità dei tuoi progetti. I cali in questo grafico possono indicare un'interruzione per una parte o per l'intera base utenti. Ti consigliamo di monitorare attentamente questo grafico per verificare la presenza di eventuali irregolarità dopo ogni modifica o aggiornamento del progetto.
  • I grafici della suddivisione degli errori sono più 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. Nella tabella riportata di seguito puoi vedere 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. Consulta la tabella riportata di seguito per informazioni sulla risoluzione dei problemi. Per un elenco completo dei codici di errore, consulta la sezione Errori ed eccezioni.

Codice di errore Descrizione Azione del partner
AGENT_ISSUE Si è verificato un problema generale con l'agente cloud del partner.

Controlla la presenza di eccezioni o arresti anomali non gestiti nei log di fulfillment. 		Sì
AGENT_UNAVAILABLE_ERROR Google non è riuscita a raggiungere l'URL di fulfillment del partner.

Assicurati che il server sia online, che il firewall non blocchi Google e che l' URL sia corretto. 		Sì
BACKEND_FAILURE_URL_TIMEOUT La richiesta di Google è scaduta durante il tentativo di raggiungere il tuo servizio.

Verifica che il servizio sia online, accetti le connessioni, e non sia in sovraccarico. 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 per la smart home. Esamina gli arresti anomali del server, i timeout, o gli errori del gateway 502/503.
COMMAND_FAILED Si è verificato un errore generico durante l'esecuzione di un comando.

Controlla i log di fulfillment per trovare requestId specifico e individuare la causa principale. 		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 fulfillment è bloccato da robots.txt o dai filtri di sicurezza.

Assicurati che l'endpoint di fulfillment sia accessibile ai crawler/servizi di Google. 		Sì
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE Google ha ricevuto un errore HTTP 5xx dal tuo servizio di fulfillment.

Assicurati che il servizio dell'URL dell'endpoint sia stabile, corretto e raggiungibile pubblicamente e che il servizio sia in esecuzione. Aggiungi controlli di integrità e gestione dei tentativi. Esamina gli arresti anomali del server, i timeout o gli errori del gateway 502/503. 		Sì
EXECUTION_BAILOUT_INVALID_RESPONSE La risposta JSON non è valida, pertanto l'elaborazione è stata interrotta.

Utilizza uno strumento di convalida JSON per assicurarti che la risposta segua rigorosamente gli schemi degli 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 Il cloud 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_NOT_FOUND I token di accesso e aggiornamento dell'utente archiviati in Google non sono validi o non possono essere aggiornati, impedendo l'autenticazione e l'accesso al servizio del partner.

Assicurati che i token rimangano validi e sincronizzati, gestisci correttamente le modifiche dello stato dell'account e richiedi agli utenti di ricollegare l'account se viene confermato che i token sono stati revocati. 		Sì
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P L'integrazione è in stato di sola lettura sul lato 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.

Esamina il motivo per cui l'utente è stato disconnesso (ad esempio, reimpostazione della sicurezza). Assicurati che il server OAuth del partner risponda correttamente alle richieste refresh_token di Google per emettere nuovi token di accesso senza problemi. 		Sì
EXECUTION_INVALID_JSON Google non è riuscita ad analizzare il payload della risposta JSON.

Controlla la presenza di errori di sintassi, parentesi mancanti o caratteri non validi nella risposta. 		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 rispetto agli schemi JSON degli intent. 		Sì
MALFORMED_JSON La struttura JSON è danneggiata (ad esempio, stringhe o oggetti non chiusi).

Assicurati che il fulfillment utilizzi una libreria JSON standard per serializzare le risposte. 		Sì
NOT_IMPLEMENTED L'intent o il tratto richiesto non è stato implementato dal partner.

Includi nella risposta SYNC solo i tratti che hai implementato completamente. 		Sì
OPEN_AUTH_FAILURE Il token di accesso dell'utente è scaduto e Google non è in grado di aggiornarlo, o Google ha ricevuto un codice di errore HTTP 401 dal tuo servizio.

Se noti un aumento della frequenza di questo codice, controlla se si verifica anche un aumento della frequenza degli 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 di Google's.

Mappa gli errori interni all' 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 fulfillment. 		Sì
PARTNER_RESPONSE_INVALID_STATUS status della risposta 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 i risultati per tutti i comandi/dispositivi richiesti.

Convalida la struttura della risposta rispetto alla documentazione per gli sviluppatori di Google Home. Assicurati che la risposta non venga troncata o che non restituisca un corpo vuoto a causa di un errore interno del server. Ogni elemento nell'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 Non è stato possibile analizzare l'intera risposta come oggetto JSON.

Controlla la presenza di caratteri finali o contenuti non JSON nel corpo della risposta HTTP. Assicurati che payload.commands[] sia un oggetto JSON corretto con ID, stato e stati facoltativi. 		Sì
REQUEST_ID_NOT_FOUND Google non è riuscita a trovare l'ID di 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 tratto) non è disponibile.

Controlla se il dispositivo è "Occupato" o è stato disattivato temporaneamente. 		Sì
RESPONSE_TIMEOUT Il servizio di fulfillment non ha risposto entro 9 secondi.

Ottimizza la latenza del backend, controlla la presenza di query DB lente o ritardi della rete regionale. 		Sì
RESPONSE_UNAVAILABLE Non è stata ricevuta alcuna risposta dall'URL di fulfillment del partner.

Verifica che il servizio sia in esecuzione e che l'endpoint non vada in crash. 		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ì

Log di ricerca

Una volta che hai acquisito familiarità con il monitoraggio delle integrazioni utilizzando le metriche, il passaggio successivo consiste nel risolvere gli errori specifici utilizzando Cloud Logging. Un log degli errori è una voce simile a JSON con campi contenenti informazioni utili come l'ora, il codice di errore e i dettagli relativi all'intent per la smart home di origine.

Esistono più sistemi all'interno di Google Cloud che inviano log a tuo progetto in ogni momento. Devi scrivere query per filtrare i log e trovare quelli di cui hai bisogno. Le query possono essere basate su un intervallo di tempo, risorsa, una gravità del log o voci personalizzate.

Eseguire query sui log di Cloud

Puoi utilizzare i pulsanti delle query per creare filtri personalizzati.

Creare query per i log di Cloud

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 visualizzati solo quelli che hanno origine nell'intervallo di tempo selezionato.

Per specificare una risorsa, fai clic sul menu a discesa Risorsa, quindi scegli Progetto di azioni per l'Assistente Google. In questo modo viene aggiunto un filtro alla query per mostrare i log provenienti dal tuo progetto.

Utilizza il pulsante Gravità per filtrare in base ai livelli di gravità dei log Emergenza, Informazioni, Debug, e altri.

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 comparatori (<, >=, !=) e operatori booleani (AND, OR, NOT).

Ad esempio, la voce personalizzata riportata di seguito restituirebbe gli errori provenienti 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 sui log.

Testare le correzioni

Dopo aver identificato gli errori e applicato gli aggiornamenti per correggerli, ti consigliamo di testare le correzioni attentamente con Google Home Test Suite. Forniamo una guida utente su come utilizzare Test Suite, che ti illustra come testare efficacemente le modifiche.

Risorse didattiche

Questo documento fornisce i passaggi per risolvere gli errori nell'azione per la smart home. Puoi anche consultare i nostri codelab per scoprire di più sul debug:

Indietro
Cloud Logging per pratica