Report State è una funzionalità importante che consente all'azione
Home di segnalare in modo proattivo lo stato più recente del
dispositivo dell'utente a
Google Home Graph
rather than waiting for a
QUERY
intent.
Report State segnala a Google gli stati dei dispositivi utente
a cui è associato il valore agentUserId
specificato (inviato nella richiesta originale
SYNC
). Quando
Google Assistant
wants to take an action
that requires understanding the current state of a device, it can simply look
up the state information in the
Home Graph instead
of issuing a QUERY
intent to various third-party clouds prior to issuing the
EXECUTE
intent.
Senza
Report State, date le luci di più provider in
un salotto, il comando Ok Google, illumina il mio salotto richiede
la risoluzione di più intent QUERY
inviati a più cloud, anziché cercare
i valori di luminosità attuali in base a quanto precedentemente riportato. Per un'esperienza utente ottimale,
Assistant deve avere lo stato attuale di un dispositivo,
senza richiedere un round trip.
In seguito all'SYNC
iniziale per un dispositivo, la piattaforma invia un intent QUERY
che raccoglie lo stato del dispositivo per completare
Home Graph.
Successivamente,
Home Graph archivia solo lo stato inviato
a Report State.
Quando chiami
Report State, assicurati di fornire dati
statali per una data caratteristica.
Home Graph aggiorna gli stati per singola caratteristica e sovrascrive tutti i dati per quella caratteristica quando viene effettuata una chiamata Report State. Ad esempio, se stai segnalando lo stato per la caratteristica StartStop, il payload deve includere valori sia per isRunning
che per isPaused
.
Inizia
Per implementare Report State, segui questi passaggi:
Abilita l'API Google HomeGraph
-
In Google Cloud Console , go to the HomeGraph API page.
Vai alla pagina dell'API HomeGraph - Seleziona il progetto che corrisponde alla tua smart home project ID.
- Fai clic su ABILITA.
Crea una chiave dell'account di servizio
Segui queste istruzioni per generare una chiave dell'account di servizio da Google Cloud Console:
-
In Google Cloud Console, vai alla pagina Crea chiave account di servizio.
Vai alla pagina Crea chiave account di servizio - Nell'elenco Account di servizio, seleziona Nuovo account di servizio.
- Inserisci un nome nel campo Service account name (Nome account di servizio).
- Inserisci un ID nel campo ID account di servizio.
Dall'elenco Role (Ruolo), seleziona Service Accounts (Account di servizio) > Service Account Token Creator (Creatore token account di servizio).
In Tipo di chiave, seleziona l'opzione JSON.
- Fai clic su Crea. Un file JSON contenente la chiave che viene scaricata sul computer.
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 JSON Web Token (JWT). Per maggiori informazioni, consulta la pagina Autenticazione con un 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
agentUserId
. Ecco una richiesta JSON di esempio per lo stato e la notifica del report: - Combina lo stato del report, la notifica JSON e il token nella richiesta HTTP POST all'endpoint di Google Home Graph. Ecco un esempio di come eseguire la richiesta dalla 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 dei buffer di protocollo per l'API Home Graph.
- Segui la documentazione per gli sviluppatori gRPC per generare stub client per uno dei lingue supportati.
- 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 le credenziali predefinite dell'applicazione. - Chiama il metodo
reportStateAndNotification
con ReportStateAndNotificationRequest. RestituiscePromise
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.
- Inizializzare
HomeGraphApiService
utilizzando le credenziali predefinite dell'applicazione. - Chiama il metodo
reportStateAndNotification
conReportStateAndNotificationRequest
. 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 del report di test
Per preparare la tua azione alla certificazione, è importante testare Report State.
Per fare ciò, ti consigliamo di utilizzare lo strumento Home Graph Visualizzatore, un'app web autonoma che non richiede il download o il deployment.
La dashboard di Report State è ancora disponibile, ma è deprecata e non è più supportata.
Segnala stato
Prerequisiti
Prima di poter testare la tua azione, devi avere la chiave dell'account di servizio e il tuo agentUserId
. Se hai già la chiave dell'account di servizio e
agentUserId
consulta Esegui il deployment della
Report State
dashboard.
Esegui il deployment della dashboard dello stato del report
Dopo aver ottenuto la chiave dell'account di servizio e l'ID utente agente per il progetto, scarica ed esegui il deployment della versione più recente dalla dashboard di Report State.
Una volta scaricata l'ultima versione, segui le istruzioni del 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, procedi nel seguente modo:
- Scegli il file della chiave dell'account
- Aggiungi il tuo user agent
Poi, fai clic su Elenco.
Sono elencati tutti i tuoi dispositivi. Una volta compilato l'elenco, puoi utilizzare il pulsante Aggiorna per aggiornare gli stati del dispositivo. In caso di cambiamento dello stato del dispositivo, la riga viene evidenziata in verde.
Risposte di errore
Quando chiami, potresti ricevere una delle seguenti risposte di errore Report State. Queste risposte si presentano 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 JSON non valido o utilizzandonull
invece di "" per un valore stringa.404 Not Found
: non è stato possibile trovare la risorsa richiesta, ma potrebbe essere disponibile in futuro. In genere questo 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 gestisci correttamente gli intent DISCONNECT.