Partager via

Formats de sérialisation et de désérialisation dans les pipelines Processeur de données Azure IoT (préversion)

  • Article

Important

Opérations Azure IoT (préversion) – activé parc Azure Arc est actuellement en PRÉVERSION. Vous ne devez pas utiliser ce logiciel en préversion dans des environnements de production.

Pour connaître les conditions juridiques qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou plus généralement non encore en disponibilité générale, consultez l’Avenant aux conditions d’utilisation des préversions de Microsoft Azure.

Le processeur de données est une plateforme indépendante des données. Le processeur de données peut ingérer, traiter et écrire des données dans n’importe quel format.

Toutefois, pour utiliser des expressions de chemin jq dans certaines phases de pipeline, les données doivent être dans un format structuré au sein d’un pipeline. Vous devrez peut-être désérialiser vos données afin qu’elles soient dans un format structuré approprié.

Certaines destinations de pipeline ou appels à partir de phases peuvent exiger que les données soient dans un format spécifique. Vous devrez peut-être sérialiser vos données dans un format approprié pour la destination.

Désérialiser des messages

Le processeur de données prend en charge de manière native la désérialisation de différents formats à la fois durant la phase de la source de données et durant les phases d’appel où le pipeline lit des données externes :

  • La phase source peut désérialiser les données entrantes.
  • Les phases d’appel peuvent désérialiser la réponse de l’API.

Vous ne devrez peut-être pas désérialiser les données entrantes si :

  • Vous n’utilisez pas les phases qui nécessitent des données désérialisées.
  • Vous traitez uniquement des métadonnées.
  • Les données entrantes sont déjà dans un format cohérent avec les phases utilisées.

Le tableau suivant liste les formats pour lesquels la désérialisation est prise en charge, et les phases correspondantes.

Format Source de données Appel
Brut Prise en charge HTTP
JSON Prise en charge HTTP
Protobuf Prise en charge Tous (HTTP et gRPC)
CSV Prise en charge HTTP
MessagePack Prise en charge HTTP
CBOR Prise en charge HTTP

Conseil

Sélectionnez Raw quand vous n’avez pas besoin de désérialisation. L’option Raw transmet les données dans leur format actuel.

Sérialiser des messages

Le processeur de données prend en charge de manière native la sérialisation dans différents formats durant les phases de destination et d’appel où le pipeline écrit des données externes :

  • La phase de destination peut sérialiser les données sortantes au format approprié.
  • Les phases d’appel peuvent sérialiser les données envoyées dans une requête d’API.
Format Appel Phase de sortie
Raw HTTP Tous sauf Microsoft Fabric
JSON HTTP Tous sauf Microsoft Fabric
Parquet Non pris en charge Microsoft Fabric
Protobuf Tous Tous sauf Microsoft Fabric
CSV HTTP Tous sauf Microsoft Fabric
MessagePack HTTP Tous sauf Microsoft Fabric
CBOR HTTP Tous sauf Microsoft Fabric

Conseil

Sélectionnez Raw quand aucune sérialisation n’est requise. L’option Raw transmet les données dans leur format actuel.

Formats de données Raw/JSON/MessagePack/CBOR

Raw est l’option à utiliser lorsque vous n’avez pas besoin de désérialiser ou sérialiser des données. Raw est la valeur par défaut dans la plupart des phases où la désérialisation ou la sérialisation n’est pas appliquée.

La configuration de sérialisation ou de désérialisation est commune pour les formats Raw, JSON, MessagePack et CBOR. Pour ces formats, utilisez les options de configuration suivantes.

Utilisez les options de configuration suivantes pour désérialiser des données :

Champ Type Description Requis ? Par défaut Exemple
type string enum Format de désérialisation Non - JSON
path Chemin d’accès Chemin de la partie du message du Processeur de données où les données désérialisées sont écrites. (voir la remarque suivante) .payload .payload.response

Remarque

Vous n’avez pas besoin de spécifier path quand vous désérialisez des données durant la phase source. Les données désérialisées sont automatiquement placées dans la section .payload du message.

Utilisez les options de configuration suivantes pour sérialiser des données :

Champ Type Description Requis ? Par défaut Exemple
type string enum Format de sérialisation Oui - JSON
path Chemin d’accès Chemin de la partie du message du Processeur de données qui doit être sérialisée. (voir la remarque suivante) .payload .payload.response

Remarque

Vous n’avez pas besoin de spécifier path quand vous sérialisez des données par lots. Le chemin par défaut est ., qui représente l’intégralité du message. Pour les données non regroupées par lots, vous devez spécifier path.

L’exemple suivant montre la configuration pour la sérialisation ou la désérialisation de données JSON non regroupées par lots :

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

L’exemple suivant montre la configuration pour la désérialisation de données JSON durant la phase source ou la sérialisation de données JSON par lots :

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

Format de données des mémoires tampons de protocole

Utilisez les options de configuration suivantes pour désérialiser des données de mémoires tampons de protocole (protobuf) :

Champ Type Description Requis ? Par défaut Exemple
type string enum Format de désérialisation Oui - protobuf
descriptor string Descripteur encodé en base64 pour le ou les fichiers de définition protobuf. Oui - Zm9v..
package string Nom du package dans le descripteur où le type est défini. Oui - package1..
message string Nom du type de message utilisé pour mettre en forme les données. Oui - message1..
path Chemin d’accès Chemin de la partie du message du Processeur de données où les données désérialisées doivent être écrites. (voir la remarque suivante) .payload .payload.gRPCResponse

Remarque

Vous n’avez pas besoin de spécifier path quand vous désérialisez des données durant la phase source. Les données désérialisées sont automatiquement placées dans la section .payload du message.

Utilisez les options de configuration suivantes pour sérialiser des données protobuf :

Champ Type Description Requis ? Par défaut Exemple
type string enum Format de sérialisation Oui - protobuf
descriptor string Descripteur encodé en base64 pour le ou les fichiers de définition protobuf. Oui - Zm9v..
package string Nom du package dans le descripteur où le type est défini. Oui - package1..
message string Nom du type de message utilisé pour mettre en forme les données. Oui - message1..
path Chemin d’accès Chemin de la partie du message du Processeur de données à partir de laquelle les données à sérialiser sont lues. (voir la remarque suivante) - .payload.gRPCRequest

Remarque

Vous n’avez pas besoin de spécifier path quand vous sérialisez des données par lots. Le chemin par défaut est ., qui représente l’intégralité du message.

L’exemple suivant montre la configuration pour la sérialisation ou la désérialisation de données protobuf non regroupées par lots :

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

L’exemple suivant montre la configuration pour la désérialisation de données protobuf durant la phase source ou la sérialisation de données protobuf par lots :

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

Format de données CSV

Utilisez les options de configuration suivantes pour désérialiser des données CSV :

Champ Type Description Requis ? Par défaut Exemple
type string enum Format de désérialisation Oui - CSV
header boolean Ce champ indique si les données d’entrée ont une ligne d’en-tête CSV. Oui - true
columns array Définition de schéma du fichier CSV à lire. Oui - (voir le tableau suivant)
path Chemin d’accès Chemin de la partie du message du Processeur de données où les données désérialisées doivent être écrites. (voir la remarque suivante) - .payload

Remarque

Vous n’avez pas besoin de spécifier path quand vous désérialisez des données durant la phase source. Les données désérialisées sont automatiquement placées dans la section .payload du message.

Chaque élément du tableau de colonnes est un objet avec le schéma suivant :

Champ Type Description Requis ? Par défaut Exemple
name string Nom de la colonne tel qu’il apparaît dans l’en-tête CSV. Oui - temperature
type string enum Type de données du Processeur de données conservé dans la colonne utilisée pour déterminer comment analyser les données. Non string integer
path Chemin d’accès Emplacement dans chaque enregistrement des données à partir duquel la valeur de la colonne doit être lue. Non .{{name}} .temperature

Utilisez les options de configuration suivantes pour sérialiser des données CSV :

Champ Type Description Requis ? Par défaut Exemple
type string enum Format de sérialisation Oui - CSV
header boolean Ce champ indique s’il faut inclure la ligne d’en-tête avec les noms de colonnes dans le fichier CSV sérialisé. Oui - true
columns array Définition de schéma du fichier CSV à écrire. Oui - (voir le tableau suivant)
path Chemin d’accès Chemin de la partie du message du Processeur de données où les données à sérialiser sont écrites. (voir la remarque suivante) - .payload

Remarque

Vous n’avez pas besoin de spécifier path quand vous sérialisez des données par lots. Le chemin par défaut est ., qui représente l’intégralité du message.

Champ Type Description Requis ? Par défaut Exemple
name string Nom de la colonne tel qu’il apparaîtrait dans un en-tête CSV. Oui - temperature
path Chemin d’accès Emplacement dans chaque enregistrement des données où la valeur de la colonne doit être écrite. Non .{{name}} .temperature

L’exemple suivant montre la configuration pour la sérialisation de données CSV non regroupées par lots :

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

L’exemple suivant montre la configuration pour la sérialisation de données CSV par lots. Omettez le path de niveau supérieur pour les données par lots :

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

L’exemple suivant montre la configuration pour la désérialisation de données CSV non regroupées par lots :

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

L’exemple suivant montre la configuration pour la désérialisation de données CSV par lots durant la phase source :

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

Contenu connexe