Partager via

Qu’est-ce que jq dans les pipelines du processeur de données Azure IoT (préversion) ?

  • Article

Important

Opérations Azure IoT (préversion) – activé parc Azure Arc est actuellement en PRÉVERSION. Vous ne devez pas utiliser ce logiciel en préversion dans des environnements de production.

Pour connaître les conditions juridiques qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou plus généralement non encore en disponibilité générale, consultez l’Avenant aux conditions d’utilisation des préversions de Microsoft Azure.

jq est un processeur JSON open source que vous pouvez utiliser pour restructurer et mettre en forme des charges utiles structurées dans des pipelines Azure IoT Data Processor (préversion) :

  • L’index de pipeline filtrer utilise jq pour activer des requêtes de filtre flexibles.
  • L’index de pipeline transformer utilise jq pour activer la transformation des données.

Conseil

jq est différent de jQuery et résout un ensemble différent de problèmes. Quand vous recherchez en ligne des informations sur jq, les résultats de la recherche peuvent inclure des informations sur jQuery. Veillez à ignorer ou à exclure ces informations sur jQuery.

Le jq que vous fournissez dans ces index doit être :

  • Valide sur le plan syntaxique.
  • Valide sur le plan sémantique pour le message auquel le jq est appliqué.

Comment utiliser jq

Il existe deux façons d’utiliser le langage jq dans les index d’un pipeline Data Processor :

  • Avec des expressions qui utilisent toute la puissance du langage jq, notamment la possibilité d’effectuer des manipulations et des calculs arbitraires avec vos données. Les expressions apparaissent dans les index d’un pipeline, comme filtrer et transformer, et sont appelées expressions où elles sont utilisées.
  • Avec des chemins d’accès qui identifient un emplacement unique dans un message. Les chemins d’accès utilisent un petit sous-ensemble du langage jq. Vous utilisez des chemins d’accès pour récupérer des informations à partir de messages et réinsérer les informations calculées dans le message en vue d’un traitement ultérieur dans un pipeline.

Conseil

Ce guide n’offre pas une vision complète des fonctionnalités de jq. Pour obtenir la référence complète du langage, consultez le manuel de jq.

Pour des raisons de performances, Data Processor bloque l’utilisation des fonctions jq suivantes :

  • Modulemeta
  • Range
  • Recurse
  • Until
  • Walk
  • While

Résolution des problèmes

Quand vous générez des chemins d’accès ou des expressions jq au sein du processeur de données, vous devez garder à l’esprit quelques points importants. Si vous rencontrez des problèmes, veillez à ne pas commettre l’une des erreurs suivantes :

Ne pas définir l’étendue sur payload

Tous les messages dans les pipelines du processeur de données commencent par une structure qui place la charge utile du message dans un champ de niveau supérieur appelé payload. Bien que cela ne soit pas obligatoire, il est fortement recommandé, quand vous traitez des messages, de conserver la charge utile principale à l’intérieur du champ payload lorsque le message passe par les différents index du pipeline.

La plupart des cas d’usage pour la transformation et le filtrage impliquent de travailler directement avec la charge utile. Il est donc courant de voir l’intégralité de la requête étendue au champ de charge utile. Vous pouvez oublier que les messages utilisent cette structure et traiter la charge utile comme si elle se trouvait au niveau supérieur.

Le correctif pour cette erreur est simple. Si vous utilisez jq pour :

  • Filtrer les messages : ajoutez .payload | au début de votre expression pour définir correctement son étendue.
  • Transformer des messages :
    • Si vous ne fractionnez pas le message, ajoutez .payload |= au début de votre expression pour définir l’étendue de votre transformation.
    • Si vous fractionnez le message, ajoutez .payload = (.payload | <expression>) autour de votre <expression> pour mettre à jour spécifiquement la charge utile tout en activant le fractionnement du message.

Tentative de combinaison de plusieurs messages

jq propose de nombreuses fonctionnalités pour séparer des messages et les restructurer. Toutefois, un seul message à la fois entrant dans un index de pipeline peut appeler une expression jq. Il n’est donc pas possible d’utiliser seulement des filtres et des transformations pour combiner des données à partir de plusieurs messages d’entrée.

Si vous souhaitez fusionner des valeurs à partir de plusieurs messages, utilisez d’abord un index d’agrégation pour combiner les valeurs, puis utilisez des transformations ou des filtres sur les données combinées.

Séparation d’arguments de fonction avec , au lieu de ;

Contrairement à la plupart des langages de programmation, jq n’utilise pas , pour séparer les arguments de fonction. jq sépare chaque argument de fonction avec ;. Cette erreur peut être difficile à déboguer, car , est une syntaxe valide dans la plupart des cas, mais elle signifie autre chose. Dans jq, , sépare les valeurs d’un flux.

Si vous utilisez un , au lieu d’un ;, l’erreur la plus courante que vous pouvez voir est une plainte indiquant que la fonction que vous essayez d’appeler n’existe pas pour le nombre d’arguments fournis. Si vous obtenez des erreurs de compilation ou d’autres erreurs qui n’ont aucun sens quand vous appelez une fonction, veillez à utiliser ; au lieu de , pour séparer vos arguments.

Ordre des opérations

L’ordre des opérations dans jq peut être déroutant et contre-intuitif. Les opérations entre les caractères | sont généralement exécutées ensemble avant que le jq n’applique le |, mais il existe quelques exceptions. En général, ajoutez () autour d’un élément si vous n’êtes pas sûr de l’ordre naturel des opérations. Quand vous maîtriserez davantage le langage, vous saurez quand utiliser des parenthèses et quand ne pas les utiliser.

Contenu connexe

Pour obtenir de l’aide sur jq, reportez-vous à ces articles :