1. Prima di iniziare
In qualità di sviluppatore di Internet of Things (IoT), puoi creare integrazioni da cloud a cloud che consentano agli utenti di controllare i propri dispositivi tramite i controlli touch nell'app Google Home e i comandi vocali con l'Assistente Google.
L'apprendimento degli strumenti di debug per le integrazioni da cloud a cloud è un passo importante per creare un'integrazione di qualità di produzione con l'Assistente Google. Per facilitare il monitoraggio e il debug, sono disponibili le metriche di Google Cloud Platform (GCP) e il logging e la Test Suite per la smart home, che ti aiutano a identificare e risolvere i problemi delle tue integrazioni.
Prerequisiti
- Leggi la guida per gli sviluppatori Creare un'integrazione da cloud a cloud
- Esegui il codelab Connetti i dispositivi per la smart home all'Assistente Google
Che cosa creerai
In questo codelab, eseguirai il deployment di un'integrazione da cloud a cloud con 2 difetti e la collegherai all'Assistente, quindi eseguirai il debug dei difetti dell'integrazione utilizzando la Test Suite per la smart home e le metriche e il logging di Google Cloud Platform (GCP).
Obiettivi didattici
- Come utilizzare le metriche e il logging di GCP per identificare e risolvere i problemi di produzione
- Come utilizzare la Test Suite per la smart home per identificare i problemi funzionali e delle API
Che cosa ti serve
- Un browser web, ad esempio Google Chrome
- Un dispositivo iOS o Android con l'app Google Home installata
- Node.js versione 24 o successive
- Un account di fatturazione Google Cloud .
2. Esegui l'app difettosa
Recupera il codice sorgente
Fai clic sul seguente link per scaricare l'esempio per questo codelab sulla tua macchina di sviluppo:
...oppure puoi clonare il repository GitHub dalla riga di comando:
$ git clone https://github.com/google-home/smarthome-debug.git
Informazioni sul progetto
L'app per la lavatrice contiene le seguenti sottodirectory:
public: un'interfaccia utente frontend per controllare e monitorare facilmente lo stato della lavatrice smart.functions: un servizio cloud completamente implementato che gestisce la lavatrice smart con Cloud Functions per Firebase e Firebase Realtime Database.
Connessione a Firebase
Apri il terminale sulla tua macchina di sviluppo. Vai alla directory washer-faulty, quindi configura l'interfaccia a riga di comando di Firebase con il progetto di integrazione creato nel codelab Connetti i dispositivi per la smart home all'Assistente Google:
$ cd washer-faulty $ firebase use <firebase-project-id>
Esegui il deployment in Firebase
Vai alla cartella functions e installa tutte le dipendenze necessarie utilizzando npm.
$ cd functions $ npm install
Nota:se vedi il messaggio riportato di seguito, puoi ignorarlo e continuare. L'avviso è dovuto ad alcune dipendenze precedenti e puoi trovare ulteriori dettagli qui.
found 5 high severity vulnerabilities run `npm audit fix` to fix them, or `npm audit` for details
Ora che hai installato le dipendenze e configurato il progetto, puoi eseguire il deployment dell'app per la lavatrice difettosa.
$ firebase deploy
Questo è l'output della console che dovresti vedere:
... ✔ Deploy complete! Project Console: https://console.firebase.google.com/project/<Firebase-project-id>/overview Hosting URL: https://<Firebase-project-id>.firebaseapp.com
Aggiorna HomeGraph
Apri l'URL di hosting nel browser (https://<firebase-project-id>.firebaseapp.com) per visualizzare l'app web. Nell'interfaccia utente web, fai clic sul pulsante Aggiorna
per aggiornare HomeGraph con i metadati del dispositivo più recenti dall'app per la lavatrice difettosa utilizzando Request Sync.
Apri l'app Google Home e verifica di poter vedere il dispositivo della lavatrice denominato Lavatrice difettosa.
3. Verifica l'integrazione
Dopo aver eseguito il deployment del progetto, verifica che l'integrazione controlli la lavatrice.
Testa la lavatrice
Controlla la modifica del valore quando provi uno dei seguenti comandi vocali tramite lo smartphone:
"Hey Google, accendi la lavatrice."
"Hey Google, avvia la lavatrice."
"Hey Google, metti in pausa la lavatrice."
"Hey Google, riprendi la lavatrice."
"Hey Google, spegni la lavatrice."
Noterai che l'Assistente risponde che qualcosa non va a voce quando metti in pausa / riprendi la lavatrice:
"Mi dispiaccio, non sono riuscito a raggiungere <project display name>."
Per eseguire il debug di questo problema, devi prima avere maggiori informazioni sull'errore per restringere e identificare la causa principale.
Dashboard di analisi della smart home
Un buon punto di partenza per esaminare gli errori è la dashboard di analisi della smart home, che aggrega i grafici delle metriche di utilizzo e integrità per il fulfillment cloud:
- Le metriche di utilizzo riflettono l'andamento dell'utilizzo dell'integrazione da cloud a cloud, incluso il numero di utenti attivi giornalieri e il numero totale di richieste al fulfillment.
- Le metriche di integrità ti aiutano a monitorare l'occorrenza di anomalie nell'integrazione da cloud a cloud, coprendo la latenza delle richieste, la percentuale di successo e la suddivisione degli errori.
Per restringere la causa dell'errore, segui i passaggi riportati di seguito per accedere alla dashboard del progetto.
- Nella Developer Console, vai alla pagina Progetti.
- Seleziona il progetto della smart home.
- Fai clic sulla scheda Analytics nel menu a sinistra.
- Viene visualizzato un elenco di dashboard per il tuo progetto su Google Cloud. Seleziona la dashboard Google Home Analytics - Integrazione cloud.
- Scorri verso il basso fino al grafico Errori di fulfillment cloud - Suddivisione dello stato per visualizzare i codici di errore per l'intervallo di tempo evidenziato.
Il codice di errore PARTNER_RESPONSE_MISSING_DEVICE fornisce un suggerimento sulla causa principale. Successivamente, recupera i log degli eventi in base al codice di errore per ulteriori dettagli.
Accedi ai log degli eventi
Per ottenere maggiori dettagli sull'errore, accedi ai log degli eventi per l'integrazione da cloud a cloud utilizzando Cloud Logging.
Apri il menu di navigazione in Google Cloud Platform e, in Operazioni, seleziona Logging > Esplora log per accedere ai log degli eventi del tuo progetto. In alternativa, puoi cercare Esplora log nella casella di ricerca.
Nel campo di immissione Cerca in tutti i campi, inserisci la query PARTNER_RESPONSE_MISSING_DEVICE e fai clic su Esegui query. I log che corrispondono alla query vengono visualizzati nella sezione Risultati.
Il log degli errori mostra un evento della smart home con dettagli dell'errore che indicano:
- L'azione dell'utente intrapresa è "riprendere la lavatrice" (
actionType:"STARTSTOP_UNPAUSE"), corrispondente al comando vocale non riuscito di recente. - Il messaggio di debug associato è "
JSON response does not include device."
In base al messaggio di debug, devi verificare perché l'app per la lavatrice non include il dispositivo corretto nella risposta EXECUTE.
Identifica la causa principale dell'errore
In functions/index.js, trova il gestore EXECUTE (nell'array onExecute) che restituisce lo stato di ogni comando e il nuovo stato del dispositivo. L'inserimento degli ID dispositivo in una risposta EXECUTE dipende dalla risoluzione della funzione updateDevice:
index.js
app.onExecute(async (body) => {
...
for (const command of intent.payload.commands) {
for (const device of command.devices) {
for (const execution of command.execution) {
executePromises.push(
updateDevice(execution, device.id)
.then((data) => {
result.ids.push(device.id);
Object.assign(result.states, data);
})
.catch((e) =>
functions.logger.error('EXECUTE',
device.id, e.message)));
}
}
}
Controlla ulteriormente il modo in cui la funzione updateDevice gestisce la pausa / ripresa della lavatrice e troverai che la stringa da abbinare al comando di pausa / ripresa non è corretta:
index.js
const updateDevice = async (execution, deviceId) => {
const {params, command} = execution;
let state; let ref;
switch (command) {
...
case 'action.devices.commands.PauseUnpausePause':
const data = await queryDevice(deviceId);
state = (data.isPaused === false && data.isRunning === false)
? {isRunning: false, isPaused: false}
: {isRunning: !params.pause, isPaused: params.pause};
ref = getFirebaseRef().child(deviceId).child('StartStop');
break;
}
return ref.update(state)
.then(() => state);
};
Correggi l'errore
Ora che hai identificato la causa principale dell'errore, puoi correggere la stringa per il comando di pausa / ripresa:
index.js
const updateDevice = async (execution, deviceId) => {
const {params, command} = execution;
let state; let ref;
switch (command) {
...
case 'action.devices.commands.PauseUnpause':
const data = await queryDevice(deviceId);
state = (data.isPaused === false && data.isRunning === false)
? {isRunning: false, isPaused: false}
: {isRunning: !params.pause, isPaused: params.pause};
ref = getFirebaseRef().child(deviceId).child('StartStop');
break;
}
return ref.update(state)
.then(() => state);
};
Verifica la correzione
Esegui il deployment del codice aggiornato utilizzando l'interfaccia a riga di comando di Firebase:
firebase deploy --only functions
Riprova i seguenti comandi vocali e vedrai che l'Assistente risponde correttamente quando metti in pausa / riprendi la lavatrice.
"Hey Google, metti in pausa la lavatrice."
=>
"Certo, metto in pausa la lavatrice."
"Hey Google, riprendi la lavatrice."
=>
"Ok, riprendo la lavatrice."
Puoi anche testare lo stato attuale della lavatrice ponendo domande.
"Hey Google, la lavatrice è accesa?"
"Hey Google, la lavatrice è in funzione?"
"Hey Google, a che ciclo è la lavatrice?"
4. Verifica l'integrazione con la Test Suite
Oltre a eseguire i test manualmente, puoi utilizzare la Test Suite automatizzata per la smart home per convalidare i casi d'uso in base ai tipi di dispositivo e alle caratteristiche associate all'integrazione. La Test Suite esegue una serie di test per rilevare problemi nell'integrazione e mostra messaggi informativi per i casi di test non riusciti per velocizzare il debug prima di approfondire i log degli eventi.
Esegui la Test Suite per la smart home
Segui queste istruzioni per testare l'integrazione da cloud a cloud con la Test Suite:
- Nel browser web, apri la Test Suite per la smart home.
- Accedi a Google utilizzando il pulsante nell'angolo in alto a destra. In questo modo, la Test Suite può inviare i comandi direttamente all'Assistente Google.
- Nel campo ID progetto, inserisci l'ID progetto dell'integrazione da cloud a cloud. Fai clic su AVANTI per continuare.
- Nel passaggio Impostazioni test, la Test Suite elenca il tipo di dispositivo e le caratteristiche della lavatrice.
- Disattiva l'opzione Test Request Sync perché l'app di esempio per la lavatrice non ha un'interfaccia utente per aggiungere, rimuovere o rinominare la lavatrice. In un sistema di produzione, devi attivare Request Sync ogni volta che l'utente aggiunge, rimuove o rinomina i dispositivi.
- Fai clic su AVANTI per avviare l'esecuzione del test.
Al termine dell'esecuzione della Test Suite, visualizza i risultati dei casi di test. Noterai due casi di test non riusciti con il rispettivo messaggio di errore:
Per eseguire il debug dell'integrazione da cloud a cloud per l'errore, devi identificare la causa principale dell'errore analizzando prima il messaggio di errore.
Analizza il messaggio di errore
Per aiutare gli sviluppatori a identificare la causa principale, la Test Suite mostra i messaggi di errore per ogni caso di test non riuscito che indicano il motivo dell'errore.
Per il primo caso di test non riuscito sopra,
il messaggio di errore indica che la Test Suite prevede "isPause": true negli stati segnalati dall'integrazione da cloud a cloud, ma gli stati effettivi includono solo "isPause": false.
Inoltre, il messaggio di errore del secondo caso di test non riuscito indica che gli stati nella risposta QUERY dell'integrazione da cloud a cloud includono "isPause": true, che è diverso da "isPause": false negli stati segnalati dall'integrazione da cloud a cloud:
In base a entrambi i messaggi di errore, devi verificare se l'integrazione segnala lo stato isPaused con il valore corretto.
Identifica la causa principale dell'errore
Apri functions/index.js, che contiene la funzione reportstate che pubblica le modifiche dello stato in Home Graph utilizzando Report State. Esamina il payload di Report State e vedrai che manca lo stato isPaused, che è esattamente ciò che la Test Suite ha verificato nei casi di test non riusciti.
index.js
exports.reportstate = functions.database.ref('{deviceId}').onWrite(
async (change, context) => {
...
const requestBody = {
requestId: 'ff36a3cc', /* Any unique ID */
agentUserId: USER_ID,
payload: {
devices: {
states: {
/* Report the current state of our washer */
[context.params.deviceId]: {
online: snapshot.online,
on: snapshot.OnOff.on,
isRunning: snapshot.StartStop.isRunning,
currentRunCycle: [{
currentCycle: 'rinse',
nextCycle: 'spin',
lang: 'en',
}],
currentTotalRemainingTime: 1212,
currentCycleRemainingTime: 301,
},
},
},
},
};
const res = await homegraph.devices.reportStateAndNotification({
requestBody,
});
...
});
Correggi l'errore
Ora che hai identificato la causa principale dell'errore, rivedi functions/index.js aggiungendo lo stato isPaused al payload di Report State:
index.js
exports.reportstate = functions.database.ref('{deviceId}').onWrite(
async (change, context) => {
...
const requestBody = {
requestId: 'ff36a3cc', /* Any unique ID */
agentUserId: USER_ID,
payload: {
devices: {
states: {
/* Report the current state of our washer */
[context.params.deviceId]: {
online: snapshot.online,
on: snapshot.OnOff.on,
isPaused: snapshot.StartStop.isPaused,
isRunning: snapshot.StartStop.isRunning,
currentRunCycle: [{
currentCycle: 'rinse',
nextCycle: 'spin',
lang: 'en',
}],
currentTotalRemainingTime: 1212,
currentCycleRemainingTime: 301,
},
},
},
},
};
...
});
Verifica la correzione
Esegui il deployment del codice aggiornato utilizzando l'interfaccia a riga di comando di Firebase:
$ firebase deploy --only functions
Esegui di nuovo la Test Suite per la smart home e vedrai che tutti i casi di test sono stati superati.
5. Complimenti
Complimenti! Hai imparato a risolvere i problemi di integrazione da cloud a cloud utilizzando la Test Suite per la smart home e le metriche e il logging di GCP.
Scopri di più
Partendo da questo codelab, prova i seguenti esercizi ed esplora le risorse aggiuntive:
- Aggiungi altre caratteristiche supportate al dispositivo e testale con la Test Suite.
- Crea dashboard, configura avvisi e accedi ai dati delle metriche a livello di programmazione per ottenere metriche di utilizzo utili sulla tua integrazione.
- Esplora il fulfillment locale per la smart home.
- Dai un'occhiata al nostro esempio GitHub per saperne di più.
Puoi anche scoprire di più su come testare e inviare un'integrazione per la revisione, inclusa la procedura di certificazione per pubblicare l'integrazione per gli utenti.