Partager via

Mapper la télémétrie en entrée dans IoT Central

  • Article

Le mappage de données vous permet de transformer des données de télémétrie d’appareil complexes en données structurées à dans IoT Central. Pour chacun de vos appareils, vous pouvez mapper un chemin JSON spécifique dans le message de télémétrie de l’appareil sur un alias. Un alias est un nom convivial pour la cible vers laquelle vous effectuez le mappage. IoT Central utilise les mappages pour transformer la télémétrie à l’entrée de IoT Central. Vous pouvez utiliser la télémétrie mappée pour :

  • Créez des modèles d’appareil et des expériences de gestion des appareils dans IoT Central.
  • Normalisez la télémétrie à partir de différents appareils en mappant les chemins JSON sur plusieurs appareils à un alias commun.
  • Exporter vers des destinations en dehors de IoT Central.

Conseil

Si vous souhaitez générer automatiquement un modèle d’appareil à partir de données de télémétrie non modélisées, consultez Générer automatiquement un modèle d’appareil.

Diagramme qui résume le processus de mappage dans IoT Central.

La vidéo suivante vous guide tout au long du processus.

Mapper la télémétrie pour votre appareil

Un mappage utilise une expression JSONPath pour identifier la valeur d’un message de télémétrie entrant à mapper à un alias.

Une expression JSONPath commence par le caractère $, qui fait référence à l’élément racine du message. Le $ est suivi d’une séquence d’éléments enfants séparés par des crochets. Par exemple :

$["messages"]["tmp"]

$["opcua"]["payload"][0]["value"]

$["Messages"]["Payload"]["nsu=http://microsoft.com/Opc/OpcPlc/;s=FastUInt1"]["Value"]

IoT Central utilise un sous-ensemble de la syntaxe d’expression JSONPath :

  • Chaque segment ne peut être qu’un nombre non négatif ou une chaîne placée entre guillemets doubles.
  • Un segment ne peut pas contenir de barre oblique inverse, de crochet ou de guillemets doubles.
  • Un chemin d’accès JSON est limité à 1 000 caractères.

Pour créer un mappage dans votre application IoT Central, choisissez l’une des options suivantes pour accéder au panneau Mapper les données :

  • À partir de n’importe quelle page de l’appareil, sélectionnez Gérer l’appareil > Mapper les données :

    Capture d’écran montrant l’élément de menu **Mapper les données**.

  • À partir de la vue Données brutes de votre appareil, développez un message de télémétrie, placez le pointeur de la souris sur un chemin d’accès, puis sélectionnez Ajouter un alias. Le panneau Mapper les données s’ouvre avec l’expression JSONPath copiée dans le champ Chemin JSON :

    Capture d’écran montrant l’option **Ajouter un alias** sur la vue **Données brutes**.

La partie gauche du panneau Mapper les données affiche le dernier message de votre appareil. Pointez sur le pointeur de la souris sur une partie des données, puis sélectionnez Ajouter un alias. L’expression JSONPath est copiée dans le chemin JSON. Ajoutez un nom d’alias ne comportant pas plus de 64 caractères. Vous ne pouvez pas utiliser l’alias pour faire référence à un champ dans un objet complexe défini dans le modèle d’appareil.

Ajoutez le nombre de mappages dont vous avez besoin, puis sélectionnez Enregistrer :

Capture d’écran de la vue **Mapper les données** montrant le chemin d’accès JSON et l’alias.

Pour un appareil donné :

  • Deux mappages ne peuvent pas avoir le même chemin JSON.
  • Deux mappages ne peuvent pas avoir le même alias.

Conseil

Vous devrez peut-être attendre quelques minutes avant que votre appareil envoie un message de télémétrie à afficher dans le panneau de gauche. S’il n’y a toujours pas de données dans le panneau de gauche, vous pouvez entrer manuellement une expression JSONPath dans le champ Chemin JSON.

Pour vérifier que IoT Central mappe la télémétrie, accédez à la vue Données brutes de votre appareil et consultez la section _mappeddata :

Capture d’écran montrant la section Données mappées dans un message dans la vue **Données brutes**.

Si vous ne voyez pas vos données mappées après l’actualisation des Données brutes plusieurs fois, vérifiez que l’expression JSONPath que vous utilisez correspond à la structure du message de télémétrie.

Pour les appareils IoT Edge, le mappage des données s’applique aux données de télémétrie de l’ensemble des modules et des hubs IoT Edge. Vous ne pouvez pas appliquer de mappages à un seul module Azure IoT Edge.

Pour les appareils affectés à un modèle d’appareil, vous ne pouvez pas mapper les données des composants ou des interfaces héritées. Toutefois, vous pouvez mapper toutes les données de votre appareil avant de les affecter à un modèle d’appareil.

Gérer des mappages

Pour afficher, modifier ou supprimer des mappages, accédez à la page Alias mappés . Sélectionnez un mappage pour le modifier ou le supprimer. Vous pouvez sélectionner plusieurs mappages et les supprimer en même temps :

Capture d’écran montrant la vue **Alias mappés** avec les boutons Modifier et Supprimer.

Par défaut, les exportations de données à partir d’IoT Central incluent des données mappées. Pour exclure les données mappées, utilisez une transformation de données dans votre exportation de données.

Mapper les données de télémétrie non modélisées

Vous pouvez mapper les données de télémétrie non modélisées, y compris les données de télémétrie venant de composants non modélisés. Par exemple, étant donné les données de télémétrie workingSet définies dans le composant racine et les données de télémétrie temperature définies dans un composant thermostat indiqué dans l’exemple suivant :

{
  "_unmodeleddata": {
    "workingSet": 74
  },
  "_eventtype": "Telemetry",
  "_timestamp": "2022-07-18T09:22:40.257Z"
}

{
  "_unmodeleddata": {
    "thermostat2": {
      "__t": "c",
      "temperature": 44
    }
  },
  "_eventtype": "Telemetry",
  "_timestamp": "2022-07-18T09:21:48.69Z"
}

Vous pouvez mapper cette télémétrie à l’aide des définitions de mappage suivantes :

  • $["workingSet"] ws
  • $["temperature"] temp

Remarque

N’incluez pas le nom du composant dans la définition de mappage.

Les résultats de ces règles de mappage ressemblent aux exemples suivants :

{
  "telemetries": {
    "workingSet": 84,
    "_mappeddata": {
      "ws": 84
    }
  }
}

{
  "_unmodeleddata": {
    "thermostat2": {
      "__t": "c",
      "temperature": 12
    },
    "_mappeddata": {
      "thermostat2": {
        "__t": "c",
        "temp": 12
      }
    }
  },
  "_eventtype": "Telemetry",
  "_timestamp": "2022-07-18T09:31:21.088Z"
}

Vous pouvez maintenant utiliser les alias mappés pour afficher les données de télémétrie sur un graphique ou un tableau de bord. Vous pouvez également utiliser les alias mappés lorsque vous exportez des données de télémétrie.