Exporter des données IoT vers Event Hubs

Cet article explique comment configurer l’exportation de données pour envoyer des données à Event Hubs.

Utilisez cette fonctionnalité pour une exportation continue des données IoT filtrées et enrichies à partir de votre application IoT Central. La fonctionnalité d'exportation de données envoie (push) les modifications en quasi-temps réel vers d'autres parties de votre solution cloud pour vous fournir des insights, des analyses et un stockage à chaud.

Par exemple, vous pouvez :

• Exportez en continu des données de télémétrie, de modifications des propriétés, de connectivité des appareils, de cycle de vie des appareils, de cycle de vie de modèle d’appareil et de journal d’audit au format JSON en quasi-temps réel.
• filtrer les flux de données pour exporter des données qui remplissent des conditions personnalisées ;
• enrichir les flux de données avec des valeurs personnalisées et des valeurs de propriété à partir de l'appareil ;
• Transformer les flux de données pour modifier leur forme et leur contenu.

Conseil

Quand vous activez l’exportation de données, vous obtenez seulement les données à partir de ce moment. Pour conserver un historique des données plus étendu, activez l’exportation de données au plus tôt. Pour exporter manuellement des données générées lorsque l’exportation des données était désactivée, consultez Comment utiliser l’API REST IoT Central pour interroger des appareils.

Remarque

Dans certains cas, l’exportation des messages peut prendre jusqu’à 60 secondes. Cette durée est mesurée à partir du moment où IoT Central reçoit le message du hub IoT sous-jacent jusqu’au moment où le message est remis au point de terminaison de destination.

Prérequis

Pour utiliser les fonctionnalités d’exportation de données, vous devez disposer d’une autorisation d’exportation de données.

Configurer une destination d’exportation Event Hubs

IoT Central exporte les données en quasi-temps réel. Les données se trouvent dans le corps du message, au format JSON encodé au format UTF-8.

Le conteneur d'annotations ou de propriétés système du message contient les champs iotcentral-device-id, iotcentral-application-id, iotcentral-message-source et iotcentral-message-type qui ont les mêmes valeurs que les champs correspondants dans le corps du message.

Options de connexion

Les destinations Event Hubs vous permettent de configurer la connexion avec une chaîne de connexion ou une identité managée.

Les identités managées sont plus sécurisées, car :

• Vous ne stockez pas les informations d’identification de votre ressource dans une chaîne de connexion de votre application IoT Central.
• Les informations d’identification sont automatiquement liées à la durée de vie de votre application IoT Central.
• Les identités managées effectuent automatiquement une rotation régulière de leurs clés de sécurité.

IoT Central utilise actuellement des identités managées affectées par le système.

Quand vous configurez une identité managée, la configuration comprend une étendue et un rôle :

• L’étendue définit l’emplacement où vous pouvez utiliser l’identité managée. Par exemple, vous pouvez utiliser un groupe de ressources Azure comme étendue. Dans ce cas, l’application IoT Central et la destination doivent être dans le même groupe de ressources.
• Le rôle définit les autorisations qui sont accordées à l’application IoT Central dans le service de destination. Par exemple, pour qu’une application IoT Central envoie des données à un Event Hub, l’identité managée a besoin de l’attribution de rôle Expéditeur de données Azure Event Hubs.

La vidéo suivante fournit plus d’informations sur les identités managées affectées par le système :

Attention

Pour exporter vers un stockage Blob, n’utilisez pas le Contributeur de compte de stockage, comme illustré dans la vidéo. Utilisez plutôt le rôle Contributeur aux données d’objets blob du stockage.

Créer une destination Event Hubs

Identité gérée

Cet article explique comment créer une identité managée à l’aide d’Azure CLI. Vous pouvez également utiliser le portail Azure pour créer une identité managée.

Si vous n’avez pas d’espace de noms Event Hubs existant vers lequel exporter, exécutez le script suivant dans l’environnement Bash Azure Cloud Shell. Le script crée un groupe de ressources, un espace de noms Event Hubs et un hub d’événements. Le script active ensuite l’identité managée pour votre application IoT Central et attribue le rôle nécessaire pour accéder à votre hub d’événements :

# Replace the Event Hubs namespace name with your own unique value
EHNS=your-event-hubs-namespace-$RANDOM

# Replace the IoT Central app name with the name of your
# IoT Central application.
CA=your-iot-central-app

EH=exportdata
RG=centralexportresources
LOCATION=eastus

RGID=$(az group create -n $RG --location $LOCATION --query "id" --output tsv)
az eventhubs namespace create --name $EHNS --resource-group $RG -l $LOCATION
az eventhubs eventhub create --name $EH --resource-group $RG --namespace-name $EHNS

# This assumes your IoT Central application is in the 
# default `IOTC` resource group.
az iot central app identity assign --name $CA --resource-group IOTC --system-assigned
PI=$(az iot central app identity show --name $CA --resource-group IOTC --query "principalId" --output tsv)

az role assignment create --assignee $PI --role "Azure Event Hubs Data Sender" --scope $RGID

az role assignment list --assignee $PI --all -o table

echo "Host name: $EHNS.servicebus.windows.net"
echo "Event Hub: $EH"

Pour sécuriser encore votre hub d’événements et autoriser uniquement l’accès à partir de services approuvés avec des identités managées, consultez Exporter des données vers une destination sécurisée sur un réseau virtuel Azure.

Pour créer la destination Event Hubs dans IoT Central sur la page Exportation de données :

1. Sélectionnez + Nouvelle destination.

2. Sélectionnez Azure Event Hubs en tant que type de destination.

3. Sélectionnez Identité managée affectée par le système comme type d’autorisation.

4. Entrez le nom d’hôte de votre ressource Event Hubs. Entrez ensuite le nom du hub d’événements en respectant la casse. Un nom d’hôte ressemble à ceci : contoso-waste.servicebus.windows.net.

5. Sélectionnez Enregistrer.

Si vous ne voyez pas de données arriver dans votre service de destination, consultez Résoudre les problèmes liés aux exportations de données à partir de votre application Azure IoT Central.

Chaîne de connexion

Si vous n’avez pas d’espace de noms Event Hubs existant vers lequel exporter, exécutez le script suivant dans l’environnement Bash Azure Cloud Shell. Le script crée un groupe de ressources, un espace de noms Event Hubs et un hub d’événements. Il imprime ensuite la chaîne de connexion à utiliser quand vous configurez l’exportation de données dans IoT Central :

# Replace the Event Hubs namespace name with your own unique value
EHNS=your-event-hubs-namespace-$RANDOM
EH=exportdata
RG=centralexportresources
LOCATION=eastus

az group create -n $RG --location $LOCATION
az eventhubs namespace create --name $EHNS --resource-group $RG -l $LOCATION
az eventhubs eventhub create --name $EH --resource-group $RG --namespace-name $EHNS
az eventhubs eventhub authorization-rule create --eventhub-name $EH --resource-group $RG --namespace-name $EHNS --name SendRule --rights Send

CS=$(az eventhubs eventhub authorization-rule keys list --eventhub-name $EH --resource-group $RG --namespace-name $EHNS --name SendRule --query "primaryConnectionString" -o tsv)

echo "Event hub connection string: $CS"

Pour créer la destination Event Hubs dans IoT Central sur la page Exportation de données :

1. Sélectionnez + Nouvelle destination.

2. Sélectionnez Azure Event Hubs en tant que type de destination.

3. Sélectionnez Chaîne de connexion comme type d’autorisation.

4. Collez la chaîne de connexion de votre ressource Event Hubs, puis entrez si nécessaire le nom du hub d’événements, en respectant la casse.

5. Sélectionnez Enregistrer.

Configurer une exportation de données

Maintenant que vous disposez d'une destination vers laquelle exporter vos données, configurez la fonctionnalité d'exportation de données dans votre application IoT Central :

1. Connectez-vous à votre application IoT Central.

2. Dans le volet gauche, sélectionnez Exportation de données.

   Conseil

   Si vous ne voyez pas Exportation de données dans le volet gauche, cela signifie que vous n’avez pas les autorisations nécessaires pour configurer l’exportation de données dans votre application. Contactez un administrateur pour configurer l’exportation de données.

3. Sélectionnez + Nouvelle exportation.

4. Entrez un nom d'affichage pour votre nouvelle exportation et assurez-vous que l'exportation de données est activée.

5. Choisissez le type de données à exporter. Le tableau suivant répertorie les types d'exportation de données pris en charge :

   Type de données	Description	Format de données
   Télémétrie	Exportez des messages de télémétrie à partir d’appareils en quasi-temps réel. Chaque message exporté contient le contenu complet du message d'origine de l'appareil, normalisé.	Format du message de télémétrie
   Modifications de la propriété	Exportez les modifications apportées aux propriétés de l’appareil et du cloud en quasi-temps réel. Pour les propriétés en lecture seule de l'appareil, les modifications apportées aux valeurs signalées sont exportées. Pour les propriétés en lecture-écriture, les valeurs signalées et souhaitées sont exportées.	Format du message de modification de la propriété
   Connectivité des appareils	Exportez les événements connectés et déconnectés des appareils.	Format de message de connectivité des appareils
   Cycle de vie des appareils	Exportez les événements enregistrés, supprimés, approvisionnés, activés, désactivés, displayNameChanged et deviceTemplateChanged de l’appareil.	Format du message relatif aux changements de cycle de vie d’appareil
   Cycle de vie de modèle d’appareil	Exportez les changements de modèle d’appareil publiés, dont les créations, les mises à jour et les suppressions.	Format de message relatif aux changements de cycle de vie d’appareil
   Journaux d’audit	Journaux des mises à jour lancées par l’utilisateur et apportées à des entités dans l’application. Pour plus d’informations, consultez Utiliser des journaux d’audit pour suivre l’activité dans votre application IoT Central	Format de message de journal d’audit

6. Vous pouvez également ajouter des filtres pour réduire la quantité de données exportées. Différents types de filtres sont disponibles pour chaque type d’exportation de données :

   Type de données	Filtres disponibles
   Télémétrie	Filtrer par nom d’appareil, identité d'appareil et modèle d’appareil et indiquez si l’appareil est simulé Filtrer le flux de façon à ce qu’il contienne uniquement la télémétrie correspondant aux conditions de filtre Filtrer le flux de façon à ce qu’il contienne uniquement la télémétrie des appareils dont les propriétés correspondent aux conditions de filtre Filtrer le flux de façon à ce qu’il contienne uniquement la télémétrie avec des propriétés de message correspondant à la condition de filtre. Les propriétés de message (également appelées propriétés d’application) sont envoyées dans un ensemble de paires clé-valeur sur chaque message de télémétrie. Pour créer un filtre de propriété de message, entrez la clé de la propriété de message que vous recherchez, et spécifiez une condition. Seuls les messages de télémétrie dont les propriétés correspondent à la condition de filtre spécifiée sont exportés. En savoir plus sur les propriétés d’application dans des documents IoT Hub
   Modifications de la propriété	Filtrer par nom d’appareil, identité d'appareil et modèle d’appareil et indiquez si l’appareil est simulé Filtrer le flux de façon à ce qu’il contienne uniquement les changements de propriété correspondant aux conditions de filtre
   Connectivité des appareils	Filtrer par nom d’appareil, ID d’appareil, modèle d’appareil, organisations et indiquer si l’appareil est simulé Filtrer le flux de façon à ce qu’il contienne uniquement les changements des appareils dont les propriétés correspondent aux conditions de filtre
   Cycle de vie des appareils	Filtrer par nom d’appareil, identité d’appareil, modèle d’appareil et indiquez si l’appareil est approvisionné, activé ou simulé Filtrer le flux de façon à ce qu’il contienne uniquement les changements des appareils dont les propriétés correspondent aux conditions de filtre
   Cycle de vie de modèle d’appareil	Filtrer par modèle d’appareil
   Journaux d’audit	S/O

7. Si vous le souhaitez, vous pouvez également enrichir les messages exportés avec des métadonnées supplémentaires dans les paires clé-valeur. Les enrichissements suivants sont disponibles pour les types d’exportation de données de télémétrie, de modification des propriétés, de connectivité des appareils et de cycle de vie des appareils :

   • Chaîne personnalisée : ajoute une chaîne statique personnalisée à chaque message. Entrez n’importe quelle clé, puis entrez une valeur de chaîne.
   • Propriété, qui ajoute à chaque message ce qui suit :
     • Métadonnées d’appareil, par exemple nom de l’appareil, nom du modèle d’appareil, informations relatives à l’activation, aux organisations, au provisionnement et à la simulation.
     • Valeur actuelle de la propriété rapportée d’appareil ou de la propriété de cloud à chaque message. Si le message exporté provient d'un appareil qui ne dispose pas de la propriété spécifiée, l'enrichissement ne s'applique pas à ce message.

Configurez la destination de l’exportation :

1. Sélectionnez + Destination pour ajouter une destination que vous avez déjà créée ou sélectionnez Créer nouveau.

2. Pour transformer vos données avant leur exportation, sélectionnez + Transformer. Pour plus d’informations, consultez Transformer des données dans votre application IoT Central pour les exporter.

3. Sélectionnez + Destination pour ajouter jusqu’à cinq destinations à une même exportation.

4. Une fois la configuration de votre exportation terminée, sélectionnez Enregistrer. Au bout de quelques minutes, vos données apparaissent dans vos destinations.

Superviser votre exportation

Dans IoT Central, la page Exportation de données vous permet de vérifier l’état de vos exportations. Vous pouvez également utiliser Azure Monitor pour connaître la quantité de données que vous exportez et voir les erreurs d’exportation. Vous pouvez accéder aux métriques d’intégrité des appareils et des exportations dans les graphiques du portail Azure en utilisant l’API REST, des requêtes dans PowerShell ou Azure CLI. Vous pouvez superviser les métriques d’exportation de données suivantes dans Azure Monitor :

• Nombre de messages entrants à exporter avant l’application de filtres.
• Nombre de messages qui passent par des filtres.
• Nombre de messages correctement exportés vers les destinations.
• Nombre d’erreurs trouvées.

Pour en savoir plus, consultez Superviser l’intégrité de l’application.

Formats de données

Les sections suivantes décrivent les formats des données exportées :

Format des données de télémétrie.

Chaque message exporté contient un formulaire normalisé du message complet que l'appareil a envoyé dans le corps du message. Le message est au format JSON et encodé en UTF-8. Chaque message contient les informations suivantes :

• applicationId : ID de l’application IoT Central.
• messageSource : source du message - telemetry.
• deviceId : ID de l’appareil qui a envoyé le message de télémétrie.
• schema : nom et version du schéma de charge utile.
• templateId : ID du modèle d’appareil affecté à l’appareil.
• enqueuedTime : heure à laquelle IoT Central a reçu ce message.
• enrichments : enrichissements configurés lors de l’exportation.
• module : module IoT Edge qui a envoyé ce message. Ce champ apparaît uniquement si le message provient d’un module IoT Edge.
• component : composant qui a envoyé ce message. Ce champ apparaît uniquement si les capacités envoyées dans le message ont été modélisées en tant que composant dans le modèle d’appareil.
• messageProperties : autres propriétés envoyées par l’appareil avec le message. Ces propriétés sont parfois appelées propriétés d'application. Pour en savoir plus, consultez la documentation d'IoT Hub.

Propriétés de message

Les messages de télémétrie ont des propriétés pour les métadonnées ainsi que pour la charge utile de télémétrie. L’extrait de code précédent montre des exemples de messages système tels que deviceId et enqueuedTime. Pour en savoir plus sur les propriétés des messages système, consultez Propriétés système des messages IoT Hub d’appareil-à-cloud.

Vous pouvez ajouter des propriétés aux messages de télémétrie si vous devez ajouter des métadonnées personnalisées à ces derniers. Par exemple, vous devez ajouter un horodatage quand l’appareil crée le message.

L’extrait de code suivant montre comment ajouter la propriété iothub-creation-time-utc au message quand vous le créez sur l’appareil :

Important

Le format de cet horodatage doit être UTC sans informations de fuseau horaire. Par exemple, 2021-04-21T11:30:16Z est valide, 2021-04-21T11:30:16-07:00 non.

JavaScript

async function sendTelemetry(deviceClient, index) {
  console.log('Sending telemetry message %d...', index);
  const msg = new Message(
    JSON.stringify(
      deviceTemperatureSensor.updateSensor().getCurrentTemperatureObject()
    )
  );
  msg.properties.add("iothub-creation-time-utc", new Date().toISOString());
  msg.contentType = 'application/json';
  msg.contentEncoding = 'utf-8';
  await deviceClient.sendEvent(msg);
}

Java

private static void sendTemperatureTelemetry() {
  String telemetryName = "temperature";
  String telemetryPayload = String.format("{\"%s\": %f}", telemetryName, temperature);

  Message message = new Message(telemetryPayload);
  message.setContentEncoding(StandardCharsets.UTF_8.name());
  message.setContentTypeFinal("application/json");
  message.setProperty("iothub-creation-time-utc", Instant.now().toString());

  deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
  log.debug("My Telemetry: Sent - {\"{}\": {}°C} with message Id {}.", telemetryName, temperature, message.getMessageId());
  temperatureReadings.put(new Date(), temperature);
}

C#

private async Task SendTemperatureTelemetryAsync()
{
  const string telemetryName = "temperature";

  string telemetryPayload = $"{{ \"{telemetryName}\": {_temperature} }}";
  using var message = new Message(Encoding.UTF8.GetBytes(telemetryPayload))
  {
      ContentEncoding = "utf-8",
      ContentType = "application/json",
  };
  message.Properties.Add("iothub-creation-time-utc", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
  await _deviceClient.SendEventAsync(message);
  _logger.LogDebug($"Telemetry: Sent - {{ \"{telemetryName}\": {_temperature}°C }}.");
}

Python

async def send_telemetry_from_thermostat(device_client, telemetry_msg):
    msg = Message(json.dumps(telemetry_msg))
    msg.custom_properties["iothub-creation-time-utc"] = datetime.now(timezone.utc).isoformat()
    msg.content_encoding = "utf-8"
    msg.content_type = "application/json"
    print("Sent message")
    await device_client.send_message(msg)

Format des modifications de propriétés

Chaque message ou enregistrement représente les modifications apportées aux propriétés de l’appareil et du cloud. Les informations incluses dans le message exporté sont les suivantes :

• applicationId : ID de l’application IoT Central.
• messageSource : source du message - properties.
• messageType : cloudPropertyChange, devicePropertyDesiredChange ou devicePropertyReportedChange.
• deviceId : ID de l’appareil qui a envoyé le message de télémétrie.
• schema : nom et version du schéma de charge utile.
• enqueuedTime : heure à laquelle IoT Central a détecté cette modification.
• templateId : ID du modèle d’appareil affecté à l’appareil.
• properties : Tableau des propriétés qui ont été modifiées, y compris les noms des propriétés et les valeurs qui ont été modifiés. Les informations sur le composant et le module sont incluses si la propriété est modélisée dans un composant ou un module IoT Edge.
• enrichments : enrichissements configurés lors de l’exportation.

Format des modifications de la connectivité des appareils

Chaque message ou enregistrement représente un événement de connectivité provenant d’un seul appareil. Les informations incluses dans le message exporté sont les suivantes :

• applicationId : ID de l’application IoT Central.
• messageSource : source du message - deviceConnectivity.
• messageType : connected ou disconnected.
• deviceId : ID de l’appareil modifié.
• schema : nom et version du schéma de charge utile.
• templateId : ID du modèle d’appareil affecté à l’appareil.
• enqueuedTime : Heure à laquelle cette modification est intervenue dans IoT Central.
• enrichments : enrichissements configurés lors de l’exportation.

Format des changements du cycle de vie d’appareil

Chaque message ou enregistrement représente une modification apportée à un appareil. Les informations incluses dans le message exporté sont les suivantes :

• applicationId : ID de l’application IoT Central.
• messageSource : source du message - deviceLifecycle.
• messageType : type de la modification effectuée. Il s’agit de l’un des éléments suivants : registered, deleted, provisioned, enabled, disabled, displayNameChanged et deviceTemplateChanged.
• deviceId : ID de l’appareil modifié.
• schema : nom et version du schéma de charge utile.
• templateId : ID du modèle d’appareil affecté à l’appareil.
• enqueuedTime : Heure à laquelle cette modification est intervenue dans IoT Central.
• enrichments : enrichissements configurés lors de l’exportation.

Format des changements de cycle de vie d’appareil

Chaque message ou enregistrement représente une modification apportée à un modèle d’appareil publié. Les informations incluses dans le message exporté sont les suivantes :

• applicationId : ID de l’application IoT Central.
• messageSource : source du message - deviceTemplateLifecycle.
• messageType : created, updated ou deleted.
• schema : nom et version du schéma de charge utile.
• templateId : ID du modèle d’appareil affecté à l’appareil.
• enqueuedTime : Heure à laquelle cette modification est intervenue dans IoT Central.
• enrichments : enrichissements configurés lors de l’exportation.

Format du journal d’audit

Chaque message de journal d’audit représente un changement à l’initiative de l’utilisateur apporté à une entité pouvant être auditée dans l’application IoT Central. Les informations incluses dans le message exporté sont les suivantes :

• actor : informations sur l’utilisateur qui a modifié l’entité.
• applicationId : ID de l’application IoT Central.
• messageSource : source du message - audit.
• messageType : type de la modification effectuée. Valeurs possibles : updated, created, deleted.
• updated : présent uniquement si messageType a la valeur updated. Fournit plus de détails sur la mise à jour.
• resource : détails de l’entité modifiée.
• schema : nom et version du schéma de charge utile.
• deviceId : ID de l’appareil modifié.
• enqueuedTime : Heure à laquelle cette modification est intervenue dans IoT Central.
• enrichments : enrichissements configurés lors de l’exportation.

Pour Event Hubs, IoT Central exporte les données des nouveaux messages vers votre hub d’événements en quasi-temps réel. Dans les propriétés utilisateur (également appelées propriétés d'application) de chaque message, les propriétés iotcentral-device-id, iotcentral-application-id, iotcentral-message-source et iotcentral-message-type sont automatiquement incluses.

Étapes suivantes

Maintenant que vous savez comment exporter vers Event Hubs, une étape suivante suggérée consiste à apprendre à exporter vers Azure Data Explorer.