數據處理者管線中的串行化和還原串行化格式
重要
已啟用 Azure Arc 的 Azure IoT 操作預覽版目前為預覽狀態。 請勿在生產環境使用此預覽版軟體。
當正式發行可供使用時，您將需要部署新的 Azure IoT 作業安裝，您將無法升級預覽安裝。
請參閱 Microsoft Azure 預覽版增補使用規定，以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未正式發行的版本) 的法律條款。
資料處理器是與資料無關的平台。 資料處理器可以內嵌、處理和寫出任何格式的資料。
不過，若要在某些管線階段使用 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 |
還原序列化的格式 | No | - | JSON |
path |
路徑 | 寫入還原串行化數據之數據處理者訊息部分的路徑。 | (請參閱下列注意事項) | .payload |
.payload.response |
注意
您不需要在來源階段還原序列化資料時指定 path。 還原序列化資料會自動放置在訊息的 .payload 區段中。
使用下列組態選項來序列化資料：
| 欄位 | 類型 | 描述 | 是必要的嗎? | 預設 | 範例 |
|---|---|---|---|---|---|
type |
string enum |
序列化的格式 | Yes | - | JSON |
path |
路徑 | 應該串行化之數據處理者訊息部分的路徑。 | (請參閱下列注意事項) | .payload |
.payload.response |
注意
您不需要在序列化已批次處理的資料時指定 path。 預設路徑為 .，代表整個訊息。 針對未批次處理的資料，您必須指定 path。
下列範例顯示序列化或還原序列化未批次處理的 JSON 資料組態：
{
"format": {
"type": "json",
"path": ".payload"
}
}
下列範例示範在來源階段還原序列化 JSON 資料的組態，或序列化已批次處理的 JSON 資料：
{
"format": {
"type": "json"
}
}
通訊協定緩衝區資料格式
使用下列組態選項來還原序列化通訊協定緩衝區 (protobuf) 資料：
| 欄位 | 類型 | 描述 | 是必要的嗎? | 預設 | 範例 |
|---|---|---|---|---|---|
type |
string enum |
還原序列化的格式 | Yes | - | protobuf |
descriptor |
string |
protobuf 定義檔的 base64 編碼描述項。 | Yes | - | Zm9v.. |
package |
string |
描述項中定義類別之套件的名稱。 | Yes | - | package1.. |
message |
string |
用於格式化資料之訊息類型的名稱。 | Yes | - | message1.. |
path |
路徑 | 應該寫入還原串行化數據之數據處理者訊息部分的路徑。 | (請參閱下列注意事項) | .payload |
.payload.gRPCResponse |
注意
您不需要在來源階段還原序列化資料時指定 path。 還原序列化資料會自動放置在訊息的 .payload 區段中。
使用下列組態選項來序列化 protobuf 資料：
| 欄位 | 類型 | 描述 | 是必要的嗎? | 預設 | 範例 |
|---|---|---|---|---|---|
type |
string enum |
序列化的格式 | Yes | - | protobuf |
descriptor |
string |
protobuf 定義檔的 base64 編碼描述項。 | Yes | - | Zm9v.. |
package |
string |
描述項中定義類別之套件的名稱。 | Yes | - | package1.. |
message |
string |
用於格式化資料之訊息類型的名稱。 | Yes | - | message1.. |
path |
路徑 | 要串行化之數據從中讀取之數據處理者訊息部分的路徑。 | (請參閱下列注意事項) | - | .payload.gRPCRequest |
注意
您不需要在序列化已批次處理的資料時指定 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 |
還原序列化的格式 | Yes | - | CSV |
header |
boolean |
此欄位指出輸入資料是否有 CSV 標頭資料列。 | Yes | - | true |
columns |
array |
要讀取之 CSV 架構定義。 | Yes | - | (請參閱下表) |
path |
路徑 | 應該寫入還原串行化數據之數據處理者訊息部分的路徑。 | (請參閱下列注意事項) | - | .payload |
注意
您不需要在來源階段還原序列化資料時指定 path。 還原序列化資料會自動放置在訊息的 .payload 區段中。
資料列陣列中的每個元素都是具有下列架構的物件：
| 欄位 | 類型 | 描述 | 是必要的嗎? | 預設 | 範例 |
|---|---|---|---|---|---|
name |
string |
CSV 標頭中顯示的資料行名稱。 | Yes | - | temperature |
type |
string enum |
保存在資料行中，用來判斷如何剖析資料的資料處理器資料類型。 | No | string | integer |
path |
路徑 | 各項資料記錄中讀取資料行值的位置。 | No | .{{name}} |
.temperature |
使用下列組態選項來序列化 CSV 資料：
| 欄位 | 類型 | 描述 | 是必要的嗎? | 預設 | 範例 |
|---|---|---|---|---|---|
type |
string enum |
序列化的格式 | Yes | - | CSV |
header |
boolean |
此欄位指出是否要在序列化 CSV 中包含具有資料行名稱的標頭行。 | Yes | - | true |
columns |
array |
要寫入之 CSV 架構定義。 | Yes | - | (請參閱下表) |
path |
路徑 | 寫入要串行化之數據之數據處理者訊息部分的路徑。 | (請參閱下列注意事項) | - | .payload |
注意
您不需要在序列化已批次處理的資料時指定 path。 預設路徑為 .，代表整個訊息。
| 欄位 | 類型 | 描述 | 是必要的嗎? | 預設 | 範例 |
|---|---|---|---|---|---|
name |
string |
在 CSV 標頭中顯示的資料行名稱。 | Yes | - | temperature |
path |
路徑 | 每個資料記錄內應該寫入資料行值的位置。 | No | .{{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
}
]
}
}