Mapping dello schema nell'attività di copiaSchema mapping in copy activity

Questo articolo illustra come l'attività di copia di Azure Data Factory esegue il mapping dello schema e dei tipi di dati dall'origine al sink quando si copiano dati.This article describes how Azure Data Factory copy activity does schema mapping and data type mapping from source data to sink data when execute the data copy.

Mapping di colonneColumn mapping

Il mapping di colonne si applica quando si esegue la copia tra dati in formato tabulare.Column mapping applies when copying data between tabular-shaped data. Per impostazione predefinita, l'attività di copia esegue il mapping dei dati di origine al sink in base ai nomi delle colonne a meno che non sia configurato il mapping esplicito di colonne.By default, copy activity map source data to sink by column names, unless explicit column mapping is configured. Più in particolare, l'attività di copia:More specifically, copy activity:

  1. Legge i dati dall'origine e determina lo schema di origineRead the data from source and determine the source schema

    • Per le origini dati con schema predefinito nel formato archivio dati/file, ad esempio database/file con metadati (Avro, ORC, Parquet, Text con intestazione), lo schema di origine viene estratto dal risultato della query o dai metadati del file.For data sources with pre-defined schema in the data store/file format, for example, databases/files with metadata (Avro/ORC/Parquet/Text with header), source schema is extracted from the query result or file metadata.
    • Per le origini di dati con schema flessibile, ad esempio tabella di Azure/Cosmos DB, lo schema di origine viene dedotto dal risultato della query.For data sources with flexible schema, for example, Azure Table/Cosmos DB, source schema is inferred from the query result. È possibile sovrascriverlo configurando la "struttura" nel set di dati.You can overwrite it by configuring the "structure" in dataset.
    • Per il file di testo senza intestazione, i nomi di colonna predefiniti vengono generati seguendo il criterio "Prop_0", "Prop_1" e così via. È possibile sovrascriverli configurando la "struttura" nel set di dati.For Text file without header, default column names are generated with pattern "Prop_0", "Prop_1", ...You can overwrite it by configuring the "structure" in dataset.
    • Per le origini Dynamics è necessario fornire le informazioni dello schema nella sezione "struttura" del set di dati.For Dynamics source, you have to provide the schema information in the dataset "structure" section.
  2. Se specificato, applicare il mapping esplicito di colonne.Apply explicit column mapping if specified.

  3. Scrivere dati nel sinkWrite the data to sink

    • Per gli archivi di dati con schema predefinito, i dati vengono scritti nelle colonne con lo stesso nome.For data stores with pre-defined schema, the data is written to the columns with the same name.
    • Per gli archivi di dati senza uno schema fisso e per i formati di file, i nomi colonna/metadati verranno generati in base allo schema di origine.For data stores without fixed schema and for file formats, the column names/metadata will be generated based on the source schema.

Mapping esplicito di colonneExplicit column-mapping

È possibile specificare il valore columnMapping nella sezione typeProperties dell'attività di copia per eseguire il mapping esplicito di colonne.You can specify columnMappings in the typeProperties section of the Copy activity to do explicit column mapping. In questo scenario la sezione "struttura" è necessaria per entrambi i set di dati di input e output.In this scenario, "structure" section is required for both input and output datasets. Il mapping di colonne supporta il mapping di tutte le colonne o di un sottoinsieme delle colonne nella "struttura" del set di dati di origine a tutte le colonne della "struttura" del set di dati del sink.Column mapping supports mapping all or subset of columns in the source dataset "structure" to all columns in the sink dataset "structure". Le seguenti sono condizioni di errore che generano un'eccezione:The following are error conditions that result in an exception:

  • Il risultato della query dell'archivio dati di origine non ha un nome colonna specificato nella sezione "struttura" del set di dati di input.Source data store query result does not have a column name that is specified in the input dataset "structure" section.
  • L'archivio dati sink (con schema predefinito) non ha un nome colonna specificato nella sezione "struttura" del set di dati di output.Sink data store (if with pre-defined schema) does not have a column name that is specified in the output dataset "structure" section.
  • Un numero inferiore o superiore di colonne nella "struttura" del set di dati di sink rispetto a quanto specificato nel mapping.Either fewer columns or more columns in the "structure" of sink dataset than specified in the mapping.
  • Mapping duplicato.Duplicate mapping.

Esempio di mapping esplicito di colonneExplicit column-mapping example

In questo esempio la tabella di input ha una struttura che fa riferimento a una tabella in un database SQL locale.In this sample, the input table has a structure and it points to a table in an on-premises SQL database.

{
    "name": "SqlServerInput",
    "properties": {
        "structure":
         [
            { "name": "UserId"},
            { "name": "Name"},
            { "name": "Group"}
         ],
        "type": "SqlServerTable",
        "linkedServiceName": {
            "referenceName": "SqlServerLinkedService",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "tableName": "SourceTable"
        }
    }
}

In questo esempio, la tabella di output ha una struttura che fa riferimento a una tabella in un database SQL di Azure.In this sample, the output table has a structure and it points to a table in an Azure SQL Database.

{
    "name": "AzureSqlOutput",
    "properties": {
        "structure":
        [
            { "name": "MyUserId"},
            { "name": "MyName" },
            { "name": "MyGroup"}
        ],
        "type": "AzureSqlTable",
        "linkedServiceName": {
            "referenceName": "AzureSqlLinkedService",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "tableName": "SinkTable"
        }
    }
}

Il codice JSON seguente definisce un'attività di copia in una pipeline.The following JSON defines a copy activity in a pipeline. Le colonne dell'origine vengono mappate alle colonne del sink (columnMappings) usando la proprietà translator.The columns from source mapped to columns in sink (columnMappings) by using the translator property.

{
    "name": "CopyActivity",
    "type": "Copy",
    "inputs": [
        {
            "referenceName": "SqlServerInput",
            "type": "DatasetReference"
        }
    ],
    "outputs": [
        {
            "referenceName": "AzureSqlOutput",
            "type": "DatasetReference"
        }
    ],
    "typeProperties":    {
        "source": { "type": "SqlSource" },
        "sink": { "type": "SqlSink" },
        "translator":
        {
            "type": "TabularTranslator",
            "columnMappings": 
            {
                "UserId": "MyUserId",
                "Group": "MyGroup",
                "Name": "MyName"
            }
        }
    }
}

La sintassi di "columnMappings": "UserId: MyUserId, Group: MyGroup, Name: MyName" per specificare il mapping di colonne è ancora supportata.If you are using the syntax of "columnMappings": "UserId: MyUserId, Group: MyGroup, Name: MyName" to specify column mapping, it is still supported as-is.

Flusso del mapping delle colonne:Column-mapping flow:

Flusso del mapping di colonne

Mapping dello schemaSchema mapping

Il mapping dello schema si applica quando si esegue la copia tra dati in formato gerarchico e dati in formato tabulare, ad esempio quando si copiano dati da MongoDB/REST a file di testo e da SQL all'API di Azure Cosmos DB per MongoDB.Schema mapping applies when copying data between hierarchical-shaped data and tabular-shaped data, e.g. copy from MongoDB/REST to text file and copy from SQL to Azure Cosmos DB's API for MongoDB. Nella sezione translator dell'attività di copia sono supportate le proprietà seguenti:The following properties are supported in copy activity translator section:

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà type del convertitore dell'attività di copia deve essere impostata su: TabularTranslatorThe type property of the copy activity translator must be set to: TabularTranslator Yes
schemaMappingschemaMapping Una raccolta di coppie chiave-valore, che rappresenta la relazione di mapping dal lato di origine al sink lato.A collection of key-value pairs, which represents the mapping relation from source side to sink side.
- Chiave: origine rappresenta.- Key: represents source. Per la origine tabulari, specificare il nome della colonna definite nella struttura di set di dati, per origine gerarchici, specificare l'espressione di percorso JSON per ogni campo da estrarre ed eseguire il mapping.For tabular source, specify the column name as defined in dataset structure; for hierarchical source, specify the JSON path expression for each field to extract and map.
- Valore: rappresenta sink.- Value: represents sink. Per la sink tabulari, specificare il nome della colonna definite nella struttura di set di dati, per sink gerarchici, specificare l'espressione di percorso JSON per ogni campo da estrarre ed eseguire il mapping.For tabular sink, specify the column name as defined in dataset structure; for hierarchical sink, specify the JSON path expression for each field to extract and map.
Nel caso i dati gerarchici, per i campi sotto l'oggetto radice, percorso JSON inizia con la radice $; per i campi nella matrice scelta dalla collectionReference percorso JSON di proprietà, inizia dall'elemento matrice.In the case of hierarchical data, for fields under root object, JSON path starts with root $; for fields inside the array chosen by collectionReference property, JSON path starts from the array element.
Yes
collectionReferencecollectionReference Per eseguire l'iterazione dei dati ed estrarli dagli oggetti presenti nel campo di una matrice con lo stesso modello e convertirli in una struttura per riga e per oggetto, specificare il percorso JSON di tale matrice per eseguire il cross apply.If you want to iterate and extract data from the objects inside an array field with the same pattern and convert to per row per object, specify the JSON path of that array to do cross-apply. Questa proprietà è supportata solo quando l'origine è costituita da dati gerarchici.This property is supported only when hierarchical data is source. No No

Esempio: copiare da MongoDB a SQL:Example: copy from MongoDB to SQL:

Se ad esempio si ha un il documento di MongoDB con il contenuto seguente:For example, if you have MongoDB document with the following content:

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

e si vuole copiare tale contenuto in una tabella SQL di Azure nel formato seguente, rendendo flat i dati nella matrice (order_pd e order_price) e nel crossjoin con le informazioni radice comuni (numero, data e città):and you want to copy it into an Azure SQL table in the following format, by flattening the data inside the array (order_pd and order_price) and cross join with the common root info (number, date, and city):

orderNumberorderNumber orderDateorderDate order_pdorder_pd order_priceorder_price citycity
0101 2017012220170122 P1P1 2323 SeattleSeattle
0101 2017012220170122 P2P2 1313 SeattleSeattle
0101 2017012220170122 P3P3 231231 SeattleSeattle

Configurare la regola di mapping dello schema come l'esempio JSON seguente di attività di copia:Configure the schema-mapping rule as the following copy activity JSON sample:

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

Mapping dei tipi di datiData type mapping

L'attività di copia esegue il mapping dei tipi di origine ai tipi sink con il metodo seguente in due passaggi:Copy activity performs source types to sink types mapping with the following 2-step approach:

  1. Conversione dai tipi di origine nativi ai tipi di dati provvisori di Azure Data FactoryConvert from native source types to Azure Data Factory interim data types
  2. Conversione dai tipi di dati provvisori di Azure Data Factory al tipo di sink nativoConvert from Azure Data Factory interim data types to native sink type

È possibile trovare il mapping dal tipo nativo al tipo provvisorio nella sezione "Mapping dei tipi di dati" di ogni argomento sui connettori.You can find the mapping between native type to interim type in the "Data type mapping" section in each connector topic.

Tipi di dati supportatiSupported data types

Data Factory supporta i tipi di dati provvisori seguenti: Quando si configurano le informazioni sui tipi nella configurazione della struttura del set di dati è possibile specificare i valori seguenti:Data Factory supports the following interim data types: You can specify below values when configuring type information in dataset structure configuration:

  • Byte[]Byte[]
  • BooleanBoolean
  • DateTimeDatetime
  • DatetimeoffsetDatetimeoffset
  • DecimalDecimal
  • DoubleDouble
  • GuidGuid
  • Int16Int16
  • Int32Int32
  • Int64Int64
  • SingleSingle
  • stringString
  • TimeSpanTimespan

Esempio di conversione esplicita dei tipi di datiExplicit data type conversion

Quando si copiano i dati negli archivi di dati con schema predefinito, ad esempio SQL Server/Oracle, o quando l'origine e il sink hanno un tipo diverso nella stessa colonna, è necessario dichiarare la conversione esplicita del tipo nel lato di origine:When copying data into data stores with fixed schema, for example, SQL Server/Oracle, when source and sink has different type on the same column,the explicit type conversion should be declared in the source side:

  • Per l'origine file, ad esempio CSV/Avro, è necessario dichiarare la conversione del tipo tramite la struttura di origine con l'elenco completo delle colonne (nome colonna del lato di origine e tipo del lato sink).For file source, for example, CSV/Avro, the type conversion shall be declared via source structure with full column list (source side column name and sink side type)
  • Per l'origine relazionale (ad esempio, SQL/Oracle), è necessario ottenere la conversione del tipo eseguendo il cast esplicito del tipo nell'istruzione della query.For relational source (for example, SQL/Oracle), the type conversion should be achieved by explicit type casting in the query statement.

Quando specificare la "struttura" del set di datiWhen to specify dataset "structure"

Negli scenari seguenti è necessario specificare la "struttura" nel set di dati:In below scenarios, "structure" in dataset is required:

  • Applicazione della conversione esplicita dei tipi di dati per le origini file durante la copia (set di dati di input)Applying explicit data type conversion for file sources during copy (input dataset)
  • Applicazione del mapping esplicito di colonne durante la copia (entrambi i set di dati di input e output)Applying explicit column mapping during copy (both input and output dataset)
  • Copia dall'origine Dynamics 365/CRM (set di dati di input)Copying from Dynamics 365/CRM source (input dataset)
  • Copia in Cosmos DB come oggetto annidato quando l'origine non è un file JSON (set di dati di output)Copying to Cosmos DB as nested object when source is not JSON files (output dataset)

Negli scenari seguenti è consigliabile specificare la "struttura" nel set di dati:In below scenarios, "structure" in dataset is suggested:

  • Copia da un file di testo senza intestazione (set di dati di input).Copying from Text file without header (input dataset). È possibile specificare i nomi delle colonne per l'allineamento del file di testo con le colonne sink corrispondenti per non dover configurare il mapping esplicito di colonne.You can specify the column names for Text file aligning with the corresponding sink columns, to save from configuring explicit column mapping.
  • Copia dagli archivi di dati con schema flessibile, ad esempio tabella Azure o Cosmos DB (set di dati di input), per garantire che i dati previsti (colonne) vengano copiati anziché lasciare che l'attività di copia deduca lo schema in base alle righe superiori durante ogni esecuzione dell'attività.Copying from data stores with flexible schema, for example, Azure Table/Cosmos DB (input dataset), to guarantee the expected data (columns) being copied over instead of let copy activity infer schema based on top row(s) during each activity run.

Passaggi successiviNext steps

Vedere gli altri articoli relativi all'attività di copia:See the other Copy Activity articles: