Mappage de schéma et de type de données dans l’activité de copie

S'APPLIQUE À : Azure Data Factory Azure Synapse Analytics

Cet article décrit la manière dont l’activité de copie d’Azure Data Factory effectue un mappage de schéma et de type de données, des données de la source au données du récepteur.

Mappage de schéma

Mappage par défaut

Par défaut, l’activité de copie mappe les données sources pour qu’elles soient distribuées par noms de colonnes de manière sensible à la casse. Si le puits n’existe pas, comme lors de l’écriture dans des fichiers, les noms des champs source deviennent les noms des puits de décharge. Si le récepteur existe déjà, il doit contenir toutes les colonnes copiées à partir de la source. Cette correspondance par défaut supporte des schémas flexibles et la dérive du schéma de la source au puits de l’exécution à l’exécution – toutes les données retournées par le stockage de données source peuvent être copiées dans le puits d’origine.

Si votre source est un fichier texte sans ligne d’en-tête, vous devez utiliser un mappage explicite car la source ne contient pas de noms de colonnes.

Mappage explicite

Spécifiez une correspondance explicite pour personnaliser la correspondance de colonnes et de champs de la source au puits de base. En utilisant un mappage explicite, vous pouvez copier seulement une partie des données sources vers le puits d’écart, mapper les données sources vers des puits avec des noms différents, ou remodeler des données tabulaires ou hiérarchiques. L’activité de copie :

1. Lit les données de la source et détermine le schéma source.
2. Applique votre mappage défini.
3. Il écrit les données dans l’évier.

Pour en savoir plus :

• De la source tabulaire vers le récepteur tabulaire
• De la source hiérarchique vers le récepteur tabulaire
• De la source tabulaire/hiérarchique vers le récepteur hiérarchique

Configurez la correspondance dans l’interface d’auteur en allant dans l’activité de copie et en sélectionnant l’onglet de correspondance . Ou bien, spécifier programmatiquement la correspondance dans l’activité de copie en utilisant la translator propriété. Les propriétés suivantes sont prises en charge dans translator ->mappings tableau -> objets - et sink>source , qui pointent vers la colonne ou le champ spécifique à mapper les données.

Les propriétés suivantes sont prises en charge sous translator en plus de mappings :

De la source tabulaire vers le récepteur tabulaire

Par exemple, pour copier des données de Salesforce vers Azure SQL Database et mapper explicitement trois colonnes :

1. Dans l’activité de copie, sélectionnez l’onglet de mappage , puis sélectionnez Importer les schémas pour importer à la fois les schémas source et puits de l’envers.

2. Mapper les champs nécessaires et exclure ou supprimer le reste.

Configurez la même correspondance dans la charge utile d’activité de copie (voir translator).

{
    "name": "CopyActivityTabularToTabular",
    "type": "Copy",
    "typeProperties": {
        "source": { "type": "SalesforceSource" },
        "sink": { "type": "SqlSink" },
        "translator": {
            "type": "TabularTranslator",
            "mappings": [
                {
                    "source": { "name": "Id" },
                    "sink": { "name": "CustomerID" }
                },
                {
                    "source": { "name": "Name" },
                    "sink": { "name": "LastName" }
                },
                {
                    "source": { "name": "LastModifiedDate" },
                    "sink": { "name": "ModifiedDate" }
                }
            ]
        }
    },
    ...
}

Pour copier des données à partir de fichiers texte délimités sans ligne d’en-tête, représentez les colonnes par ordinal au lieu de noms.

{
    "name": "CopyActivityTabularToTabular",
    "type": "Copy",
    "typeProperties": {
        "source": { "type": "DelimitedTextSource" },
        "sink": { "type": "SqlSink" },
        "translator": {
            "type": "TabularTranslator",
            "mappings": [
                {
                    "source": { "ordinal": "1" },
                    "sink": { "name": "CustomerID" }
                }, 
                {
                    "source": { "ordinal": "2" },
                    "sink": { "name": "LastName" }
                }, 
                {
                    "source": { "ordinal": "3" },
                    "sink": { "name": "ModifiedDate" }
                }
            ]
        }
    },
    ...
}

De la source hiérarchique vers le récepteur tabulaire

Lorsque vous copiez des données d’une source hiérarchique vers un puits tabulaire, l’activité de copie prend en charge les fonctionnalités suivantes :

• Extraire des données d’objets et de tableaux.
• Cross applique plusieurs objets avec le même modèle à partir d’un tableau, dans ce cas pour convertir un objet JSON en plusieurs enregistrements dans un résultat tabulaire.

Pour une transformation hiérarchique en tabulaire plus avancée, utilisez Data Flow.

Par exemple, si vous avez un document source Azure DocumentDB ou MongoDB contenant le contenu suivant :

{
    "id": {
        "$oid": "592e07800000000000000000"
    },
    "number": "01",
    "date": "20170122",
    "orders": [
        {
            "prod": "p1",
            "price": 23
        },
        {
            "prod": "p2",
            "price": 13
        },
        {
            "prod": "p3",
            "price": 231
        }
    ],
    "city": [ { "name": "Seattle" } ]
}

Pour copier les données dans un fichier texte, utilisez le format suivant avec une ligne d’en-tête. Aplatir les données à l’intérieur des tableaux (order_et order_price) et utiliser une jointure croisée avec les informations racines communes (numéro, date et ville) :

Définissez cette correspondance dans l’interface de création Data Factory :

1. Lors de l’activité de copie, allez dans l’onglet Cartographie et sélectionnez Importer les schémas pour importer à la fois les schémas source et puéril. Au fur et à mesure que le service échantillonne les premiers objets lors de l’importation du schéma, si aucun champ n’apparaît, ajoutez-le à la bonne couche de la hiérarchie : passez la souris sur un nom de champ existant et choisissez d’ajouter un nœud, un objet ou un tableau.

2. Sélectionnez le tableau à partir duquel vous souhaitez effectuer une itération et extraire des données. L’interface automatique remplit la référence de la Collection. Notez que cette opération ne supporte qu’un seul tableau.

3. Mappez les champs nécessaires au récepteur. Le service détermine automatiquement les chemins JSON correspondants pour le côté hiérarchique.

Vous pouvez aussi passer à l’éditeur Avancé. Vous pouvez voir et modifier directement les chemins JSON des champs. Si vous choisissez d’ajouter un nouveau mappage dans cette vue, spécifiez le chemin JSON.

Vous pouvez configurer la même correspondance dans la charge utile d’activité de copie (voir translator) :

{
    "name": "CopyActivityHierarchicalToTabular",
    "type": "Copy",
    "typeProperties": {
        "source": { "type": "MongoDbV2Source" },
        "sink": { "type": "DelimitedTextSink" },
        "translator": {
            "type": "TabularTranslator",
            "mappings": [
                {
                    "source": { "path": "$['number']" },
                    "sink": { "name": "orderNumber" }
                },
                {
                    "source": { "path": "$['date']" },
                    "sink": { "name": "orderDate" }
                },
                {
                    "source": { "path": "['prod']" },
                    "sink": { "name": "order_pd" }
                },
                {
                    "source": { "path": "['price']" },
                    "sink": { "name": "order_price" }
                },
                {
                    "source": { "path": "$['city'][0]['name']" },
                    "sink": { "name": "city" }
                }
            ],
            "collectionReference": "$['orders']"
        }
    },
    ...
}

De la source tabulaire/hiérarchique vers le récepteur hiérarchique

Le flux de l’expérience utilisateur est similaire à De la source hiérarchique vers le récepteur tabulaire.

Lors de la copie de données d’une source tabulaire vers un puits hiérarchique, le service ne supporte pas l’écriture sur un tableau à l’intérieur d’un objet.

En copiant des données d’une source hiérarchique vers un puits hiérarchique, on peut préserver toute la hiérarchie d’une couche en sélectionnant l’objet ou le tableau et en mappant vers le puits sans toucher aux champs internes.

Pour une transformation de reconfiguration des données plus avancée, utilisez Data Flow.

Paramétrer le mappage

Pour créer un pipeline templaisé qui copie dynamiquement un grand nombre d’objets, déterminez d’abord si vous pouvez utiliser la correspondance par défaut ou si vous devez définir une correspondance explicite pour chaque objet.

Si vous avez besoin d’un mappage explicite, suivez ces étapes :

1. Définissez un paramètre avec un type d’objet au niveau du pipeline, tel que mapping.

2. Paramétrez la correspondance : dans l’activité de copie, allez dans l’onglet cartographie, choisissez d’ajouter du contenu dynamique, et sélectionnez le paramètre que vous avez créé. La charge utile d’activité est la suivante :

   {
       "name": "CopyActivityHierarchicalToTabular",
       "type": "Copy",
       "typeProperties": {
           "source": {...},
           "sink": {...},
           "translator": {
               "value": "@pipeline().parameters.mapping",
               "type": "Expression"
           },
           ...
       }
   }
   

3. Construisez la valeur à transférer dans le paramètre de mappage. Cela devrait être l’objet même de la translator définition. Pour les exemples, voir la section correspondance explicite . Par exemple, pour la copie de la source tabulaire vers le récepteur tabulaire, la valeur doit être {"type":"TabularTranslator","mappings":[{"source":{"name":"Id"},"sink":{"name":"CustomerID"}},{"source":{"name":"Name"},"sink":{"name":"LastName"}},{"source":{"name":"LastModifiedDate"},"sink":{"name":"ModifiedDate"}}]}.

Mappage de types de données

activité Copy mappe les types sources en types puits en utilisant le flux suivant :

1. Convertissez des types de données natifs sources en types de données intermédiaires utilisés par des pipelines Azure Data Factory et Synapse.
2. Convertir automatiquement le type de données intermédiaire selon les besoins pour correspondre aux types de puits correspondants. Cette étape s’applique à la fois au mappage par défaut et au mappage explicite.
3. Conversion de types de données intermédiaires en types de données natifs de récepteur.

activité Copy prend actuellement en charge les types de données intermédiaires suivants : Boolean, Byte, Byte array, Datetime, DatetimeOffset, Decimal, Double, GUID, Int16, Int32, Int64, SByte, Single, String, Timespan, UInt16, UInt32 et UInt64.

Les conversions de types de données suivantes sont prises en charge entre les types intermédiaires de la source au récepteur.

(1) La date/heure inclut la dateTime, la DateTimeOffset, la Date et l’Heure.

(2) Virgule flottante inclut Simple et Double.

(3) Integer inclut SByte, Byte, Int16, UInt16, Int32, UInt32, Int64 et UInt64.

activité Copy prend en charge les propriétés suivantes pour la conversion des types de données (dans la translator section sur l’authoring programmatique) :

| Propriété | Description | Obligatoire | | -------------------------------- | ------------------------------------------------------------ | -------- | | typeConversion | Activez la nouvelle expérience de conversion de type de données. La valeur par défaut est false en raison de la compatibilité descendante.

Pour les nouvelles activités de copie créées via l’interface utilisateur Data Factory depuis fin juin 2020, cette conversion de type de données est activée par défaut pour une meilleure expérience. Vous pouvez voir les paramètres suivants de conversion de type dans l’onglet Copy Activity -> mappage pour les scénarios applicables. Pour créer un pipeline programmatiquement, vous devez définir explicitement la propriété typeConversion sur true pour l’activer. Pour les activités de copie existantes créées avant la publication de cette fonctionnalité, vous ne verrez pas les options de conversion de type sur l’interface utilisateur de création pour la compatibilité descendante. | Non | | typeConversionParamètres | Un groupe de paramètres de conversion de types. Appliquer lorsque typeConversion a la valeur true. Les propriétés suivantes sont toutes sous ce groupe. | Non | | Sous typeConversionSettings | | | | allowDataTroncation | Autoriser la troncature des données lors de la conversion des données sources en encapsulant avec un type différent lors de la copie, par exemple, de décimal à entier, de DatetimeOffset à Datetimetime.
La valeur par défaut est true. | Non | | treatBooleanAsNumber | Considérez les booléens comme des nombres, par exemple, vrais comme 1.
La valeur par défaut est false. | Non | | dateFormat | Formatez la chaîne lors de la conversion entre dates et chaînes, comme yyyy-MM-dd. Reportez-vous à Chaînes de format Date et Heure personnalisées pour obtenir des informations détaillées. | Non | | dateTimeFormat | Formatez la chaîne lors de la conversion entre des dates sans décalage de fuseau horaire ni chaînes, comme yyyy-MM-dd HH:mm:ss.fff. Reportez-vous à Chaînes de format Date et Heure personnalisées pour obtenir des informations détaillées. | Non | | dateTimeOffsetFormat | Formatez la chaîne lors de la conversion entre les dates avec décalage de fuseau horaire et chaînes, comme yyyy-MM-dd HH:mm:ss.fff zzz. Reportez-vous à Chaînes de format Date et Heure personnalisées pour obtenir des informations détaillées. | Non | | tempsFormatÉtendue | Formatez la chaîne lors de la conversion entre périodes et chaînes de temps, comme dd\.hh\:mm. Reportez-vous à Chaînes de format TimeSpan personnalisées pour obtenir des informations détaillées. | Non | | timeFormat | Formatez la chaîne lors de la conversion entre temps et chaînes, comme HH:mm:ss.fff. Reportez-vous à Chaînes de format Date et Heure personnalisées pour obtenir des informations détaillées. | Non | | Culture | Informations de culture à utiliser lors de la conversion de types, tels que en-us ou fr-fr. | Non |

Exemple :

{
    "name": "CopyActivity",
    "type": "Copy",
    "typeProperties": {
        "source": {
        	"type": "ParquetSource"
        },
        "sink": {
            "type": "SqlSink"
        },
        "translator": {
            "type": "TabularTranslator",
            "typeConversion": true,
            "typeConversionSettings": {
                "allowDataTruncation": true,
                "treatBooleanAsNumber": true,
                "dateTimeFormat": "yyyy-MM-dd HH:mm:ss.fff",
                "dateTimeOffsetFormat": "yyyy-MM-dd HH:mm:ss.fff zzz",
                "timeSpanFormat": "dd\.hh\:mm",
                "culture": "en-gb"
            }
        }
	},
    ...
}

Modèles hérités

Mappage alternatif des colonnes (modèle hérité)

Pour mapper entre des données en forme de table, spécifiez copy activity -> translator -> columnMappings. Dans ce cas, les jeux de données d’entrée et de sortie nécessitent tous deux la section structure . La cartographie de colonnes permet de mapper toutes ou un sous-ensemble de colonnes de la structure du jeu de données source à toutes les colonnes de la structure du jeu de données de puits (sink). Les conditions d’erreur suivantes entraînent une exception :

• Le résultat de la requête du magasin de données source n’a pas de nom de colonne que vous avez spécifié dans la section structure du jeu de données d’entrée.
• Le stockage de données de l’enclave (s’il possède un schéma prédéfini) n’a pas de nom de colonne que vous avez spécifié dans la section structure du jeu de données de sortie.
• Soit moins de colonnes, soit plus de colonnes dans la structure du jeu de données de puits que ce qui est spécifié dans la cartographie.
• Mappage en double.

Dans l’exemple suivant, le jeu de données d’entrée possède une structure et pointe vers une table dans une base de données Oracle locale.

{
    "name": "OracleDataset",
    "properties": {
        "structure":
         [
            { "name": "UserId"},
            { "name": "Name"},
            { "name": "Group"}
         ],
        "type": "OracleTable",
        "linkedServiceName": {
            "referenceName": "OracleLinkedService",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "tableName": "SourceTable"
        }
    }
}

Dans cet exemple, le jeu de données de sortie a une structure et pointe vers une table dans Salesforce.

{
    "name": "SalesforceDataset",
    "properties": {
        "structure":
        [
            { "name": "MyUserId"},
            { "name": "MyName" },
            { "name": "MyGroup"}
        ],
        "type": "SalesforceObject",
        "linkedServiceName": {
            "referenceName": "SalesforceLinkedService",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "tableName": "SinkTable"
        }
    }
}

Le JSON suivant définit une activité de copie dans un pipeline. Les colonnes de la source s’associent aux colonnes dans le puits en utilisant la propriété traducteur ->columnMappings .

{
    "name": "CopyActivity",
    "type": "Copy",
    "inputs": [
        {
            "referenceName": "OracleDataset",
            "type": "DatasetReference"
        }
    ],
    "outputs": [
        {
            "referenceName": "SalesforceDataset",
            "type": "DatasetReference"
        }
    ],
    "typeProperties":    {
        "source": { "type": "OracleSource" },
        "sink": { "type": "SalesforceSink" },
        "translator":
        {
            "type": "TabularTranslator",
            "columnMappings":
            {
                "UserId": "MyUserId",
                "Group": "MyGroup",
                "Name": "MyName"
            }
        }
    }
}

Si vous utilisez la syntaxe "columnMappings": "UserId: MyUserId, Group: MyGroup, Name: MyName" pour spécifier le mappage des colonnes, elle est toujours prise en charge as-is.

Mappage de schéma alternatif (modèle hérité)

Vous pouvez spécifier l’activité de copie ->translator ->schemaMapping pour correspondre entre les données hiérarchiques et les données en forme de tableau. Par exemple, vous pouvez copier depuis MongoDB ou REST vers un fichier texte, puis copier d’Oracle vers Azure Cosmos DB pour MongoDB ou Azure DocumentDB (compatible avec MongoDB). La section activité translator de copie prend en compte les propriétés suivantes :

• Clé : représente la source. Pour la source tabulaire, spécifiez le nom de la colonne tel que défini dans la structure du jeu de données. Pour la source hiérarchique, spécifiez l’expression de chemin JSON pour chaque champ à extraire et à mapper.
• Valeur : représente le puits (sink). Pour le puits tabulaire, spécifiez le nom de la colonne tel que défini dans la structure du jeu de données. Pour le puits hiérarchique, spécifiez l’expression de chemin JSON pour chaque champ à extraire et à mapper. Dans le cas de données hiérarchiques, pour les champs situés sous l’objet racine, le chemin JSON commence par $ racine ; pour ceux qui se trouvent dans le tableau sélectionné par la propriété collectionReference, le chemin JSON commence par l’élément de tableau. | Oui | | Collection Référence | Si vous souhaitez itérer et extraire des données des objets à l’intérieur d’un champ de tableau avec le même schéma et convertir en ligne par objet, spécifiez le chemin JSON de ce tableau pour faire un cross-application. Cette propriété est prise en charge uniquement quand des données hiérarchiques sont la source. | Non |

Exemple : copier à partir de MongoDB vers Oracle :

Par exemple, si vous avez un document MongoDB contenant le contenu suivant :

{
    "id": {
        "$oid": "592e07800000000000000000"
    },
    "number": "01",
    "date": "20170122",
    "orders": [
        {
            "prod": "p1",
            "price": 23
        },
        {
            "prod": "p2",
            "price": 13
        },
        {
            "prod": "p3",
            "price": 231
        }
    ],
    "city": [ { "name": "Seattle" } ]
}

Et vous souhaitez copier dans une table Azure SQL au format suivant en aplatissant les données à l’intérieur du tableau (order_et order_price) et en croisant avec les informations racines communes (nombre, date et ville) :

Configurez la règle de mappage du schéma comme l’exemple JSON suivant :

{
    "name": "CopyFromMongoDBToOracle",
    "type": "Copy",
    "typeProperties": {
        "source": {
            "type": "MongoDbV2Source"
        },
        "sink": {
            "type": "OracleSink"
        },
        "translator": {
            "type": "TabularTranslator",
            "schemaMapping": {
                "$.number": "orderNumber",
                "$.date": "orderDate",
                "prod": "order_pd",
                "price": "order_price",
                "$.city[0].name": "city"
            },
            "collectionReference":  "$.orders"
        }
    }
}

Contenu connexe

Voir les autres articles relatifs à l’activité de copie :

• vue d’ensemble de l'activité de copie