Azure IoT Data Processor プレビュー パイプラインのシリアル化と逆シリアル化の形式
重要
Azure Arc によって有効にされる Azure IoT Operations Preview は、 現在プレビュー段階です。 運用環境ではこのプレビュー ソフトウェアを使わないでください。
ベータ版、プレビュー版、または一般提供としてまだリリースされていない Azure の機能に適用される法律条項については、「Microsoft Azure プレビューの追加使用条件」を参照してください。
データ プロセッサは、データに依存しないプラットフォームです。 データ プロセッサは、任意の形式でデータを取り込み、処理、書き出すことができます。
ただし、一部のパイプライン ステージで jq パス式を使用するには、データがパイプライン内の構造化形式である必要があります。 データを適切な構造化形式に変換するには、データの逆シリアル化が必要になる場合があります。
一部のパイプライン変換先またはステージからの呼び出しでは、場合によってはデータを特定の形式にする必要があります。 データを変換先に適した形式にシリアル化することが必要になる場合があります。
メッセージを逆シリアル化する
データ プロセッサは、データ ソース ステージと、パイプラインが外部データを読み取る呼び出しステージの両方で、さまざまな形式の逆シリアル化をネイティブにサポートします。
- ソース ステージでは、受信データを逆シリアル化できます。
- 呼び出しステージでは、API 応答を逆シリアル化できます。
次の場合は、受信データを逆シリアル化する必要がない場合があります。
- 逆シリアル化されたデータを必要とするステージを使用していない。
- メタデータのみを処理している。
- 受信データは既に、使用されているステージと一致する形式になっている。
次の表に、逆シリアル化がサポートされる形式と、対応するステージを示します。
| 形式 | データ ソース | 呼び出し |
|---|---|---|
| Raw | サポートされています | HTTP |
| JSON | サポートされています | HTTP |
| Protobuf | サポートされています | すべて (HTTP と gRPC) |
| CSV | サポートされています | HTTP |
| MessagePack | サポートされています | HTTP |
| CBOR | サポートされています | HTTP |
ヒント
逆シリアル化が必要ない場合は Raw を選択します。 Raw オプションは、データをその現在の形式で渡します。
メッセージをシリアル化する
データ プロセッサは、パイプラインが外部データを書き込む宛先と呼び出し先の両方のステージで、さまざまな形式へのシリアル化をネイティブにサポートします。
- 宛先ステージでは、送信データを適切な形式にシリアル化できます。
- 呼び出しステージでは、API 要求で送信されたデータをシリアル化できます。
| 形式 | 呼び出し | 出力ステージ |
|---|---|---|
Raw |
HTTP | Microsoft Fabric を除くすべて |
JSON |
HTTP | Microsoft Fabric を除くすべて |
Parquet |
サポートされていません | Microsoft Fabric |
Protobuf |
すべて | Microsoft Fabric を除くすべて |
CSV |
HTTP | Microsoft Fabric を除くすべて |
MessagePack |
HTTP | Microsoft Fabric を除くすべて |
CBOR |
HTTP | Microsoft Fabric を除くすべて |
ヒント
シリアル化が必要ない場合は、Raw を選択します。 Raw オプションは、データを現在の形式で渡します。
Raw/JSON/MessagePack/CBOR データ形式
Raw は、データを逆シリアル化またはシリアル化する必要がない場合に使用するオプションです。 Raw は、逆シリアル化またはシリアル化が適用されないほとんどのステージで、既定値です。
シリアル化または逆シリアル化の構成は、Raw、JSON、MessagePack、CBOR 形式で共通です。 これらの形式の場合は、次の構成オプションを使用します。
データを逆シリアル化するには、次の構成オプションを使用します。
| フィールド | タイプ | 説明 | 必須 | 既定値 | 例 |
|---|---|---|---|---|---|
type |
string enum |
逆シリアル化の形式 | いいえ | - | JSON |
path |
Path | 逆シリアル化されたデータを書き込むデータ プロセッサ メッセージの部分へのパス。 | (下記の注を参照) | .payload |
.payload.response |
Note
ソース ステージでデータを逆シリアル化する場合、path を指定する必要はありません。 逆シリアル化されたデータは、メッセージの .payload セクションに自動的に配置されます。
データをシリアル化するには、次の構成オプションを使用します。
| フィールド | タイプ | 説明 | 必須 | 既定値 | 例 |
|---|---|---|---|---|---|
type |
string enum |
シリアル化の形式 | はい | - | JSON |
path |
Path | シリアル化する必要があるデータ プロセッサ メッセージの部分へのパス。 | (下記の注を参照) | .payload |
.payload.response |
Note
バッチ処理されたデータをシリアル化する場合、path を指定する必要はありません。 既定のパスは、. で、これはメッセージ全体を表します。 バッチ処理されていないデータの場合は、path を指定する必要があります。
次の例は、バッチ処理されていない JSON データをシリアル化または逆シリアル化するための構成を示しています。
{
"format": {
"type": "json",
"path": ".payload"
}
}
次の例は、ソース ステージで JSON データを逆シリアル化するか、バッチ処理された JSON データをシリアル化するための構成を示しています。
{
"format": {
"type": "json"
}
}
プロトコル バッファーのデータ形式
プロトコル バッファー (protobuf) データを逆シリアル化するには、次の構成オプションを使用します。
| フィールド | タイプ | 説明 | 必須 | 既定値 | 例 |
|---|---|---|---|---|---|
type |
string enum |
逆シリアル化の形式 | はい | - | protobuf |
descriptor |
string |
protobuf 定義ファイルの base64 エンコード記述子。 | はい | - | Zm9v.. |
package |
string |
型が定義されている記述子内のパッケージの名前。 | はい | - | package1.. |
message |
string |
データのフォーマットに使用されるメッセージ型の名前。 | はい | - | message1.. |
path |
Path | 逆シリアル化されたデータを書き込むデータ プロセッサ メッセージの部分へのパス。 | (下記の注を参照) | .payload |
.payload.gRPCResponse |
Note
ソース ステージでデータを逆シリアル化する場合、path を指定する必要はありません。 逆シリアル化されたデータは、メッセージの .payload セクションに自動的に配置されます。
protobuf データをシリアル化するには、次の構成オプションを使用します。
| フィールド | タイプ | 説明 | 必須 | 既定値 | 例 |
|---|---|---|---|---|---|
type |
string enum |
シリアル化の形式 | はい | - | protobuf |
descriptor |
string |
protobuf 定義ファイルの base64 エンコード記述子。 | はい | - | Zm9v.. |
package |
string |
型が定義されている記述子内のパッケージの名前。 | はい | - | package1.. |
message |
string |
データのフォーマットに使用されるメッセージ型の名前。 | はい | - | message1.. |
path |
Path | シリアル化するデータが読み取られるデータ プロセッサ メッセージの部分へのパス。 | (下記の注を参照) | - | .payload.gRPCRequest |
Note
バッチ処理されたデータをシリアル化する場合、path を指定する必要はありません。 既定のパスは、. で、これはメッセージ全体を表します。
次の例は、バッチ処理されていない protobuf データをシリアル化または逆シリアル化するための構成を示しています。
{
"format": {
"type": "protobuf",
"descriptor": "Zm9v..",
"package": "package1",
"message": "message1",
"path": ".payload"
}
}
次の例は、ソース ステージで protobuf データを逆シリアル化するか、バッチ処理された protobuf データをシリアル化するための構成を示しています。
{
"format": {
"type": "protobuf",
"descriptor": "Zm9v...", // The full descriptor
"package": "package1",
"message": "message1"
}
}
CSV データ形式
CSV データを逆シリアル化するには、次の構成オプションを使用します。
| フィールド | タイプ | 説明 | 必須 | 既定値 | 例 |
|---|---|---|---|---|---|
type |
string enum |
逆シリアル化の形式 | はい | - | CSV |
header |
boolean |
このフィールドは、入力データに CSV ヘッダー行があるかどうかを示します。 | はい | - | true |
columns |
array |
読み取る CSV のスキーマ定義。 | はい | - | (下記の表を参照) |
path |
Path | 逆シリアル化されたデータを書き込むデータ プロセッサ メッセージの部分へのパス。 | (下記の注を参照) | - | .payload |
Note
ソース ステージでデータを逆シリアル化する場合、path を指定する必要はありません。 逆シリアル化されたデータは、メッセージの .payload セクションに自動的に配置されます。
列配列内の各要素は、次のスキーマを持つオブジェクトです。
| フィールド | タイプ | 説明 | 必須 | 既定値 | 例 |
|---|---|---|---|---|---|
name |
string |
CSV ヘッダーに表示される列の名前。 | はい | - | temperature |
type |
string enum |
データの解析方法を決定するために使用される列に保持されているデータ プロセッサのデータ型。 | いいえ | string | integer |
path |
Path | 列の値を読み取るデータの各レコード内の場所。 | いいえ | .{{name}} |
.temperature |
CSV データをシリアル化するには、次の構成オプションを使用します。
| フィールド | タイプ | 説明 | 必須 | 既定値 | 例 |
|---|---|---|---|---|---|
type |
string enum |
シリアル化の形式 | はい | - | CSV |
header |
boolean |
このフィールドは、シリアル化された CSV に列名を含むヘッダー行を含めるかどうかを示します。 | はい | - | true |
columns |
array |
書き込む CSV のスキーマ定義。 | はい | - | (下記の表を参照) |
path |
Path | シリアル化するデータが書き込まれるデータ プロセッサ メッセージの部分へのパス。 | (下記の注を参照) | - | .payload |
Note
バッチ処理されたデータをシリアル化する場合、path を指定する必要はありません。 既定のパスは、. で、これはメッセージ全体を表します。
| フィールド | タイプ | 説明 | 必須 | 既定値 | 例 |
|---|---|---|---|---|---|
name |
string |
CSV ヘッダーに表示される列の名前。 | はい | - | temperature |
path |
Path | 列の値の書き込み先となるデータの各レコード内の場所。 | いいえ | .{{name}} |
.temperature |
次の例は、バッチ処理されていない CSV データをシリアル化するための構成を示しています。
{
"format": {
"type": "csv",
"header": true,
"columns": [
{
"name": "assetId",
"path": ".assetId"
},
{
"name": "timestamp",
"path": ".eventTime"
},
{
"name": "temperature",
// Path is optional, defaults to the name
}
],
"path": ".payload"
}
}
次の例は、バッチ処理されている CSV データをシリアル化するための構成を示しています。 バッチ処理されているデータの最上位レベル path を省略します。
{
"format": {
"type": "csv",
"header": true,
"columns": [
{
"name": "assetId",
"path": ".assetId"
},
{
"name": "timestamp",
"path": ".eventTime"
},
{
"name": "temperature",
// Path is optional, defaults to .temperature
}
]
}
}
次の例は、バッチ処理されていない CSV データを逆シリアル化するための構成を示しています。
{
"format": {
"type": "csv",
"header": false,
"columns": [
{
"name": "assetId",
"type": "string",
"path": ".assetId"
},
{
"name": "timestamp",
// Type is optional, defaults to string
"path": ".eventTime"
},
{
"name": "temperature",
"type": "float"
// Path is optional, defaults to .temperature
}
],
"path": ".payload"
}
}
次の例は、ソース ステージでバッチ処理された CSV データを逆シリアル化するための構成を示しています。
{
"format": {
"type": "csv",
"header": false,
"columns": [
{
"name": "assetId",
"type": "string",
"path": ".assetId"
},
{
"name": "timestamp",
// Type is optional, defaults to string
"path": ".eventTime"
},
{
"name": "temperature",
"type": "float",
// Path is optional, defaults to .temperature
}
]
}
}