Schema- en gegevenstypetoewijzing in kopieeractiviteit

Van toepassing op: Azure Data Factory Azure Synapse Analytics

In dit artikel wordt beschreven hoe de Azure Data Factory kopieeractiviteit schematoewijzing en toewijzing van gegevenstypen uitvoert van brongegevens naar sinkgegevens.

Schematoewijzing

Standaardtoewijzing

Standaard koppelt kopieeractiviteit brongegevens aan kolomnamen op een naamloze naam, waarbij hoofdletters gevoelig zijn. Als de sink niet bestaat, bijvoorbeeld bij het schrijven naar bestanden, worden de bronveldnamen de sinknamen. Als de sink al bestaat, moet deze alle kolommen bevatten die uit de bron worden gekopieerd. Deze standaardmapping ondersteunt flexibele schema's en schema-drift van bron naar sink van uitvoering naar uitvoering - alle data die door de bron-datastore wordt teruggegeven, kan naar de sink worden gekopieerd.

Als je bron een tekstbestand is zonder kopregel, moet je expliciet mapping gebruiken omdat de bron geen kolomnamen bevat.

Expliciete toewijzing

Specificeer expliciete mapping om de kolom- en veldmapping van bron naar put aan te passen. Door expliciet te mappen kun je slechts een deel van de brondata naar de sink kopiëren, brondata mappen naar de sink met verschillende namen, of tabel- of hiërarchische data hervormen. De kopieeractiviteit:

1. Leet de gegevens van de bron en bepaalt het bronschema.
2. Hiermee past u de gedefinieerde toewijzing toe.
3. Schrijft de data naar de sink.

Meer informatie over:

• Tabellaire bron naar sink in tabelvorm
• Hiërarchische bron naar sink in tabelvorm
• Tabellaire/hiërarchische bron naar hiërarchische sink

Configureer de mapping in de Authoring UI door naar de kopieeractiviteit te gaan en het mapping-tabblad te selecteren. Of je specificeert programmatisch de mapping in de kopieeractiviteit door gebruik te maken van de translator eigenschap. De volgende eigenschappen worden ondersteund in translator ->mappings array -> objecten ->source en sink, die wijzen op de specifieke kolom of het veld om data te mappen.

De volgende eigenschappen worden ondersteund naast translatormappings:

Tabellaire bron naar sink in tabelvorm

Als u bijvoorbeeld gegevens van Salesforce wilt kopiëren naar Azure SQL Database en expliciet drie kolommen wilt toewijzen:

1. Selecteer bij de kopieeractiviteit het tabblad mapping en selecteer vervolgens Schema's importeren om zowel bron- als sinkschema's te importeren.

2. Map de benodigde velden en sluit de rest uit of verwijder ze.

Configureer dezelfde mapping in de kopieeractiviteitspayload (zie 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" }
                }
            ]
        }
    },
    ...
}

Om gegevens te kopiëren uit gescheiden tekstbestanden zonder kopregel, vertegenwoordig je de kolommen met ordinaal in plaats van namen.

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

Hiërarchische bron naar sink in tabelvorm

Wanneer je data kopieert van een hiërarchische bron naar een tabulaire sink, ondersteunt de kopieeractiviteit de volgende mogelijkheden:

• Gegevens extraheren uit objecten en matrices.
• Pas meerdere objecten met hetzelfde patroon toe vanuit een array met behulp van 'cross apply', waarbij één JSON-object wordt omgezet in meerdere records in tabelvorm.

Voor een meer geavanceerde transformatie van hiërarchisch naar tabel, gebruik Gegevensstroom.

Bijvoorbeeld, als je een brondocument hebt van Azure DocumentDB of MongoDB met de volgende inhoud:

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

Om de gegevens naar een tekstbestand te kopiëren, gebruik je het volgende formaat met een headerregel. Vlak de data binnen de arrays (order_pd en order_price) en gebruik een kruisverbinding met de gemeenschappelijke wortelinformatie (nummer, datum en stad):

Definieer deze mapping in de Data Factory-authoring UI:

1. Ga bij kopieeractiviteit naar het tabblad Mapping en selecteer Importeren schema's om zowel bron- als sinkschema's te importeren. Terwijl de service bij het importeren van schema's de bovenste objecten samplet, voeg een veld toe aan de juiste laag in de hiërarchie – ga met de muis over een bestaande veldnaam en kies om een node, object of array toe te voegen.

2. Selecteer de matrix waaruit u gegevens wilt herhalen en extraheren. De UI vult automatisch de referentie van de collectie in. Let op dat deze bewerking slechts één array ondersteunt.

3. Wijs de benodigde velden toe aan de sink. De service bepaalt automatisch de bijbehorende JSON-paden voor de hiërarchische zijde.

Je kunt ook overstappen naar een geavanceerde editor. Je kunt direct de JSON-paden van de velden zien en bewerken. Als u ervoor kiest om nieuwe toewijzingen toe te voegen in deze weergave, geeft u het JSON-pad op.

Je kunt dezelfde mapping configureren in copy activity payload (zie 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']"
        }
    },
    ...
}

Tabellaire/hiërarchische bron naar hiërarchische sink

De gebruikerservaringsstroom is vergelijkbaar met hiërarchische bron naar sink in tabelvorm.

Bij het kopiëren van gegevens van een tabelbron naar een hiërarchische sink ondersteunt de service geen schrijven naar een array binnen een object.

Bij het kopiëren van data van een hiërarchische bron naar een hiërarchische sink, kun je de hiërarchie van een hele laag behouden door het object of de array te selecteren en het in de sink te mappen zonder de binnenste velden aan te raken.

Voor meer geavanceerde data reshape transformatie, gebruik Gegevensstroom.

Toewijzing parameteriseren

Om een getemplatiseerde pijplijn te maken die dynamisch een groot aantal objecten kopieert, bepaal eerst of je de standaardmapping kunt gebruiken of dat je expliciete mapping voor elk object moet definiëren.

Als je expliciete mapping nodig hebt, volg dan deze stappen:

1. Definieer een parameter met een objecttype op pijplijnniveau, zoals mapping.

2. Parametriseer de mapping: Ga bij de kopieeractiviteit naar het mapping-tabblad, kies om dynamische content toe te voegen en selecteer de parameter die je hebt aangemaakt. De activiteitslading is als volgt:

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

3. Stel de waarde op die moet worden doorgegeven aan de koppelingsparameter. Het zou het volledige object van de translator definitie moeten zijn. Voor voorbeelden, zie de sectie expliciete mapping . Bijvoorbeeld, voor een kopie van tabelbron naar tabelsink moet de waarde {"type":"TabularTranslator","mappings":[{"source":{"name":"Id"},"sink":{"name":"CustomerID"}},{"source":{"name":"Name"},"sink":{"name":"LastName"}},{"source":{"name":"LastModifiedDate"},"sink":{"name":"ModifiedDate"}}]} zijn.

Koppeling van gegevenstypen

Copy-activiteit koppelt brontypes aan sinktypes door de volgende flow te gebruiken:

1. Converteer van systeemeigen brongegevenstypen naar tussentijdse gegevenstypen die worden gebruikt door Azure Data Factory- en Synapse-pijplijnen.
2. Converteer automatisch het tussentijdse datatype indien nodig om overeen te komen met de bijbehorende sinktypes. Deze stap geldt zowel voor standaardmapping als expliciete mapping.
3. Converteer van tussentijdse gegevenstypen naar systeemeigen sinkgegevenstypen.

Copy-activiteit ondersteunt momenteel de volgende tussentijdse gegevenstypen: Booleaanse, Byte-, Bytematrix, Datetime, DatetimeOffset, Decimal, Double, GUID, Int16, Int32, Int64, SByte, Single, String, Timespan, UInt16, UInt32 en UInt64.

De volgende conversies van gegevenstypen worden ondersteund tussen de tussentijdse typen van bron naar sink.

(1) Datum/Tijd omvat DatumTijd, DatumTijdOffset, Datum en Tijd.

(2) Float-point omvat enkel en dubbel.

(3) Integer omvat SByte, Byte, Int16, UInt16, Int32, UInt32, Int64 en UInt64.

Copy-activiteit ondersteunt de volgende eigenschappen voor datatypeconversie (onder de translator sectie voor programmatic authoring):

| Eigendom | Beschrijving | Vereist | | -------------------------------- | ------------------------------------------------------------ | -------- | | typeConversie | Schakel de nieuwe datatypeconversie-ervaring in. De standaardwaarde is onwaar vanwege compatibiliteit met eerdere versies.

Voor nieuwe kopieeractiviteiten die sinds eind juni 2020 zijn aangemaakt via de Data Factory authoring UI, is deze datatype-conversie standaard ingeschakeld voor de beste ervaring. Je kunt de volgende typeconversie-instellingen zien op het tabblad kopieeractiviteit -> mapping voor toepasselijke scenario's. Als u pijplijn programmatisch wilt maken, moet u expliciet de eigenschap instellen typeConversion op true om deze in te schakelen. Voor bestaande kopieeractiviteiten die zijn gemaakt voordat deze functie wordt uitgebracht, ziet u geen opties voor typeconversie in de ontwerpinterface voor compatibiliteit met eerdere versies. | Nee | | typeConversieInstellingen | Een groep typeconversie-instellingen. Toepassen wanneer typeConversion is ingesteld op true. De volgende eigenschappen bevinden zich allemaal onder deze groep. | Nee | | Onder typeConversionSettings | | | | allowDataTruncation | Sta data-afkorting toe bij het omzetten van brondata naar sink met een ander type tijdens het kopiëren, bijvoorbeeld van decimaal naar geheel getal, van DatetimeOffset naar Datetime.
De standaardwaarde is waar. | Nee | | treatBooleanAsNumber | Behandel bijvoorbeeld booleanen als getallen, waar als 1.
De standaardwaarde is onwaar. | Nee | | datumFormaat | Formatteren van een string bij het converteren tussen data en strings, zoals yyyy-MM-dd. Raadpleeg Aangepaste datum- en tijdnotatie tekenreeksen voor gedetailleerde informatie. | Nee | | datumTijdFormaat | Formatteer string bij het converteren tussen data zonder tijdzone-offset en strings, zoals yyyy-MM-dd HH:mm:ss.fff. Raadpleeg Aangepaste datum- en tijdnotatie tekenreeksen voor gedetailleerde informatie. | Nee | | datumTijdOffsetFormaat | Formatteren van string bij het converteren tussen data met tijdzone-offset en strings, zoals yyyy-MM-dd HH:mm:ss.fff zzz. Raadpleeg Aangepaste datum- en tijdnotatie tekenreeksen voor gedetailleerde informatie. | Nee | | timeSpanFormat | Formatteren van string bij het converteren tussen tijdsperioden en strings, zoals dd\.hh\:mm. Raadpleeg Custom TimeSpan Format Strings voor gedetailleerde informatie. | Nee | | tijdFormat | Formatteer string bij het converteren tussen tijd en strings, zoals HH:mm:ss.fff. Raadpleeg Aangepaste datum- en tijdnotatie tekenreeksen voor gedetailleerde informatie. | Nee | | Cultuur | Cultuurinformatie om te gebruiken bij het omzetten van types, zoals en-us of fr-fr. | Nee |

Voorbeeld:

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

Verouderde modellen

Alternatieve kolomtoewijzing (verouderd model)

Om tussen tabelvormige gegevens te koppelen, specificeer copy activity -> translator -> columnMappingsje . In dit geval vereisen zowel invoer- als uitvoerdatasets de structuursectie . Kolommapping ondersteunt het toewijzen van alle of een subset van kolommen in de brondatasetstructuur naar alle kolommen in de sink-datasetstructuur. De volgende foutvoorwaarden leiden tot een uitzondering:

• Het queryresultaat van de brondatawinkel heeft geen kolomnaam die je hebt opgegeven in de structuursectie van de invoerdataset.
• De Sink Data Store (als het een vooraf gedefinieerd schema heeft) heeft geen kolomnaam die je hebt opgegeven in de sectie 'output dataset structure'.
• Ofwel minder kolommen of meer kolommen in de structuur van de sink-dataset dan gespecificeerd in de mapping.
• Dubbele toewijzing.

In het volgende voorbeeld heeft de invoergegevensset een structuur en verwijst deze naar een tabel in een on-premises Oracle-database.

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

In dit voorbeeld heeft de uitvoergegevensset een structuur en verwijst deze naar een tabel in Salesforce.

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

De volgende JSON definieert een kopieeractiviteit in een pijplijn. De kolommen van de bron worden naar kolommen in sink gekoppeld door gebruik te maken van de translator ->columnMappings-eigenschap .

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

Als je de syntaxis "columnMappings": "UserId: MyUserId, Group: MyGroup, Name: MyName" gebruikt om kolommapping te specificeren, wordt het nog steeds ondersteund as-is.

Alternatieve schemamapping (legacy-model)

Je kunt kopieeractiviteit specificeren ->translator ->schemaMapping om te koppelen tussen hiërarchisch gevormde data en tabelvormige gegevens. Je kunt bijvoorbeeld kopiëren van MongoDB of REST naar een tekstbestand, en van Oracle naar Azure Cosmos DB voor MongoDB of Azure DocumentDB (met MongoDB-compatibiliteit). De kopieeractiviteitssectie translator ondersteunt de volgende eigenschappen:

• Sleutel: vertegenwoordigt bron. Voor tabulaire broncode specificeert u de kolomnaam zoals gedefinieerd in de datasetstructuur. Voor hiërarchische bron, specificeer de JSON-padexpressie voor elk veld dat te extraheren en in kaart moet worden gebracht.
• Waarde: staat voor de afneem. Voor tabular sink specificeer je de kolomnaam zoals gedefinieerd in de datasetstructuur. Voor hiërarchische sink specificeer je de JSON-padexpressie voor elk veld dat te extraheren en in kaart moet worden gebracht. In het geval van hiërarchische gegevens begint het JSON-pad voor velden onder hoofdobject met root $; voor velden in de matrix die door collectionReference de eigenschap is gekozen, begint het JSON-pad vanaf het matrixelement. | Ja | | collectieReferentie | Als je data wilt itereren en extraheren uit objecten binnen een arrayveld met hetzelfde patroon en converteren naar per rij per object, specificeer dan het JSON-pad van die array om cross-apply te doen. Deze eigenschap wordt alleen ondersteund wanneer hiërarchische gegevens bron zijn. | Nee |

Voorbeeld: kopiëren van MongoDB naar Oracle:

Bijvoorbeeld, als je een MongoDB-document hebt met de volgende inhoud:

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

en je wilt het kopiëren naar een Azure SQL tabel in het volgende formaat door de data binnen de array (order_pd en order_price) te flatten en te kruisen met de gemeenschappelijke wortelinformatie (nummer, datum en stad):

Configureer de schema-mappingregel als het volgende kopieeractiviteit JSON-voorbeeld:

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

Gerelateerde inhoud

Zie de andere artikelen over kopieeractiviteiten:

• overzicht van Copy-activiteit