共用方式為

使用數據流轉換來轉換數據

  • 發行項

重要

此頁面包含使用 Kubernetes 部署指令清單來管理 Azure IoT Operations 元件的指示，其處於預覽狀態。 這項功能隨附 數個限制，不應用於生產工作負載。

請參閱 Microsoft Azure 預覽版增補使用規定，以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未正式發行的版本) 的法律條款。

您可以使用資料流程轉換以轉換 Azure IoT 操作中的資料。 資料流程中的轉換元素是用於計算輸出欄位的值。 您可以在資料流程轉換中使用輸入欄位、可用的作業、資料類型和類型轉換。

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

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)'

在此範例中，轉換會產生包含 [Max, Min, Mid.Avg, Mid.Mean] 值的陣列。 YAML 檔案中的批註是# - $1# - $2選擇性的，但它們有助於釐清每個欄位屬性與其在轉換公式中的角色之間的連接。

資料類型

不同的序列化格式支援各種資料類型。 例如，JSON 提供一些基本類型：字串、數位、布爾值和 Null。 它也包含這些基本類型的陣列。

當對應工具讀取輸入屬性時，便會將其轉換為內部類型。 在將資料寫入輸出欄位之前，您必須進行此轉換，才能在記憶體中保留資料。 不論輸入和輸出序列化公式是否相同，都會發生內部類型的轉換。

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

類型 描述
bool 邏輯 true/false。
integer 儲存為128位帶正負號的整數。
float 儲存為64位浮點數。
string UTF-8 字串。
bytes 二進位數據，8 位不帶正負號值的字串。
datetime 使用 nanosecond 解析度的 UTC 或當地時間。
time 使用奈秒解析度的一天時間。
duration 具有奈秒解析度的持續時間。
array 先前所列之任何類型的陣列。
map 先前所列任何類型的 （索引鍵、值） 配對向量。

輸入記錄欄位

讀取輸入記錄欄位時，其基礎類型會轉換為下列其中一個內部類型變體。 內部表示法適用於多種情況，可以處理低或無轉換的大部分輸入類型。

針對某些格式，會使用代理類型。 例如，JSON 沒有 datetime 類型，而是將值儲存 datetime 為根據ISO8601格式化的字串。 當對應工具讀取這類欄位時，內部表示法會維持字串。

輸出記錄欄位

對應工具旨在於提供彈性，將內部類型轉換為輸出類型以因應資料來自具有有限類型系統序列化格式的案例。 下列範例示範如何處理轉換：

  • 數值類型： 這些類型可以轉換成其他表示法，即使表示失去有效位數也一樣。 例如，64 位浮點數 （f64） 可以轉換成 32 位整數 （i32）。
  • 數位字串： 如果連入記錄包含類似 123 且輸出欄位為32位整數的字串，對應程式會轉換值，並將值寫入為數位。
  • 其他類型的字串：
    • 如果輸出欄位為 datetime，對應程式會嘗試將字串剖析為格式化 datetime的ISO8601。
    • 如果輸出欄位為 binary/bytes，對應程式會嘗試從base64編碼的字串還原串行化字串。
  • 布林值：
    • 0/1如果輸出欄位為數值，則轉換成 。
    • true/false如果輸出欄位是字串，則轉換成 。

搭配類型使用轉換公式

在對應中，選擇性公式可以指定處理輸入資料的方式，然後再將其寫入輸入欄位。 如果未指定任何公式，對應程式會使用內部類型和轉換規則，將輸入字段複製到輸出。

如果指定公式，則可在公式中使用的資料類型限制如下：

  • 整數
  • 浮點數
  • 字串
  • 布林值
  • 上述類型的陣列
  • 遺失值

Map 和 byte 無法參與公式。

與時間 （datetime、 time和 duration） 相關的類型會轉換成整數值，以秒為單位來表示時間。 公式評估之後，結果會儲存再內部表示法，而不會還原轉換。 例如， datetime 轉換成秒會維持整數。 如果值將用於 datetime 欄位，則必須套用明確的轉換方法。 例如，將值轉換成自動轉換成 datetime 輸出串行化格式類型的ISO8601字串。

使用不規則的類型

特殊考慮適用於數位和 遺漏值等類型。

陣列

您可以使用聚合函數從多個元素計算單一值來處理數位。 例如，使用輸入記錄：

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

使用對應：

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)'

此對應會建立陣列，其中包含最小值、最大值、平均值和平均值。

遺失值

遺漏值是用於案例的特殊類型，例如：

  • 提供替代值以處理輸入中的遺失欄位。
  • 根據欄位是否存在，條件式移除該欄位。

使用遺漏值的範例對應：

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

conversion 會使用具有三個參數的 if 參數：

  • 第一個參數為條件。 在此範例中，它會檢查輸入字段的欄位（別名為 $1） 是否BaseSalary為遺漏值。
  • 如果第一個參數中的條件為 true，則第二個參數為函數的結果。 在此範例中，此參數是內容化資料集 (別名為 $2) 的 BaseSalary 欄位。
  • 如果第一個參數為 false，第三個參數為條件的值。

可用的函數

數據流提供一組可用於轉換公式的內建函式。 這些函式可用來執行一般運算，例如算術、比較和字串操作。 可用函式包括：

函式 描述 範例
min 從陣列傳回最小值。 min(2, 3, 1) 會傳 1回 ， min($1) 從陣列傳回最小值 $1
max 從陣列傳回最大值。 max(2, 3, 1) 會傳 3回 ， max($1) 從陣列傳回最大值 $1
if 根據條件傳回值。 if($1 > 10, 'High', 'Low')如果 $1 大於 10，則傳'High'回 ，否則傳回'Low'
len 傳回字串的字元長度或 Tuple 中的項目數目。 len("Azure")會傳5回 ，len(1, 2, 3)傳回 len($1) 3，傳回數位列中的項目數$1
floor 傳回小於或等於數位的最大整數。 floor(2.9) 傳回 2
round 將最接近的整數傳回至數位，將半向大小寫捨入為0.0。 round(2.5) 傳回 3
ceil 傳回大於或等於數位的最小整數。 ceil(2.1) 傳回 3
scale 將值從某個範圍調整為另一個範圍。 scale($1, 0, 10, 0, 100) 將輸入值從範圍 0 調整為 10 到範圍 0 到 100

轉換函數

數據流提供數個內建轉換函式，用於常見的單位轉換，例如溫度、壓力、長度、重量和體積。 以下列出一些範例：

轉換 公式 函式名稱
攝氏至華氏 F = (C * 9/5) + 32 cToF
PSI 到列 Bar = PSI * 0.0689476 psiToBar
英吋到 cm Cm = 英吋 * 2.54 inToCm
腳對計量 計量 = 腳 * 0.3048 ftToM
磅到公斤 Kg = lbs * 0.453592 lbToKg
加侖到升 升數 = 加侖 * 3.78541 galToL

也支援反向轉換：

轉換 公式 函式名稱
華氏至攝氏 C = (F - 32) * 5/9 fToC
Bar 至 PSI PSI = bar / 0.0689476 barToPsi
Cm 到英吋 英吋 = cm / 2.54 cmToIn
計量到腳 Foot = meter / 0.3048 mToFt
公斤到磅 Lbs = kg / 0.453592 kgToLb
升至加侖 加侖 = 升 / 3.78541 lToGal

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

依優先順序排列的可用運算符

Operator 描述
^ 乘冪：$1 ^ 3

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

  • $1 * 2 ^ 3 會解譯為 $1 * 8，因為會先執行 2 ^ 3 部分，再進行乘法。
  • ($1 * 2) ^ 3 先處理乘法再處理乘冪。
Operator 描述
- 否定
! 邏輯 NOT

Negation 和 Logical not 的優先順序較高，因此一律會相互接續進行，但在包含乘冪時除外：

  • -$1 * 2 先否定 $1 ，然後再乘以。
  • -($1 * 2) 乘以，然後否定結果。
Operator 描述
* 乘法：$1 * 10
/ 除法：$1 / 25 (如果兩個引數都為整數，則結果為整數，否則為浮點數)
% 模數：$1 % 25

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

Operator 描述
+ 數值的加法、字串的串連
- 減

Addition 與上一個群組中的作業相比，和 Subtraction 視為較弱的作業：

  • $1 + 2 * 3 結果為 ， $1 + 6 因為 2 * 3 的優先順序 multiplication較高，因此會先執行 。
  • ($1 + 2) * 3 優先於 Addition Multiplication之前。
Operator 描述
< 小於
> 大於
<= 小於或等於
>= 大於或等於
== 等於
!= 不等於

Comparisons 操作數值、布爾值和字串值。 因為它們的優先順序低於算術運算元，因此不需要括弧來有效地比較結果：

  • $1 * 2 <= $2 等於 ($1 * 2) <= $2。
Operator 描述
|| 邏輯 OR
&& 邏輯 AND

邏輯運算子可用來鏈結條件：

  • $1 > 100 && $2 > 200