Kopieren und Transformieren von Daten in Dynamics 365 (Microsoft Dataverse) oder Dynamics CRM mithilfe von Azure Data Factory oder Azure Synapse Analytics

GILT FÜR: Azure Data Factory Azure Synapse Analytics

In diesem Artikel wird beschrieben, wie Sie eine Copy-Aktivität in Azure Data Factory- oder Synapse-Pipelines verwenden, um Daten aus und nach Dynamics 365 (Microsoft Dataverse) oder Dynamics CRM zu kopieren, und einen Datenfluss zum Transformieren von Daten in Dynamics 365 (Microsoft Dataverse) oder Dynamics CRM verwenden. Weitere Informationen finden Sie in den Einführungsartikeln zu Azure Data Factory und Azure Synapse Analytics.

Supported capabilities

Dieser Connector wird für die folgenden Aktivitäten unterstützt:

① Azure Integration Runtime ② Selbstgehostete Integration Runtime

Eine Liste der Datenspeicher, die von einer Kopieraktivität als Quellen und Senken unterstützt werden, finden Sie in der Tabelle Unterstützte Datenspeicher.

Dieser Dynamics-Connector unterstützt die Dynamics-Versionen 7 bis 9 sowohl online als auch lokal. More specifically:

• Version 7 ist Dynamics CRM 2015 zugeordnet.
• Version 8 ist Dynamics CRM 2016 und der frühen Version von Dynamics 365 zugeordnet.
• Version 9 ist der neueren Version von Dynamics 365 zugeordnet.

In der folgenden Tabelle finden Sie Informationen zu den unterstützten Authentifizierungstypen und Konfigurationen für die jeweiligen Dynamics-Versionen und -Produkte.

Für Dynamics 365 werden insbesondere die folgenden Anwendungstypen unterstützt:

• Dynamics 365 for Sales
• Dynamics 365 for Customer Service
• Dynamics 365 for Field Service
• Dynamics 365 for Project Service Automation
• Dynamics 365 for Marketing

Andere Anwendungstypen wie Dynamics 365 Finance, Dynamics 365 for Operations und Dynamics 365 Talent werden von diesem Connector nicht unterstützt.

Dieser Dynamics-Connector basiert auf Dynamics XRM-Tools.

Prerequisites

Wenn Sie sich mit diesem Connector bei einem Microsoft Entra-Dienstprinzipal authentifizieren möchten, müssen Sie die Server-zu-Server-Authentifizierung (S2S) in Dataverse oder Dynamics einrichten. Registrieren Sie zunächst den Anwendungsbenutzer (Dienstprinzipal) in Microsoft Entra ID. Eine Anleitung dazu finden Sie hier. Während der Anwendungsregistrierung müssen Sie diesen Benutzer in Dataverse oder Dynamics erstellen und Berechtigungen erteilen. Diese Berechtigungen können entweder direkt oder indirekt gewährt werden, indem der Anwendungsbenutzer einem Team hinzugefügt wird, dem Berechtigungen in Dataverse oder Dynamics erteilt wurden. Weitere Informationen zum Einrichten eines Anwendungsbenutzers für die Authentifizierung bei Dataverse finden Sie hier.

Get started

Sie können eines der folgenden Tools oder SDKs verwenden, um die Kopieraktivität mit einer Pipeline zu verwenden:

• Das Tool „Daten kopieren“
• Azure-Portal
• Das .NET SDK
• Das Python SDK
• Azure PowerShell
• Die REST-API
• Die Azure Resource Manager-Vorlage

Erstellen eines verknüpften Diensts mit Dynamics 365 (Microsoft Dataverse) oder Dynamics CRM mithilfe der Benutzeroberfläche

Führen Sie die folgenden Schritte aus, um über die Benutzeroberfläche des Azure-Portals einen verknüpften Dienst für Dynamics 365 zu erstellen.

1. Navigieren Sie in Ihrem Azure Data Factory- oder Synapse-Arbeitsbereich zur Registerkarte „Verwalten“, und wählen Sie „Verknüpfte Dienste“ und anschließend „Neu“ aus:

   • Azure Data Factory
   • Azure Synapse

   

2. Suchen Sie nach Dynamics oder Dataverse, und wählen Sie den Dynamics 365-Connector (Microsoft Dataverse) oder Dynamics CRM-Connector aus.

   

   

3. Konfigurieren Sie die Dienstdetails, testen Sie die Verbindung, und erstellen Sie den neuen verknüpften Dienst.

   

Details zur Connectorkonfiguration

Die folgenden Abschnitte enthalten Details zu den Eigenschaften, die zum Definieren von Entitäten speziell für Dynamics verwendet werden.

Eigenschaften des verknüpften Diensts

Die folgenden Eigenschaften werden für den mit Dynamics verknüpften Dienst unterstützt.

Dynamics 365 und Dynamics CRM Online

Beispiel: Onlineversion von Dynamics unter Verwendung des Microsoft Entra-Dienstprinzipals und der Schlüsselauthentifizierung

{  
    "name": "DynamicsLinkedService",  
    "properties": {  
        "type": "Dynamics",  
        "typeProperties": {  
            "deploymentType": "Online",  
            "serviceUri": "https://<organization-name>.crm[x].dynamics.com",  
            "authenticationType": "AADServicePrincipal",  
            "servicePrincipalId": "<service principal id>",  
            "servicePrincipalCredentialType": "ServicePrincipalKey",  
            "servicePrincipalCredential": "<service principal key>"
        },  
        "connectVia": {  
            "referenceName": "<name of Integration Runtime>",  
            "type": "IntegrationRuntimeReference"  
        }  
    }  
}  

Beispiel: Onlineversion von Dynamics unter Verwendung des Microsoft Entra-Dienstprinzipals und der Zertifikatsauthentifizierung

{ 
    "name": "DynamicsLinkedService", 
    "properties": { 
        "type": "Dynamics", 
        "typeProperties": { 
            "deploymentType": "Online", 
            "serviceUri": "https://<organization-name>.crm[x].dynamics.com", 
            "authenticationType": "AADServicePrincipal", 
            "servicePrincipalId": "<service principal id>", 
            "servicePrincipalCredentialType": "ServicePrincipalCert", 
            "servicePrincipalCredential": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<AKV reference>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<certificate name in AKV>" 
            } 
        }, 
        "connectVia": { 
            "referenceName": "<name of Integration Runtime>", 
            "type": "IntegrationRuntimeReference" 
        } 
    } 
} 

Beispiel: Onlineversion von Dynamics mit Office 365-Authentifizierung

{
    "name": "DynamicsLinkedService",
    "properties": {
        "type": "Dynamics",
        "typeProperties": {
            "deploymentType": "Online",
            "serviceUri": "https://<organization-name>.crm[x].dynamics.com",
            "authenticationType": "Office365",
            "username": "test@contoso.onmicrosoft.com",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Beispiel: Onlineversion von Dynamics unter Verwendung der Authentifizierung mit benutzerseitig zugewiesener verwalteter Identität

{
    "name": "DynamicsLinkedService",
    "properties": {
        "type": "Dynamics",
        "typeProperties": {
            "deploymentType": "Online",
            "serviceUri": "https://<organization-name>.crm[x].dynamics.com",
            "authenticationType": "ManagedIdentity",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Dynamics 365 und Dynamics CRM lokal mit IFD

Weitere Eigenschaften, die mit Dynamics online verglichen werden, sind hostName und Port.

Beispiel: Dynamics lokal mit IFD mithilfe der Active Directory-Authentifizierung

{
    "name": "DynamicsLinkedService",
    "properties": {
        "type": "Dynamics",
        "description": "Dynamics on-premises with IFD linked service using IFD authentication",
        "typeProperties": {
            "deploymentType": "OnPremisesWithIFD",
            "hostName": "contosodynamicsserver.contoso.com",
            "port": 443,
            "organizationName": "admsDynamicsTest",
            "authenticationType": "ActiveDirectoryAuthentication",
            "___domain": "< Active Directory ___domain >", 
            "username": "test@contoso.onmicrosoft.com",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Dataset properties

Eine vollständige Liste mit den Abschnitten und Eigenschaften, die zum Definieren von Datasets zur Verfügung stehen, finden Sie im Artikel zu Datasets. Dieser Abschnitt enthält eine Liste der Eigenschaften, die vom Dynamics-Dataset unterstützt werden.

Beim Kopieren von Daten aus und nach Dynamics werden die folgenden Eigenschaften unterstützt:

Example

{
    "name": "DynamicsDataset",
    "properties": {
        "type": "DynamicsEntity",
        "schema": [],
        "typeProperties": {
            "entityName": "account"
        },
        "linkedServiceName": {
            "referenceName": "<Dynamics linked service name>",
            "type": "linkedservicereference"
        }
    }
}

Eigenschaften der Kopieraktivität

Eine vollständige Liste mit den Abschnitten und Eigenschaften zum Definieren von Aktivitäten finden Sie im Artikel Pipelines. Dieser Abschnitt enthält eine Liste der Eigenschaften, die von den Quell- und Senkentypen für Dynamics unterstützt werden.

Dynamics als Quelltyp

Beim Kopieren von Daten aus Dynamics werden die folgenden Eigenschaften im Abschnitt source der Kopieraktivität unterstützt:

Example

"activities":[
    {
        "name": "CopyFromDynamics",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Dynamics input dataset>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "DynamicsSource",
                "query": "<FetchXML Query>"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

FetchXML-Beispielabfrage

<fetch>
  <entity name="account">
    <attribute name="accountid" />
    <attribute name="name" />
    <attribute name="marketingonly" />
    <attribute name="modifiedon" />
    <order attribute="modifiedon" descending="false" />
    <filter type="and">
      <condition attribute ="modifiedon" operator="between">
        <value>2017-03-10 18:40:00z</value>
        <value>2017-03-12 20:40:00z</value>
      </condition>
    </filter>
  </entity>
</fetch>

Dynamics als Senkentyp

Beim Kopieren von Daten nach Dynamics werden die folgenden Eigenschaften im Abschnitt sink der Kopieraktivität unterstützt:

Für Dynamics 365 (online) besteht ein Limit von 52 gleichzeitigen Batchaufrufen pro Organisation. Bei Überschreitung dieses Grenzwerts wird eine Ausnahme aufgrund von Serverauslastung ausgelöst, bevor die erste Anforderung jemals ausgeführt wird. Sorgen Sie dafür, dass writeBatchSize den Wert 10 nicht überschreitet, um eine solche Einschränkung gleichzeitiger Aufrufe zu vermeiden.

Die optimale Kombination von writeBatchSize und parallelCopies hängt vom Schema Ihrer Entität ab. Schemaelemente enthalten die Anzahl von Spalten, die Zeilengröße und die Anzahl der Plug-Ins, Workflows oder Workflowaktivitäten, die an diese Aufrufe gekoppelt sind. Die Standardeinstellung writeBatchSize (10) x parallelCopies (10) wird für den Dynamics-Dienst empfohlen. Dieser Wert funktioniert für die meisten Dynamics-Entitäten, obwohl er unter Umständen nicht die beste Leistung erzielt. Sie können die Leistung optimieren, indem Sie die Kombination in Ihren Kopieraktivitätseinstellungen anpassen.

Example

"activities":[
    {
        "name": "CopyToDynamics",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Dynamics output dataset>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "DynamicsSink",
                "writeBehavior": "Upsert",
                "writeBatchSize": 10,
                "ignoreNullValues": true
            }
        }
    }
]

Wenn Sie eine elastische Tabelle in der Senke der Copy-Aktivität auswählen, unterstützt die Connectorzuordnung die Spalte partitionid. Sie können die Quelldatenspalte der Spalte partitionid der Senke zuordnen. Wenn er nicht zugeordnet ist, wird der Primärschlüsselwert als Standardwert für die partitionid Spalte verwendet.

partitionid kann in alternativen Dataverse-Schlüssels oder Primärschlüsselszenarien für den Schreibpfad verwendet werden. Jede elastische Tabelle enthält eine systemdefinierte partitionid Spalte und einen alternativen Schlüssel mit dem Namen KeyForNoSqlEntityWithPKPartitionId, der den Primärschlüssel der Tabelle mit der partitionid Spalte kombiniert. Weitere Informationen finden Sie in diesem Artikel.

Abrufen von Daten aus Ansichten

Wenn Sie Daten aus Dynamics-Sichten abrufen möchten, müssen Sie die gespeicherte Abfrage der Sicht abrufen und dann die Daten mithilfe der Abfrage abrufen.

Es gibt zwei Entitäten, die unterschiedliche Ansichtstypen speichern: "Gespeicherte Abfrage" speichert die Systemansicht und "Benutzerabfrage" speichert die Benutzeransicht. Um die Informationen der Ansichten zu erhalten, schauen Sie sich die folgende FetchXML-Abfrage an und ersetzen Sie "TARGETENTITY" durch savedquery oder userquery. Jeder Entitätstyp hat mehrere Attribute, die Sie der Abfrage nach Bedarf hinzufügen können. Weitere Informationen dazu finden Sie unter „savedquery“-Entität und „userquery“-Entität.

<fetch top="5000" >
  <entity name="<TARGETENTITY>">
    <attribute name="name" />
    <attribute name="fetchxml" />
    <attribute name="returnedtypecode" />
    <attribute name="querytype" />
  </entity>
</fetch>

Sie können auch Filter hinzufügen, um die Sichten zu filtern. Fügen Sie beispielsweise den folgenden Filter hinzu, um die Sicht „Meine aktiven Konten“ in der Kontoentität zu erhalten.

<filter type="and" >
    <condition attribute="returnedtypecode" operator="eq" value="1" />
    <condition attribute="name" operator="eq" value="My Active Accounts" />
</filter>

Datentypzuordnung für Dynamics

In der folgenden Tabelle finden Sie die Zuordnungen von Dynamics-Datentypen zu Zwischendatentypen im Dienst, die beim Kopieren von Daten aus Dynamics verwendet werden. Informationen dazu, wie eine Kopieraktivität einem Quellschema und einer Datentypzuordnung zu einer Spüle zugeordnet wird, finden Sie unter Schema- und Datentypzuordnungen.

Konfigurieren Sie anhand der folgenden Zuordnungstabelle den entsprechenden Zwischendatentyp in einer Datasetstruktur, die auf Ihrem Dynamics-Quelldatentyp basiert:

Daten in ein Nachschlagefeld schreiben

Wenn Sie Daten in ein Nachschlagefeld mit mehreren Zielen wie „Kunde“ und „Besitzer“ schreiben möchten, halten Sie sich an die folgende Anleitung und das entsprechende Beispiel:

1. Stellen Sie sicher, dass Ihre Quelle beide Feldwerte und den Namen der Zielentität enthält.

   • Wenn alle Datensätze der gleichen Zielentität zugeordnet werden, stellen Sie sicher, dass eine der folgenden Bedingungen zutrifft:
     • Ihre Quelldaten verfügen über eine Spalte, in der der Name der Zielentität gespeichert ist.
     • Sie haben der Kopieraktivitätsquelle eine zusätzliche Spalte hinzugefügt, um die Zielentität zu definieren.
   • Wenn unterschiedliche Datensätze verschiedenen Zielentitäten zugeordnet werden, müssen Sie sich vergewissern, dass Ihre Quelldaten über eine Spalte verfügen, in der der Name der entsprechenden Zielentität gespeichert ist.

2. Ordnen Sie die Quellspalte mit den Werten und die mit den Entitätsverweisen der Senke zu. Die Spalte mit den Entitätsverweisen muss einer virtuellen Spalte mit dem besonderen Benennungsmuster {lookup_field_name}@EntityReference zugeordnet werden. Die Spalte gibt es in Dynamics in der Tat gar nicht. Mit ihr wird angegeben, dass es sich bei dieser Spalte um die Metadatenspalte eines bestimmten Nachschlagefelds mit mehreren Zielen handelt.

Festlegen des Felds „Besitzer“

Wenn Sie das Feld "Besitzer" in Dynamics 365 (Microsoft Dataverse) oder Dynamics CRM festlegen, ist es wichtig, einen gültigen Verweis bereitzustellen. Die gültigen Optionen für @EntityReference sind:

• systemuser: Bezieht sich auf einen einzelnen Benutzer innerhalb des Systems.
• team: Bezieht sich auf ein Team von Benutzern innerhalb der Organisation.

Stellen Sie sicher, dass der bereitgestellte Wert einer dieser Optionen entspricht, um Fehler während der Datentransformation zu vermeiden.

Angenommen, die Quelle verfügt über die folgenden beiden Spalten:

• Die Spalte CustomerField weist den Typ GUID auf, wobei es sich um den Wert des Primärschlüssels der Zielentität in Dynamics handelt.
• Die Spalte Target weist den Typ String (Zeichenfolge) auf, wobei es sich um den logischen Namen der Zielentität handelt.

Sie möchten nun solche Daten für die Senke in das Dynamics-Entitätsfeld CustomerField vom Typ Customer kopieren.

In der Spaltenzuordnung für die Kopieraktivität ordnen Sie die beiden Spalten wie folgt zu:

• CustomerField zu CustomerField. Bei dieser Zuordnung handelt es sich um die normale Feldzuordnung.
• Target zu CustomerField@EntityReference. Die Senkenspalte ist virtuell und stellt den Entitätsverweis dar. Solche Feldnamen sollten in einer Zuordnung eingegeben werden, da sie beim Importieren von Schemata nicht angezeigt werden.

Wenn alle Quelldaten der gleichen Zielentität zugeordnet sind und Die Quelldaten nicht den Namen der Zielentität enthalten, finden Sie hier eine Verknüpfung: Fügen Sie in der Kopieraktivitätsquelle eine weitere Spalte hinzu. Geben Sie der neuen Spalte einen Namen nach dem Muster {lookup_field_name}@EntityReference, legen Sie den Namen der Zielentität als Wert fest, und fahren Sie wie gewohnt mit der Spaltenzuordnung fort. Wenn die Spaltennamen Ihrer Quelle und Senke identisch sind, können Sie die explizite Spaltenzuordnung auch überspringen, da die Kopieraktivität standardmäßig Spalten automatisch nach dem Namen zuordnet.

Schreiben von Daten in ein Nachschlagefeld über alternative Schlüssel

Wenn Sie unter Verwendung von alternativen Schlüsselspalten Daten in ein Nachschlagefeld schreiben möchten, folgen Sie dieser Anleitung und diesem Beispiel:

1. Vergewissern Sie sich, dass Ihre Quelle alle Nachschlageschlüsselspalten enthält.

2. Die alternativen Schlüsselspalten müssen der Spalte mit dem speziellen Benennungsmuster {lookup_field_name}@{alternate_key_column_name}zugeordnet werden. Die Spalte ist in Dynamics nicht vorhanden. Mit ihr wird angezeigt, dass diese Spalte zum Nachschlagen des Datensatzes in der Zielentität verwendet wird.

3. Wechseln Sie zur Registerkarte Zuordnung in der Senkentransformation von Zuordnungsdatenflüssen. Wählen Sie die alternativen Schlüssel als Ausgabespalten unter dem Nachschlagefeld aus. Der Wert dahinter gibt die Schlüsselspalten dieses alternativen Schlüssels an.

   

4. Nach der Auswahl werden die alternativen Schlüsselspalten automatisch unten angezeigt.

   

5. Ordnen Sie Ihre Eingabespalten auf der linken Seite den Ausgabespalten zu.

   

Eigenschaften des Zuordnungsdatenflusses

Beim Transformieren von Daten im Zuordnungsdatenfluss können Sie in Dynamics Tabellen lesen und in diese schreiben. Weitere Informationen finden Sie unter Quellentransformation und Senkentransformation in Zuordnungsdatenflüssen. Sie können ein Dynamics-Dataset oder Inlinedataset als Quell- und Senkentyp verwenden.

Source transformation

In der folgenden Tabelle sind die von Dynamics unterstützten Eigenschaften aufgeführt. Sie können diese Eigenschaften auf der Registerkarte Quelloptionen bearbeiten.

Skriptbeispiel für Dynamics-Quelle

Wenn Sie ein Dynamics-Dataset als Quelltyp verwenden, sieht das zugehörige Datenflussskript wie folgt aus:

source(allowSchemaDrift: true,
	validateSchema: false,
	query: '<fetch mapping='logical' count='3 paging-cookie=''><entity name='new_dataflow_crud_test'><attribute name='new_name'/><attribute name='new_releasedate'/></entity></fetch>') ~> DynamicsSource

Wenn Sie ein Inlinedataset verwenden, sieht das zugehörige Datenflussskript wie folgt aus:

source(allowSchemaDrift: true,
	validateSchema: false,
	store: 'dynamics',
	format: 'dynamicsformat',
	entity: 'Entity1',
	query: '<fetch mapping='logical' count='3 paging-cookie=''><entity name='new_dataflow_crud_test'><attribute name='new_name'/><attribute name='new_releasedate'/></entity></fetch>') ~> DynamicsSource

Sink transformation

In der folgenden Tabelle sind die von der Dynamics-Senke unterstützten Eigenschaften aufgeführt. Sie können diese Eigenschaften auf der Registerkarte Senkenoptionen bearbeiten.

Skriptbeispiel für Dynamics-Senke

Wenn Sie ein Dynamics-Dataset als Senkentyp verwenden, sieht das zugehörige Datenflussskript wie folgt aus:

IncomingStream sink(allowSchemaDrift: true,
    validateSchema: false,
    deletable:true,
    insertable:true,
    updateable:true,
    upsertable:true,
    skipDuplicateMapInputs: true,
    skipDuplicateMapOutputs: true) ~> DynamicsSink

Wenn Sie ein Inlinedataset verwenden, sieht das zugehörige Datenflussskript wie folgt aus:

IncomingStream sink(allowSchemaDrift: true,
    validateSchema: false,
    store: 'dynamics',
    format: 'dynamicsformat',
    entity: 'Entity1',
    deletable: true,
    insertable: true,
    updateable: true,
    upsertable: true,
    skipDuplicateMapInputs: true,
    skipDuplicateMapOutputs: true) ~> DynamicsSink

Eigenschaften der Lookup-Aktivität

Ausführliche Informationen zu den Eigenschaften finden Sie unter Lookup-Aktivität in Azure Data Factory.

Related content

Eine Liste der von der Kopieraktivität als Quellen und Senken unterstützten Datenspeicher finden Sie unter Unterstützte Datenspeicher und Formate.