Cette page a été traduite par l'API Cloud Translation.

Événements

Les événements sont asynchrones et gérés par Google Cloud Pub/Sub, dans un seul sujet par ProjectLes événements fournissent des mises à jour pour tous les appareils et toutes les structures. La réception des événements est à condition que le jeton d'accès ne soit pas révoqué par l'utilisateur et que les messages d'événement n'aient pas est arrivé à expiration.

Activer les événements

Les événements sont une fonctionnalité facultative de l'API SDM. Voir Activer les événements pour découvrir comment les activer sur 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 :

Découvrez les principes de base de Pub/Sub avec leur Guides d'utilisation
Découvrez le fonctionnement de l'authentification.
Choisissez une bibliothèque cliente fournie. ou écrire votre propre code Surfaces d'API REST/HTTP ou gRPC

Abonnement à un événement

Lorsque les événements sont activés pour votre Project, un thème spécifique à ce sujet vous est fourni Project ID, au format suivant:

projects/sdm-prod/topics/enterprise-project-id

Pour recevoir des événements, créez une fonction pull ou push pour ce sujet, en fonction de votre de ce cas d'utilisation. Vous pouvez souscrire plusieurs abonnements au sujet SDM. Voir Gérer les abonnements pour plus des informations.

Lancer des événements

Pour lancer des événements pour la première fois une fois l'abonnement Pub/Sub créé, effectuez une <ph type="x-smartling-placeholder"></ph> devices.list comme déclencheur unique. Les événements pour toutes les structures et tous les appareils seront publiés après cette date .

Pour voir un exemple, consultez la Page Authorize (Autoriser) du démarrage rapide Guide.

Ordre des événements

Pub/Sub ne garantit pas la livraison ordonnée des événements, et il se peut que l'ordre de réception des événements ne soit pas correspondent à l'ordre dans lequel les événements se sont réellement produits. Utiliser le timestamp pour faciliter le rapprochement de l'ordre de l'événement. Les événements peuvent également apparaître individuellement ou de manière combinée. dans un même message d'événement.

Pour en savoir plus, consultez Trier les messages.

ID utilisateur

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

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

Événements de relations

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

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

CRÉÉ
SUPPRIMÉE
MISE À JOUR

La charge utile d'un événement de relation se présente comme suit:

Charge utile

{
  "eventId" : "9857c933-765e-44b4-8da0-2828478bffb3",
  "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. subject est la ressource avec laquelle object est désormais en relation. Dans exemple ci-dessus, un user a accordé l'accès à cet appareil spécifique à un developer, et l'appareil autorisé de userest désormais associé à son appareil autorisé qui déclenche l'événement.

Un élément subject ne peut être qu'une pièce ou une structure. Si a developer ne contient pas autorisation d'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 : "60a1cea9-8e7c-4120-9376-e2389af6c9b7"
`timestamp`	L'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 l'article Événements pour en savoir plus sur les différents types d'événements et comment ils fonctionnent.

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"
}

SUPPRIMÉE

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 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 dans un champ de caractéristique (par exemple, changer le mode d'un thermostat). Il peut également s'agir d'une action sur l'appareil ne modifie pas un champ de caractéristique, comme le fait d'appuyer sur le bouton d'un appareil.

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

Charge utile

{
  "eventId" : "c8812099-2d88-41cc-9836-36e07e89f673",
  "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"
  ]
}

Utilisez les individuel Documentation sur les caractéristiques pour comprendre le format de la charge utile pour toute ressource de modification du champ de caractéristique .

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

Charge utile

{
  "eventId" : "ebb925cc-8ce9-4602-b63f-3a6410029de9",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "pCxyP1zQ57t1gDg5i14_4B9WXs...",
      }
    }
  }
  "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 ressource sont définis par des caractéristiques spécifiques. Par exemple, L'événement de mouvement est défini dans CameraMotion trait. Voir la documentation de chaque caractéristique pour comprendre le format de la charge utile pour ces types d'événements de ressources.

Champs

Champ	Description	Type de données
`eventId`	Identifiant unique de l'événement.	`string` Exemple : "ebb925cc-8ce9-4602-b63f-3a6410029de9"
`timestamp`	L'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 fil de discussion de l'é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 semblables à 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 l'article Événements pour en savoir plus sur les différents types d'événements et comment ils fonctionnent.

Notifications pouvant être mises à jour

Des 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, lorsque les notifications existantes sont mis à jour avec les nouvelles informations basées sur les événements ultérieurs du même événement ; thread.

Certains événements proposent la prise en charge des notifications pouvant être mises à jour et sont marqués comme Mise à jour dans la documentation. Ces événements comportent un champ supplémentaire appelé eventThreadId dans leurs charges utiles. Utiliser ceci permettant de lier des événements individuels afin de mettre à jour une qui s'affiche pour un utilisateur.

Un thread d'événement est différent d'une session d'événement. Le fil de discussion de l'événement identifie l'état mis à jour d'un événement précédent dans le même fil de discussion. La event session identifie des événements distincts liés les uns aux autres, et il peut y avoir plusieurs threads d'événement pour une session d'événement donnée.

À des fins de notification, différents types d'événements sont regroupés dans différentes les threads.

Cette logique de regroupement et de synchronisation des threads est gérée par Google et soumise à à tout moment. A developer doit mettre à jour les notifications en fonction les threads et les sessions d'événement fournis par l'API SDM.

État des threads

Les événements compatibles avec les notifications pouvant être mises à jour disposent également d'un eventThreadState qui indique l'état du thread d'événement à ce moment précis. Ce comporte les valeurs suivantes:

DÉMARRÉ : premier événement d'un fil de discussion d'événement.
MISE À JOUR : événement dans un fil de discussion 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 permet de suivre la progression d'un thread d'événement et lorsqu'il a terminé.

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 Pub/Sub SDM. Ce comportement s'appelle le filtrage des événements. Le filtrage des événements permet d'éviter la publication d'un trop grand nombre de messages d'événement similaires en peu de temps.

Par exemple, un message peut être publié dans un sujet SDM. pour un premier événement "Mouvement". Autre messages pour Motion par la suite seront sont exclus de la publication jusqu'à ce qu'une période définie soit écoulée. Une fois cette période écoulée, une fois le temps écoulé, un message d'événement pour ce type d'événement peut être publié à nouveau.

Dans l'application Google Home, les événements qui ont été filtré apparaîtra toujours dans l'historique des événements de user. Toutefois, une telle les é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, définie par Google et peuvent être modifiées à tout moment. Cette logique de filtrage des événements indépendamment du thread d'événement et de la logique de session.

Comptes de service

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

Autorisation via un compte de service pour l'API Pub/Sub 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 des appels à l'API.

Pour en savoir plus sur Google 2LO et sur sa configuration, consultez Utiliser OAuth 2.0 pour une connexion de serveur à serveur Applications.

Autorisation

Le compte de service doit pouvoir être utilisé avec API Pub/Sub:

Activer Cloud Pub/Sub API 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échargez 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) à votre code d'application en suivant les instructions fournies sur la page ou obtenir un jeton d'accès manuellement à l'aide de oauth2l, si vous tester rapidement l'accès aux API.
Utilisez les identifiants du compte de service ou le jeton d'accès avec Pub/Sub project.subscriptions API pour extraire et accuser réception des messages.

OAuth2L

Google oauth2l est un outil de ligne de commande pour OAuth écrit en Go. Installer pour Mac ou Linux avec Go.

Si vous n'avez pas installé Go sur votre système, téléchargez d'abord et installez-le.
Une fois Go, installez oauth2l et ajoutez son emplacement à votre PATH. variable d'environnement:
```
go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
```

Utilisez oauth2l pour obtenir un jeton d'accès pour l'API, à l'aide de la méthode Habilitations OAuth :

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 dans ~/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 des informations.

Bibliothèques clientes pour les API Google

Plusieurs bibliothèques clientes sont disponibles pour les API Google qui utilisent OAuth 2.0. Consultez la page Bibliothèques clientes des API Google pour en savoir plus sur les dans la langue de votre choix.

Lorsque vous utilisez ces bibliothèques avec Pub/Sub API, utilisez la chaîne(s) de champ d'application suivante(s):

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 en rapport avec ce guide:

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

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