Stato rapporto

Report State è una funzionalità importante che consente all'Home Action di segnalare in modo proattivo lo stato più recente del dispositivo dell'utente a Google Home Graph anziché attendere un intento QUERY.

Report State segnala a Google gli stati dei dispositivi degli utenti con il agentUserId specificato associato (inviato nella richiesta SYNC originale). Quando Google Assistant vuole intraprendere un'azione che richiede la comprensione dello 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, se in un soggiorno sono presenti luci di più fornitori, il comando Hey Google, alza la luminosità del soggiorno richiede la risoluzione di più intent QUERY inviati a più cloud, anziché semplicemente cercare i valori di luminosità attuali in base a quanto registrato in precedenza. Per un'esperienza utente ottimale,Assistant deve avere lo stato corrente di un dispositivo, senza richiedere un viaggio di andata e ritorno al dispositivo.

Dopo il messaggio SYNC iniziale per un dispositivo, la piattaforma invia un'intenzione QUERY che raccoglie lo stato del dispositivo per compilare Home Graph. Dopodiché, Home Graph memorizza solo lo stato inviato con Report State.

Quando chiami Report State, assicurati di fornire dati completi dello stato per un determinato tratto. Home Graph aggiorna gli stati su base alle caratteristiche e sovrascrive tutti i dati relativi a quella caratteristica quando viene eseguita una chiamata Report State. Ad esempio, se stai registrando lo stato per l'attributo StartStop, il payload deve includere i valori sia per isRunning sia per isPaused.

Inizia

Per implementare Report State:

Attiva l'API Google HomeGraph

  1. In Google Cloud Console, vai alla pagina API HomeGraph.

    Vai alla pagina dell'API HomeGraph
  2. Seleziona il progetto che corrisponde al tuo ID progetto smart home.
  3. Fai clic su ABILITA.

Creare una chiave dell'account di servizio

Segui queste istruzioni per generare una chiave dell'account di servizio da Google Cloud Console:

Nota: assicurati di utilizzare il progetto Google Cloud corretto quando esegui questi passaggi. Questo è il progetto che corrisponde al tuo ID progetto smart home.
  1. In Google Cloud Console, vai alla pagina Crea chiave account di servizio.

    Vai alla pagina Crea chiave dell'account di servizio
  2. Nell'elenco Account di servizio, seleziona Nuovo account di servizio.
  3. Inserisci un nome nel campo Nome account di servizio.
  4. Nel campo ID account di servizio, inserisci un ID.
  5. Nell'elenco Ruolo, seleziona Account di servizio > Creatore token account di servizio.

  6. In Tipo di chiave, seleziona l'opzione JSON.

  7. 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

  1. Utilizza il file JSON dell'account di servizio scaricato per creare un token web JSON (JWT). Per maggiori informazioni, consulta Autenticazione tramite un account di servizio.
  2. Ottieni un token di accesso OAuth 2.0 con l'ambito https://www.googleapis.com/auth/homegraph utilizzando oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Crea la richiesta JSON con agentUserId. Ecco una richiesta JSON di esempio per lo stato del report e la notifica:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
  6. Combina lo stato del report e il JSON della notifica e il token nella richiesta HTTP POST all'endpoint del grafo di Google Home. Ecco un esempio di come effettuare la richiesta nella riga di comando utilizzando curl, come test:
  7. 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

  1. Ottieni la definizione del servizio Protocol Buffers per l'API Home Graph.
  2. Segui la documentazione per gli sviluppatori di gRPC per generare stub di client per una delle lingue supportate.
  3. Chiama il metodo ReportStateAndNotification.

Node.js

Il client Node.js per le API di Google fornisce associazioni per l'API Home Graph.

  1. Inizializza il servizio google.homegraph utilizzando Credenziali predefinite dell'applicazione.
  2. Chiama il metodo reportStateAndNotification con ReportStateAndNotificationRequest. Restituisce un valore Promise 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 HomeGraph.

  1. Inizializza HomeGraphApiService utilizzando le Credenziali predefinite dell'applicazione.
  2. Chiama il metodo reportStateAndNotification con ReportStateAndNotificationRequest. Restituisce un ReportStateAndNotificationResponse.
  // 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 del test

Strumenti consigliati per questa attività

Per preparare l'azione alla certificazione, è importante eseguire il testReport State.

Per farlo, 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 è stata ritirata e non è più supportata.

Dashboard Stato report

Prerequisiti

Prima di poter testare l'azione, devi disporre della chiave dell'account servizio e di agentUserId. Se hai già la chiave dell'account di servizio eagentUserId consulta Eseguire il deployment della dashboard Report State.

Eseguire il deployment della dashboard dello stato del report

Dopo aver ottenuto la chiave dell'account di servizio e l'ID utente dell'agente per il tuo progetto, scarica e esegui il deployment della versione più recente dalla dashboard Report State. Una volta scaricata la versione più recente, segui le istruzioni riportate nel file README.MD incluso.

Dopo aver eseguito il deployment della dashboard Report State, accedi alla dashboard dal seguente URL (sostituisci your_project_id con l'ID del tuo progetto):

http://<your-project-id>.appspot.com

Nella dashboard, procedi nel seguente modo:

  • Scegli il file della chiave dell'account
  • Aggiungi il tuo agentUserId

Quindi, fai clic su Elenco.

Tutti i tuoi dispositivi sono elencati. Una volta che l'elenco è compilato, puoi utilizzare il pulsante Aggiorna per aggiornare gli stati del dispositivo. Se si verifica una modifica dello stato del dispositivo, la riga viene evidenziata in verde.

Risposte di errore

Quando chiami Report State, potresti ricevere una delle seguenti risposte di errore. Queste risposte si presentano sotto forma di codici di stato HTTP.

  • 400 Bad Request - Il server non è stato in grado di elaborare la richiesta inviata dal client a causa di una sintassi non valida. Le cause comuni includono JSON non valido o l'utilizzo di null anziché "" per un valore di stringa.
  • 404 Not Found - La risorsa richiesta non è stata trovata, ma potrebbe essere disponibile in futuro. In genere, significa che non possiamo trovare il dispositivo richiesto. Potrebbe anche significare che l'account utente non è collegato a Google o che abbiamo ricevuto un agentUserId non valido. Assicurati che agentUserId corrisponda al valore fornito nella risposta SYNC e gestisci correttamente gli intent DISCONNECT.