Die Anfragesynchronisierung löst für jeden Google-Nutzer mit Geräten, auf denen die angegebene agentUserId (die Sie in der ursprünglichen SYNC-Anfrage gesendet haben) eine SYNC-Anfrage an Ihre Auftragsausführung aus. So können Sie die Geräte der Nutzer aktualisieren, ohne die Verknüpfung des Kontos aufzuheben oder es wieder zu verknüpfen. Alle Nutzer, die mit dieser ID verknüpft sind, erhalten eine SYNC-Anfrage.
Sie müssen eine SYNC-Anfrage auslösen:
- Der Nutzer fügt ein neues Gerät hinzu.
- Wenn der Nutzer ein vorhandenes Gerät entfernt.
- Wenn der Nutzer ein vorhandenes Gerät umbenennt.
- Wenn du einen neuen Gerätetyp oder eine neue Trait implementierst oder eine neue Gerätefunktion hinzufügst.
Erste Schritte
Führen Sie die folgenden Schritte aus, um die Anfragesynchronisierung zu implementieren:
Google HomeGraph API aktivieren
-
Rufen Sie in Google Cloud Console die Seite HomeGraph API auf.
Zur Seite „HomeGraph API“ - Wählen Sie das Projekt aus, das Ihrer smart home-Projekt-ID entspricht.
- Klicken Sie auf AKTIVIEREN.
Dienstkontoschlüssel erstellen
Folgen Sie dieser Anleitung, um einen Dienstkontoschlüssel aus Google Cloud Console zu generieren:
-
Rufen Sie in Google Cloud Console die Seite Dienstkontoschlüssel erstellen auf.
Zur Seite Dienstkontoschlüssel erstellen - Wählen Sie in der Liste Dienstkonto die Option Neues Dienstkonto aus.
- Geben Sie im Feld Dienstkontoname einen Namen ein.
- Geben Sie im Feld Dienstkonto-ID eine ID ein.
Wählen Sie in der Liste Rolle die Option Dienstkonten > Ersteller von Dienstkonto-Tokens aus.
Wählen Sie als Schlüsseltyp die Option JSON aus.
- Klicken Sie auf Erstellen. Eine JSON-Datei mit Ihrem Schlüssel wird auf Ihren Computer heruntergeladen.
API aufrufen
HTTP
Die Home Graph API stellt einen HTTP-Endpunkt bereit.
- Verwenden Sie die heruntergeladene JSON-Datei des Dienstkontos, um ein JSON Web Token (JWT) zu erstellen. Weitere Informationen findest du unter Authentifizierung mit einem Dienstkonto.
- Rufen Sie mit oauth2l ein OAuth 2.0-Zugriffstoken im Bereich
https://www.googleapis.com/auth/homegraphab: - Erstellen Sie die JSON-Anfrage mit der
agentUserId. Hier sehen Sie eine Beispiel-JSON-Anfrage für die Anfragesynchronisierung: - Kombinieren Sie „Request Sync JSON“ mit dem Token in Ihrer HTTP-POST-Anfrage an den Google Home Graph-Endpunkt. Hier sehen Sie ein Beispiel dafür, wie Sie die Anfrage mit
curlin der Befehlszeile als Test stellen:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{
"agentUserId": "user-123"
}
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 stellt einen gRPC-Endpunkt bereit.
- Rufen Sie die Protokollzwischenspeicher-Dienstdefinition für die Home Graph API ab.
- Folgen Sie der gRPC-Entwicklerdokumentation, um Client-Stubs für eine der unterstützten Sprachen zu generieren.
- Rufen Sie die Methode RequestSync auf.
Node.js
Der Google APIs-Node.js-Client stellt Bindungen für die Home Graph API bereit.
- Initialisieren Sie den
google.homegraph-Dienst mit den Standardanmeldedaten für Anwendungen. - Rufen Sie die Methode
requestSyncmit der RequestSyncDevicesRequest auf. Sie gibt einPromisemit einem 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.
- Initialisieren Sie
HomeGraphApiServicemit den Standardanmeldedaten für Anwendungen. - Rufen Sie die Methode
requestSyncmitRequestSyncDevicesRequestauf. Es wird ein leeresReportStateAndNotificationResponsezurü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
Beim Aufrufen von "Request Sync" kann eine der folgenden Fehlerantworten angezeigt werden. Diese Antworten werden in Form von HTTP-Statuscodes ausgegeben.
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 vonnullanstelle von „“ für einen Stringwert.403 Forbidden: Der Server konnte die Anfrage für den angegebenenagentUserIdaufgrund eines Fehlers beim Aktualisieren des Tokens nicht verarbeiten. Achten Sie darauf, dass Ihr OAuth-Endpunkt korrekt auf Aktualisierungstokenanfragen reagiert und prüfen Sie den Kontoverknüpfungsstatus des Nutzers.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ültigeagentUserIderhalten haben. Prüfen Sie, obagentUserIdmit dem Wert in der SYNC-Antwort übereinstimmt und DISCONNECT-Intents ordnungsgemäß verarbeiten.429 Too Many Requests: Die maximale Anzahl gleichzeitiger Synchronisierungsanfragen wurde für die angegebeneagentUserIdüberschritten. Ein Aufrufer darf nur eine einzige Synchronisierungsanfrage gleichzeitig senden, es sei denn, das Flagasyncist auf „true“ gesetzt.