Willkommen beim Google Home Developer Center, der neuen Anlaufstelle für Smart-Home-Aktionen. Hinweis:Sie erstellen weiterhin Aktionen in der Actions Console.

Berichtstatus

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Die Seite

Report State ist eine wichtige Funktion, mit der die Aktion Home den aktuellen Status des Nutzergeräts proaktiv an Google Home Graph rather than waiting for a QUERY intent. melden kann

Report State meldet Google den Status der Nutzergeräte mit den entsprechenden agentUserId (die in der ursprünglichen SYNC-Anfrage gesendet wurden). Wenn 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.

Ohne Report State ist es aufgrund der Beleuchtung von mehreren Anbietern in einem Wohnzimmer erforderlich, den Befehl Ok Google, heller mein Wohnzimmer zu machen, mehrere QUERY-Intents aufzulösen, die an mehrere Clouds gesendet werden, anstatt einfach die aktuellen Helligkeitswerte anhand der zuvor gemeldeten Daten zu ermitteln. Für eine optimale Nutzerfreundlichkeit muss Assistant den aktuellen Status eines Geräts haben, ohne dass ein Umlauf zum Gerät erforderlich ist.

Nach dem anfänglichen SYNC für ein Gerät sendet die Plattform einen QUERY-Intent, der den Status des Geräts erfasst, um Home Graph auszufüllen. Nach diesem Zeitpunkt speichert Home Graph nur den Status, der mit Report State gesendet wurde.

Achten Sie beim Aufrufen von Report State darauf, vollständige Statusdaten für ein bestimmtes Merkmal anzugeben. Home Graph aktualisiert den Status pro Merkmal und überschreibt alle Daten für diesen Merkmal, wenn ein Report State-Aufruf erfolgt. Wenn Sie beispielsweise den Status des Attributs StartStop melden, muss die Nutzlast Werte für isRunning und isPaused enthalten.

Erste Schritte

So implementieren Sie Report State:

Google HomeGraph API aktivieren

  1. Im Google Cloud Console , go to the HomeGraph API page.

    Zur Seite der HomeGraph API
  2. Wählen Sie das Projekt aus, das smart home project ID. entspricht
  3. Klicken Sie auf AKTIVIEREN.

Dienstkontoschlüssel erstellen

Folgen Sie dieser Anleitung, um einen Dienstkontoschlüssel aus Google Cloud Console zu generieren:

Hinweis: Achten Sie darauf, dass Sie bei diesen Schritten das richtige GCP-Projekt verwenden. Dies ist das Projekt, das Ihrer Projekt-ID smart home entspricht.
  1. Rufen Sie in der Google Cloud Console die Seite Dienstkontoschlüssel erstellen auf.

    Zur Seite Dienstkontoschlüssel erstellen
  2. Wählen Sie in der Liste Dienstkonto die Option Neues Dienstkonto aus.
  3. Geben Sie im Feld Dienstkontoname einen Namen ein.
  4. Geben Sie in das Feld Dienstkonto-ID eine ID ein.
  5. Wählen Sie in der Liste Rolle die Option Dienstkonten > Ersteller von Dienstkonto-Tokens aus.

  6. Wählen Sie für Schlüsseltyp die Option JSON aus.

  7. Klicken Sie auf Erstellen. Eine JSON-Datei mit Ihrem Schlüssel wird auf Ihren Computer heruntergeladen.

API aufrufen

Wählen Sie eine der folgenden Optionen aus:

HTTP

Home Graph bietet einen HTTP-Endpunkt.

  1. Verwenden Sie die heruntergeladene JSON-Datei des Dienstkontos, um ein JSON Web Token (JWT) zu erstellen. Weitere Informationen finden Sie unter Authentifizierung mit einem Dienstkonto.
  2. Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken mit dem Bereich https://www.googleapis.com/auth/homegraph ab:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Erstellen Sie die JSON-Anfrage mit agentUserId. Hier ist ein Beispiel für eine JSON-Anfrage für den Berichtstatus und die Benachrichtigung:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Kombiniere den Berichtsstatus und die JSON-Benachrichtigungen mit dem Token in deiner HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Hier siehst du ein Beispiel dafür, wie du die Anfrage in der Befehlszeile mit curl testest:
  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 bietet einen gRPC-Endpunkt.

  1. Rufen Sie die Servicedefinition des Protokollpuffers für die Home Graph API ab.
  2. Folgen Sie der gRPC-Entwicklerdokumentation, um Client-Stubs für eine der unterstützten Sprachen zu generieren.
  3. Rufen Sie die Methode ReportStateAndNotification auf.

Node.js

Der Google APIs-Node.js-Client bietet Bindungen für die Home Graph API.

  1. Initialisieren Sie den Dienst google.homegraph mit Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Es wird ein Promise mit der ReportStateAndNotificationResponse zurückgegeben.
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

Die HomeGraph API-Clientbibliothek für Java enthält Bindungen für die Home Graph API.

  1. Initialisieren Sie die HomeGraphApiService mit Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Es wird ein ReportStateAndNotificationResponse zurückgegeben.
  // 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);
}
    

Status des Testberichts

Empfohlene Tools für diese Aufgabe

Damit Sie Ihre Aktion auf die Zertifizierung vorbereiten können, sollten Sie unbedingt Report State testen.

Dazu empfehlen wir das Home Graph-Viewer-Tool. Dies ist eine eigenständige Webanwendung, die nicht heruntergeladen oder bereitgestellt werden muss.

Das Report State-Dashboard ist weiterhin verfügbar, wurde jedoch eingestellt und wird nicht mehr unterstützt.

Berichtstatus-Dashboard

Voraussetzungen

Bevor Sie die Aktion testen können, benötigen Sie Ihren Dienstkontoschlüssel und Ihre agentUserId. Wenn Sie bereits einen Dienstkontoschlüssel und agentUserId haben, finden Sie weitere Informationen unter Dashboard auf Report State bereitstellen.

Dashboard „Berichtsstatus“ bereitstellen

Nachdem Sie den Dienstkontoschlüssel und die Agent-Nutzer-ID für Ihr Projekt erhalten haben, laden Sie die neueste Version vom Dashboard Report State herunter und stellen Sie sie bereit. Nachdem Sie die neueste Version heruntergeladen haben, folgen Sie der Anleitung in der enthaltenen Datei README.MD.

Nachdem Sie das Dashboard Report State bereitgestellt haben, können Sie über die folgende URL auf das Dashboard zugreifen (ersetzen Sie your_project_id durch Ihre Projekt-ID):

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

Gehen Sie im Dashboard so vor:

  • Datei für Kontoschlüssel auswählen
  • AgentUserID hinzufügen

Klicken Sie dann auf Liste.

Alle Ihre Geräte sind aufgelistet. Sobald die Liste ausgefüllt ist, können Sie die Schaltfläche Aktualisieren verwenden, um den Gerätestatus zu aktualisieren. Bei einer Gerätestatusänderung wird die Zeile grün hervorgehoben.

Fehlermeldungen

Wenn Sie Report State aufrufen, erhalten Sie möglicherweise eine der folgenden Fehlermeldungen. Diese Antworten werden als HTTP-Statuscodes ausgegeben.

  • 400 Bad Request: Der Server konnte die vom Client aufgrund einer ungültigen Syntax gesendete Anfrage nicht verarbeiten. Häufige Ursachen sind fehlerhaftes JSON-Format oder die Verwendung von null anstelle von „“ für einen Stringwert.
  • 404 Not Found: Die angeforderte Ressource wurde nicht gefunden, ist aber möglicherweise in Zukunft verfügbar. In der Regel können wir das angeforderte Gerät nicht finden. Es kann auch sein, dass das Nutzerkonto nicht mit Google verknüpft ist oder wir eine ungültige agentUserId erhalten haben. Achten Sie darauf, dass agentUserId mit dem Wert in Ihrer SYNC-Antwort übereinstimmt und Sie DISCONNECT-Intents ordnungsgemäß verarbeiten.