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.
Aktiviere die Option

Der Berichtsstatus ist eine wichtige Funktion, mit der die Smart-Home-Aktion proaktiv den neuesten Status des Nutzergeräts an den Google Home Graph von Google melden kann, anstatt auf den Intent QUERY zu warten.

Melde den Status von Google-Nutzergeräten mit der angegebenen agentUserId, die in der ursprünglichen SYNC-Anfrage gesendet wurde. Wenn Google Assistant eine Aktion durchführen möchte, für die der aktuelle Status eines Geräts erforderlich ist, kann er einfach die Statusinformationen im Home Graph nachschlagen, anstatt einen QUERY-Intent an verschiedene Drittanbieter-Clouds zu senden, bevor der Intent EXECUTE ausgegeben wird.

Wenn kein Status angegeben ist und ein Licht von mehreren Anbietern in einem Wohnzimmer vorkommt, erfordert der Befehl Ok Google, erhöhe mein Wohnzimmer, dass mehrere QUERY-Intents aufgelöst werden müssen, die an mehrere Clouds gesendet werden. Die aktuellen Helligkeitswerte müssen dann nicht mehr anhand der zuvor gemeldeten Werte ermittelt werden. Für eine optimale Nutzerfreundlichkeit muss Google Assistant den aktuellen Status eines Geräts abrufen, ohne dass ein Umlauf an das Gerät erfolgen muss.

Nach dem ersten SYNC für ein Gerät sendet die Plattform einen QUERY-Intent, der den Status des Geräts erfasst, um Home Graph zu füllen. Danach wird in Home Graph nur der Status gespeichert, der mit dem Berichtstatus gesendet wird.

Achten Sie beim Aufrufen des Berichtstatus darauf, vollständige Statusdaten für ein bestimmtes Merkmal anzugeben. Home Graph aktualisiert den Zustand pro Merkmal und überschreibt alle Daten für diesen Merkmal bei einem Berichtstatusaufruf. Wenn Sie beispielsweise einen Berichtsstatus für die Eigenschaft StartStop melden, muss die Nutzlast Werte für isRunning und isPaused enthalten.

Erste Schritte

So implementieren Sie den Berichtsstatus:

Google HomeGraph API aktivieren

  1. Rufen Sie in der Google Cloud Platform Console die Seite HomeGraph API auf.

    Zur Seite „HomeGraph API“
  2. Wählen Sie das Projekt aus, das Ihrer Smart-Home-Projekt-ID entspricht.
  3. Klicken Sie auf AKTIVIEREN.

Dienstkontoschlüssel erstellen

So generieren Sie einen Dienstkontoschlüssel über die GCP Console:

Hinweis: Achten Sie darauf, dass Sie bei diesen Schritten das richtige GCP-Projekt verwenden. Dies ist das Projekt, das Ihrer Smart-Home-Projekt-ID entspricht.
  1. Wechseln Sie in der GCP Console zur Seite Dienstkontoschlüssel erstellen.

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

Die Home Graph API bietet einen HTTP-Endpunkt

  1. Verwenden Sie die heruntergeladene JSON-Datei mit dem Dienstkonto, 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 sehen Sie eine JSON-Beispielanfrage für den Berichtstatus und die Benachrichtigung:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Kombinieren Sie den JSON-Status für Berichte und Benachrichtigungen mit dem Token in Ihrer HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Hier siehst du ein Beispiel dafür, wie du die Anfrage zu Testzwecken in der Befehlszeile mit curl erstellst:
  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

Die Home Graph API bietet einen gRPC-Endpunkt

  1. Rufen Sie die Dienstdefinition von Protokollpuffern 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 Node.js-Client der Google APIs bietet Bindungen für die Home Graph API.

  1. Initialisieren Sie den google.homegraph-Dienst mit den Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode reportStateAndNotification mit ReportStateAndNotificationRequest auf. Sie gibt ein Promise mit der ReportStateAndNotificationResponse zurück.
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 bietet Bindungen für die Home Graph API.

  1. Initialisieren Sie den HomeGraphApiService mithilfe von 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

Damit deine Aktion auf die Zertifizierung vorbereitet werden kann, ist es wichtig, den Berichtstatus zu testen.

Voraussetzungen

Bevor Sie Ihre Aktion testen können, benötigen Sie Ihren Dienstkontoschlüssel und Ihre agentUserId. Wenn Sie Ihren Dienstkontoschlüssel bereits haben und agentUserId siehe Dashboard für Berichtsstatus bereitstellen.

Dashboard „Berichtsstatus“ bereitstellen

Nachdem Sie den Dienstkontoschlüssel und die agentUserId für Ihr Projekt erhalten haben, laden Sie die neueste Version aus dem Dashboard „Berichtsstatus“ herunter und stellen Sie sie bereit. Nachdem Sie die neueste Version heruntergeladen haben, folgen Sie der Anleitung aus der enthaltenen README.MD-Datei.

Nachdem Sie das Dashboard für den Berichtsstatus bereitgestellt haben, können Sie über die folgende URL auf das Dashboard zugreifen. Ersetzen Sie dabei your_project_id durch Ihre Projekt-ID:

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

Führen Sie auf dem Dashboard folgende Schritte aus:

  • Kontoschlüsseldatei 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 Geräte mit der Schaltfläche Aktualisieren aktualisieren. Bei einer Gerätestatusänderung wird die Zeile grün hervorgehoben.

Fehlermeldungen

Beim Aufrufen des Berichtstatus kann eine der folgenden Fehlermeldungen angezeigt werden. Die Antworten erfolgen in Form von HTTP-Statuscodes.

  • 400 Bad Request: Der Server konnte die vom Client gesendete Anfrage aufgrund einer ungültigen Syntax nicht verarbeiten. Häufige Ursachen sind fehlerhafte JSON-Daten oder die Verwendung von null statt „“ als 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 gewünschte Gerät nicht finden. Es kann aber auch bedeuten, dass das Nutzerkonto nicht mit Google verknüpft ist oder wir eine ungültige agentUserId erhalten haben. Achten Sie darauf, dass agentUserId dem in Ihrer SYNC-Antwort angegebenen Wert entspricht und Sie DISConnect-Intents richtig verarbeiten.