Exporter des données IoT vers Azure Data Explorer

Cet article explique comment configurer l’exportation de données pour envoyer des données au Azure Data Explorer.

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 Azure Data Explorer

Vous pouvez utiliser un cluster Azure Data Explorer ou un pool Azure Synapse Data Explorer. Pour plus d’informations, consultez Différences entre Azure Synapse Data Explorer et Azure Data Explorer.

IoT Central exporte des données en quasi-temps réel vers une table de base de données dans le cluster Azure Data Explorer. Les données se trouvent dans le corps du message, au format JSON encodé au format UTF-8. Vous pouvez ajouter une Transformation dans IoT Central pour exporter des données qui correspondent au schéma de table.

Pour interroger les données exportées dans le portail Azure Data Explorer, accédez à la base de données et sélectionnez Requête.

La vidéo suivante vous guide tout au long de l’exportation de données vers Azure Data Explorer :

Options de connexion

Les destinations Azure Data Explorer vous permettent de configurer la connexion avec un principal de service 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 Azure Data Explorer

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 ne disposez pas d’une base de données Azure Data Explorer existante vers laquelle exporter, effectuez les étapes suivantes. Vous avez deux possibilités pour créer une base de données Azure Data Explorer :

  • Créez un cluster et une base de données Azure Data Explorer. Pour plus d’informations, consultez le Guide de démarrage rapide d’Azure Data Explorer. Prenez note de l’URI du cluster et du nom de la base de données que vous créez, car vous avez besoin de ces valeurs dans les étapes suivantes.
  • Créez un pool et une base de données Azure Synapse Data Explorer. Pour plus d’informations, consultez le Guide de démarrage rapide d’Azure Data Explorer. Prenez note de l’URI du pool et du nom de la base de données que vous créez, car vous avez besoin de ces valeurs dans les étapes suivantes.

Pour configurer l’identité managée qui permet à votre application IoT Central d’exporter des données de façon sécurisée vers votre ressource Azure :

  1. Créez une identité managée que votre application IoT Central utilisera pour se connecter à votre base de données. Utilisez Azure Cloud Shell pour exécuter la commande suivante :

    az iot central app identity assign --name {your IoT Central app name} \
        --resource-group {resource group name} \
        --system-assigned
    

    Prenez note des sorties principalId et tenantId de la commande. Vous utilisez ces valeurs à l’étape suivante.

  2. Configurez les autorisations de la base de données pour autoriser les connexions à partir de votre application IoT Central. Utilisez Azure Cloud Shell pour exécuter la commande suivante :

    az kusto database-principal-assignment create --cluster-name {name of your cluster} \
        --database-name {name of your database}    \
        --resource-group {resource group name} \
        --principal-assignment-name {name of your IoT Central application} \
        --principal-id {principal id from the previous step} \
        --principal-type App --role Admin \
        --tenant-id {tenant id from the previous step}
    

    Conseil

    Si vous utilisez Azure Synapse, consultez az synapse kusto database-principal-assignment.

  3. Créez une table dans votre base de données avec un schéma approprié pour les données que vous exportez. L’exemple de requête suivant crée une table appelée smartvitalspatch. Pour plus d’informations, consultez Transformer des données à l’intérieur de votre application IoT Central pour les exporter :

    .create table smartvitalspatch (
      EnqueuedTime:datetime,
      Message:string,
      Application:string,
      Device:string,
      Simulated:boolean,
      Template:string,
      Module:string,
      Component:string,
      Capability:string,
      Value:dynamic
    )
    
  4. (Facultatif) Pour accélérer l’ingestion des données dans votre base de données Azure Data Explorer :

    1. Accédez à la page Configurations de votre cluster Azure Data Explorer. Activez ensuite l’option Ingestion de streaming.

    2. Exécutez la requête suivante pour modifier la stratégie de table afin d’activer l’ingestion en streaming :

      .alter table smartvitalspatch policy streamingingestion enable
      

Pour créer la destination Azure Data Explorer dans IoT Central sur la page Exportation de données :

  1. Sélectionnez + Nouvelle destination.

  2. Sélectionnez Azure Data Explorer comme type de destination.

  3. Entrez l’URL de votre cluster ou votre pool Azure Data Explorer, le nom de la base de données et le nom de la table. Sélectionnez Identité managée affectée par le système comme type d’autorisation.

    Conseil

    L’URL du cluster d’une instance Azure Data Explorer autonome se présente comme ceci : https://<ClusterName>.<AzureRegion>.kusto.windows.net. L’URL du cluster d’un pool Azure Synapse Data Explorer se présente comme ceci : https://<DataExplorerPoolName>.<SynapseWorkspaceName>.kusto.azuresynapse.net.

    Capture d’écran de la destination d’exportation Azure Data Explorer qui utilise une identité managée.

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.

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 D2C.

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.

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);
}

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.

Étapes suivantes

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