データフローグラフでマップを使用してデータを変換する

Azure IoT Operationsでは、マップ変換がデータフローグラフ内の各受信メッセージを、あなたのルールに基づいて出力メッセージを生成します。フィールドの名前変更、新しい構造への再構成、派生値の計算、不要なフィールドの削除を行うことができます。ワイルドカードルールを使うことで、すべてのフィールドを一度にコピーできます。

データフローグラフの概要と、パイプラインでの変換の構成方法については、データフローグラフの概要に関するページを参照してください。

変換は式言語を用いて値、テスト条件、参照フィールドを計算します。式は名前ではなく位置で入力を参照します。 inputs リストの最初の入力は $1、2番目は $2、という具合です。 cToFのような組み込み関数がこれらの値を変換・操作します。

演算子、関数、データ型、メタデータフィールドの完全なリストについては、Expressionsリファレンスを参照してください。

前提条件

Kubernetes クラスターにデプロイされた Azure IoT Operations のインスタンス。詳細については、「Deploy Azure IoT Operations」をご覧ください。

defaultを指すmcr.microsoft.comという名前の既定のレジストリエンドポイントは、デプロイ時に自動的に作成されます。組み込みの変換では、このエンドポイントが使用されます。

この記事のAzure CLI例は環境変数を使っており、各値を一度設定してからコマンドをコピー&ペーストできます as-is。クイックスタートのAzure IoT Operations Codespaces環境を使っている場合、これらの変数はすでに設定済みなので、このステップを省略できます。そうでなければ、コマンドを実行する前にシェル内で以下の環境変数を設定してください。

以下のスクリプトは、最も一般的に使われる環境変数を設定します。

環境変数	説明
`SUBSCRIPTION_ID`	Azure IoT Operationsインスタンスを含むサブスクリプションのIDです。
`RESOURCE_GROUP`	あなたのAzure IoT Operationsインスタンスを含むリソースグループの名前です。
`AIO_INSTANCE_NAME`	あなたのAzure IoT Operationsインスタンスの名前です。インスタンスを挙げるには、 `az iot ops list -o table`を実行してください。
`CLUSTER_NAME`	あなたのインスタンスをホストしているAzure Arc対応のKubernetesクラスターの名前です。
`LOCATION`	例えば`eastus`など、新しい資源を活用するためのAzure地域。

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>"

この記事で使っている変数を設定するだけで十分です。この記事では、選択したリソース名に追加の環境変数を使う場合があります。記事では、導入された場所の位置をどう設定するか説明しています。

マップルールのしくみ

各マップルールには、次の 4 つの部分があります。

財産	必須	説明
`inputs`	はい	受信メッセージから読み取るフィールドパスの一覧。
`output`	はい	フィールドパスで、結果が出力メッセージに現れます。
`expression`	いいえ	入力値に適用される数式。もし省略すると、最初の入力値が直接コピーされます。
`description`	いいえ	ルールの人間が理解できるラベルがエラーメッセージに含まれています。

マップ変換は入力に位置変数を順番に割り当てます。例えば、 inputs が ['Position', 'Office']であれば、 $1 は Position の値、 $2 は Officeの値です。

フィールドの名前を変更する

BirthDateの名前をDateOfBirthに変更するには、1 つの入力を別の出力パスにマップします。表現なんていらないよ。値はそのままコピーします。

マップ変換の構成で、次の規則を追加します。

Setting	価値
入力	`BirthDate`
アウトプット	`DateOfBirth`

CLI は、1 つの構成ファイルからグラフ全体を適用するため、これを graph.json 内の対応する場所に追加し、 az iot ops dataflowgraph applyで適用します。

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

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

Important

Kubernetes 配置マニフェストの使用は運用環境ではサポートされていないため、デバッグとテストにのみ使用する必要があります。

- inputs:
    - BirthDate
  output: DateOfBirth

フィールドを再構築する

フィールドを入れ子構造に移動するには、出力パスでドット表記を使用します。

次の 2 つのルールを追加します。

入力	アウトプット
`Name`	`Employee.Name`
`BirthDate`	`Employee.DateOfBirth`

CLI は、1 つの構成ファイルからグラフ全体を適用するため、これを graph.json 内の対応する場所に追加し、 az iot ops dataflowgraph applyで適用します。

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

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

Important

Kubernetes 配置マニフェストの使用は運用環境ではサポートされていないため、デバッグとテストにのみ使用する必要があります。

- inputs:
    - Name
  output: Employee.Name

- inputs:
    - BirthDate
  output: Employee.DateOfBirth

次の入力を与える

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

次の 2 つのルールが生成されます。

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

ルールの出力に一覧表示されているフィールドのみが結果に表示されます。結果には Position フィールドが含まれません。なぜなら、そのフィールドをマッピングするルールが存在しないためです。

複数の入力を結合する

複数の入力をリストアップするときは、それらの位置変数を使って式に統合します。

ルールを追加します。

Setting	価値
入力	`Position`、`Office`
アウトプット	`Employment.Position`
式	`$1 + ", " + $2`

CLI は、1 つの構成ファイルからグラフ全体を適用するため、これを graph.json 内の対応する場所に追加し、 az iot ops dataflowgraph applyで適用します。

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

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

Important

Kubernetes 配置マニフェストの使用は運用環境ではサポートされていないため、デバッグとテストにのみ使用する必要があります。

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

Position: "Analyst"とOffice: "Kent, WA"を指定すると、出力は"Analyst, Kent, WA"。

式を使用して値を変換する

expression フィールドを使用して、組み込みの関数または算術演算を適用します。以下の例では、セルシウス値を華氏に変換する組み込みの単位変換関数 cToFを使用しています。「 $1 はフィールド名ではなく最初の入力を指すことを覚えておいてください。」

演算子、関数、高度な機能の完全なリストについては、 Expressions referenceを参照してください。参照グループは単位変換、スケーリングと四捨五入、数学、文字列関数などのカテゴリごとに機能します。

コンピューティングルールを追加します。たとえば、摂氏を華氏に変換するには、次のようにします。

Setting	価値
入力	`temperature`
アウトプット	`temperature_f`
式	`cToF($1)`

センサーの読み取り値を 0 ~ 100 の範囲にスケーリングするには、式 scale($1, 0, 4095, 0, 100)を使用します。

CLI は、1 つの構成ファイルからグラフ全体を適用するため、これを graph.json 内の対応する場所に追加し、 az iot ops dataflowgraph applyで適用します。

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

センサーの読み取り値をスケーリングするには:

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

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

センサーの読み取り値をスケーリングするには:

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

Important

Kubernetes 配置マニフェストの使用は運用環境ではサポートされていないため、デバッグとテストにのみ使用する必要があります。

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

センサーの読み取り値をスケーリングするには:

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

ワイルドカードを使用してすべてのフィールドをコピーする

出力が少数の変更のみで入力と密接に一致する必要がある場合は、ワイルドカードルールを使用してすべてのフィールドを一度にコピーします。次に、特定のフィールドをオーバーライド、追加、または削除するルールを追加します。

すべてのフィールドをコピーするパススルー規則を追加します。入力を * に設定し、出力を * に設定します。

CLI は、1 つの構成ファイルからグラフ全体を適用するため、これを graph.json 内の対応する場所に追加し、 az iot ops dataflowgraph applyで適用します。

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

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

Important

Kubernetes 配置マニフェストの使用は運用環境ではサポートされていないため、デバッグとテストにのみ使用する必要があります。

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

ワイルドカード規則の要件

ワイルドカードルールは、マップ構成の 最初のルール である必要があります。
マップ変換はワイルドカードルールを1つだけサポートします。
アスタリスクは 1 つ以上のパスセグメントと一致し、完全なセグメントを表す必要があります。マップ変換は partial*のような部分的なパターンをサポートしていません。

プレフィックスワイルドカード

ワイルドカードを特定のプレフィックスにスコープします。すべてのフィールドを ColorProperties からルートレベルにフラット化するには:

入力 ColorProperties.* と出力 *を含むルールを追加します。

CLI は、1 つの構成ファイルからグラフ全体を適用するため、これを graph.json 内の対応する場所に追加し、 az iot ops dataflowgraph applyで適用します。

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

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

Important

Kubernetes 配置マニフェストの使用は運用環境ではサポートされていないため、デバッグとテストにのみ使用する必要があります。

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

たとえば、以下のように指定したとします。

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

出力は次のようになります。

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

出力からフィールドを削除する

特定のフィールドを除外するには、 output を空の文字列に設定します。通常はワイルドカードルールの後にこの方法を使いましょう:すべてコピーし、不要なものは削除します。

すべてのフィールドをコピーするパススルー規則を追加します。
削除ルールを追加し、除外するフィールド ( password や internal_idなど) を選択します。

CLI は、1 つの構成ファイルからグラフ全体を適用するため、これを graph.json 内の対応する場所に追加し、 az iot ops dataflowgraph applyで適用します。

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

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

Important

Kubernetes 配置マニフェストの使用は運用環境ではサポートされていないため、デバッグとテストにのみ使用する必要があります。

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

- inputs:
    - password
    - internal_id
  output: ""

削除ルールには表現を含めることはできません。

特定のフィールドのワイルドカードをオーバーライドする

ワイルドカードルールと特定のルールの両方が同じフィールドと一致する場合は、より具体的なルールが優先されます。

すべてのフィールドをコピーするパススルー規則を追加します。
式temperatureを使用してcToF($1)の計算ルールを追加します。

マップ変換は、特定のルールを temperature に適用し、他のすべてのフィールドを as-isコピーします。

CLI は、1 つの構成ファイルからグラフ全体を適用するため、これを graph.json 内の対応する場所に追加し、 az iot ops dataflowgraph applyで適用します。

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

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

Important

Kubernetes 配置マニフェストの使用は運用環境ではサポートされていないため、デバッグとテストにのみ使用する必要があります。

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

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

メタデータフィールドを使用する

MQTTトピックやユーザープロパティなどのメッセージメタデータから読み書きできます。式リファレンスのメタデータフィールドを参照してください。

MQTT ユーザープロパティにフィールド値を書き込むには、入力 region と出力 $metadata.user_property.region を含むルールを追加します。

CLI は、1 つの構成ファイルからグラフ全体を適用するため、これを graph.json 内の対応する場所に追加し、 az iot ops dataflowgraph applyで適用します。

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

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

Important

Kubernetes 配置マニフェストの使用は運用環境ではサポートされていないため、デバッグとテストにのみ使用する必要があります。

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

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

動的トピック・ルーティングの完全な例については、メッセージを別のトピックにルーティングするを参照してください。

最後の既知の値と既定値を使用する

センサーデータが断続的に到着すると、不足しているフィールドに最後の既知の値または静的な既定値を入力できます。式リファレンスの最後の既知の値と既定値を参照してください。

temperature フィールドのルールを追加し、[最後の既知の値] を有効にします。フォールバックとして既定値の 0 を設定します。

CLI は、1 つの構成ファイルからグラフ全体を適用するため、これを graph.json 内の対応する場所に追加し、 az iot ops dataflowgraph applyで適用します。

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

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

Important

Kubernetes 配置マニフェストの使用は運用環境ではサポートされていないため、デバッグとテストにのみ使用する必要があります。

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

この規則では、現在の値が存在する場合に使用され、最後の既知の値にフォールバックし、どちらも使用できない場合は 0 を使用します。

外部データを使用してエンリッチする

エンリッチメントは任意です。これは、受信メッセージとステートストアに保存されている参照データ(例えばデバイスメタデータのルックアップテーブル)を組み合わせたい場合だけです。もしメッセージにすでに必要なものが含まれているなら、このセクションは飛ばしてください。

エンリッチメントが必要なら、処理中にランタイムが参照する コンテキスト化データセット を設定してください。たとえば、デバイスのメタデータを ID で検索し、出力に含めます。詳細については、「外部データを使用したエンリッチメント」を参照してください。

データフローグラフの排他機能

データフローグラフでは、データフロー builtInTransformation マッピングでは使用できないいくつかの機能がサポートされています。

見つからないフィールドの既定値

フィールドがない場合に静的フォールバックを提供するには、入力に対して ?? <default> 構文を使用します。これは、空の値をチェックする if 式を記述するよりも簡単です。

マップ変換の構成で、 ?? 構文の後に既定値を含むように入力を設定します。たとえば、温度フィールドがない場合にtemperature ?? 0を使用する入力フィールドとして「0」と入力します。

CLI は、1 つの構成ファイルからグラフ全体を適用するため、これを graph.json 内の対応する場所に追加し、 az iot ops dataflowgraph applyで適用します。

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

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

Important

Kubernetes 配置マニフェストの使用は運用環境ではサポートされていないため、デバッグとテストにのみ使用する必要があります。

- inputs:
    - temperature ?? 0
  output: temperature

サポートされている既定の型と、既定値と最後の既知の値の組み合わせの詳細については、式リファレンスの既定値を参照してください。

Regex 関数

データフローグラフでは、正規表現の照合と置換がサポートされています。

str::regex_matches(string, pattern): 文字列が正規表現パターンと一致する場合は true を返します。
str::regex_replace(string, pattern, replacement): すべての正規表現の一致を置換文字列に置き換えます。

これらの関数は、フィルター式や文字列データのクリーニングと変換に役立ちます。文字列関数の完全な一覧については、式リファレンスの「文字列関数」を参照してください。

完全な構成の例

すべてのフィールドをコピーし、機密データを削除し、フィールドを再構築し、派生値を計算する完全なマップ構成を次に示します。

ワイルドカード、削除、再構築、コンピューティング、マージに関する複数のルールを示す操作エクスペリエンスマップ変換構成パネルのスクリーンショット。

操作エクスペリエンスで、データフローグラフを作成し、マップ変換を追加します。マップ構成パネルで、次の規則を追加します。

ワイルドカードパススルーを使用してすべてのフィールドをコピーします。
とpasswordの出力を空に設定してsecret_keyします。
フィールドを BirthDate にEmployee.DateOfBirthします。
temperature場上の式cToF($1)を用いて華氏変換を計算します。
フィールドとPosition フィールドを数式Officeに$1 + ", " + $2します。

Azure CLIは、1 つの JSON 構成ファイルからデータフローグラフを適用します。グラフプロパティを使用して graph.json ファイルを作成します。 graph.jsonファイル内のvalueフィールドは、各変換のルールをエスケープされたJSON文字列として保存しています。各変換のルールの読み取り可能な形式については、その変換の種類のハウツーを参照してください。

{
  "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

エスケープ文字列を生成するには、ルールを rules.jsonのようなファイルに保存し、 jq -c . rules.jsonを実行し、1行の出力を value フィールドに貼り付けます。

構成ファイルを適用します。

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

Kubernetes 配置マニフェストの使用は運用環境ではサポートされていないため、デバッグとテストにのみ使用する必要があります。

ルールの構成は、value 変換ノードの rules セクション内の DataflowGraph キーに対して configuration として配置される JSON 文字列です。

{
  "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"
    }
  ]
}

完全な DataflowGraph リソース構造については、「データフローグラフの概要」を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-24

データ フロー グラフでマップを使用してデータを変換する

前提条件

マップ ルールのしくみ

フィールドの名前を変更する

フィールドを再構築する

複数の入力を結合する

式を使用して値を変換する

ワイルドカードを使用してすべてのフィールドをコピーする

ワイルドカード 規則の要件

プレフィックスワイルドカード

出力からフィールドを削除する

特定のフィールドのワイルドカードをオーバーライドする

メタデータ フィールドを使用する

最後の既知の値と既定値を使用する

外部データを使用してエンリッチする

データ フロー グラフの排他機能

見つからないフィールドの既定値

Regex 関数

完全な構成の例

関連するコンテンツ

フィードバック

その他のリソース

データフローグラフでマップを使用してデータを変換する

マップルールのしくみ

ワイルドカード規則の要件

メタデータフィールドを使用する

データフローグラフの排他機能