Convertir des données à l’aide de conversions de flux de données

Vous pouvez utiliser des conversions de flux de données pour transformer des données dans Opérations Azure IoT. L’élément conversion dans un flux de données est utilisé pour calculer des valeurs pour les champs de sortie. Vous pouvez utiliser des champs d’entrée, des opérations disponibles, des types de données et des conversions de types dans les conversions de flux de données.

L’élément conversion d’un flux de données est utilisé pour calculer des valeurs pour les champs de sortie :

inputs: [
  '*.Max' // - $1
  '*.Min' // - $2
]
output: 'ColorProperties.*'
expression: '($1 + $2) / 2'

- inputs:
  - *.Max   # - $1
  - *.Min   # - $2
  output: ColorProperties.*
  expression: ($1 + $2) / 2

Plusieurs aspects doivent être compris concernant les conversions :

• Référence aux champs d’entrée : comment référencer les valeurs des champs d’entrée dans la formule de conversion.
• Opérations disponibles : opérations qui peuvent être utilisées dans les conversions. Par exemple : addition, soustraction, multiplication et division.
• Types de données : types de données qu’une formule peut traiter et manipuler. Par exemple : entier, nombre à virgule flottante et chaîne.
• Conversions de types : comment les types de données sont convertis entre les valeurs des champs d’entrée, l’évaluation de la formule et les champs de sortie.

Champs d’entrée

Dans les conversions, les formules peuvent opérer sur des valeurs statiques comme un nombre tel que 25 ou sur des paramètres dérivés des champs d’entrée. Un mappage définit les champs d’entrée auxquels la formule peut accéder. Chaque champ est référencé en fonction de sa position dans la liste d’entrée :

inputs: [
  '*.Max'      // - $1
  '*.Min'      // - $2
  '*.Mid.Avg'  // - $3
  '*.Mid.Mean' // - $4
]
output: 'ColorProperties.*'
expression: '($1, $2, $3, $4)'

- inputs:
  - *.Max        # - $1
  - *.Min        # - $2
  - *.Mid.Avg    # - $3
  - *.Mid.Mean   # - $4
  output: ColorProperties.*
  expression: ($1, $2, $3, $4)

Dans cet exemple, la conversion génère un tableau contenant les valeurs de [Max, Min, Mid.Avg, Mid.Mean]. Les commentaires inclus dans le fichier YAML (# - $1, # - $2) sont facultatifs, mais ils aident à clarifier la connexion entre chaque propriété de champ et son rôle dans la formule de conversion.

Types de données

Différents formats de sérialisation prennent en charge différents types de données. Par exemple, JSON propose quelques types primitifs : chaîne, nombre, booléen et null. Il inclut également des tableaux de ces types primitifs.

Lorsque le mappeur lit une propriété d’entrée, il la convertit en un type interne. Cette conversion est nécessaire pour conserver les données en mémoire jusqu’à ce qu’elles soient écrites dans un champ de sortie. La conversion en un type interne se produit, que les formats de sérialisation d’entrée et de sortie soient identiques ou non.

La représentation interne utilise les types de données suivants :

Champs d’enregistrement d’entrée

Lorsqu’un champ d’enregistrement d’entrée est lu, son type sous-jacent est converti en l’une de ces variantes de type interne. La représentation interne est suffisamment polyvalente pour gérer la plupart des types d’entrée avec une conversion minimale, voire aucune conversion.

Pour certains formats, des types de substitution sont utilisés. Par exemple, JSON ne possède pas de type datetime et stocke à la place les valeurs datetime sous forme de chaînes formatées selon ISO8601. Lorsque le mappeur lit un tel champ, la représentation interne reste une chaîne.

Champs d’enregistrement de sortie

Le mappeur est conçu pour être flexible en convertissant des types internes en types de sortie afin de prendre en charge les scénarios où les données proviennent d’un format de sérialisation avec un système de type limité. Les exemples suivants montrent comment les conversions sont gérées :

• Types numériques : ces types peuvent être convertis en d’autres représentations, même si cela signifie une perte de précision. Par exemple, un nombre à virgule flottante 64 bits (f64) peut être converti en entier 32 bits (i32).
• Chaînes en nombres : si l’enregistrement entrant contient une chaîne telle que 123 et que le champ de sortie est un entier 32 bits, le mappeur convertit et écrit la valeur sous forme de nombre.
• Chaînes en d’autres types :
  • Si le champ de sortie est datetime, le mappeur tente d’analyser la chaîne comme un datetime formaté selon la norme ISO8601.
  • Si le champ de sortie est binary/bytes, le mappeur tente de désérialiser la chaîne à partir d’une chaîne encodée en base64.
• Valeurs booléennes :
  • Converti en 0/1 si le champ de sortie est numérique.
  • Converti en true/false si le champ de sortie est une chaîne.

Utiliser une formule de conversion avec des types

Dans les mappages, une formule facultative peut spécifier la façon dont les données de l’entrée sont traitées avant d’être écrites dans le champ de sortie. Si aucune formule n’est spécifiée, le mappeur copie le champ d’entrée dans la sortie en utilisant le type interne et les règles de conversion.

Si une formule est spécifiée, les types de données disponibles pour une utilisation dans les formules sont limités à :

• Entiers
• Nombres à virgule flottante
• Chaînes
• valeurs booléennes
• Tableaux des types précédents
• Valeur manquante

Map et byte ne peuvent pas participer aux formules.

Les types liés à l’heure (datetime, time et duration) sont convertis en valeurs entières qui représentent le temps en secondes. Après l’évaluation de la formule, les résultats sont stockés dans la représentation interne et ne sont pas reconvertis. Par exemple, datetime converti en secondes reste un entier. Si la valeur sera utilisée dans les champs datetime, une méthode de conversion explicite doit être appliquée. Un exemple consiste à convertir la valeur en chaîne ISO8601 qui est automatiquement convertie en type datetime par le format de sérialisation de sortie.

Utiliser des types irréguliers

Des considérations spéciales s’appliquent aux types tels que les tableaux et valeur manquante.

Tableaux

Les tableaux peuvent être traités à l’aide de fonctions d’agrégation pour calculer une valeur unique à partir de plusieurs éléments. Par exemple, à l’aide de l’enregistrement d’entrée :

{
  "Measurements": [2.34, 12.3, 32.4]
}

Avec le mappage :

inputs: [
  'Measurements' // - $1
]
output: 'Measurement'
expression: 'min($1)'

- inputs:
  - Measurements # - $1
  output: Measurement
  expression: min($1)

Cette configuration sélectionne la plus petite valeur dans le tableau Measurements pour le champ de sortie.

Les tableaux peuvent également être créés à partir de plusieurs valeurs uniques :

inputs: [
  'minimum' // - - $1
  'maximum' // - - $2
  'average' // - - $3
  'mean'    // - - $4
]
output: 'stats'
expression: '($1, $2, $3, $4)'

- inputs:
  - minimum  # - - $1
  - maximum  # - - $2
  - average  # - - $3
  - mean     # - - $4
  output: stats
  expression: ($1, $2, $3, $4)

Ce mappage crée un tableau contenant le minimum, le maximum et la moyenne.

Valeur manquante

Valeur manquante est un type spécial utilisé dans des scénarios, tels que :

• Gestion des champs manquants dans l’entrée en fournissant une valeur de remplacement.
• Suppression conditionnelle d’un champ en fonction de sa présence.

Exemple de mappage qui utilise une valeur manquante :

{
  "Employment": {      
    "Position": "Analyst",
    "BaseSalary": 75000,
    "WorkingHours": "Regular"
  }
}

L’enregistrement d’entrée contient le champ BaseSalary, mais celui-ci peut être facultatif. Supposons que si le champ est manquant, une valeur doit être ajoutée à partir d’un jeu de données de contextualisation :

{
  "Position": "Analyst",
  "BaseSalary": 70000,
  "WorkingHours": "Regular"
}

Un mappage peut vérifier si le champ est présent dans l’enregistrement d’entrée. Si le champ est trouvé, la sortie reçoit cette valeur existante. Sinon, la sortie reçoit la valeur du jeu de données de contexte. Voici un exemple :

inputs: [
  'BaseSalary' // - - - - - - - - - - - $1
  '$context(position).BaseSalary' //  - $2
]
output: 'BaseSalary'
expression: 'if($1 == (), $2, $1)'

- inputs:
  - BaseSalary  # - - - - - - - - - - $1
  - $context(position).BaseSalary # - $2
  output: BaseSalary
  expression: if($1 == (), $2, $1)

La conversion utilise la fonction if qui comporte trois paramètres :

• Le premier paramètre est une condition. Dans cet exemple, il vérifie si le champ BaseSalary du champ d’entrée (alias $1) correspond à la valeur manquante.
• Le deuxième paramètre est le résultat de la fonction si la condition du premier paramètre est vraie. Dans cet exemple, il s’agit du champ BaseSalary du jeu de données de contextualisation (alias $2).
• Le troisième paramètre est la valeur utilisée si la condition du premier paramètre est fausse.

Fonctions disponibles

Les flux de données fournissent un ensemble de fonctions intégrées qui peuvent être utilisées dans les formules de conversion. Ces fonctions permettent d’effectuer des opérations courantes telles que l’arithmétique, la comparaison et la manipulation de chaînes. Les fonctions disponibles sont les suivantes :

Fonctions de conversion

Les flux de données fournissent plusieurs fonctions de conversion intégrées pour les conversions d’unités courantes, telles que la température, la pression, la longueur, le poids et le volume. Voici quelques exemples :

Les conversions inverses sont également prises en charge :

En outre, vous pouvez définir vos propres fonctions de conversion à l’aide de formules mathématiques de base. Le système prend en charge les opérateurs tels que l’addition (+), la soustraction (-), la multiplication (*) et la division (/). Ces opérateurs suivent les règles standard de précédence, qui peuvent être ajustées à l’aide de parenthèses afin de garantir l’ordre correct des opérations. Cela vous permet de personnaliser les conversions d’unités pour répondre à des besoins spécifiques.

Opérateurs disponibles par précédence

Comme Exponentiation possède la précédence la plus élevée, elle est exécutée en premier, sauf si des parenthèses modifient cet ordre :

• $1 * 2 ^ 3 est interprété comme $1 * 8, car la partie 2 ^ 3 est exécutée en premier, avant la multiplication.
• ($1 * 2) ^ 3 traite la multiplication avant l’élévation à une puissance.

Negation et Logical not ont une précédence élevée, de sorte qu’ils s’appliquent toujours à la valeur qui les suit immédiatement, sauf lorsqu’une élévation à la puissance est impliquée :

• -$1 * 2 applique d’abord la négation à $1, puis effectue la multiplication.
• -($1 * 2) effectue la multiplication, puis applique la négation au résultat.

Multiplication, Division et Modulo ayant la même précédence, ils sont exécutés de gauche à droite, sauf si l’ordre est modifié par des parenthèses.

Addition et Subtraction sont considérés comme des opérations plus faibles par rapport aux opérations du groupe précédent :

• $1 + 2 * 3 donne $1 + 6 parce que 2 * 3 est exécuté en premier en raison de la précédence plus élevée de la multiplication.
• ($1 + 2) * 3 donne la priorité à l’Addition avant la Multiplication.

Comparisons opèrent sur des valeurs numériques, booléennes et de chaînes. Étant donné qu’ils ont une précédence inférieure à celle des opérateurs arithmétiques, aucune parenthèse n’est nécessaire pour comparer efficacement les résultats :

• $1 * 2 <= $2 équivaut à ($1 * 2) <= $2.

Les opérateurs logiques sont utilisés pour chaîner des conditions :

• $1 > 100 && $2 > 200