Ti diamo il benvenuto nel Centro sviluppatori Google Home, la nuova destinazione per scoprire come sviluppare azioni per la smart home. Nota: continuerai a creare azioni nella console di Actions.

Stato rapporto

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 anziché attendere un'intenzione di QUERY.

Report State segnala a Google gli stati dei dispositivi utente con l'oggetto agentUserId specificato associato (inviato nella richiesta originale SYNC). Quando Google Assistant vuole compiere un'azione che richiede la comprensione dello stato attuale di un dispositivo, può semplicemente cercare le informazioni sullo stato in Home Graph invece di emettere un intent QUERY a vari cloud di terze parti prima di emettere l'intent EXECUTE.

Senza Report State, date le luci di più fornitori in un salotto, il comando Ok Google, illumina il mio salotto richiede la risoluzione di più intent QUERY inviati a più cloud, anziché cercare semplicemente i valori di luminosità attuali in base a quanto riportato in precedenza. Per offrire un'esperienza utente ottimale, Assistant deve avere lo stato attuale di un dispositivo, senza bisogno di un round trip.

Dopo l'iniziale SYNC per un dispositivo, la piattaforma invia un intent QUERY che raccoglie lo stato del dispositivo per completare Home Graph. Dopodiché, Home Graph archivia solo lo stato inviato a Report State.

Quando chiami Report State, assicurati di fornire dati completi sullo stato di un determinato tratto. Home Graph aggiorna gli stati per ogni singola caratteristica e sovrascrive tutti i dati relativi a questa caratteristica quando viene effettuata una chiamata Report State. Ad esempio, se vuoi segnalare lo stato del tratto StartStop, il payload deve includere i valori di isRunning e isPaused.

Inizia

Per implementare Report State, segui questi passaggi:

Abilita l'API Google HomeGraph

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

    Vai alla pagina API HomeGraph
  2. Seleziona il progetto che corrisponde al tuo ID progetto smart home.
  3. 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:

Nota: assicurati di utilizzare il progetto GCP 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 account di servizio
  2. Dall'elenco Account di servizio, seleziona Nuovo account di servizio.
  3. Nel campo Nome account di servizio, inserisci un nome.
  4. Inserisci un ID nel campo ID account di servizio.
  5. Dall'elenco Ruolo, seleziona Account di servizio > Creatore token account di servizio.

  6. Per il tipo di chiave, seleziona l'opzione JSON.

  7. Fai clic su Crea. Un file JSON contenente la chiave viene scaricato sul computer.

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 la pagina relativa all' 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 un esempio di richiesta JSON 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 dei report e delle notifiche JSON e il token nella richiesta HTTP POST con l'endpoint del grafico Google Home. Di seguito è riportato un esempio di come eseguire 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 di buffer di protocollo per l'API Home Graph.
  2. Segui la documentazione per gli sviluppatori gRPC per generare stub client per uno dei lingue supportati.
  3. Chiama il metodo ReportStateAndNotification.

Node.js

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

  1. Inizializzare il servizio google.homegraph utilizzando le credenziali predefinite dell'applicazione.
  2. Richiama il metodo reportStateAndNotification con ReportStateAndNotificationRequest. Restituisce 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 Home Graph.

  1. Inizializzare HomeGraphApiService utilizzando le credenziali predefinite dell'applicazione.
  2. Richiama il metodo reportStateAndNotification con il ReportStateAndNotificationRequest. Restituisce 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 di test

Strumenti consigliati per questa attività

Per preparare l'azione per la certificazione, è importante testare Report State.

Per eseguire questa operazione, consigliamo di utilizzare lo strumento Visualizzatore Home Graph, che è un'app web autonoma che non richiede download o deployment.

La dashboard Report State è ancora disponibile, ma è deprecata e non è più supportata.

Dashboard dello stato dei report

Prerequisiti

Per poter testare l'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 Deployment della dashboard Report State.

Esegui il deployment della dashboard dello stato dei report

Quando disponi della chiave dell'account di servizio e dell'ID utente dell'agente per il progetto, scarica ed esegui il deployment della versione più recente dalla Report Statedashboard. Una volta scaricata la versione più recente, 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

Quindi, fai clic su Elenco.

Sono elencati tutti i tuoi dispositivi. Una volta completato l'elenco, puoi utilizzare il pulsante Aggiorna per aggiornare gli stati del dispositivo. Se lo stato del dispositivo cambia, la riga viene evidenziata in verde.

Risposte di errore

Potresti ricevere una delle seguenti risposte di errore quando chiami 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 un JSON non valido o l'uso di null anziché "" per un valore stringa.
  • 404 Not Found: non è stato possibile trovare la risorsa richiesta, ma potrebbe essere disponibile in futuro. Ciò significa che non riusciamo a 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 di gestire correttamente gli intent DISCONNECT.