La requête de synchronisation déclenche une requête SYNC
pour votre traitement pour tout utilisateur Google dont les appareils auxquels sont associés les agentUserId
spécifiés (que vous avez envoyée dans la requête SYNC initiale). Cela vous permet de mettre à jour les appareils des utilisateurs sans dissocier ni réassocier leur compte. Tous les utilisateurs associés à cet identifiant recevront une requête SYNC
.
Vous devez déclencher une requête SYNC
:
- Si l'utilisateur ajoute un nouvel appareil
- Si l'utilisateur supprime un appareil existant.
- si l'utilisateur renomme un appareil existant ;
- vous implémentez un nouveau type d'appareil ou une nouvelle caractéristique, ou ajoutez une nouvelle fonctionnalité d'appareil ;
Premiers pas
Pour implémenter Request Sync, procédez comme suit:
Activer l'API Google HomeGraph
-
Dans Google Cloud Console, accédez à la page API HomeGraph.
Accéder à la page de l'API HomeGraph - Sélectionnez le projet qui correspond à l'ID de votre projet smart home.
- Cliquez sur ENABLE (ACTIVER).
Créer une clé de compte de service
Suivez ces instructions pour générer une clé de compte de service à partir de Google Cloud Console:
-
Dans Google Cloud Console, accédez à la page Créer une clé de compte de service.
Accéder à la page Créer une clé de compte de service - Dans la liste Compte de service, sélectionnez Nouveau compte de service.
- Dans le champ Nom du compte de service, saisissez un nom.
- Dans le champ ID du compte de service, saisissez un ID.
Dans la liste Rôle, sélectionnez Comptes de service > Créateur de jetons du compte de service.
Pour le type de clé, sélectionnez l'option JSON.
- Cliquez sur Créer. Un fichier JSON contenant votre clé est téléchargé sur votre ordinateur.
Appeler l'API
HTTP
L'API Home Graph fournit un point de terminaison HTTP
- Utilisez le fichier JSON du compte de service téléchargé pour créer un jeton Web JSON (JWT). Pour en savoir plus, consultez S'authentifier à l'aide d'un compte de service.
- Obtenez un jeton d'accès OAuth 2.0 avec le champ d'application
https://www.googleapis.com/auth/homegraph
à l'aide d'oauth2l: - Créez la requête JSON avec le
agentUserId
. Voici un exemple de requête JSON pour Request Sync: - Combinez le fichier JSON Request Sync et le jeton de votre requête HTTP POST adressée au point de terminaison Google Home Graph. Voici un exemple d'exécution de la requête dans la ligne de commande en utilisant
curl
comme test:
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
L'API Home Graph fournit un point de terminaison gRPC.
- Obtenez la définition du service Protocol Buffers pour l'API Home Graph.
- Suivez la documentation gRPC pour les développeurs afin de générer des bouchons de client pour l'un des langages compatibles.
- Appelez la méthode RequestSync.
Node.js
Le client Node.js des API Google fournit des liaisons pour l'API Home Graph.
- Initialisez le service
google.homegraph
à l'aide des identifiants par défaut de l'application. - Appelez la méthode
requestSync
avec RequestSyncDevicesRequest. Elle renvoie une réponsePromise
avec une réponse RequestSyncDevicesResponse vide.
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
La bibliothèque cliente de l'API HomeGraph pour Java fournit des liaisons pour l'API Home Graph.
- Initialisez
HomeGraphApiService
à l'aide des identifiants par défaut de l'application. - Appelez la méthode
requestSync
avec laRequestSyncDevicesRequest
. Elle renvoie unReportStateAndNotificationResponse
vide.
// 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);
Réponses d'erreur
Vous pouvez recevoir l'une des réponses d'erreur suivantes lorsque vous appelez Request Sync. Ces réponses se présentent sous la forme de codes d'état HTTP.
400 Bad Request
: le serveur n'a pas pu traiter la requête envoyée par le client en raison d'une syntaxe non valide. Les causes courantes incluent le format JSON incorrect ou l'utilisation denull
au lieu de "" pour une valeur de chaîne.403 Forbidden
: le serveur n'a pas pu traiter la requête pour leagentUserId
donné en raison d'une erreur lors de l'actualisation du jeton. Assurez-vous que votre point de terminaison OAuth répond correctement à l'actualisation des requêtes de jeton et vérifiez l'état de l'association du compte de l'utilisateur.404 Not Found
: la ressource demandée est introuvable, mais elle pourrait l'être ultérieurement. En règle générale, cela signifie que le compte utilisateur n'est pas associé à Google ou que nous avons reçu unagentUserId
non valide. Assurez-vous queagentUserId
correspond à la valeur fournie dans votre réponse SYNC et que vous gérez correctement les intents DISCONNECT.429 Too Many Requests
: le nombre maximal de requêtes de synchronisation simultanées a été dépassé pour leagentUserId
donné. Un appelant ne peut émettre qu'une seule requête de synchronisation simultanée, sauf si l'optionasync
est définie sur "true".