データ プロセッサ パイプラインの jq とは

  • [アーティクル]

重要

Azure Arc によって有効にされる Azure IoT Operations Preview は、 現在プレビュー段階です。 運用環境ではこのプレビュー ソフトウェアを使わないでください。

一般公開リリースが利用可能になった場合は、新しい Azure IoT Operations インストールをデプロイする必要があります。プレビュー インストールをアップグレードすることはできません。

ベータ版、プレビュー版、または一般提供としてまだリリースされていない Azure の機能に適用される法律条項については、「Microsoft Azure プレビューの追加使用条件」を参照してください。

jq はオープンソースの JSON プロセッサであり、データ プロセッサ) パイプラインで構造化ペイロードの再構築と書式設定を使用できます。

  • filter パイプライン ステージでは、jq を使用して柔軟なフィルター クエリを有効にします。
  • transform パイプライン ステージでは、jq を使用してデータ変換を有効にします。

ヒント

jq は jQuery と同じではなく、異なる一連の問題を解決します。 オンラインで jq に関する情報を検索すると、検索結果に jQuery の情報が含まれる場合があります。 jQuery 情報は無視するか除外してください。

これらのステージで提供する jq は次のものである必要があります。

  • 構文的に有効。
  • jq が適用されるメッセージに対して意味的に有効。

jq の使用方法

データ プロセッサ パイプラインステージで jq 言語を使用するには、次の 2 つの方法があります。

  • データを使用して任意の操作や計算を実行する機能など、jq 言語の全機能を使用する式。 式は、フィルターや変換などのパイプライン ステージに表示され、使用される場合は式と呼ばれます。
  • パスは、メッセージ内の 1 つの場所を識別します。 パスは、jq 言語の小さなサブセットを使用します。 パスを使用してメッセージから情報を取得し、計算された情報をメッセージに戻してパイプラインで後で処理します。

ヒント

このガイドでは、jq の機能の全体像を提供していません。 完全な言語リファレンスについては、「jq マニュアル」を参照してください。

パフォーマンス上の理由から、データ プロセッサは次の jq 関数の使用をブロックします。

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

トラブルシューティング

データ プロセッサ内に jq パスまたは式を作成する際に留意すべき点はほとんどありません。 問題が発生した場合は、次のいずれかの誤りがないことを確認してください。

スコープを payload に設定していない

データ プロセッサ パイプライン内のすべてのメッセージは、メッセージのペイロードを最上位のフィールド payload に配置する構造で始まります。 必須ではありませんが、メッセージがさまざまなパイプライン ステージを通過する際に、メイン ペイロードを payload フィールド内に保持するようにメッセージを処理する場合の強い規則です。

変換とフィルター処理のほとんどのユース ケースでは、ペイロードを直接操作する必要があるため、クエリ全体がペイロード フィールドにスコープ設定されているのを確認するのが一般的です。 メッセージはこの構造を使用し、ペイロードを最上位レベルにあるかのように扱うことを忘れないでください。

この間違いの修正は簡単です。 jq を使用する場合:

  • メッセージをフィルター処理し、式の先頭に .payload | を追加して、正しくスコープを設定します。
  • メッセージを変換する:
    • メッセージを分割しない場合は、式の先頭に .payload |= を追加して変換のスコープを設定します。
    • メッセージを分割する場合は、メッセージを分割できるようにしながら、ペイロードを特に更新するように、<expression> 間に .payload = (.payload | <expression>) を追加します。

複数のメッセージを結合しようとしている

jq には、メッセージを分解して再構築できる多くの機能があります。 ただし、jq 式を呼び出すことができるのは、パイプライン ステージに入る一度に 1 つのメッセージだけです。 そのため、フィルターと変換だけでは、複数の入力メッセージのデータを結合することはできません。

複数のメッセージの値をマージする場合は、集計ステージを使用して最初に値を結合してから、変換またはフィルターを使用して結合されたデータを操作します。

; の代わりに , で関数引数を区切っている

ほとんどのプログラミング言語とは異なり、jq は関数引数を区切るために , を使用しません。 jq は、各関数引数を ; で区切ります。 この間違いは、デバッグが難しい場合があります。, ほとんどの場所で有効な構文ですが、何か違うことを意味するためです。 jq では、, はストリーム内の値を区切ります。

; の 代わりに , を使用する場合に表示される最も一般的なエラーは、呼び出そうとしている関数が指定された引数の数に対して存在しないというものです。 意味のない関数を呼び出すときにコンパイル エラーやその他の奇妙なエラーが発生する場合は、引数を区切るのに , ではなく ; を使用していないか確認してください。

演算の順序

jq での操作の順序は、紛らわしく、直感に反しているように思える場合があります。 | 文字間の操作はすべて、jq が | を適用する前にすべて一緒に実行されますが、いくつかの例外があります。 一般に、操作の自然な順序がわからない場合は、任意のものの間に () を追加してください。 言語をさらに使用する際に、かっこが必要なものと必要ない内容について学習します。

関連するコンテンツ

jq を使用している場合のヘルプについては、次の記事を参照してください。