Mapping di schema e tipo di dati nell'attività Copy

APPLICABILE A: Azure Data Factory Azure Synapse Analytics

Questo articolo descrive come l'attività di copia in Azure Data Factory esegue il mapping degli schemi e dei tipi di dati dai dati di origine a quelli di destinazione.

Mapping dello schema

Mapping predefinito

Per impostazione predefinita, copia l'attività mappa i dati sorgente per essere assegnati per nomi di colonna in modo sensibile alla maiuscola. Se il sink non esiste, ad esempio durante la scrittura nei file, i nomi dei campi sorgente diventano i nomi dei sink. Se il sink esiste già, deve contenere tutte le colonne copiate dall'origine. Questa mappatura predefinita supporta schemi flessibili e deriva dello schema dalla sorgente al sink, dall'esecuzione all'esecuzione: tutti i dati restituiti dallo store di dati sorgente possono essere copiati nel sink.

Se la tua sorgente è un file di testo senza una linea di intestare, devi usare la mappatura esplicita perché la sorgente non contiene nomi di colonne.

Mappatura esplicita

Specificare una mappatura esplicita per personalizzare la mappatura di colonne e campi dalla sorgente al sink. Utilizzando la mappatura esplicita, puoi copiare solo una parte dei dati sorgente nel sink, mappare i dati sorgente su sink con nomi diversi, oppure rimodellare dati tabulari o gerarchici. L'attività di copia:

1. Legge i dati dalla sorgente e determina lo schema sorgente.
2. Applica il mapping definito.
3. Scrive i dati nel sink.

Altre informazioni su:

• Da origine tabulare a sink tabulare
• Da origine gerarchica a sink tabulare
• Da origine tabulare/gerarchica a sink gerarchico

Configura la mappatura nell'interfaccia di autoria andando all'attività di copia e selezionando la scheda di mappatura . Oppure, specificare programmaticamente la mappatura nell'attività di copia usando la translator proprietà. Le seguenti proprietà sono supportate in translator ->mappings array -> oggetti - e sink>source , che puntano alla colonna o campo specifico da mappare i dati.

Le proprietà seguenti sono supportate in translator oltre a mappings:

Da origine tabulare a sink tabulare

Ad esempio, per copiare dati da Salesforce in database SQL di Azure ed eseguire il mapping esplicito di tre colonne:

1. Nell'attività di copia, seleziona la scheda di mappatura , poi seleziona Importa schemi per importare sia lo schema sorgente che quello di sink.

2. Mappare i campi necessari ed escludi o elimina il resto.

Configura la stessa mappatura nel payload di attività di copia (vedi 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" }
                }
            ]
        }
    },
    ...
}

Per copiare dati da file di testo delimitati senza una riga di intestare, rappresenta le colonne tramite ordinale invece che con i nomi.

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

Da origine gerarchica a sink tabulare

Quando copi dati da una fonte gerarchica a un sink tabulare, l'attività di copia supporta le seguenti funzionalità:

• Estrarre dati da oggetti e matrici.
• Applicare più oggetti con lo stesso modello da una matrice, nel qual caso si converte un oggetto JSON in più record nel risultato tabulare.

Per una trasformazione gerarchica a tabulare più avanzata, usa Flusso di dati.

Ad esempio, se hai un documento sorgente Azure DocumentDB o MongoDB con il seguente contenuto:

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

Per copiare i dati in un file di testo, usa il seguente formato con una linea di intestare. Appiattire i dati all'interno degli array (order_pd e order_price) e utilizzare un cross join con le informazioni radici comuni (numero, data e città):

Definisci questa mappatura nell'interfaccia di authoring di Data Factory:

1. Durante l'attività di copia, vai nella scheda Mappatura e seleziona Importa schemi per importare sia lo schema sorgente che quello di sink. Man mano che il servizio campiona i primi oggetti durante l'importazione dello schema, se non appare un campo, aggiungilo al livello corretto nella gerarchia: passa il mouse su un nome di campo esistente e scegli di aggiungere un nodo, un oggetto o un array.

2. Selezionare la matrice da cui eseguire l'iterazione ed estrarre i dati. L'interfaccia utente popola automaticamente i riferimenti alla Collezione. Si noti che questa operazione supporta solo un singolo array.

3. Mappare i campi necessari al sink. Il servizio determina automaticamente i percorsi JSON corrispondenti per il lato gerarchico.

Mappare da gerarchico a tabulare tramite interfaccia utente

Puoi anche passare all'editor Avanzato. Puoi vedere e modificare direttamente i percorsi JSON dei campi. Se si sceglie di aggiungere un nuovo mapping in questa visualizzazione, specificare il percorso JSON.

Puoi configurare la stessa mappatura nel payload di attività di copia (vedi 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']"
        }
    },
    ...
}

Da origine tabulare/gerarchica a sink gerarchico

Il flusso dell'esperienza utente è simile a Da origine gerarchica a sink tabulare.

Quando si copiano dati da una sorgente tabellare a un sink gerarchico, il servizio non supporta la scrittura in un array all'interno di un oggetto.

Quando si copiano dati da una sorgente gerarchica a un sink gerarchico, si può preservare l'intera gerarchia di un intero livello selezionando l'oggetto o l'array e mapponolo a sink senza toccare i campi interni.

Per una trasformazione più avanzata della rimodellazione dei dati, usa Flusso di dati.

Parametrizzare il mapping

Per creare una pipeline templatizzata che copia dinamicamente un gran numero di oggetti, prima determina se puoi usare la mappatura predefinita o se devi definire una mappatura esplicita per ogni oggetto.

Se hai bisogno di una mappatura esplicita, segui questi passaggi:

1. Definisci un parametro con un tipo di oggetto a livello di pipeline, come mapping.

2. Parametrizza la mappatura: nell'attività di copia, vai nella scheda mappatura, scegli di aggiungere contenuti dinamici e seleziona il parametro che hai creato. Il payload dell'attività è il seguente:

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

3. Costruire il valore da passare al parametro di mappatura. Dovrebbe essere l'intero oggetto della translator definizione. Per i campioni, vedi la sezione mappatura esplicita . Ad esempio, per la copia da origine tabulare a sink tabulare, il valore deve essere {"type":"TabularTranslator","mappings":[{"source":{"name":"Id"},"sink":{"name":"CustomerID"}},{"source":{"name":"Name"},"sink":{"name":"LastName"}},{"source":{"name":"LastModifiedDate"},"sink":{"name":"ModifiedDate"}}]}.

Mapping del tipo di dati

attività Copy mappa i tipi sorgente ai tipi di sink utilizzando il seguente flow:

1. Eseguire la conversione da tipi di dati nativi di origine a tipi di dati provvisori usati dalle pipeline di Azure Data Factory e Synapse.
2. Convertire automaticamente il tipo di dato intermedio secondo necessità per corrispondere ai corrispondenti tipi di sink. Questo passaggio si applica sia alla mappatura predefinita che alla mappatura esplicita.
3. Eseguire la conversione da tipi di dati provvisori a tipi di dati nativi sink.

attività Copy supporta attualmente i tipi di dati provvisori seguenti: Boolean, Byte, Byte array, Datetime, DatetimeOffset, Decimal, Double, GUID, Int16, Int32, Int64, SByte, Single, String, Timespan, UInt16, UInt32 e UInt64.

Le conversioni dei tipi di dati seguenti sono supportate tra i tipi provvisori dall'origine al sink.

(1) Data/Ora include DateTime, DateTimeOffset, Date e Time.

(2) Float-point include Single e Double.

(3) Integer include SByte, Byte, Int16, UInt16, Int32, UInt32, Int64 e UInt64.

attività Copy supporta le seguenti proprietà per la conversione dei tipi di dati (nella translator sezione per l'authoring programmatico):

| Proprietà | Descrizione | Richiesto | | -------------------------------- | ------------------------------------------------------------ | -------- | | typeConversione | Abilita la nuova esperienza di conversione dei tipi di dati. Il valore predefinito è `false` a causa della compatibilità retroattiva.

Per le nuove attività di copia create tramite l'interfaccia di authoring di Data Factory dalla fine di giugno 2020, questa conversione del tipo di dato è abilitata di default per la migliore esperienza. Puoi vedere le seguenti impostazioni di conversione dei tipi su attività di copia -> scheda mappatura per gli scenari applicabili. Per creare una pipeline a livello di codice, è necessario impostare in modo esplicito la proprietà typeConversion su true per abilitarla. Per le attività di copia esistenti create prima del rilascio di questa funzionalità, non verranno visualizzate le opzioni di conversione dei tipi nell'interfaccia utente di creazione per garantire la compatibilità con le versioni precedenti. | No | | typeConversionImpostazioni | Un gruppo di impostazioni di conversione di tipi. Applicare quando typeConversion è impostato su true. Tutte le proprietà seguenti sono incluse in questo gruppo. | No | | Sotto typeConversionSettings | | | | allowDataTruncation | Consentire la troncatura dei dati quando si convertono i dati sorgente a sink con un tipo diverso durante la copia, ad esempio da decimale a intero, da DatetimeOffset a Datetime.
Il valore predefinito è true. | No | | treatBooleanAsNumber | Considera i booleani come numeri, ad esempio, veri come 1.
Il valore predefinito è false. | No | | dateFormat | Formatta la stringa quando si converte tra date e stringhe, come yyyy-MM-dd. Per informazioni dettagliate, vedere Stringhe di formato di data e ora personalizzato. | No | | dataTempoFormato | Formatta la stringa quando si converte tra date senza offset di fuso orario e stringhe, come yyyy-MM-dd HH:mm:ss.fff. Per informazioni dettagliate, vedere Stringhe di formato di data e ora personalizzato. | No | | dataTempoOffsetFormato | Formatta la stringa quando si converte tra date con offset di fuso orario e stringhe, come yyyy-MM-dd HH:mm:ss.fff zzz. Per informazioni dettagliate, vedere Stringhe di formato di data e ora personalizzato. | No | | tempoFormatoIntervallo | Formattare la stringa quando si converte tra periodi di tempo e stringhe, come dd\.hh\:mm. Per informazioni dettagliate, vedere Stringhe di formato TimeSpan personalizzate. | No | | timeFormat | Formattare la stringa quando si converte tra tempo e stringhe, come HH:mm:ss.fff. Per informazioni dettagliate, vedere Stringhe di formato di data e ora personalizzato. | No | | Cultura | Informazioni sulla cultura da utilizzare durante la conversione di tipi, come en-us o fr-fr. | No |

Esempio:

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

Modalità legacy

Mapping delle colonne alternativo (modello legacy)

Per mappare tra dati a forma tabellare, specificare copy activity -> translator -> columnMappings. In questo caso, sia i dataset di input che quelli di output richiedono la sezione struttura . La mappatura delle colonne supporta la mappatura di tutte o di un sottoinsieme di colonne nella struttura del dataset sorgente a tutte le colonne della struttura del dataset sink. Le seguenti condizioni di errore portano a un'eccezione:

• Il risultato della query del deposito dati di sorgente non ha un nome di colonna che hai specificato nella sezione struttura del dataset di input.
• Lo storage dati del sink (se con uno schema predefinito) non ha un nome di colonna che hai specificato nella sezione struttura del dataset in output.
• O meno colonne o più colonne nella struttura del dataset del sink rispetto a quelle specificate nella mappatura.
• Mappatura duplicata.

Nell'esempio seguente il set di dati di input ha una struttura e punta a una tabella in un database Oracle locale.

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

In questo esempio il set di dati di output ha una struttura e punta a una tabella in Salesforce.

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

Il codice JSON seguente definisce un'attività di copia in una pipeline. Le colonne dalla sorgente si mappano alle colonne nel sink usando la proprietà traduttore ->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"
            }
        }
    }
}

Se usi la sintassi "columnMappings": "UserId: MyUserId, Group: MyGroup, Name: MyName" per specificare la mappatura delle colonne, è comunque supportata as-is.

Mappatura alternativa dello schema (modello legacy)

Puoi specificare l'attività di copia ->translator ->schemaMapping per mappare tra dati a forma gerarchica e dati a forma tabellare. Ad esempio, puoi copiare da MongoDB o REST in un file di testo, e copiare da Oracle su Azure Cosmos DB per MongoDB o Azure DocumentDB (compatibile con MongoDB). La sezione di attività translator di copia supporta le seguenti proprietà:

• Tonalità: rappresenta la fonte. Per la sorgente tabulare, specificare il nome della colonna come definito nella struttura del dataset. Per la sorgente gerarchica, specifica l'espressione JSON path per ogni campo da estrarre e mappare.
• Valore: rappresenta il pozzo. Per il sink tabulare, specifica il nome della colonna come definito nella struttura del dataset. Per il sink gerarchico, specifica l'espressione JSON path per ogni campo da estrarre e mappare. Nel caso dei dati gerarchici, per i campi nell'oggetto radice, il percorso JSON inizia con root $; per i campi all'interno della matrice scelta dalla proprietà collectionReference, il percorso JSON inizia dall'elemento della matrice. | Sì | | collezioneRiferimento | Se vuoi iterare ed estrarre dati dagli oggetti all'interno di un campo array con lo stesso pattern e convertire in per riga per oggetto, specifica il percorso JSON di quell'array per fare cross-applic. Questa proprietà è supportata solo quando l'origine è costituita da dati gerarchici. | No |

Esempio: copiare da MongoDB a Oracle:

Ad esempio, se hai un documento MongoDB con il seguente contenuto:

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

E vuoi copiarlo in una tabella Azure SQL nel formato seguente appiattendo i dati all'interno dell'array (order_pd e order_price) e collegandolo con le informazioni root comuni (numero, data e città):

Configura la regola di mappatura dello schema come il seguente esempio JSON di attività di copia:

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

Contenuto correlato

Vedere gli altri articoli relativi all'attività di copia:

• Panoramica dell'attività di copia