Notifications d’événement

  • Article

Cet article traite des notifications d’événements générées par Azure Digital Twins, leur structure et des détails sur les différents types qui peuvent être générés.

Dans Azure Digital Twins, plusieurs événements peuvent produire des notifications. Celles-ci permettent au back-end de la solution de savoir quand des actions se produisent. Ces notifications sont ensuite routées vers différents emplacements, à l’intérieur et à l’extérieur d’Azure Digital Twins, qui peuvent utiliser ces informations pour prendre des mesures.

Plusieurs types de notifications peuvent être générés. En outre, les messages de notification peuvent être différents selon le type d’événement qui les a générés. Cet article donne des détails sur les différents types de messages, ainsi que sur leur aspect.

Ce graphique montre les différents types de notifications :

Type de notification Nom de la source de routage Généré à partir de…
Notification de modification du jumeau numérique Notification de modification du jumeau numérique Toute modification de propriété du jumeau numérique
Notification de cycle de vie du jumeau numérique Notification de cycle de vie du jumeau numérique Toute opération de création ou de suppression de jumeau numérique
Notification de modification de relation du jumeau numérique Notification de modification de relation du jumeau numérique Modification de relation du jumeau numérique
Messages de télémétrie du jumeau numérique Messages de télémétrie Tout message de télémétrie

Structure de notification

La structure d’une notification d’événement à partir d’Azure Digital Twins dépend de la destination de la notification.

Les notifications envoyées à Event Grid sont conformes à l’un des formats suivants (en fonction des paramètres Event Grid) :

Les notifications envoyées à Event Hubs et Service Bus sont conformes à la liaison de protocole AMQP pour CloudEvents.

Notification de changement du jumeau numérique

Les notifications de changement de jumeau numérique sont déclenchées lors de la mise à jour d’un jumeau numérique, par exemple :

  • Lorsque les valeurs de propriété ou les métadonnées sont modifiées.
  • En cas de modification des métadonnées d’un jumeau numérique ou d’un composant. C’est le cas, par exemple, lorsque vous changez le modèle d’un jumeau numérique.

Propriétés

Voici les champs compris dans le corps d’une notification de modification d’un jumeau numérique.

Nom Valeur
id Identificateur de la notification, tel qu’un UUID ou un compteur géré par le service. source + id est unique pour chaque événement.
source Nom de l’instance IoT Hub ou Azure Digital Twins, par exemple myhub.azure-devices.net ou mydigitaltwins.westus2.azuredigitaltwins.net
data Document de correctif JSON décrivant la mise à jour apportée au jumeau. Pour plus d’informations, consultez les Détails du corps ci-dessous.
specversion 1.0
Le message est conforme à cette version de la spécification CloudEvents.
type Microsoft.DigitalTwins.Twin.Update
datacontenttype application/json
subject ID du jumeau numérique
time Horodatage du moment où l’opération s’est produite au niveau du jumeau numérique
traceparent Contexte de trace W3C pour l’événement

Détails du corps

Dans le message, le champ data contient un document de correctif JSON contenant la mise à jour du jumeau numérique.

Vous trouverez ci-dessous des exemples de ce type de message pour chaque schéma de notification possible.

{
    "id": "39d4abb9-e3ee-4ed5-ad17-2243a9784946",
    "subject": "example-twin1",
    "data": {
      "data": {
        "modelId": "dtmi:examplecom:interfaceName;1",
        "patch": [
          {
            "value": "new name",
            "path": "/room",
            "op": "replace"
          }
        ]
      },
      "contenttype": "application/json",
      "traceparent": "00-2aa957558db348f387ef704b37631a1d-c28d665340fe5045-01"
    },
    "eventType": "Microsoft.DigitalTwins.Twin.Update",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:52.9795363Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Notes

Azure Digital Twins ne prend actuellement pas en charge le filtrage d’événements basés sur les champs d’un tableau. Cela comprend le filtrage des propriétés au sein d’une section patch d’une notification de modification de jumeau numérique.

Notifications de cycle de vie de jumeaux numériques

Tous les jumeaux numériques émettent des notifications, qu’ils représentent ou non des appareils IoT Hub dans Azure Digital Twins. Ceci est dû aux notifications de cycle de vie, qui concernent uniquement le jumeau numérique.

Des notifications de cycle de vie sont déclenchées dans les cas suivants :

  • La création d’un jumeau numérique
  • La suppression d’un jumeau numérique

Propriétés

Voici les champs compris dans le corps d’une notification de cycle de vie.

Nom Valeur
id Identificateur de la notification, tel qu’un UUID ou un compteur géré par le service. source + id est unique pour chaque événement.
source Nom de l’instance IoT Hub ou Azure Digital Twins, par exemple myhub.azure-devices.net ou mydigitaltwins.westus2.azuredigitaltwins.net
data Les données du jumeau numérique qui rencontre l’événement du cycle de vie. Pour plus d’informations, consultez les Détails du corps ci-dessous.
specversion 1.0
Le message est conforme à cette version de la spécification CloudEvents.
type Microsoft.DigitalTwins.Twin.Create
Microsoft.DigitalTwins.Twin.Delete
datacontenttype application/json
subject ID du jumeau numérique
time Horodatage du moment où l’opération s’est produite au niveau du jumeau
traceparent Contexte de trace W3C pour l’événement

Détails du corps

Vous trouverez ci-dessous des exemples de ce type de message pour chaque schéma de notification possible.

{
    "id": "6ccdb1cd-0dc3-450f-8730-ceccda8439be",
    "subject": "example-twin1",
    "data": {
      "data": {
        "$dtId": "example-twin1",
        "$etag": "W/\"ecf81d6c-8c1a-4a95-afd8-13bd4cea436f\"",
        "room": "room name",
        "$metadata": {
          "$model": "dtmi:examplecom:interfaceName;1",
          "room": {
            "lastUpdateTime": "2021-12-09T20:28:52.6651216Z"
          }
        }
      },
      "contenttype": "application/json",
      "traceparent": "00-2aa957558db348f387ef704b37631a1d-51f716e7397ec64b-01"
    },
    "eventType": "Microsoft.DigitalTwins.Twin.Create",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:52.6745538Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Notifications de modification d’une relation de jumeau numérique

Les notifications de modification de relation sont déclenchées lorsqu’une relation d’un jumeau numérique est créée, mise à jour ou supprimée.

Propriétés

Voici les champs du corps d’une notification de modification d’une relation.

Nom Valeur
id Identificateur de la notification, tel qu’un UUID ou un compteur géré par le service. source + id est unique pour chaque événement.
source Nom de l’instance Azure Digital Twins, comme mydigitaltwins.westus2.azuredigitaltwins.net
data Charge utile de la relation qui a été modifiée. Pour plus d’informations, consultez les Détails du corps ci-dessous.
specversion 1.0
Le message est conforme à cette version de la spécification CloudEvents.
type Microsoft.DigitalTwins.Relationship.Create
Microsoft.DigitalTwins.Relationship.Update
Microsoft.DigitalTwins.Relationship.Delete
datacontenttype application/json
subject ID de la relation, comme <twin-ID>/relationships/<relationshipID>
time Horodatage du moment où l’opération s’est produite au niveau de la relation
traceparent Contexte de trace W3C pour l’événement

Détails du corps

Dans le message, le champ data contient la charge utile d’une relation, au format JSON. Il utilise le même format qu’une requête GET pour une relation via l’API DigitalTwins.

Vous trouverez ci-dessous des exemples de ce type de message pour chaque schéma de notification possible.

{
    "id": "4d850574-0a28-4667-a59e-3b382ff0e74e",
    "subject": "example-twin1/relationships/RuntimeEventsScenario_edge",
    "data": {
    "data": {
        "modelId": "dtmi:examplecom:interfaceName;1",
        "patch": [
        {
            "value": "new value",
            "path": "/prop1",
            "op": "replace"
        }
        ]
    },
    "contenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-c1fcf951f540ec44-01"
    },
    "eventType": "Microsoft.DigitalTwins.Relationship.Update",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:53.2016395Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Messages de télémétrie du jumeau numérique

Les jumeaux numériques peuvent utiliser l’API SendTelemetry pour émettre des messages de télémétrie et les envoyer aux points de terminaison de sortie.

Propriétés

Voici les champs compris dans le corps d’un message de télémétrie.

Nom Valeur
id Identificateur de la notification, fourni par le client lors de l’appel de l’API de télémétrie.
source Nom complet du jumeau numérique depuis lequel l’événement de télémétrie a été envoyé. Utilisez le format suivant : <your-Digital-Twin-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>.
specversion 1.0
Le message est conforme à cette version de la spécification CloudEvents.
type microsoft.iot.telemetry
data Message de télémétrie envoyé à partir du jumeau. La charge utile n’a pas besoin d’être alignée sur un schéma défini dans votre instance Azure Digital Twins.
dataschema le schéma de données est l'ID de modèle du jumeau ou du composant qui émet les données de télémétrie. Par exemple : dtmi:example:com:floor4;2.
datacontenttype application/json
traceparent Contexte de trace W3C pour l’événement.

Détails du corps

Le corps contient la mesure de télémétrie, ainsi que des informations contextuelles sur le jumeau. Vous trouverez ci-dessous des exemples de ce type de message pour chaque schéma de notification possible.

{
    "id": "6f6635d8-f1b8-43ec-80fb-bb9453fc611c",
    "subject": "example-twin1",
    "data": {
        "data": {
        "prop": "hello from telemetry"
        },
        "dataschema": "dtmi:examplecom:interfaceName;1",
        "contenttype": "application/json-patch+json; charset=utf-8",
        "traceparent": "00-2aa957558db348f387ef704b37631a1d-e894098b46243743-01"
    },
    "eventType": "microsoft.iot.telemetry",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "0001-01-01T00:00:00Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Étapes suivantes

En savoir plus sur la transmission d’événements à différentes destinations, à l’aide des points de terminaison et des itinéraires :