Bienvenue dans le Centre des développeurs Google Home, la nouvelle destination pour apprendre à développer des actions pour la maison connectée. Remarque : Vous continuerez à créer des actions dans la console Actions.

Demander la synchronisation

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.
Vous pouvez :

Request Sync déclenche l'envoi d'une requête SYNC à votre traitement pour tout utilisateur Google associé à des appareils qui sont associés au paramètre agentUserId spécifié (que vous avez envoyé dans la requête SYNC d'origine). 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 appareil.
  • Indique si l'utilisateur supprime un appareil existant.
  • Si l'utilisateur renomme un appareil existant.
  • Si vous mettez en œuvre un nouveau type d'appareil, une caractéristique ou ajoutez une fonctionnalité.

Commencer

Pour implémenter une synchronisation des requêtes, procédez comme suit:

Activer l'API Google HomeGraph

  1. Dans Google Cloud Platform Console, accédez à la page API HomeGraph.

    Accéder à la page de l'API HomeGraph
  2. Sélectionnez le projet correspondant à votre ID de projet smart home.
  3. 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 GCP Console:

Remarque: Veillez à utiliser le bon projet GCP lorsque vous effectuez ces étapes. Il s'agit du projet qui correspond à votre ID de projet smart home.
  1. Dans GCP 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
  2. Dans la liste Compte de service, sélectionnez Nouveau compte de service.
  3. Dans le champ Nom du compte de service, saisissez un nom.
  4. Dans le champ ID de compte de service, saisissez un ID.
  5. Dans la liste Rôle, sélectionnez Comptes de service > Créateur de jetons du compte de service.

  6. Pour Type de clé, sélectionnez l'option JSON.

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

  1. Utilisez le fichier JSON du compte de service téléchargé pour créer un jeton Web JSON (JWT). Pour en savoir plus, consultez la page S'authentifier à l'aide d'un compte de service.
  2. Obtenez un jeton d'accès OAuth 2.0 avec le champ d'application https://www.googleapis.com/auth/homegraph à l'aide de oauth2l :
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Créez la requête JSON avec agentUserId. Voici un exemple de requête JSON pour Request Sync:
  5. {
      "agentUserId": "user-123"
    }
    
  6. Combinez le fichier JSON Request Sync et le jeton de votre requête HTTP POST au point de terminaison Google Home Graph. Voici un exemple d'envoi de requête dans la ligne de commande à l'aide de curl, à des fins de test:
  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

L'API Home Graph fournit un point de terminaison gRPC

  1. Obtenez la définition de service de tampons de protocole pour l'API Home Graph.
  2. Suivez la documentation pour les développeurs gRPC afin de générer des simulations de client pour l'un des langages compatibles.
  3. Appelez la méthode RequestSync.

Node.js

Le client Node.js des API Google fournit des liaisons pour l'API Home Graph.

  1. Initialisez le service google.homegraph à l'aide des identifiants par défaut de l'application.
  2. Appelez la méthode requestSync avec RequestSyncDevicesRequest. Elle renvoie un Promise 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.

  1. Initialisez HomeGraphApiService à l'aide des identifiants par défaut de l'application.
  2. Appelez la méthode requestSync avec RequestSyncDevicesRequest. Elle renvoie un ReportStateAndNotificationResponse 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 aux erreurs

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. Parmi les causes courantes, on peut citer le format JSON incorrect ou l'utilisation de null au lieu de "" pour une valeur de chaîne.
  • 403 Forbidden : le serveur n'a pas pu traiter la requête agentUserId fournie en raison d'une erreur lors de l'actualisation du jeton. Assurez-vous que votre point de terminaison OAuth répond correctement pour actualiser les requêtes de jeton et vérifiez l'état d'association du compte de l'utilisateur.
  • 404 Not Found : la ressource demandée est introuvable, mais peut être disponible à l'avenir. En général, cela signifie que le compte utilisateur n'est pas associé à Google ou que nous avons reçu un agentUserId non valide. Assurez-vous que agentUserId correspond à la valeur fournie dans votre réponse SYNC et que vous gérez correctement les intents DÉCONNECTER.
  • 429 Too Many Requests : le nombre maximal de requêtes de synchronisation simultanées a été dépassé pour la ressource agentUserId donnée. Un appelant ne peut émettre qu'une seule requête de synchronisation simultanée, sauf si l'option async est définie sur "true".