Report State è una funzionalità importante che consente all'Azione Home di segnalare in modo proattivo lo stato più recente del dispositivo dell'utente su Google Home Graph, anziché attendere un intent QUERY
.
Report State segnala a Google gli stati dei dispositivi degli utenti
a cui sono associati agentUserId
specificati (inviati nella richiesta
SYNC
originale). Quando Google Assistant vuole intraprendere un'azione
che richiede di comprendere lo stato attuale di un dispositivo, può semplicemente cercare
le informazioni sullo stato in Home Graph anziché
inviare un intent QUERY
a vari cloud di terze parti prima di inviare l'intent
EXECUTE
.
Senza Report State, date le luci di diversi fornitori in un salotto, il comando Hey Google, illumina il mio salotto richiede la risoluzione di diversi intent QUERY
inviati a più cloud, anziché la semplice ricerca dei valori di luminosità attuali in base a quanto segnalato in precedenza. Per un'esperienza utente ottimale, Assistant deve avere lo stato attuale del dispositivo, senza richiedere un round trip.
Dopo il SYNC
iniziale per un dispositivo, la piattaforma invia un intent QUERY
che raccoglie lo stato del dispositivo per completare Home Graph.
Dopodiché, Home Graph memorizza solo lo stato inviato con Report State.
Quando chiami Report State, assicurati di fornire dati completi sullo stato per un determinato trait. Home Graph aggiorna gli stati in base alle singole trait e sovrascrive tutti i dati per quel trait quando viene effettuata una chiamata Report State. Ad esempio, se segnali lo stato per il trait StartStop, il payload deve includere i valori sia per isRunning
sia per isPaused
.
Inizia
Per implementare Report State, segui questi passaggi:
Attiva l'API Google HomeGraph
-
In Google Cloud Console, vai alla pagina dell'API HomeGraph.
Vai alla pagina dell'API HomeGraph - Seleziona il progetto che corrisponde al tuo ID progetto smart home.
- Fai clic su ABILITA.
Crea una chiave dell'account di servizio
Segui queste istruzioni per generare una chiave dell'account di servizio dal Google Cloud Console:
-
In Google Cloud Console, vai alla pagina Crea chiave account di servizio.
Vai alla pagina Crea chiave account di servizio - Dall'elenco Account di servizio, seleziona Nuovo account di servizio.
- Inserisci un nome nel campo Nome account di servizio.
- Inserisci un ID nel campo ID account di servizio.
Nell'elenco Ruolo, seleziona Account di servizio > Creatore token account di servizio.
In Tipo di chiave, seleziona l'opzione JSON.
- Fai clic su Crea. Sul computer viene scaricato un file JSON contenente la chiave.
Chiama l'API
Seleziona un'opzione dalle schede seguenti:
HTTP
Home Graph fornisce un endpoint HTTP
- Utilizza il file JSON dell'account di servizio scaricato per creare un token JWT (JSON Web Token). Per maggiori informazioni, consulta la pagina relativa all' autenticazione tramite account di servizio.
- Ottieni un token di accesso OAuth 2.0 con l'ambito
https://www.googleapis.com/auth/homegraph
utilizzando oauth2l: - Crea la richiesta JSON con l'elemento
agentUserId
. Ecco un esempio di richiesta JSON per lo stato del report e la notifica: - Combina i valori JSON della notifica e dello stato del report e il token nella richiesta HTTP POST
all'endpoint di Google Home Graph. Ecco un esempio di come effettuare la richiesta nella riga di comando utilizzando
curl
, come test:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
gRPC
Home Graph fornisce un endpoint gRPC
- Recupera la definizione del servizio di buffer di protocollo per l'API Home Graph.
- Segui la documentazione per gli sviluppatori gRPC per generare stub client per una delle lingue supportate.
- Chiama il metodo ReportStateAndNotification.
Node.js
Il client Node.js delle API di Google fornisce associazioni per l'API Home Graph.
- Inizializza il servizio
google.homegraph
utilizzando Credenziali predefinite dell'applicazione. - Chiama il metodo
reportStateAndNotification
con ReportStateAndNotificationRequest. Restituisce un valorePromise
con ReportStateAndNotificationResponse.
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.reportStateAndNotification({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { states: { "PLACEHOLDER-DEVICE-ID": { on: true } } } } } });
Java
La libreria client dell'API HomeGraph per Java fornisce associazioni per l'API Home Graph.
- Inizializza
HomeGraphApiService
utilizzando Credenziali predefinite dell'applicazione. - Chiama il metodo
reportStateAndNotification
con ilReportStateAndNotificationRequest
. Restituisce unReportStateAndNotificationResponse
.
// Get Application Default credentials. GoogleCredentials credentials = GoogleCredentials.getApplicationDefault() .createScoped(List.of("https://www.googleapis.com/auth/homegraph")); // Create Home Graph service client. HomeGraphService homegraphService = new HomeGraphService.Builder( GoogleNetHttpTransport.newTrustedTransport(), GsonFactory.getDefaultInstance(), new HttpCredentialsAdapter(credentials)) .setApplicationName("HomeGraphExample/1.0") .build(); // Build device state payload. Map<?, ?> states = Map.of("on", true); // Report device state. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states)))); homegraphService.devices().reportStateAndNotification(request); }
Stato report di test
Per preparare la tua azione alla certificazione, è importante testare Report State.
A questo scopo, ti consigliamo di utilizzare lo strumento Visualizzatore Home Graph, un'app web autonoma che non richiede download o deployment.
La dashboard Report State è ancora disponibile, ma è ritirata e non più supportata.
Dashboard dello stato del report
Prerequisiti
Per poter testare l'azione, devi avere la chiave dell'account di servizio e agentUserId
. Se disponi già della chiave dell'account di servizio e
agentUserId
consulta l'articolo sul deployment della Report State
dashboard.
Esegui il deployment della dashboard dello stato dei report
Quando disponi della chiave dell'account di servizio e dello User-ID dell'agente per il progetto, scarica ed esegui il deployment della versione più recente dalla dashboard di Report State.
Una volta scaricata la versione più recente, segui le istruzioni dal file README.MD
incluso.
Dopo aver eseguito il deployment della dashboard Report State, accedi alla dashboard dal seguente URL (sostituisci your_project_id con il tuo ID progetto):
http://<your-project-id>.appspot.com
Nella dashboard, segui questi passaggi:
- Scegli il file della chiave dell'account
- Aggiungi il tuo agentUserId
Poi, fai clic su Elenco.
Sono elencati tutti i tuoi dispositivi. Una volta completato l'elenco, puoi utilizzare il pulsante Aggiorna per aggiornare gli stati dei dispositivi. In caso di modifica dello stato del dispositivo, la riga è evidenziata in verde.
Risposte di errore
Durante la chiamata a Report State potresti ricevere una delle seguenti risposte di errore. Queste risposte vengono presentate sotto forma di codici di stato HTTP.
400 Bad Request
: il server non è riuscito a elaborare la richiesta inviata dal client a causa di una sintassi non valida. Le cause comuni includono un JSON non corretto o l'utilizzo dinull
anziché "" per un valore stringa.404 Not Found
- Impossibile trovare la risorsa richiesta, ma potrebbe essere disponibile in futuro. In genere, significa che non riusciamo a trovare il dispositivo richiesto. Potrebbe anche significare che l'account utente non è collegato a Google o che abbiamo ricevuto unagentUserId
non valido. Assicurati cheagentUserId
corrisponda al valore fornito nella risposta SYNC e di gestire correttamente gli intent DISCONNECT.