Visão geral dos formatos de serialização e desserialização
Importante
O recurso Pré-visualização de Operações do Azure IoT — habilitado pelo Azure Arc — está atualmente em VERSÃO PRÉVIA. Você não deve usar esse software em versão prévia em ambientes de produção.
Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.
O processador de dados é uma plataforma independente de dados. O processador de dados pode ingerir, processar e gravar dados em qualquer formato.
No entanto, para usar expressões de caminho jq em alguns estágios de pipeline, os dados devem estar em um formato estruturado dentro de um pipeline. Talvez seja necessário desserializar seus dados para obtê-los em um formato estruturado adequado.
Alguns destinos de pipeline ou chamadas de estágios podem exigir que os dados estejam em um formato específico. Talvez seja necessário serializar seus dados em um formato adequado para o destino.
Desserializar mensagens
O processador de dados dá suporte nativo à desserialização de vários formatos no estágio da fonte de dados e nos estágios de chamada em que o pipeline lê dados externos:
- O estágio de origem pode desserializar os dados de entrada.
- Os estágios de chamada podem desserializar a resposta da API.
Talvez você não precise desserializar os dados de entrada se:
- Você não está usando os estágios que exigem dados desserializados.
- Você está processando metadados apenas.
- Os dados de entrada já estão em um formato consistente com os estágios que estão sendo usados.
A tabela a seguir lista os formatos para os quais há suporte para desserialização e os estágios correspondentes.
| Formatar | Fonte de dados | Chamar para fora |
|---|---|---|
| Raw | Com suporte | HTTP |
| JSON | Com suporte | HTTP |
| Protobuf | Com suporte | All (HTTP e gRPC) |
| CSV | Com suporte | HTTP |
| MessagePack | Com suporte | HTTP |
| CBOR | Com suporte | HTTP |
Dica
Selecione Raw quando você não precisar de desserialização. A opção Raw passa os dados no formato atual.
Serializar mensagens
O processador de dados dá suporte nativo à serialização em vários formatos nos estágios de destino e de chamada em que o pipeline grava dados externos:
- O estágio de destino pode serializar os dados de saída para um formato adequado.
- Estágios de chamada podem serializar os dados enviados em uma solicitação de API.
| Formatar | Chamar para fora | Estágio de saída |
|---|---|---|
Raw |
HTTP | Todos, exceto o Microsoft Fabric |
JSON |
HTTP | Todos, exceto o Microsoft Fabric |
Parquet |
Sem suporte | Microsoft Fabric |
Protobuf |
Tudo | Todos, exceto o Microsoft Fabric |
CSV |
HTTP | Todos, exceto o Microsoft Fabric |
MessagePack |
HTTP | Todos, exceto o Microsoft Fabric |
CBOR |
HTTP | Todos, exceto o Microsoft Fabric |
Dica
Selecione Raw quando nenhuma serialização for necessária. A opção Raw passa os dados no formato atual.
Formatos de dados Raw/JSON/MessagePack/CBOR
Raw é a opção a ser usada quando você não precisa desserializar ou serializar dados. Raw é o padrão na maioria dos estágios em que a desserialização ou serialização não é imposta.
A configuração de serialização ou desserialização é comum para os formatos Raw, JSON, MessagePack e CBOR. Para esses formatos, use as seguintes opções de configuração.
Use as seguintes opções de configuração para desserializar dados:
| Campo | Type | Descrição | Obrigatório? | Padrão | Exemplo |
|---|---|---|---|---|---|
type |
string enum |
O formato para desserialização | Não | - | JSON |
path |
Caminho | O caminho para a parte da mensagem do Processador de Dados na qual os dados desserializados são gravados. | (confira a observação a seguir) | .payload |
.payload.response |
Observação
Você não precisa especificar path quando desserializar dados no estágio de origem. Os dados desserializados são colocados automaticamente na seção da mensagem .payload.
Use as seguintes opções de configuração para serializar dados:
| Campo | Type | Descrição | Obrigatório? | Padrão | Exemplo |
|---|---|---|---|---|---|
type |
string enum |
O formato para serialização | Sim | - | JSON |
path |
Caminho | O caminho para a parte da mensagem do Processador de Dados que deve ser serializada. | (confira a observação a seguir) | .payload |
.payload.response |
Observação
Você não precisa especificar path ao serializar dados de em lote. O caminho padrão é ., que representa toda a mensagem. Para dados sem correspondência, você deve especificar path.
O exemplo a seguir mostra a configuração para serializar ou desserializar dados JSON sem correspondência:
{
"format": {
"type": "json",
"path": ".payload"
}
}
O exemplo a seguir mostra a configuração para desserializar dados JSON no estágio de origem ou serializar dados JSON em lote:
{
"format": {
"type": "json"
}
}
Formato de dados de buffers de protocolo
Use as seguintes opções de configuração para desserializar dados de buffers de protocolo (protobuf):
| Campo | Type | Descrição | Obrigatório? | Padrão | Exemplo |
|---|---|---|---|---|---|
type |
string enum |
O formato para desserialização | Sim | - | protobuf |
descriptor |
string |
O descritor codificado em base64 para os arquivos de definição de protobuf. | Sim | - | Zm9v.. |
package |
string |
O nome do pacote no descritor em que o tipo é definido. | Sim | - | package1.. |
message |
string |
O nome do tipo de mensagem usado para formatar os dados. | Sim | - | message1.. |
path |
Caminho | O caminho para a parte da mensagem do Processador de Dados em que os dados desserializados devem ser gravados. | (confira a observação a seguir) | .payload |
.payload.gRPCResponse |
Observação
Você não precisa especificar path quando desserializar dados no estágio de origem. Os dados desserializados são colocados automaticamente na seção da mensagem .payload.
Use as seguintes opções de configuração para serializar dados protobuf:
| Campo | Type | Descrição | Obrigatório? | Padrão | Exemplo |
|---|---|---|---|---|---|
type |
string enum |
O formato para serialização | Sim | - | protobuf |
descriptor |
string |
O descritor codificado em base64 para os arquivos de definição de protobuf. | Sim | - | Zm9v.. |
package |
string |
O nome do pacote no descritor em que o tipo é definido. | Sim | - | package1.. |
message |
string |
O nome do tipo de mensagem usado para formatar os dados. | Sim | - | message1.. |
path |
Caminho | O caminho para a parte da mensagem do Processador de Dados da qual os dados a serem serializados são lidos. | (confira a observação a seguir) | - | .payload.gRPCRequest |
Observação
Você não precisa especificar path ao serializar dados de em lote. O caminho padrão é ., que representa toda a mensagem.
O exemplo a seguir mostra a configuração para serializar ou desserializar dados de protobuf sem correspondência:
{
"format": {
"type": "protobuf",
"descriptor": "Zm9v..",
"package": "package1",
"message": "message1",
"path": ".payload"
}
}
O exemplo a seguir mostra a configuração para desserializar dados protobuf no estágio de origem ou serializar dados protobuf em lote:
{
"format": {
"type": "protobuf",
"descriptor": "Zm9v...", // The full descriptor
"package": "package1",
"message": "message1"
}
}
Formato de dados CSV
Use as seguintes opções de configuração para desserializar dados CSV:
| Campo | Type | Descrição | Obrigatório? | Padrão | Exemplo |
|---|---|---|---|---|---|
type |
string enum |
O formato para desserialização | Sim | - | CSV |
header |
boolean |
Esse campo indica se os dados de entrada têm uma linha de cabeçalho CSV. | Sim | - | true |
columns |
array |
A definição de esquema do CSV a ser lido. | Sim | - | (consulte a tabela a seguir) |
path |
Caminho | O caminho para a parte da mensagem do Processador de Dados em que os dados desserializados devem ser gravados. | (confira a observação a seguir) | - | .payload |
Observação
Você não precisa especificar path quando desserializar dados no estágio de origem. Os dados desserializados são colocados automaticamente na seção da mensagem .payload.
Cada elemento na matriz de colunas é um objeto com o seguinte esquema:
| Campo | Type | Descrição | Obrigatório? | Padrão | Exemplo |
|---|---|---|---|---|---|
name |
string |
O nome da coluna como ela aparece no cabeçalho CSV. | Sim | - | temperature |
type |
string enum |
O tipo de dados do processador de dados mantido na coluna usada para determinar como analisar os dados. | Não | string | integer |
path |
Caminho | O local dentro de cada registro dos dados nos quais o valor da coluna deve ser lido. | Não | .{{name}} |
.temperature |
Use as seguintes opções de configuração para serializar dados CSV:
| Campo | Type | Descrição | Obrigatório? | Padrão | Exemplo |
|---|---|---|---|---|---|
type |
string enum |
O formato para serialização | Sim | - | CSV |
header |
boolean |
Esse campo indica se a linha de cabeçalho deve ser incluída com nomes de coluna no CSV serializado. | Sim | - | true |
columns |
array |
A definição de esquema do CSV a ser gravado. | Sim | - | (consulte a tabela a seguir) |
path |
Caminho | O caminho para a parte da mensagem do Processador de Dados em que os dados a serem serializados são gravados. | (confira a observação a seguir) | - | .payload |
Observação
Você não precisa especificar path ao serializar dados de em lote. O caminho padrão é ., que representa toda a mensagem.
| Campo | Type | Descrição | Obrigatório? | Padrão | Exemplo |
|---|---|---|---|---|---|
name |
string |
O nome da coluna como ela seria exibida em um cabeçalho CSV. | Sim | - | temperature |
path |
Caminho | O local dentro de cada registro dos dados nos quais o valor da coluna deve ser gravado. | Não | .{{name}} |
.temperature |
O exemplo a seguir mostra a configuração para serializar dados CSV sem correspondência:
{
"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"
}
}
O exemplo a seguir mostra a configuração para serializar dados CSV em lote. Omita o nível superior path para dados em lote:
{
"format": {
"type": "csv",
"header": true,
"columns": [
{
"name": "assetId",
"path": ".assetId"
},
{
"name": "timestamp",
"path": ".eventTime"
},
{
"name": "temperature",
// Path is optional, defaults to .temperature
}
]
}
}
O exemplo a seguir mostra a configuração para desserializar dados CSV sem correspondência:
{
"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"
}
}
O exemplo a seguir mostra a configuração para desserializar dados CSV em lote no estágio de origem:
{
"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
}
]
}
}