Transformer des données avec une carte dans des graphiques de flux de données

Dans Opérations Azure IoT, une transformation cartographique prend chaque message entrant dans un graphique de flux de données et produit un message de sortie basé sur vos règles. Vous pouvez renommer des champs, les réorganiser en nouvelles structures, calculer des valeurs dérivées ou supprimer des champs indésirables. En utilisant les règles des jokers, vous pouvez copier tous les champs en même temps.

Pour obtenir une vue d’ensemble des graphiques de flux de données et la façon dont les transformations composent dans un pipeline, consultez vue d’ensemble des graphiques de flux de données.

Les transformations utilisent un langage d’expressions pour calculer les valeurs, les conditions de test et les champs de référence. Les expressions désignent les entrées par position, et non par le nom : la première entrée de la inputs liste est $1, la seconde est $2, et ainsi de suite. Des fonctions intégrées telles que cToF convertissent et manipulent ces valeurs.

Pour la liste complète des opérateurs, fonctions, types de données et champs de métadonnées, voir la référence Expressions.

Prerequisites

Instance de Opérations Azure IoT déployée dans un cluster Kubernetes. Pour plus d’informations, consultez Deploy Opérations Azure IoT.

Un point de terminaison de registre par défaut nommé default qui pointe vers mcr.microsoft.com est créé automatiquement pendant le déploiement. Les transformations intégrées utilisent ce point de terminaison.

Les exemples Azure CLI de cet article utilisent des variables d’environnement afin de pouvoir définir chaque valeur une fois puis copier-coller les commandes as-is. Si vous utilisez l'environnement Opérations Azure IoT Codespaces du quickstart, ces variables sont déjà définies pour vous et vous pouvez sauter cette étape. Sinon, définissez les variables d’environnement suivantes dans votre shell avant d’exécuter les commandes.

Les scripts suivants définissent les variables d’environnement les plus couramment utilisées :

Variable d'environnement	Description
`SUBSCRIPTION_ID`	L’identifiant de l’abonnement contenant votre instance Opérations Azure IoT.
`RESOURCE_GROUP`	Le nom du groupe de ressources contenant votre instance Opérations Azure IoT.
`AIO_INSTANCE_NAME`	Le nom de votre instance Opérations Azure IoT. Pour lister vos instances, exécutez `az iot ops list -o table`.
`CLUSTER_NAME`	Le nom du cluster Kubernetes compatible Azure Arc qui héberge votre instance.
`LOCATION`	La région Azure à utiliser pour de nouvelles ressources, par exemple `eastus`.

Bash
Powershell

SUBSCRIPTION_ID=<subscription-id>
RESOURCE_GROUP=<resource-group-name>
AIO_INSTANCE_NAME=<instance-name>
CLUSTER_NAME=<cluster-name>
LOCATION=<region>

$SUBSCRIPTION_ID = "<subscription-id>"
$RESOURCE_GROUP = "<resource-group-name>"
$AIO_INSTANCE_NAME = "<instance-name>"
$CLUSTER_NAME = "<cluster-name>"
$LOCATION = "<region>"

Vous n’avez qu’à définir les variables utilisées dans cet article. Cet article peut utiliser des variables d’environnement supplémentaires pour les noms de ressources que vous choisissez. L’article explique comment les placer là où ils sont introduits.

Fonctionnement des règles de mappage

Chaque règle de carte comporte quatre parties :

Propriété	Obligatoire	Description
`inputs`	Oui	Liste des chemins de champ à lire à partir du message entrant.
`output`	Oui	Chemin de champ où le résultat apparaît dans le message de sortie.
`expression`	Non	Formule appliquée aux valeurs d’entrée. Si vous l’omettez, la première valeur d’entrée se copie directement.
`description`	Non	Étiquette lisible par les humains pour la règle, incluse dans les messages d’erreur.

La transformation de l’application attribue des variables de position aux entrées dans l’ordre. Par exemple, si inputs est , alors ['Position', 'Office'] est la valeur de $1 et Position est la valeur de $2Office.

Renommer un champ

Pour renommer BirthDateDateOfBirth, mappez une entrée à un autre chemin de sortie. Tu n’as pas besoin d’expression. La valeur est copiée telle quelle.

Dans la configuration de la transformation de carte, ajoutez une règle :

Réglage	Valeur
Input	`BirthDate`
Output	`DateOfBirth`

L’outil en ligne de commande applique l’intégralité du graphe à partir d’un seul fichier de configuration. Ajoutez donc ceci à l’emplacement correspondant dans votre graph.json et appliquez-le avec az iot ops dataflowgraph apply :

{
  "inputs": [
    "BirthDate"
  ],
  "output": "DateOfBirth"
}

{
  inputs: [
    'BirthDate'
  ]
  output: 'DateOfBirth'
}

Important

L’utilisation des manifestes de déploiement Kubernetes n’est pas prise en charge dans les environnements de production et ne doit être utilisée que pour le débogage et le test.

- inputs:
    - BirthDate
  output: DateOfBirth

Restructurer les champs

Utilisez la notation par points dans le chemin de sortie pour déplacer des champs dans une structure imbriquée.

Ajoutez deux règles :

Input	Sortie
`Name`	`Employee.Name`
`BirthDate`	`Employee.DateOfBirth`

{
  "inputs": [
    "Name"
  ],
  "output": "Employee.Name"
},
{
  "inputs": [
    "BirthDate"
  ],
  "output": "Employee.DateOfBirth"
}

{
  inputs: [ 'Name' ]
  output: 'Employee.Name'
}
{
  inputs: [ 'BirthDate' ]
  output: 'Employee.DateOfBirth'
}

Important

L’utilisation des manifestes de déploiement Kubernetes n’est pas prise en charge dans les environnements de production et ne doit être utilisée que pour le débogage et le test.

- inputs:
    - Name
  output: Employee.Name

- inputs:
    - BirthDate
  output: Employee.DateOfBirth

Étant donné cette entrée :

{
  "Name": "Grace Owens",
  "BirthDate": "19840202",
  "Position": "Analyst"
}

Ces deux règles produisent :

{
  "Employee": {
    "Name": "Grace Owens",
    "DateOfBirth": "19840202"
  }
}

Seuls les champs répertoriés dans la sortie d’une règle apparaissent dans le résultat. Le résultat n’inclut pas le Position champ car aucune règle ne le mappe.

Combiner plusieurs entrées

Lorsque vous listez plusieurs entrées, utilisez leurs variables de position pour les fusionner dans une expression.

Ajoutez une règle :

Réglage	Valeur
Entrées	`Position`, `Office`
Output	`Employment.Position`
Expression	`$1 + ", " + $2`

{
  "inputs": [
    "Position",
    "Office"
  ],
  "output": "Employment.Position",
  "expression": "$1 + \", \" + $2"
}

{
  inputs: [ 'Position', 'Office' ]
  output: 'Employment.Position'
  expression: '$1 + ", " + $2'
}

Important

L’utilisation des manifestes de déploiement Kubernetes n’est pas prise en charge dans les environnements de production et ne doit être utilisée que pour le débogage et le test.

- inputs:
    - Position     # $1
    - Office       # $2
  output: Employment.Position
  expression: "$1 + \", \" + $2"

Donné Position: "Analyst" et Office: "Kent, WA", la sortie est "Analyst, Kent, WA".

Transformer des valeurs avec des expressions

Utilisez le expression champ pour appliquer des fonctions intégrées ou des arithmétiques. L’exemple suivant utilise cToF, une fonction de conversion unitaire intégrée qui convertit une valeur Celsius en Fahrenheit. N’oubliez pas que cela $1 fait référence à la première entrée, pas à un nom de champ.

Pour la liste complète des opérateurs, fonctions et fonctionnalités avancées, voir la référence Expressions. Les groupes de référence fonctionnent par catégorie, telles que la conversion d’unités, l’échelle et l’arrondi, les mathématiques et les fonctions de chaînes .

Ajoutez une règle de calcul. Par exemple, pour convertir Celsius en Fahrenheit :

Réglage	Valeur
Input	`temperature`
Output	`temperature_f`
Expression	`cToF($1)`

Pour mettre à l’échelle une lecture de capteur à une plage de 0 à 100, utilisez l’expression scale($1, 0, 4095, 0, 100).

{
  "inputs": [
    "temperature"
  ],
  "output": "temperature_f",
  "expression": "cToF($1)"
}

Pour mettre à l’échelle une lecture de capteur :

{
  "inputs": [
    "raw_pressure"
  ],
  "output": "pressure_pct",
  "expression": "scale($1, 0, 4095, 0, 100)"
}

{
  inputs: [ 'temperature' ]
  output: 'temperature_f'
  expression: 'cToF($1)'
}

Pour mettre à l’échelle une lecture de capteur :

{
  inputs: [ 'raw_pressure' ]
  output: 'pressure_pct'
  expression: 'scale($1, 0, 4095, 0, 100)'
}

Important

L’utilisation des manifestes de déploiement Kubernetes n’est pas prise en charge dans les environnements de production et ne doit être utilisée que pour le débogage et le test.

- inputs:
    - temperature     # $1
  output: temperature_f
  expression: "cToF($1)"

Pour mettre à l’échelle une lecture de capteur :

- inputs:
    - raw_pressure     # $1
  output: pressure_pct
  expression: "scale($1, 0, 4095, 0, 100)"

Copier tous les champs avec des caractères génériques

Lorsque la sortie doit correspondre étroitement à l’entrée avec seulement quelques modifications, utilisez une règle générique pour copier chaque champ à la fois. Ensuite, ajoutez des règles pour remplacer, ajouter ou supprimer des champs spécifiques.

Ajoutez une règle de passthrough qui copie tous les champs. Définissez l’entrée sur * et la sortie sur *.

{
  "inputs": [
    "*"
  ],
  "output": "*"
}

{
  inputs: [ '*' ]
  output: '*'
}

Important

L’utilisation des manifestes de déploiement Kubernetes n’est pas prise en charge dans les environnements de production et ne doit être utilisée que pour le débogage et le test.

- inputs:
    - '*'
  output: '*'

Exigences des règles de caractères génériques

Une règle générique doit être la première règle dans votre configuration de carte.
Une transformation de carte ne supporte qu’une seule règle de joker.
L’astérisque correspond à un ou plusieurs segments de chemin d’accès et doit représenter un segment complet. La transformation de la carte ne supporte pas les motifs partiels comme partial*.

Caractères génériques de préfixe

Attribuez un préfixe spécifique au joker de la carte sauvage. Pour aplatir tous les champs depuis ColorProperties jusqu'au niveau racine :

Ajoutez une règle avec entrée ColorProperties.* et sortie *.

{
  "inputs": [
    "ColorProperties.*"
  ],
  "output": "*"
}

{
  inputs: [ 'ColorProperties.*' ]
  output: '*'
}

Important

L’utilisation des manifestes de déploiement Kubernetes n’est pas prise en charge dans les environnements de production et ne doit être utilisée que pour le débogage et le test.

- inputs:
    - 'ColorProperties.*'
  output: '*'

Soit :

{
  "ColorProperties": {
    "Hue": "blue",
    "Saturation": "90%",
    "Brightness": "50%"
  }
}

La sortie est la suivante :

{
  "Hue": "blue",
  "Saturation": "90%",
  "Brightness": "50%"
}

Supprimer des champs de la sortie

Définissez la output valeur sur une chaîne vide pour exclure des champs spécifiques. En général, on utilise cette approche après une règle de joker : copier tout, puis retirer ce dont tu n’as pas besoin.

Ajoutez une règle de passthrough pour copier tous les champs.
Ajoutez une règle de suppression et sélectionnez les champs à exclure (par exemple, password et internal_id).

{
  "inputs": [
    "*"
  ],
  "output": "*"
},
{
  "inputs": [
    "password",
    "internal_id"
  ],
  "output": ""
}

{
  inputs: [ '*' ]
  output: '*'
}
{
  inputs: [ 'password', 'internal_id' ]
  output: ''
}

Important

L’utilisation des manifestes de déploiement Kubernetes n’est pas prise en charge dans les environnements de production et ne doit être utilisée que pour le débogage et le test.

- inputs:
    - '*'
  output: '*'

- inputs:
    - password
    - internal_id
  output: ""

Une règle de suppression ne peut pas inclure d’expression.

Vous pouvez remplacer les caractères génériques pour des champs spécifiques.

Lorsqu’une règle générique et une règle spécifique correspondent tous deux au même champ, la règle plus spécifique est prioritaire.

Ajoutez une règle de passthrough pour copier tous les champs.
Ajoutez une règle de calcul pour temperature avec l’expression cToF($1).

La transformation de carte applique la règle spécifique à temperature et copie tous les autres champs as-is.

{
  "inputs": [
    "*"
  ],
  "output": "*"
},
{
  "inputs": [
    "temperature"
  ],
  "output": "temperature",
  "expression": "cToF($1)"
}

{
  inputs: [ '*' ]
  output: '*'
}
{
  inputs: [ 'temperature' ]
  output: 'temperature'
  expression: 'cToF($1)'
}

Important

L’utilisation des manifestes de déploiement Kubernetes n’est pas prise en charge dans les environnements de production et ne doit être utilisée que pour le débogage et le test.

- inputs:
    - '*'
  output: '*'

- inputs:
    - temperature     # $1
  output: temperature
  expression: "cToF($1)"

Utiliser des champs de métadonnées

Lisez et écrivez sur les métadonnées des messages comme les sujets MQTT et les propriétés utilisateur. Consultez les champs métadonnées dans la référence des expressions.

Ajoutez une règle avec entrée region et sortie $metadata.user_property.region pour écrire une valeur de champ dans une propriété utilisateur MQTT.

{
  "inputs": [
    "*"
  ],
  "output": "*"
},
{
  "inputs": [
    "region"
  ],
  "output": "$metadata.user_property.region"
}

{
  inputs: [ '*' ]
  output: '*'
}
{
  inputs: [ 'region' ]
  output: '$metadata.user_property.region'
}

Important

L’utilisation des manifestes de déploiement Kubernetes n’est pas prise en charge dans les environnements de production et ne doit être utilisée que pour le débogage et le test.

- inputs:
    - '*'
  output: '*'

- inputs:
    - region
  output: $metadata.user_property.region

Pour obtenir un exemple complet de routage de rubriques dynamiques, consultez Acheminer les messages vers différentes rubriques.

Utiliser la dernière valeur connue et les valeurs par défaut

Lorsque les données du capteur arrivent par intermittence, vous pouvez renseigner les champs manquants avec la dernière valeur connue ou une valeur statique par défaut. Consultez la dernière valeur connue et les valeurs par défaut dans la référence des expressions.

Ajoutez une règle pour le temperature champ et activez la dernière valeur connue. Définissez une valeur par défaut de 0 comme solution de secours.

{
  "inputs": [
    "temperature ? $last ?? 0"
  ],
  "output": "temperature"
}

{
  inputs: [ 'temperature ? $last ?? 0' ]
  output: 'temperature'
}

Important

L’utilisation des manifestes de déploiement Kubernetes n’est pas prise en charge dans les environnements de production et ne doit être utilisée que pour le débogage et le test.

- inputs:
    - temperature ? $last ?? 0     # $1
  output: temperature

Cette règle utilise la valeur actuelle lorsqu’elle est présente, revient à la dernière valeur connue et utilise 0 si aucun des deux n’est disponible.

Enrichir avec des données externes

L’enrichissement est optionnel. Vous n’en avez besoin que si vous souhaitez combiner les messages entrants avec les données de référence stockées dans le magasin d’états, comme une table de recherche des métadonnées de l’appareil. Si vos messages contiennent déjà tout ce dont vous avez besoin, passez cette section.

Lorsque vous avez besoin d’enrichissement, configurez un jeu de données de contextualisation que le moteur d’exécution interroge pendant le traitement. Par exemple, recherchez les métadonnées d’un appareil par son ID et incluez-la dans la sortie. Pour plus d’informations, consultez Enrichir avec des données externes.

Fonctionnalités exclusives du graphe de flux de données

Les graphiques de flux de données prennent en charge plusieurs fonctionnalités qui ne sont pas disponibles dans les mappages de flux builtInTransformation de données.

Valeurs par défaut pour les champs manquants

Utilisez la syntaxe ?? <default> sur une entrée pour fournir une solution de repli statique lorsqu'un champ est manquant. Cela est plus simple que d’écrire une if expression pour rechercher des valeurs vides.

Dans la configuration de la transformation de carte, définissez l’entrée pour inclure la ?? syntaxe suivie de la valeur par défaut. Par exemple, entrez temperature ?? 0 en tant que champ d’entrée à utiliser 0 lorsque le champ de température est manquant.

{
  "inputs": [
    "temperature ?? 0"
  ],
  "output": "temperature"
}

{
  inputs: [ 'temperature ?? 0' ]
  output: 'temperature'
}

Important

L’utilisation des manifestes de déploiement Kubernetes n’est pas prise en charge dans les environnements de production et ne doit être utilisée que pour le débogage et le test.

- inputs:
    - temperature ?? 0
  output: temperature

Pour plus d’informations sur les types par défaut pris en charge et la combinaison des valeurs par défaut avec les dernières valeurs connues, consultez Valeurs par défaut dans la référence des expressions.

Fonctions Regex

Les graphiques de flux de données prennent en charge la correspondance et le remplacement des expressions régulières :

str::regex_matches(string, pattern): retourne true si la chaîne correspond au modèle regex.
str::regex_replace(string, pattern, replacement): remplace toutes les correspondances regex par la chaîne de remplacement.

Ces fonctions sont utiles dans les expressions de filtre ou pour nettoyer et transformer des données de chaîne. Pour obtenir la liste complète des fonctions de chaîne, consultez Fonctions de chaîne dans la référence d’expressions.

Exemple de configuration complète

Voici une configuration de carte complète qui copie tous les champs, supprime les données sensibles, restructure un champ et calcule une valeur dérivée :

Capture d’écran du panneau de configuration de transformation de la carte d’expérience des opérations montrant plusieurs règles pour le caractère générique, la suppression, la restructuration, le calcul et la fusion

Dans l’expérience Opérations, créez un graphique de flux de données et ajoutez une transformation de carte. Dans le panneau de configuration de la carte, ajoutez des règles à :

Copier tous les champs avec un passage générique.
Supprimez les champs sensibles en définissant la sortie sur vide pour password et secret_key.
Restructurez le BirthDate champ en Employee.DateOfBirth.
Calculez une conversion Fahrenheit en utilisant la formule cToF($1) du temperature champ.
Fusionnez les champs Position et Office avec la formule $1 + ", " + $2.

Le Azure CLI applique un graphe de flux de données à partir d’un seul fichier de configuration JSON. Créez un graph.json fichier avec les propriétés du graphique. Dans le graph.json fichier, le value champ stocke les règles de chaque transformation sous forme de chaîne JSON échappée. Pour obtenir la forme lisible des règles de chaque transformation, consultez la procédure de ce type de transformation.

{
  "mode": "Enabled",
  "nodes": [
    {
      "nodeType": "Source",
      "name": "sensors",
      "sourceSettings": {
        "endpointRef": "default",
        "dataSources": [
          "telemetry/sensors"
        ]
      }
    },
    {
      "nodeType": "Graph",
      "name": "transform",
      "graphSettings": {
        "registryEndpointRef": "default",
        "artifact": "azureiotoperations/graph-dataflow-map:1.0.0",
        "configuration": [
          {
            "key": "rules",
            "value": "{\"map\":[{\"inputs\":[\"*\"],\"output\":\"*\",\"description\":\"Copy all fields\"},{\"inputs\":[\"password\",\"secret_key\"],\"output\":\"\",\"description\":\"Remove sensitive fields\"},{\"inputs\":[\"BirthDate\"],\"output\":\"Employee.DateOfBirth\",\"description\":\"Restructure birth date\"},{\"inputs\":[\"temperature\"],\"output\":\"temperature_f\",\"expression\":\"cToF($1)\",\"description\":\"Convert Celsius to Fahrenheit\"},{\"inputs\":[\"Position\",\"Office\"],\"output\":\"Employment.Position\",\"expression\":\"$1 + \\\", \\\" + $2\",\"description\":\"Merge position and office\"}]}"
          }
        ]
      }
    },
    {
      "nodeType": "Destination",
      "name": "output",
      "destinationSettings": {
        "endpointRef": "default",
        "dataDestination": "telemetry/processed"
      }
    }
  ],
  "nodeConnections": [
    {
      "from": {
        "name": "sensors"
      },
      "to": {
        "name": "transform"
      }
    },
    {
      "from": {
        "name": "transform"
      },
      "to": {
        "name": "output"
      }
    }
  ]
}

Tip

Pour générer la chaîne échappée, sauvegardez les règles dans un fichier comme rules.json, exécutez jq -c . rules.json, puis collez la sortie ligne unique dans le value champ.

Appliquez le fichier de configuration.

az iot ops dataflowgraph apply \
  --name temperature-map-example \
  --instance $AIO_INSTANCE_NAME \
  --resource-group $RESOURCE_GROUP \
  --config-file graph.json

resource dataflowGraph 'Microsoft.IoTOperations/instances/dataflowProfiles/dataflowGraphs@2026-03-01' = {
  name: 'temperature-map-example'
  parent: dataflowProfile
  properties: {
    mode: 'Enabled'
    nodes: [
      {
        nodeType: 'Source'
        name: 'sensors'
        sourceSettings: {
          endpointRef: 'default'
          dataSources: [
            'telemetry/sensors'
          ]
        }
      }
      {
        nodeType: 'Graph'
        name: 'transform'
        graphSettings: {
          registryEndpointRef: 'default'
          artifact: 'azureiotoperations/graph-dataflow-map:1.0.0'
          configuration: [
            {
              key: 'rules'
              value: '{"map":[{"inputs":["*"],"output":"*","description":"Copy all fields"},{"inputs":["password","secret_key"],"output":"","description":"Remove sensitive fields"},{"inputs":["BirthDate"],"output":"Employee.DateOfBirth","description":"Restructure birth date"},{"inputs":["temperature"],"output":"temperature_f","expression":"cToF($1)","description":"Convert Celsius to Fahrenheit"},{"inputs":["Position","Office"],"output":"Employment.Position","expression":"$1 + \\", \\" + $2","description":"Merge position and office"}]}'
            }
          ]
        }
      }
      {
        nodeType: 'Destination'
        name: 'output'
        destinationSettings: {
          endpointRef: 'default'
          dataDestination: 'telemetry/processed'
        }
      }
    ]
    nodeConnections: [
      {
        from: { name: 'sensors' }
        to: { name: 'transform' }
      }
      {
        from: { name: 'transform' }
        to: { name: 'output' }
      }
    ]
  }
}

Important

L’utilisation des manifestes de déploiement Kubernetes n’est pas prise en charge dans les environnements de production et ne doit être utilisée que pour le débogage et le test.

La configuration des règles est une chaîne JSON placée en tant que value pour la clé rules dans la section DataflowGraph du nœud de transformation configuration :

{
  "map": [
    {
      "inputs": ["*"],
      "output": "*",
      "description": "Copy all fields"
    },
    {
      "inputs": ["password", "secret_key"],
      "output": "",
      "description": "Remove sensitive fields"
    },
    {
      "inputs": ["BirthDate"],
      "output": "Employee.DateOfBirth",
      "description": "Restructure birth date"
    },
    {
      "inputs": ["temperature"],
      "output": "temperature_f",
      "expression": "cToF($1)",
      "description": "Convert Celsius to Fahrenheit"
    },
    {
      "inputs": ["Position", "Office"],
      "output": "Employment.Position",
      "expression": "$1 + \", \" + $2",
      "description": "Merge position and office"
    }
  ]
}

Pour obtenir la structure complète DataflowGraph des ressources, consultez la vue d’ensemble des graphiques de flux de données.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-07-31

Transformer des données avec une carte dans des graphiques de flux de données

Prerequisites

Fonctionnement des règles de mappage

Renommer un champ

Restructurer les champs

Combiner plusieurs entrées

Transformer des valeurs avec des expressions

Copier tous les champs avec des caractères génériques

Exigences des règles de caractères génériques

Caractères génériques de préfixe

Supprimer des champs de la sortie

Vous pouvez remplacer les caractères génériques pour des champs spécifiques.

Utiliser des champs de métadonnées

Utiliser la dernière valeur connue et les valeurs par défaut

Enrichir avec des données externes

Fonctionnalités exclusives du graphe de flux de données

Valeurs par défaut pour les champs manquants

Fonctions Regex

Exemple de configuration complète

Contenu connexe

Commentaires

Ressources supplémentaires