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

Synchronisierung anfordern

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

Request Sync löst für alle Google-Nutzer mit Geräten, denen der angegebene agentUserId zugeordnet ist, den Sie in der ursprünglichen SYNC-Anfrage gesendet haben, eine SYNC-Anfrage an die Auftragsausführung aus. So können Sie die Geräte der Nutzer aktualisieren, ohne die Verknüpfung mit ihrem Konto aufheben oder wieder verknüpfen zu müssen. 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
  • Der Nutzer hat ein vorhandenes Gerät umbenannt.
  • Wenn Sie einen neuen Gerätetyp implementieren, eine neue Eigenschaft oder eine neue Gerätefunktion hinzufügen

Erste Schritte

So implementieren Sie die Anfragesynchronisierung:

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 Ihrer Projekt-ID smart home 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

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 ist ein Beispiel für eine JSON-Anfrage für die Anfragesynchronisierung:
  5. {
      "agentUserId": "user-123"
    }
    
  6. Kombinieren Sie die JSON-Anfrage und das Token in Ihrer 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:requestSync"
    

gRPC

Die Home Graph API 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 RequestSync auf.

Node.js

Der Node.js-Client der Google APIs 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 requestSync mit RequestSyncDevicesRequest auf. Sie gibt ein Promise mit einer leeren RequestSyncDevicesResponse zurück.
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 enthält Bindungen für die Home Graph API.

  1. Initialisieren Sie die HomeGraphApiService mit Standardanmeldedaten für Anwendungen.
  2. Rufen Sie die Methode requestSync mit RequestSyncDevicesRequest auf. Ein leeres ReportStateAndNotificationResponse wird 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 die Anfragesynchronisierung 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.
  • 403 Forbidden: Der Server konnte die Anfrage für die angegebene agentUserId aufgrund eines Fehlers beim Aktualisieren des Tokens nicht verarbeiten. Achten Sie darauf, dass der OAuth-Endpunkt korrekt auf Aktualisierungsanfragen reagiert und den Kontoverknü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 ist das Nutzerkonto nicht mit Google verknüpft oder wir haben eine ungültige agentUserId erhalten. Achten Sie darauf, dass agentUserId mit dem Wert in Ihrer SYNC-Antwort übereinstimmt und Sie DISCONNECT-Intents ordnungsgemäß verarbeiten.
  • 429 Too Many Requests: Die maximale Anzahl gleichzeitiger Synchronisierungsanfragen wurde für die angegebene agentUserId überschritten. Ein Aufrufer kann nur eine gleichzeitige Synchronisierungsanfrage senden, es sei denn, das Flag async ist auf „true“ gesetzt.