次の方法で共有

データ フロー変換を使用してデータを変換する

  • [アーティクル]

重要

このページには、プレビュー段階にある Kubernetes デプロイ マニフェストを使用して Azure IoT Operations コンポーネントを管理する手順が含まれます。 この機能はいくつかの制限を設けて提供されており、運用環境のワークロードには使用しないでください。

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

データ フロー変換を使用して、Azure IoT Operations でデータを変換できます。 データ フローの conversion 要素は、出力フィールドの値を計算するために使用されます。 データ フロー変換では、入力フィールド、使用可能な操作、データ型、および型変換を使用できます。

データ フローの変換要素は、次のように出力フィールドの値を計算するために使用されます。

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 ナノ秒の解像度の UTC または現地時刻。
time ナノ秒の解像度の時刻。
duration ナノ秒の解像度の期間。
array 前記の任意の型の配列。
map 前記の任意の型の (キー、値) ペアのベクトル。

入力レコード フィールド

入力レコード フィールドが読み取られると、その基になる型が、次の内部型バリアントのいずれかに変換されます。 内部表現は、ほとんどの入力型を最小限の変換で、またはまったく変換なしで処理するのに十分な汎用性があります。

一部の形式には、サロゲート型が使用されます。 たとえば、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)'

この構成では、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 は、次の 3 つのパラメーターを持つ if 関数を使用します。

  • 最初のパラメーターは条件です。 この例では、入力フィールドの BaseSalary フィールド (エイリアスは $1) が欠損値かどうかを調べます。
  • 2 番めのパラメーターは、最初のパラメーターの条件が true の場合の関数の結果です。 この例では、コンテキスト化データセットの BaseSalary フィールド (エイリアスは $2) です。
  • 3 番めのパラメーターは、最初のパラメーターが false の場合の条件の値です。

使用できる関数

データ フローには、変換式で使用できる一連の組み込み関数が用意されています。 これらの関数を使用すると、算術や比較または文字列の操作など、一般的な処理を実行できます。 使用できる関数は次のとおりです。

関数 説明 例
min 配列から最小値を返します。 min(2, 3, 1) は 1 を返し、 min($1) は配列 $1 から最小値を返します
max 配列から最大値を返します。 max(2, 3, 1) は 3 を返し、max($1) は配列 $1 から最大値を返します
if 条件に基づいて値の間を返します。 $1 が 10 より大きい場合 if($1 > 10, 'High', 'Low') は 'High' を返し、そうでない場合は 'Low' を返します
len 文字列の文字長またはタプル内の要素の数を返します。 len("Azure") は 5 を返し、len(1, 2, 3) は 3 を返し、len($1) は配列 $1 内の要素の数を返します
floor ある数値以下の最大の整数を返します。 floor(2.9) は 2 を返します。
round 中間値 （0.5) を 0.0 から遠い値に丸めて、ある数値に最も近い整数を返します。 round(2.5) は 3 を返します。
ceil ある数値以上の最小の整数を返します。 ceil(2.1) は 3 を返します。
scale ある範囲から別の範囲に値をスケーリングします。 scale($1, 0, 10, 0, 100) は、入力値を 0 から 10 の範囲から 0 から 100 の範囲にスケーリングします

変換関数

データ フローには、温度、圧力、長さ、重量、体積など一般的な単位の変換用に、組み込みの変換関数がいくつか用意されています。 次に例をいくつか示します。

Conversion 式 関数名
摂氏から華氏 F = (C * 9/5) + 32 cToF
PSI から bar Bar = PSI * 0.0689476 psiToBar
インチからセンチメートル cm = inch * 2.54 inToCm
フィートからメートル meter = foot * 0.3048 ftToM
ボンドからキログラム Kg = lbs * 0.453592 lbToKg
ガロンからリットル liters = gallons * 3.78541 galToL

逆変換もサポートされています。

Conversion 式 関数名
華氏から摂氏 C = (F - 32) * 5/9 fToC
BAR から PSI PSI = bar / 0.0689476 barToPsi
センチメートルからインチ inch = cm / 2.54 cmToIn
メートルからフィート foot = meter / 0.3048 mToFt
キログラムからポンド lbs = Kg / 0.453592 kgToLb
リットルからガロン gallons = liters / 3.78541 lToGal

また、基本的な数式を使用して独自の変換関数を定義することもできます。 システムでは、加算 (+)、減算 (-)、乗算 (*)、除算 (/) などの演算子がサポートされています。 これらの演算子は標準的な優先順位規則に従います。かっこを使用してこれらの規則を調整することで、適切な順序で処理が行われるようにできます。 これにより、特定のニーズに合わせて単位変換をカスタマイズできます。

優先順位で使用できる演算子

Operator 説明
^ 累乗: $1 ^ 3

Exponentiation は最も優先順位が高いため、かっこでこの順序がオーバーライドされない限り、最初に実行されます。

  • $1 * 2 ^ 3 は、乗算の前に最初に 2 ^ 3 部分が実行されるため、$1 * 8 と解釈されます。
  • ($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 の結果は、multiplication の優先順位が高いために 2 * 3 が最初に実行されるので、$1 + 6 になります。
  • ($1 + 2) * 3 では、Multiplication より Addition が優先されます。
Operator 説明
< より小さい
> より大きい
<= 以下
>= 以上
== 等しい
!= 等しくない

Comparisons は、数値、ブール値、文字列値を操作します。 これらは算術演算子より優先順位が低いため、結果を効果的に比較するためにかっこは必要ありません。

  • $1 * 2 <= $2 は ($1 * 2) <= $2 と等価です。
Operator 説明
|| 論理和
&& 論理 AND

論理演算子は、条件を連結するために使用されます。

  • $1 > 100 && $2 > 200