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 mises à jour pour tous les appareils et structures, et leur réception est garantie 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. Pour savoir comment les activer pour votre Project, consultez Activer les événements .
Google Cloud Pub/Sub
Consultez la documentation de Google Cloud Pub/Sub pour en savoir plus sur son fonctionnement. Plus spécifiquement :
- Découvrez les principes de base de Pub/Sub grâce à leurs guides d'utilisation.
- Découvrez le fonctionnement de l'authentification.
- Choisissez une bibliothèque cliente fournie ou créez votre propre bibliothèque cliente et utilisez les surfaces de l'API REST/HTTP ou gRPC.
Abonnement à un événement
Lorsque des événements sont activés pour votre Project, vous recevez un sujet spécifique à cet ID Project , sous la forme suivante:
projects/sdm-prod/topics/enterprise-project-id
Pour recevoir des événements, créez un abonnement pull ou push associé à ce sujet, en fonction de votre cas d'utilisation. Plusieurs abonnements au sujet SDM sont acceptés. Pour en savoir plus, consultez la page Gérer les abonnements.
Lancer des événements
Pour lancer 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 unique. Les événements pour l'ensemble des structures et des appareils seront publiés après cet appel.
Pour obtenir un exemple, consultez la page Autoriser du guide de démarrage rapide.
Ordre des événements
Pub/Sub ne garantit pas une distribution ordonnée des événements, et leur ordre de réception peut ne pas correspondre à l'ordre dans lequel ils se sont réellement produits. Utilisez le champ timestamp
pour faciliter le rapprochement de l'ordre des événements. Les événements peuvent également arriver individuellement ou combinés dans un seul message d'événement.
Pour en savoir plus, consultez la section Commander 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 obscurci 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 d'une ressource. (par exemple, lorsqu'un appareil est ajouté à une structure ou supprimé d'une structure).
Il existe trois types d'événements de relation:
- CRÉÉ
- DELETED
- MISE À JOUR
La charge utile d'un événement de relation est la suivante:
Charge utile
{ "eventId" : "eed9763a-8735-45d9-81d9-e0621c130eb1", "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
est désormais en relation. Dans l'exemple ci-dessus, un user a accordé l'accès à cet appareil spécifique à un developer, et l'appareil autorisé de userest désormais lié à sa structure autorisée, ce qui déclenche l'événement.
Un élément subject
ne peut être qu'une pièce ou une structure. Si a developer ne dispose pas des autorisations nécessaires pour 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: "1362476b-4ac4-4608-a8be-4c8cf4101426" |
timestamp |
Heure à laquelle l'événement s'est produit. | string Exemple: "2019-01-01T00:00:01Z" |
relationUpdate |
Objet qui détaille des informations sur la mise à jour de la relation. | object |
userId |
Identifiant unique et obscurci qui représente l'utilisateur. | string Exemple: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
Consultez la section Événements pour en savoir plus sur les différents types d'événements et leur fonctionnement.
Exemples
Les charges utiles d'événement 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" }
DELETED
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 lorsque:
- Une pièce est supprimée
Événements liés aux ressources
Un événement de ressource représente une mise à jour spécifique à une ressource. Elle peut être en réponse à un changement de la valeur d'un champ de caractéristique, comme un changement de mode d'un thermostat. Elle peut également représenter une action sur un appareil qui ne modifie pas un champ de caractéristique, comme appuyer sur un bouton de l'appareil.
Un événement généré en réponse à une modification de la valeur du champ de trait contient un objet traits
, semblable à un appel GET de l'appareil:
Charge utile
{
"eventId" : "5b98a768-6771-4d4d-836d-58cce3a62cca",
"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"
]
}
Reportez-vous à la documentation sur les caractéristiques individuelles pour comprendre le format de charge utile pour tout événement de ressource de modification de champ de caractéristique.
Un événement généré en réponse à une action sur un appareil qui ne modifie pas un champ de caractéristique possède également une charge utile avec un objet resourceUpdate
, mais avec un objet events
au lieu d'un objet traits
:
Charge utile
{ "eventId" : "3426d266-406b-48f3-9595-5192229a39a0",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "8XZ1cQ76Becovj551YfM9ZnuwB...", } } } "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 par des caractéristiques spécifiques. Par exemple, l'événement "Mouvement" est défini dans la caractéristique CameraMotion . Consultez la documentation de chaque caractéristique pour comprendre le format de la charge utile pour ces types d'événements de ressource.
Champs
Champ | Description | Type de données |
---|---|---|
eventId |
Identifiant unique de l'événement. | string Exemple: "3426d266-406b-48f3-9595-5192229a39a0" |
timestamp |
Heure à laquelle l'événement s'est produit. | string Exemple: "2019-01-01T00:00:01Z" |
resourceUpdate |
Objet qui détaille des informations sur la mise à jour de la ressource. | object |
userId |
Identifiant unique et obscurci qui représente l'utilisateur. | string Exemple: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
eventThreadId |
Identifiant unique du thread de l'événement. | string Exemple: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59" |
eventThreadState |
État du thread de l'événement. | string Valeurs: "STARTED", "UPDATED", "ENDED" |
resourceGroup |
Objet indiquant 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 |
Consultez la section Événements pour en savoir plus sur les différents types d'événements et leur fonctionnement.
Notifications pouvant être mises à jour
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 pouvant être mises à jour peut être implémentée. Les notifications existantes sont mises à jour avec de nouvelles informations en fonction des événements ultérieurs du même thread d'événements.Sélectionnez la compatibilité des fonctionnalités d'événements pour les notifications pouvant être mises à jour. Elles sont marquées comme Updateable 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 thread d'événement n'est pas identique à une session d'événement. Le thread d'événement identifie un état mis à jour pour un événement précédent dans le même thread. La session d'événements identifie des événements distincts qui sont liés les uns aux autres, et il peut y avoir plusieurs threads d'événements pour une session d'événement donnée.
À des fins de notification, différents types d'événements sont regroupés dans différents threads.
Cette logique de regroupement et de synchronisation des threads est gérée par Google et peut être modifiée à tout moment. A developer doit mettre à jour les notifications en fonction des sessions et des threads d'événements fournis par l'API SDM.
État des threads
Les événements compatibles avec les notifications pouvant être mises à jour comportent également un champ eventThreadState
qui indique l'état du thread d'événements à ce moment-là. Ce champ contient les valeurs suivantes:
- DÉMARRÉ : premier événement d'un fil d'événements.
- MISE À JOUR : événement dans un thread d'événement en cours. Il peut y avoir zéro ou plusieurs événements avec cet état dans un même thread.
- ENDED : dernier événement d'un thread d'événement, qui peut être un doublon du dernier événement UPDATED, en fonction du type de thread.
Ce champ peut être utilisé pour suivre la progression d'un thread d'événement et sa fin.
Filtrage des événements
Dans certains cas, les événements détectés par un appareil peuvent être exclus de la publication dans un sujet SDM Pub/Sub. Ce comportement est appelé filtrage des événements. L'objectif du filtrage des événements est 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 "Motion" initial. Les autres messages envoyés à Motion par la suite seront exclus de la publication jusqu'à ce qu'un certain délai soit écoulé. Une fois cette période écoulée, un message d'événement correspondant à ce type d'événement peut être publié à nouveau.
Dans l'application Google Home (GHA), les événements filtrés s'affichent toujours dans l'historique des événements de user. Toutefois, de tels é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 des événements, qui est définie par Google et peut être modifiée à tout moment. Cette logique de filtrage des événements est indépendante du thread d'événements et de la logique de session.
Comptes de service
Les comptes de service sont recommandés pour gérer les abonnements à l'API SDM et les messages d'événement. 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 par compte de service pour l'API Pub/Sub utilise l'authentification OAuth à deux acteurs (2LO).
Dans le flux d'autorisation 2LO:
- Le developer demande un jeton d'accès à l'aide d'une clé de service.
- developer utilise le jeton d'accès avec les appels à l'API.
Pour en savoir plus sur Google 2LO et sa configuration, consultez la page Utiliser OAuth 2.0 pour les applications de serveur à serveur.
Autorisation
Vous devez autoriser l'utilisation du compte de service avec l'API Pub/Sub:
- Activez l'API Cloud Pub/Sub dans Google Cloud.
- Créez un compte de service et une clé de compte de service comme décrit dans la section Créer un compte de service. Nous vous recommandons de ne lui attribuer que 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.
- Fournissez vos identifiants d'authentification (clé de compte de service) au code de votre 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. - Utilisez les identifiants du compte de service ou le jeton d'accès avec l'API
project.subscriptions
Pub/Sub pour extraire et accuser réception des 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.
- Si l'application Go n'est pas installée sur votre système, commencez par la télécharger et l'installer.
- Une fois Go, installez
oauth2l
et ajoutez son emplacement à votre variable d'environnementPATH
:go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
- Utilisez
oauth2l
pour obtenir un jeton d'accès pour l'API, en utilisant le ou les champs d'application OAuth appropriés :
Par exemple, si votre clé de service se trouve dansoauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
~/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...
Consultez le fichier README de oauth2l
pour en savoir plus sur l'utilisation.
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 la page Bibliothèques clientes pour les API Google.
Lorsque vous utilisez ces bibliothèques avec Pub/Sub API, utilisez la ou les chaînes de champ d'application suivantes :
https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
Erreurs
Le ou les codes d'erreur suivants peuvent être renvoyés par rapport à ce guide:
Message d'erreur | RPC | Dépannage |
---|---|---|
L'image de l'appareil photo n'est plus disponible en 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 de l'événement n'appartient pas à la caméra. | FAILED_PRECONDITION |
Utilisez le eventID correct renvoyé par l'événement enregistré. |
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.