在資料流程圖中轉換帶有地圖的資料

在 Azure IoT 操作中，地圖轉換會根據你的規則，將每則進來訊息從資料流程圖中產生。你可以重新命名欄位、將它們重新組織成新結構、計算衍生值，或移除不需要的欄位。使用萬用字碼規則，你可以一次複製所有欄位。

關於資料流程圖的概述以及在管線中轉換的組合方式，請參見資料流程圖概覽。

轉換使用表達式語言來計算數值、測試條件及參考欄位。表達式以位置指代輸入，而非名稱：列表中的 inputs 第一個輸入為 $1，第二個為 $2，依此類推。例如 cToF 的內建函式可轉換及操作這些值。

完整的運算子、函式、資料型態及元資料欄位清單，請參見 Expressions 參考文獻。

先決條件

Azure IoT 操作的一個實例部署在 Kubernetes 叢集中。如需詳細資訊，請參閱部署 Azure IoT 作業。

在部署過程中，會自動建立一個指向 default 的預設登錄端點，名為 mcr.microsoft.com。內建的轉換會使用這個端點。

本文Azure CLI範例使用環境變數，讓你可以設定一次每個值，然後複製貼上指令 as-is。如果你使用的是快速入門的 Azure IoT 操作 Codespaces 環境，這些變數已經為你設定好，可以跳過這個步驟。否則，在執行指令前，先在 shell 裡設定以下環境變數。

以下腳本設定最常用的環境變數：

環境變數	說明
`SUBSCRIPTION_ID`	包含您的 Azure IoT 操作實例的訂閱 ID。
`RESOURCE_GROUP`	包含你的 Azure IoT 操作實例的資源群組名稱。
`AIO_INSTANCE_NAME`	你的 Azure IoT 操作實例名稱。要列出你的實例，請執行 `az iot ops list -o table`。
`CLUSTER_NAME`	這是支援 Azure Arc 的 Kubernetes 叢集名稱，該叢集負責承載你的實例。
`LOCATION`	例如，使用新資源`eastus`的 Azure 區域。

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

你只需要設定這篇文章所使用的變數。本文可能會使用額外環境變數來表示你選擇的資源名稱。文章說明了如何將它們放置在引入的位置。

地圖規則的運作方式

每條地圖規則包含四個部分：

房產	Required	說明
`inputs`	是的	從收到訊息中可讀取的欄位路徑列表。
`output`	是的	欄位路徑，結果出現在輸出訊息中。
`expression`	No	公式套用到輸入值上。如果你省略了它，第一個輸入值會直接複製。
`description`	No	規則的人類可讀標籤，會包含在錯誤訊息中。

映射轉換會依序將位置變數指派給輸入。例如，若 inputs 是 ['Position', 'Office']，則 $1 是 Position 的值，而 $2 是 Office 的值。

重新命名欄位

若要將重新命名 BirthDate 為 DateOfBirth，將一個輸入映射到另一個輸出路徑。你不需要什麼表情。系統會原樣複製該值。

在映射轉換配置中，加入一條規則：

Setting	價值
輸入	`BirthDate`
Output	`DateOfBirth`

CLI 會從單一設定檔套用整個圖表，因此請將這段內容加入 graph.json 中對應的位置，並使用 az iot ops dataflowgraph apply 套用。

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

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

這很重要

正式生產環境不支援使用 Kubernetes 部署資訊清單，且僅應用於偵錯與測試。

- inputs:
    - BirthDate
  output: DateOfBirth

重組欄位

在輸出路徑中使用點符號來將欄位移動到巢狀結構中。

新增兩條規則：

輸入	Output
`Name`	`Employee.Name`
`BirthDate`	`Employee.DateOfBirth`

CLI 會從單一設定檔套用整個圖表，因此請將這段內容加入 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'
}

這很重要

正式生產環境不支援使用 Kubernetes 部署資訊清單，且僅應用於偵錯與測試。

- inputs:
    - Name
  output: Employee.Name

- inputs:
    - BirthDate
  output: Employee.DateOfBirth

假設輸入如下：

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

這兩條規則會產生：

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

結果中只會出現規則輸出中列出的欄位。結果不會包含欄位， Position 因為沒有規則映射它。

合併多個輸入

當你列出多個輸入時，使用它們的位置變數將它們合併成一個表達式。

新增規則：

Setting	價值
Inputs	`Position`、`Office`
Output	`Employment.Position`
表達	`$1 + ", " + $2`

CLI 會從單一設定檔套用整個圖表，因此請將這段內容加入 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'
}

這很重要

正式生產環境不支援使用 Kubernetes 部署資訊清單，且僅應用於偵錯與測試。

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

給定 Position: "Analyst" 和 Office: "Kent, WA"，輸出為 "Analyst, Kent, WA"。

用表達式轉換值

利用這個 expression 欄位來套用內建函數或算術運算。以下範例使用 cToF了，一個內建的單位轉換函數，將攝氏值轉換為華氏度。請記得，這是 $1 指第一個輸入，而不是欄位名稱。

完整的運算子、函式及進階功能清單，請參見 Expressions 參考文獻。參考群組依類別運作，例如單位轉換、縮放與四捨五入、數學運算及字串函數。

新增一個計算規則。例如，將攝氏轉換成華氏度：

Setting	價值
輸入	`temperature`
Output	`temperature_f`
表達	`cToF($1)`

要將感測器讀數縮放到 0-100 範圍，請使用表達式 scale($1, 0, 4095, 0, 100)。

CLI 會從單一設定檔套用整個圖表，因此請將這段內容加入 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)'
}

這很重要

正式生產環境不支援使用 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 會從單一設定檔套用整個圖表，因此請將這段內容加入 graph.json 中對應的位置，並使用 az iot ops dataflowgraph apply 套用。

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

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

這很重要

正式生產環境不支援使用 Kubernetes 部署資訊清單，且僅應用於偵錯與測試。

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

外卡規則要求

萬用符規則必須是你的映射配置中第一條規則。
地圖轉換只支援一個萬用符規則。
星號與一個或多個路徑段相匹配，必須代表完整的段子。地圖轉換不支援像 partial*.

前綴通配符

把萬用卡範圍限定到特定的前綴。若要將 ColorProperties 中的所有欄位攤平至根層級：

加入一條包含輸入 ColorProperties.* 與輸出 *的規則。

CLI 會從單一設定檔套用整個圖表，因此請將這段內容加入 graph.json 中對應的位置，並使用 az iot ops dataflowgraph apply 套用。

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

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

這很重要

正式生產環境不支援使用 Kubernetes 部署資訊清單，且僅應用於偵錯與測試。

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

假設：

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

輸出如下：

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

從輸出中移除欄位

將設 output 為空字串以排除特定欄位。通常，在有萬用符規則後會用這個方法：先複製所有東西，然後移除不需要的。

新增傳遞規則以複製所有欄位。
新增移除規則並選擇要排除的欄位（例如， password 和 internal_id）。

CLI 會從單一設定檔套用整個圖表，因此請將這段內容加入 graph.json 中對應的位置，並使用 az iot ops dataflowgraph apply 套用。

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

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

這很重要

正式生產環境不支援使用 Kubernetes 部署資訊清單，且僅應用於偵錯與測試。

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

- inputs:
    - password
    - internal_id
  output: ""

移除規則不能包含表達式。

針對特定欄位覆寫萬用字元

當一個外牌規則和某個特定規則都對應在同一個欄位時，較具體的規則會優先。

新增傳遞規則以複製所有欄位。
為 temperature 新增計算規則，運算式為 cToF($1)。

映射變換將特定規則套用至temperature，並按原樣複製所有其他欄位。

CLI 會從單一設定檔套用整個圖表，因此請將這段內容加入 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)'
}

這很重要

正式生產環境不支援使用 Kubernetes 部署資訊清單，且僅應用於偵錯與測試。

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

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

使用元資料欄位

讀取並寫入訊息的元資料，例如 MQTT 主題和使用者屬性。請參見表達式參考中的元資料欄位。

新增具有輸入region和輸出$metadata.user_property.region的規則，以將欄位值寫入 MQTT 使用者屬性。

CLI 會從單一設定檔套用整個圖表，因此請將這段內容加入 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'
}

這很重要

正式生產環境不支援使用 Kubernetes 部署資訊清單，且僅應用於偵錯與測試。

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

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

欲了解動態主題路由的完整範例，請參見「將訊息導向不同主題」。

使用最後已知的數值和預設值

當感測器資料間歇性抵達時，你可以用最後已知的值或靜態預設值填補缺失欄位。請參見表達式參考中的最後已知值與預設值。

為該欄位新增規則 temperature 並啟用 最後已知值。設定 0 作為預設值備用。

CLI 會從單一設定檔套用整個圖表，因此請將這段內容加入 graph.json 中對應的位置，並使用 az iot ops dataflowgraph apply 套用。

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

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

這很重要

正式生產環境不支援使用 Kubernetes 部署資訊清單，且僅應用於偵錯與測試。

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

此規則在存在時使用當前值，回退至最後已知值，若兩者皆不可用則使用0。

使用外部資料進行擴充

擴充是選用的。只有當你想將收到的訊息與儲存在狀態儲存中的參考資料結合時才需要，例如裝置元資料的查詢表。如果你的訊息已經包含你需要的所有內容，請跳過此區。

當你需要擴充資訊時，請設定一個情境化資料集，供執行階段在處理期間查詢。例如，透過裝置的 ID 查詢其元資料，並將其包含在輸出中。詳情請參見「以外部資料豐富」一詞。

資料流程圖專屬功能

資料流程圖支援多項資料流程 builtInTransformation 映射中無法具備的功能。

缺失欄位的預設值

當欄位缺失時，使用 ?? <default> 語法在輸入上提供靜態備援。這比寫 if 一個檢查空值的表達式簡單。

在對應轉換組態中，將輸入設定為包含 ?? 語法，後面接預設值。例如，輸入欄位請填入 temperature ?? 0，這樣當溫度欄位遺漏時，就會使用 0。

CLI 會從單一設定檔套用整個圖表，因此請將這段內容加入 graph.json 中對應的位置，並使用 az iot ops dataflowgraph apply 套用。

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

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

這很重要

正式生產環境不支援使用 Kubernetes 部署資訊清單，且僅應用於偵錯與測試。

- inputs:
    - temperature ?? 0
  output: temperature

關於支援的預設類型以及將預設值與最後已知值結合的詳細資訊，請參見表達式參考中的預設值。

正則表達式函數

資料流程圖支援正則表達式匹配與替換：

str::regex_matches(string, pattern)：若字串符合正則表達式模式，則回傳為真。
str::regex_replace(string, pattern, replacement)：將所有正則表達式的匹配項替換為替換字串。

這些函式在篩選表達式或清理與轉換字串資料時非常有用。完整的字串函數列表，請參見表達式參考中的字串函數。

完整配置範例

這裡有一個完整的映射配置，可以複製所有欄位、移除敏感資料、重組欄位，並計算出導出值：

操作體驗地圖轉換配置面板的截圖，顯示多種規則，包括通配符、移除、重組、計算和合併。

在 Operations 體驗中，建立資料流程圖並加入地圖轉換。在地圖設定面板中，新增規則：

使用萬用字元傳遞來複製所有欄位。
將和password的輸出設為空來移除敏感欄位secret_key。
將欄位 BirthDate 重組為 Employee.DateOfBirth。
利用場上的temperature公式cToF($1)計算華氏度轉換。
將和 Position 字段與公式 Office 合併。

Azure CLI 是從單一 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這樣的檔案，然後將單行輸出貼到欄位中 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-07-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' }
      }
    ]
  }
}

這很重要

正式生產環境不支援使用 Kubernetes 部署資訊清單，且僅應用於偵錯與測試。

規則組態是 JSON 字串，會放在 value 轉換節點 rules 區段中，DataflowGraph 索引鍵的 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"
    }
  ]
}

完整 DataflowGraph 資源結構請參閱資料流程圖概述。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-07-31

在資料流程圖中轉換帶有地圖的資料

先決條件

地圖規則的運作方式

重新命名欄位

重組欄位

合併多個輸入

用表達式轉換值

使用萬用字元來複製所有欄位

外卡規則要求

前綴通配符

從輸出中移除欄位

針對特定欄位覆寫萬用字元

使用元資料欄位

使用最後已知的數值和預設值

使用外部資料進行擴充

資料流程圖專屬功能

缺失欄位的預設值

正則表達式函數

完整配置範例

相關內容

意見反應

其他資源