Événements

Les événements sont asynchrones et gérés par Google Cloud Pub/Sub, dans un seul sujet par Project. Les événements fournissent des informations à l'ensemble des appareils et des structures. La réception des événements est assurée tant que le jeton d'accès n'est pas révoqué par l'utilisateur et que les messages d'événement n'ont pas expiré.

Activer les événements

Les événements sont une fonctionnalité facultative de l'API SDM. Consultez Activer les événements pour découvrir comment les activer pour votre Project.

Google Cloud Pub/Sub

Consultez la documentation Google Cloud Pub/Sub pour en savoir plus sur le fonctionnement de Pub/Sub. En particulier :

Abonnement aux événements

Avant janvier 2025, si les événements étaient activés pour votre Project, vous auriez reçu un sujet spécifique à cet ID Project , sous la forme suivante :

projects/gcp-project-name/subscriptions/topic-id
 Les projets créés après janvier 2025 doivent auto-héberger leurs sujets Pub/Sub. Vous devrez fournir votre propre ID de sujet. Pour en savoir plus, consultez Créer un sujet.

Pour recevoir des événements, créez un abonnement pull ou push à ce sujet, selon votre cas d'utilisation. Plusieurs abonnements au sujet SDM sont acceptés. Pour en savoir plus, consultez Gérer les abonnements.

Initier des événements

Pour initier des événements pour la première fois une fois l'abonnement Pub/Sub créé, effectuez un appel d'API devices.list en tant que déclencheur ponctuel. Les événements pour toutes les structures et tous les appareils seront publiés après cet appel.

Pour obtenir un exemple, consultez la page Autoriser du guide de démarrage rapide.

Ordre de l'événement

Pub/Sub ne garantit pas la diffusion ordonnée des événements, et l'ordre de réception des événements peut ne pas correspondre à l'ordre dans lequel ils se sont réellement produits. Utilisez le champ timestamp pour faciliter la réconciliation de l'ordre des événements. Les événements peuvent également arriver individuellement ou être combinés dans un seul message d'événement.

Pour en savoir plus, consultez Trier des messages.

ID utilisateur

Si votre implémentation est basée sur les utilisateurs (plutôt que sur la structure ou l'appareil), utilisez le champ userID de la charge utile de l'événement pour corréler les ressources et les événements. Ce champ est un ID brouillé représentant un utilisateur spécifique.

Le userID est également disponible dans l'en-tête de réponse HTTP de chaque appel d'API.

Événements de relation

Les événements de relation représentent une mise à jour relationnelle pour une ressource. Par exemple, lorsqu'un appareil est ajouté à une structure ou supprimé de celle-ci.

Il existe trois types d'événements de relation :

  • CREATED
  • SUPPRIMÉ
  • MISE À JOUR

La charge utile d'un événement de relation est la suivante :

Charge utile

{
  "eventId" : "e69327b2-da1e-40a2-a957-0ab5bc1b4112",
  "timestamp" : "2019-01-01T00:00:01Z",
  "relationUpdate" : {
    "type" : "CREATED",
    "subject" : "enterprises/project-id/structures/structure-id",
    "object" : "enterprises/project-id/devices/device-id"
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
}

Dans un événement de relation, object est la ressource qui a déclenché l'événement et subject est la ressource avec laquelle object a désormais une relation. Dans l'exemple ci-dessus, un user a accordé l'accès à cet appareil spécifique à un developer, et l'appareil autorisé du userest désormais associé à sa structure autorisée, ce qui déclenche l'événement.

Un subject ne peut être qu'une pièce ou une structure. Si a developer n'est pas autorisé à afficher la structure de user, subject est toujours vide.

Champs

Champ Description Type de données
eventId Identifiant unique de l'événement. string
Exemple : "fa33a804-74da-4a74-8aa0-5b576123ddc3"
timestamp Heure à laquelle l'événement s'est produit. string
Exemple : "2019-01-01T00:00:01Z"
relationUpdate Objet contenant des informations détaillées sur la mise à jour de la relation. object
userId Identifiant unique et brouillé représentant l'utilisateur. string
Exemple : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"

Pour en savoir plus sur les différents types d'événements et leur fonctionnement, consultez Événements.

Exemples

Les charges utiles des événements diffèrent pour chaque type d'événement de relation :

CREATED

Structure créée

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

Appareil créé

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

Appareil créé

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

MISE À JOUR

Appareil déplacé

"relationUpdate" : {
  "type" : "UPDATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

SUPPRIMÉ

Structure supprimée

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

Appareil supprimé

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

Appareil supprimé

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

Les événements de relation ne sont pas envoyés dans les cas suivants :

  • Une salle est supprimée

Événements liés aux ressources

Un événement de ressource représente une mise à jour spécifique à une ressource. Il peut s'agir d'une réponse à une modification de la valeur d'un champ de caractéristique, par exemple le changement de mode d'un thermostat. Il peut également représenter une action de l'appareil qui ne modifie pas un champ de trait, comme appuyer sur un bouton de l'appareil.

Un événement généré en réponse à une modification de la valeur d'un champ de caractéristique contient un objet traits, semblable à un appel GET d'appareil :

Charge utile

{
  "eventId" : "6fe39a35-78a8-47c4-993b-920c50ba350e",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.ThermostatMode" : {
        "mode" : "COOL"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Consultez la documentation sur les traits individuels pour comprendre le format de charge utile de tout événement de ressource de modification de champ de trait.

Un événement généré en réponse à une action de l'appareil qui ne modifie pas un champ de caractéristique comporte également une charge utile avec un objet resourceUpdate, mais avec un objet events au lieu d'un objet traits :

Charge utile

{
  "eventId" : "05a312b1-be42-43cc-8def-004763b62da2",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "iPEA_LiD1rSya2EaaknTX7-xj2...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Ces types d'événements de ressources sont définis dans des traits spécifiques. Par exemple, l'événement de mouvement est défini dans le trait CameraMotion . Consultez la documentation de chaque caractéristique pour comprendre le format de charge utile de ces types d'événements de ressources.

Champs

Champ Description Type de données
eventId Identifiant unique de l'événement. string
Exemple : "05a312b1-be42-43cc-8def-004763b62da2"
timestamp Heure à laquelle l'événement s'est produit. string
Exemple : "2019-01-01T00:00:01Z"
resourceUpdate Objet contenant des informations détaillées sur la mise à jour de la ressource. object
userId Identifiant unique et brouillé représentant l'utilisateur. string
Exemple : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
eventThreadId Identifiant unique du fil d'événement. string
Exemple : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
eventThreadState État du thread d'événement. string
Valeurs : "STARTED", "UPDATED", "ENDED"
resourceGroup Objet qui indique les ressources susceptibles d'avoir des mises à jour similaires à cet événement. La ressource de l'événement lui-même (à partir de l'objet resourceUpdate) sera toujours présente dans cet objet. object

Pour en savoir plus sur les différents types d'événements et leur fonctionnement, consultez Événements.

Notifications modifiables

Les notifications basées sur des événements de ressources peuvent être implémentées dans une application, par exemple pour Android ou iOS. Pour réduire le nombre de notifications envoyées, une fonctionnalité appelée notifications modifiables peut être implémentée. Elle permet de mettre à jour les notifications existantes avec de nouvelles informations en fonction des événements ultérieurs dans le même fil d'événement.

Les événements compatibles avec les notifications modifiables sont marqués comme Modifiable  dans la documentation. Ces événements comportent un champ supplémentaire appelé eventThreadId dans leurs charges utiles. Utilisez ce champ pour associer des événements individuels afin de mettre à jour une notification existante qui a été présentée à un utilisateur.

Un fil d'événements n'est pas la même chose qu'une session d'événements. Le fil d'événements identifie un état mis à jour pour un événement précédent du même fil. La session d'événement identifie les événements distincts qui sont liés les uns aux autres. Une session d'événement donnée peut comporter plusieurs threads d'événements.

Pour les notifications, différents types d'événements sont regroupés dans différents fils de discussion.

Cette logique de regroupement et de timing des fils de discussion est gérée par Google et peut être modifiée à tout moment. A developer doit mettre à jour les notifications en fonction des fils d'événements et des sessions fournis par l'API SDM.

État du thread

Les événements compatibles avec les notifications modifiables comportent également un champ eventThreadState qui indique l'état du fil d'événement à ce moment-là. Ce champ accepte les valeurs suivantes :

  • STARTED (DÉMARRÉ) : premier événement d'un fil d'événements.
  • UPDATED (MIS À JOUR) : événement dans un fil d'événements en cours. Il peut y avoir zéro ou plusieurs événements avec cet état dans un même thread.
  • ENDED (TERMINÉ) : dernier événement d'un fil d'événements, qui peut être une copie du dernier événement UPDATED (MIS À JOUR), selon le type de fil.

Ce champ peut être utilisé pour suivre la progression d'un thread d'événements et savoir quand il s'est terminé.

Filtrer les événements

Dans certains cas, les événements détectés par un appareil peuvent être filtrés et ne pas être publiés dans un sujet SDM Pub/Sub. Ce comportement est appelé filtrage des événements. Le filtrage des événements permet d'éviter de publier trop de messages d'événements similaires en peu de temps.

Par exemple, un message peut être publié dans un sujet SDM pour un événement de mouvement initial. Les autres messages concernant Motion seront filtrés et ne seront pas publiés pendant une période définie. Une fois ce délai écoulé, un message d'événement pour ce type d'événement peut être publié à nouveau.

Dans l'application Google Home (AGH), les événements filtrés s'affichent toujours dans l'historique des événements de user. Toutefois, ces événements ne génèrent pas de notification d'application (même si ce type de notification est activé).

Chaque type d'événement possède sa propre logique de filtrage, qui est définie par Google et peut être modifiée à tout moment. Cette logique de filtrage des événements est indépendante de la logique de thread et de session d'événement.

Comptes de service

Les comptes de service sont recommandés pour gérer les abonnements à l'API SDM et les messages d'événements. Un compte de service est utilisé par une application ou une machine virtuelle, et non par une personne. Il possède sa propre clé de compte unique.

L'autorisation de compte de service pour l'API Pub/Sub utilise OAuth à deux facteurs (2LO).

Dans le flux d'autorisation 2LO :

  • developer demande un jeton d'accès à l'aide d'une clé de service.
  • Le developer utilise le jeton d'accès avec les appels à l'API.

Pour en savoir plus sur l'authentification Google 2LO et sur la façon de la configurer, consultez Utiliser OAuth 2.0 pour les applications de serveur à serveur.

Autorisation

Le compte de service doit être autorisé à être utilisé avec l'API Pub/Sub :

  1. Activez l'API Cloud Pub/Sub dans Google Cloud.
  2. Créez un compte de service et une clé de compte de service, comme décrit dans Créer un compte de service. Nous vous recommandons de lui attribuer uniquement le rôle Abonné Pub/Sub. Veillez à télécharger la clé du compte de service sur la machine qui utilisera l'API Pub/Sub.
  3. Fournissez vos identifiants d'authentification (clé de compte de service) à votre code d'application en suivant les instructions de la page de l'étape précédente, ou obtenez un jeton d'accès manuellement à l'aide de oauth2l si vous souhaitez tester rapidement l'accès à l'API.
  4. Utilisez les identifiants du compte de service ou le jeton d'accès avec l'API Pub/Sub project.subscriptions pour extraire et confirmer les messages.

oauth2l

Google oauth2l est un outil de ligne de commande pour OAuth écrit en Go. Installez-le pour Mac ou Linux à l'aide de Go.

  1. Si Go n'est pas installé sur votre système, téléchargez-le et installez-le d'abord.
  2. Une fois Go installé, installez oauth2l et ajoutez son emplacement à votre variable d'environnement PATH : 
    go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
  3. Utilisez oauth2l pour obtenir un jeton d'accès à l'API, en utilisant le ou les champs d'application OAuth appropriés : 
    oauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
     Par exemple, si votre clé de service se trouve à l'emplacement ~/myServiceKey-eb0a5f900ee3.json : 
    oauth2l fetch --credentials ~/myServiceKey-eb0a5f900ee3.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
ya29.c.Elo4BmHXK5...

Pour en savoir plus sur l'utilisation, consultez le fichier oauth2l README.

Bibliothèques clientes pour les API Google

Plusieurs bibliothèques clientes sont disponibles pour les API Google qui utilisent OAuth 2.0. Pour en savoir plus sur le langage de votre choix, consultez Bibliothèques clientes des API Google.

Lorsque vous utilisez ces bibliothèques avec Pub/Sub API, utilisez les chaînes de portée suivantes :

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

Erreurs

Les codes d'erreur suivants peuvent être renvoyés en lien avec ce guide :

Message d'erreur RPC Dépannage
L'image de la caméra n'est plus disponible au téléchargement. DEADLINE_EXCEEDED Les images d'événements expirent 30 secondes après la publication de l'événement. Veillez à télécharger l'image avant son expiration.
L'ID d'événement n'appartient pas à la caméra. FAILED_PRECONDITION Utilisez le eventID correct renvoyé par l'événement de l'appareil photo.

Consultez la documentation de référence sur les codes d'erreur de l'API pour obtenir la liste complète des codes d'erreur de l'API.