Willkommen beim Google Home Developer Center, der neuen Anlaufstelle für Informationen über Smart-Home-Aktionen. Hinweis:Die Aktionen in der Actions Console werden weiterhin erstellt.

Synchronisierung anfordern

Request Sync löst eine SYNC-Anfrage für die Auftragsausführung für alle Google-Nutzer mit Geräten aus, die die angegebene agentUserId haben, die Sie in der ursprünglichen SYNC-Anfrage gesendet haben. So kannst du die Geräte der Nutzer aktualisieren, ohne die Verknüpfung aufzuheben oder ihr Konto wieder zu verknüpfen. Alle mit dieser ID verknüpften Nutzer erhalten eine SYNC-Anfrage.

Sie müssen eine SYNC-Anfrage auslösen:

  • Wenn der Nutzer ein neues Gerät hinzufügt.
  • Wenn der Nutzer ein vorhandenes Gerät entfernt
  • Wenn der Nutzer ein vorhandenes Gerät umbenennt:
  • Wenn du einen neuen Gerätetyp implementierst, eine Eigenschaft machst oder eine neue Gerätefunktion hinzufügst:

Erste Schritte

So implementieren Sie Request Sync:

Google HomeGraph API aktivieren

  1. Rufen Sie in Google Cloud 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

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 smart home-Projekt-ID entspricht.
  1. Rufen Sie in 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

HTTP

Die Home Graph API 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 ein Beispiel für eine JSON-Anfrage für die Anfragesynchronisierung:
  5. {
      "agentUserId": "user-123"
    }
    
  6. Kombinieren Sie das JSON-Objekt für die Anfragesynchronisierung mit dem Token aus Ihrer HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Das folgende Beispiel zeigt, wie Sie die Anfrage als Test mit curl in der Befehlszeile ausführen:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:requestSync"
    

gRPC

Die Home Graph API bietet einen gRPC-Endpunkt

  1. Rufen Sie die Protokollzwischenspeicher-Dienstdefinition 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 RequestSync-Methode auf.

Node.js

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

  1. Initialisieren Sie den google.homegraph-Dienst mit Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die requestSync-Methode mit der RequestSyncDevicesRequest auf. Es wird ein Promise mit einer leeren RequestSyncDevicesResponse zurückgegeben.
const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.requestSync({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    async: false
  }
});
    

Java

Die HomeGraph API-Clientbibliothek für Java stellt Bindungen für die Home Graph API bereit.

  1. Initialisieren Sie HomeGraphApiService mit Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die requestSync-Methode mit der RequestSyncDevicesRequest auf. Es wird ein leeres 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();

// Request sync.
RequestSyncDevicesRequest request =
    new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false);
homegraphService.devices().requestSync(request);
    

Fehlerantworten

Wenn Sie Anfragesynchronisierung aufrufen, erhalten Sie möglicherweise eine der folgenden Fehlermeldungen. Diese 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 fehlerhafter JSON-Code oder die Verwendung von null anstelle von „“ für einen Stringwert.
  • 403 Forbidden: Der Server konnte die Anfrage für den angegebenen agentUserId aufgrund eines Fehlers bei der Aktualisierung des Tokens nicht verarbeiten. Achte darauf, dass dein OAuth-Endpunkt korrekt auf Aktualisierungsanfragen von Tokens reagiert und den Verknüpfungsstatus des Nutzers prüft.
  • 404 Not Found: Die angeforderte Ressource wurde nicht gefunden, ist aber möglicherweise in Zukunft verfügbar. In der Regel bedeutet dies, 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 DISCONNECT-Intents richtig verarbeitet werden.
  • 429 Too Many Requests: Die maximale Anzahl gleichzeitiger Synchronisierungsanfragen für den angegebenen agentUserId wurde überschritten. Ein Aufrufer darf nur eine gleichzeitige Synchronisierungsanfrage senden, es sei denn, das Flag async ist auf „true“ gesetzt.