使用資料流程轉換來轉換資料

您可以使用資料流程轉換，在 Azure IoT 操作中轉換資料。 資料流程中的轉換元素用來計算輸出欄位的值。 您可以在資料流程轉換中使用輸入欄位、可用的運算、資料型別與型別轉換。

資料流程轉換元素用於計算輸出欄位的值：

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

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

關於轉換，您需要了解以下幾個面向：

• 輸入欄位的參考方式：如何在轉換公式中參考輸入欄位中的值。
• 可用的運算：可在轉換中使用的運算。 例如，加法、減法、乘法與除法。
• 資料型別：公式可處理與操作的資料型別。 例如，整數、浮點數與字串。
• 型別轉換：在輸入欄位值、公式評估與輸出欄位之間，資料型別如何進行轉換。

輸入欄位

在轉換中，公式可以對靜態值 (例如數字 25) 或來自輸入欄位的參數進行運算。 對應會定義這些公式可存取的輸入欄位。 每個欄位都會依其在輸入清單中的順序進行參考：

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)

在此範例中，轉換結果會產生一個陣列，包含 [Max, Min, Mid.Avg, Mid.Mean] 的值。 YAML 檔案中的註解 (# - $1、# - $2) 為選用項目，但有助於釐清每個欄位屬性與其在轉換公式中角色之間的關聯。

資料類型

不同的序列化格式支援各種資料型別。 例如，JSON 提供幾種基本型別：字串、數值、布林值，以及 null。 它也包含這些基本型別的陣列。

當對應程式讀取輸入屬性時，會將其轉換為內部型別。 此轉換是必要的，用以在資料寫入輸出欄位之前，將資料保留在記憶體中。 無論輸入與輸出的序列化格式是否相同，都會進行轉換為內部型別的處理。

內部表示法使用下列資料型別：

輸入記錄欄位

讀取輸入記錄欄位時，其基礎型別會轉換為上述其中一種內部型別變體。 內部表示法具備足夠的彈性，可在幾乎不需或完全不需轉換的情況下處理大多數輸入型別。

對於某些格式，會使用替代型別。 例如，JSON 沒有 datetime 型別，而是將 datetime 值以符合 ISO8601 格式的字串來儲存。 當對應程式讀取這類欄位時，內部表示法仍會維持為字串。

輸出記錄欄位

對應程式的設計具備彈性，會將內部型別轉換為輸出型別，以因應資料來自型別系統受限的序列化格式之情境。 以下範例顯示轉換的處理方式：

• 數值型別：這些型別可以轉換為其他表示方式，即使這代表會失去精確度。 例如，64 位元浮點數 (f64) 可以轉換為 32 位元整數 (i32)。
• 字串轉為數值：如果傳入的記錄包含像 123 這樣的字串，而輸出欄位是 32 位元整數，對應程式會將該值轉換並以數值形式寫入。
• 字串轉為其他型別：
  • 如果輸出欄位是 datetime，對應程式會嘗試將字串解析為 ISO8601 格式的 datetime。
  • 如果輸出欄位是 binary/bytes，對應程式會嘗試將該字串從 base64 編碼的字串進行反序列化。
• 布林值：
  • 如果輸出欄位是數值型別，會轉換為 0/1。
  • 如果輸出欄位是字串，會轉換為 true/false。

在轉換公式中使用型別

在對應中，可以選擇性地指定公式，說明在將資料寫入輸出欄位之前，如何處理來自輸入的資料。 如果未指定公式，對應程式會依據內部型別與轉換規則，將輸入欄位直接複製到輸出。

如果指定了公式，可在公式中使用的資料型別僅限於：

• 整數
• 浮點數
• 字串
• 布林值
• 前述型別的陣列
• 缺失值

Map 與 byte 不能參與公式運算。

與時間相關的型別 (datetime、time 及 duration) 會轉換為代表秒數的整數值。 在公式評估完成後，結果會儲存在內部表示法中，而不會再轉換回原型別。 例如，datetime 轉換為秒數後，會維持為整數。 如果該值將用於 datetime 欄位，則必須套用明確的轉換方法。 其中一個範例是將該值轉換為 ISO8601 字串，系統會自動將其轉換為輸出序列化格式中的 datetime 型別。

使用非規則型別

對於像是陣列與缺失值這類型別，需有特別考量。

陣列

陣列可以透過彙總函式來處理，從多個元素中計算出單一值。 例如，使用以下輸入記錄：

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

搭配此對應設定：

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

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

此設定會從 Measurements 陣列中選取最小的值，作為輸出欄位。

也可以由多個單一值建立陣列：

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)

此對應會建立一個陣列，包含最小值、最大值、平均值與均值。

缺失值

缺失值是一種特殊型別，適用於下列情境，例如：

• 在輸入中處理缺少的欄位，並提供替代值。
• 根據欄位是否存在，有條件地移除欄位。

使用缺失值的範例對應：

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

輸入記錄包含 BaseSalary 欄位，但該欄位可能是選用的。 假設如果該欄位不存在，則必須從情境化資料集新增一個值：

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

對應可以檢查該欄位是否存在於輸入記錄中。 如果找到該欄位，輸出就會接收該既有值。 否則，輸出會接收來自情境資料集的值。 例如：

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)

conversion 會使用 if 函式，該函式具有三個參數：

• 第一個參數是條件。 在此範例中，它會檢查輸入欄位 (別名為 $1) 的 BaseSalary 欄位是否為缺失值。
• 第二個參數是在第一個參數條件為 true 時的函式結果。 在此範例中，這是情境化資料集 (別名為 $2) 的 BaseSalary 欄位。
• 第三個參數是在第一個參數條件為 false 時所使用的值。

可用的函數

資料流程提供一組內建函式，可用於轉換公式中。 這些函式可用來執行常見作業，例如算術、比較與字串操作。 可用的函式如下：

轉換函數

資料流程提供多個內建的轉換函式，可用於常見的單位轉換，例如溫度、壓力、長度、重量和體積。 這裡有一些範例：

也支援反向轉換：

此外，您也可以使用基本的數學公式來定義自己的轉換函式。 系統支援加法 (+)、減法 (-)、乘法 (*) 與除法 (/) 等運算子。 這些運算子遵循標準的優先順序規則，您可以使用括號來調整，以確保正確的運算順序。 這可讓您自訂單位轉換以符合特定需求。

依優先順序提供的可用運算子

由於 Exponentiation 具有最高的優先順序，除非以括號覆寫此順序，否則會先執行：

• $1 * 2 ^ 3 會解讀為 $1 * 8，因為 2 ^ 3 的部分會在乘法之前先執行。
• ($1 * 2) ^ 3 會先處理乘法，再進行指數運算。

Negation 與 Logical not 具有較高的優先順序，因此通常會緊貼其相鄰的運算元，除非涉及指數運算：

• -$1 * 2 會先對 $1 取負值，然後再相乘。
• -($1 * 2) 會先相乘，然後再對結果取負值。

Multiplication、Division 與 Modulo 具有相同的優先順序，除非使用括號改變順序，否則會由左至右依序執行。

Addition 與 Subtraction 相較於前一組運算屬於較低優先順序：

• $1 + 2 * 3 的結果為 $1 + 6，因為 2 * 3 由於 multiplication 具有較高的優先順序而先執行。
• ($1 + 2) * 3 會先執行 Addition，再執行 Multiplication。

Comparisons 運算會作用於數值、布林值與字串值。 由於其優先順序低於算術運算子，因此不需要使用括號即可正確比較結果：

• $1 * 2 <= $2 等同於 ($1 * 2) <= $2。

邏輯運算子用於串接條件：

• $1 > 100 && $2 > 200