Compartir por

Formatos de serialización y deserialización en canalizaciones de la versión preliminar del procesador de datos de Azure IoT

  • Artigo

Importante

Operaciones de IoT de Azure, habilitado por Azure Arc, está actualmente en VERSIÓN PRELIMINAR. No se debería usar este software en versión preliminar en entornos de producción.

Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure para conocer los términos legales que se aplican a las características de Azure que se encuentran en la versión beta, en versión preliminar o que todavía no se han publicado para que estén disponibles con carácter general.

El procesador de datos es una plataforma independiente de datos. El procesador de datos puede ingerir, procesar y escribir datos en cualquier formato.

Sin embargo, para usar expresiones de ruta de acceso jq en algunas fases de canalización, los datos deben estar en un formato estructurado dentro de una canalización. Es posible que tenga que deserializar los datos para obtenerlos en un formato estructurado adecuado.

Algunos destinos de canalización o llamadas de fases pueden requerir que los datos estén en un formato específico. Es posible que tenga que serializar los datos en un formato adecuado para el destino.

Deserialización de mensajes

El procesador de datos admite de forma nativa la deserialización de varios formatos en la fase de origen de datos y en las fases de llamada en las que la canalización lee datos externos:

  • La fase de origen puede deserializar los datos entrantes.
  • Las fases de llamada pueden deserializar la respuesta de la API.

Es posible que no tenga que deserializar los datos entrantes si:

  • No está usando las fases que requieren datos deserializados.
  • Solo está procesando metadatos.
  • Los datos entrantes ya están en un formato coherente con las fases que se usan.

En la tabla siguiente se enumeran los formatos para los que se admite la deserialización y las fases correspondientes.

Format Origen de datos Llamada
Sin formato Compatible HTTP
JSON Compatible HTTP
Protobuf Compatible Todos (HTTP y gRPC)
CSV Compatible HTTP
MessagePack Compatible HTTP
CBOR Compatible HTTP

Sugerencia

Seleccione Raw cuando no necesite deserialización. La opción Raw pasa los datos a través del formato actual.

Serialización de mensajes

El procesador de datos admite de forma nativa la serialización en varios formatos tanto en el destino como en las fases de llamada en las que la canalización escribe datos externos:

  • La fase de destino puede serializar los datos salientes en un formato adecuado.
  • Las fases de llamada pueden serializar los datos enviados en una solicitud de API.
Format Llamada Fase de salida
Raw HTTP Todos excepto Microsoft Fabric
JSON HTTP Todos excepto Microsoft Fabric
Parquet No compatible Microsoft Fabric
Protobuf All Todos excepto Microsoft Fabric
CSV HTTP Todos excepto Microsoft Fabric
MessagePack HTTP Todos excepto Microsoft Fabric
CBOR HTTP Todos excepto Microsoft Fabric

Sugerencia

Seleccione Raw cuando no se requiera ninguna serialización. La opción Raw pasa los datos en su formato actual.

Formatos de datos Raw/JSON/MessagePack/CBOR

Raw es la opción que se debe usar cuando no es necesario deserializar o serializar datos. Raw es el valor predeterminado en la mayoría de las fases en las que no se aplica la deserialización o la serialización.

La configuración de serialización o deserialización es común para los formatos Raw, JSON, MessagePack y CBOR. Para estos formatos, use las siguientes opciones de configuración.

Use las siguientes opciones de configuración para deserializar datos:

Campo Tipo Description ¿Necesario? Valor predeterminado Ejemplo
type string enum El formato para la deserialización No - JSON
path Path Ruta de acceso a la parte del mensaje del procesador de datos donde se escriben los datos deserializados. (consulte la nota siguiente) .payload .payload.response

Nota:

No es necesario especificar path al deserializar los datos en la fase de origen. Los datos deserializados se colocan automáticamente en la sección .payload del mensaje.

Use las siguientes opciones de configuración para serializar datos:

Campo Tipo Description ¿Necesario? Valor predeterminado Ejemplo
type string enum El formato para la serialización Sí - JSON
path Path Ruta de acceso a la parte del mensaje del procesador de datos que se debe serializar. (consulte la nota siguiente) .payload .payload.response

Nota:

No es necesario especificar path al serializar datos por lotes. La ruta de acceso predeterminada es ., que representa todo el mensaje. Para los datos no asignados, debe especificar path.

En el ejemplo siguiente se muestra la configuración para serializar o deserializar datos JSON no dispuestos en lotes:

{
    "format": {
        "type": "json",
        "path": ".payload"
    }
}

En el ejemplo siguiente se muestra la configuración para deserializar datos JSON en la fase de origen o serializar datos JSON por lotes:

{
    "format": {
        "type": "json"
    }
}

Formato de datos de búferes de protocolo

Use las siguientes opciones de configuración para deserializar datos de búferes de protocolo (protobuf):

Campo Tipo Description ¿Necesario? Valor predeterminado Ejemplo
type string enum El formato para la deserialización Sí - protobuf
descriptor string Descriptor codificado en base64 para los archivos de definición protobuf. Sí - Zm9v..
package string Nombre del paquete en el descriptor donde se define el tipo. Sí - package1..
message string Nombre del tipo de mensaje que se usa para dar formato a los datos. Sí - message1..
path Path Ruta de acceso a la parte del mensaje del procesador de datos donde se deben escribir los datos deserializados. (consulte la nota siguiente) .payload .payload.gRPCResponse

Nota:

No es necesario especificar path al deserializar los datos en la fase de origen. Los datos deserializados se colocan automáticamente en la sección .payload del mensaje.

Use las siguientes opciones de configuración para serializar datos protobuf:

Campo Tipo Description ¿Necesario? Valor predeterminado Ejemplo
type string enum El formato para la serialización Sí - protobuf
descriptor string Descriptor codificado en base64 para los archivos de definición protobuf. Sí - Zm9v..
package string Nombre del paquete en el descriptor donde se define el tipo. Sí - package1..
message string Nombre del tipo de mensaje que se usa para dar formato a los datos. Sí - message1..
path Path Ruta de acceso a la parte del mensaje del procesador de datos desde la que se leen los datos que se van a serializar. (consulte la nota siguiente) - .payload.gRPCRequest

Nota:

No es necesario especificar path al serializar datos por lotes. La ruta de acceso predeterminada es ., que representa todo el mensaje.

En el ejemplo siguiente se muestra la configuración para serializar o deserializar datos protobuf no dispuestos en lotes:

{
    "format": {
        "type": "protobuf",
        "descriptor": "Zm9v..",
        "package": "package1",
        "message": "message1",
        "path": ".payload"
    }
}

En el ejemplo siguiente se muestra la configuración para deserializar datos protobuf en la fase de origen o serializar datos protobuf por lotes:

{
    "format": {
        "type": "protobuf",
        "descriptor": "Zm9v...", // The full descriptor
        "package": "package1",
        "message": "message1"
    }
}

Formato de datos CSV

Use las siguientes opciones de configuración para deserializar datos CSV:

Campo Tipo Description ¿Necesario? Valor predeterminado Ejemplo
type string enum El formato para la deserialización Sí - CSV
header boolean Este campo indica si los datos de entrada tienen una fila de encabezado CSV. Sí - true
columns array Definición de esquema del CSV que se va a leer. Sí - (consulte la tabla siguiente)
path Path Ruta de acceso a la parte del mensaje del procesador de datos donde se deben escribir los datos deserializados. (consulte la nota siguiente) - .payload

Nota:

No es necesario especificar path al deserializar los datos en la fase de origen. Los datos deserializados se colocan automáticamente en la sección .payload del mensaje.

Cada elemento de la matriz de columnas es un objeto con el esquema siguiente:

Campo Tipo Description ¿Necesario? Valor predeterminado Ejemplo
name string Nombre de la columna tal como aparece en el encabezado CSV. Sí - temperature
type string enum El tipo de datos del procesador de datos que se mantiene en la columna que se usa para determinar cómo analizar los datos. No cadena integer
path Path Ubicación dentro de cada registro de los datos desde los que se debe leer el valor de la columna. No .{{name}} .temperature

Use las siguientes opciones de configuración para serializar datos CSV:

Campo Tipo Description ¿Necesario? Valor predeterminado Ejemplo
type string enum El formato para la serialización Sí - CSV
header boolean Este campo indica si se debe incluir la línea de encabezado con nombres de columna en el CSV serializado. Sí - true
columns array Definición de esquema del CSV que se va a escribir. Sí - (consulte la tabla siguiente)
path Path Ruta de acceso a la parte del mensaje del procesador de datos donde se escriben los datos que se van a serializar. (consulte la nota siguiente) - .payload

Nota:

No es necesario especificar path al serializar datos por lotes. La ruta de acceso predeterminada es ., que representa todo el mensaje.

Campo Tipo Description ¿Necesario? Valor predeterminado Ejemplo
name string Nombre de la columna tal como aparecería en un encabezado CSV. Sí - temperature
path Path Ubicación dentro de cada registro de los datos en los que se debe escribir el valor de la columna. No .{{name}} .temperature

En el ejemplo siguiente se muestra la configuración para serializar datos CSV no dispuestos en lotes:

{
    "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"
    }
}

En el ejemplo siguiente se muestra la configuración para serializar datos CSV por lotes. Omita el path de nivel superior para los datos por lotes:

{
    "format": {
        "type": "csv",
        "header": true,
        "columns": [
            {
                "name": "assetId",
                "path": ".assetId"
            },
            {
                "name": "timestamp",
                "path": ".eventTime"
            },
            {
                "name": "temperature",
                // Path is optional, defaults to .temperature
            }
        ]
    }
}

En el ejemplo siguiente se muestra la configuración para deserializar datos CSV no dispuestos en lotes:

{
    "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"
    }
}

En el ejemplo siguiente se muestra la configuración para deserializar datos CSV por lotes en la fase de origen:

{
    "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
            }
        ]
    }
}

Contenido relacionado