Copier et transformer des données dans Dynamics 365 (Microsoft Dataverse) ou Dynamics CRM à l’aide d’Azure Data Factory ou d’Azure Synapse Analytics

S’APPLIQUE À : Azure Data Factory Azure Synapse Analytics

Cet article explique comment utiliser une activité de copie dans des pipelines Azure Data Factory ou Synapse pour copier des données depuis et vers Dynamics 365 (Microsoft Dataverse) ou Dynamics CRM, et comment utiliser un workflow pour transformer des données dans Dynamics 365 (Microsoft Dataverse) ou Dynamics CRM. Pour en savoir plus, lisez les articles d’introduction d’Azure Data Factory et d’Azure Synapse Analytics.

Fonctionnalités prises en charge

Ce connecteur est pris en charge pour les activités suivantes :

① Runtime d’intégration Azure ② Runtime d’intégration auto-hébergé

Pour obtenir la liste des magasins de données prises en charge par l'activité de copie en tant que sources et récepteurs, consultez la table Magasins de données pris en charge.

Ce connecteur Dynamics prend en charge Dynamics versions 7 à 9, aussi bien en ligne qu’en local. Plus précisément :

• La version 7 mappe vers Dynamics CRM 2015.
• La version 8 mappe vers Dynamics CRM 2016 et la version anticipée de Dynamics 365.
• La version 9 mappe vers la dernière version de Dynamics 365.

Consultez le tableau suivant sur les configurations et les types d’authentification pris en charge pour en savoir plus sur les versions et produits Dynamics.

Plus spécifiquement pour Dynamics 365, les types d’applications suivants sont pris en charge :

• Dynamics 365 pour les ventes
• Dynamics 365 pour le service client
• Dynamics 365 pour le service après-vente
• Dynamics 365 pour l’automatisation de service de projet
• Dynamics 365 pour le marketing

Ce connecteur ne prend pas en charge d’autres types d’applications comme Finance, Operations et Talent.

Ce connecteur Dynamics se base sur les outils Dynamics XRM.

Prérequis

Pour utiliser ce connecteur avec l’authentification du principal de service Microsoft Entra, vous devez configurer une authentification S2S (serveur à serveur) dans Dataverse ou Dynamics. Commencez par inscrire l’utilisateur de l’application (principal de service) dans Microsoft Entra ID. Vous pouvez découvrir comment procéder ici. Lors de l’inscription de l’application, vous devez créer cet utilisateur dans Dataverse ou Dynamics et accorder des autorisations. Ces autorisations peuvent être accordées directement ou indirectement en ajoutant l’utilisateur de l’application à une équipe à laquelle des autorisations ont été accordées dans Dataverse ou Dynamics. Vous trouverez plus d’informations sur la configuration d’un utilisateur d’application pour l’authentification auprès de Dataverse ici.

Bien démarrer

Pour effectuer l’activité Copie avec un pipeline, vous pouvez vous servir de l’un des outils ou kits SDK suivants :

• L’outil Copier des données
• Le portail Azure
• Le kit SDK .NET
• Le kit SDK Python
• Azure PowerShell
• L’API REST
• Le modèle Azure Resource Manager

Créer un service lié à Dynamics 365 (Microsoft Dataverse) ou Dynamics CRM à l’aide de l’interface utilisateur

Utilisez les étapes suivantes pour créer un service lié à Dynamics 365 dans l’interface utilisateur du portail Azure.

1. Accédez à l’onglet Gérer dans votre espace de travail Azure Data Factory ou Synapse et sélectionnez Services liés, puis cliquez sur Nouveau :

   • Azure Data Factory.
   • Azure Synapse

   

2. Recherchez Dynamics ou Dataverse et sélectionnez le connecteur Dynamics 365 (Microsoft Dataverse) ou Dynamics CRM.

   

   

3. Configurez les informations du service, testez la connexion et créez le nouveau service lié.

   

Informations de configuration des connecteurs

Les sections suivantes fournissent des informations détaillées sur les propriétés utilisées pour définir les entités spécifiques de Dynamics.

Propriétés du service lié

Les propriétés prises en charge pour le service lié Dynamics sont les suivantes :

Dynamics 365 et Dynamics CRM en ligne

Exemple : Dynamics Online avec le principal de service Microsoft Entra et l’authentification par clé

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

Exemple : Dynamics Online avec le principal de service Microsoft Entra et l’authentification par certificat

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

Exemple : Dynamics en ligne utilisant l’authentification Office 365

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

Exemple : Dynamics en ligne utilisant l’authentification via une identité managée affectée par l’utilisateur

{
    "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 et Dynamics CRM locaux avec IFD

Les propriétés supplémentaires comparables à celles de Dynamics en ligne sont hostName et port.

Exemple : Dynamics local avec IFD utilisant l’authentification Active Directory

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

Propriétés du jeu de données

Pour obtenir la liste complète des sections et propriétés disponibles pour la définition de jeux de données, consultez l’article Jeux de données. Cette section fournit la liste des propriétés prises en charge par le jeu de données Dynamics.

Pour copier des données depuis et vers Dynamics, les propriétés suivantes sont prises en charge :

Exemple

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

Propriétés de l’activité de copie

Pour obtenir la liste complète des sections et des propriétés disponibles pour la définition des activités, consultez l’article Pipelines. Cette section fournit la liste des propriétés prises en charge par les types de source et de récepteur Dynamics.

Dynamics en tant que type de source

Pour copier des données depuis Dynamics, les propriétés suivantes sont prises en charge dans la section source de l’activité de copie :

Exemple

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

Exemple de requête FetchXML

<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 comme type de récepteur

Pour copier des données dans Dynamics, les propriétés suivantes sont prises en charge dans la section récepteur de l’activité de copie :

Pour Dynamics 365 (en ligne), il existe une limite de 52 appels simultanés de lot par organisation. Si cette limite est dépassée, une exception « Serveur occupé » est levée avant l’exécution de la première requête. Conservez une valeur writeBatchSize inférieure ou égale à 10 pour éviter la limitation des appels simultanés.

La combinaison optimale de writeBatchSize et parallelCopies dépend du schéma de votre entité. Les éléments de schéma incluent le nombre de colonnes, la taille des lignes et le nombre de plug-ins, de flux de travail ou d’activités de flux de travail raccordés à ces appels. Le paramètre par défaut de writeBatchSize (10) × parallelCopies (10) est la recommandation du service Dynamics. Cette valeur fonctionne pour la plupart des entités Dynamics, même si elle peut ne pas offrir les meilleures performances. Vous pouvez améliorer les performances en ajustant cette combinaison dans les paramètres de votre activité de copie.

Exemple

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

Récupération des données à partir des vues

Pour récupérer des données à partir des vues Dynamics, vous devez obtenir la requête enregistrée de la vue et utiliser la requête pour obtenir les données.

Il existe deux entités qui stockent différents types de vues : « requête enregistrée » stocke la vue système et « requête utilisateur » stocke la vue utilisateur. Pour obtenir les informations des vues, reportez-vous à la requête FetchXML suivante en remplaçant « TARGETENTITY » par savedquery ou userquery. Chaque type d’entité a plus d’attributs disponibles que vous pouvez ajouter à la requête en fonction de vos besoins. En savoir plus sur l’entité savedquery et l’entité userquery.

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

Vous pouvez également ajouter des filtres pour filtrer les vues. Par exemple, ajoutez le filtre suivant pour obtenir une vue nommée « Mes comptes actifs » dans l’entité de compte.

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

Mappage de type de données pour Dynamics

Lorsque vous copiez des données de Dynamics, la table suivante montre les mappages utilisés entre les types de données Dynamics et les types de données intermédiaires dans le service. Pour découvrir comment l’activité de copie mappe le schéma et le type de données sources au récepteur, consultez Mappages de schémas et de types de données.

Configurez le type de données intermédiaire correspondant dans une structure du jeu de données en fonction du type de données Dynamics de votre source à l’aide de la table de mappage suivante :

Écriture de données dans un champ de recherche

Pour écrire des données dans un champ de recherche avec plusieurs cibles comme le client et le propriétaire, suivez les instructions et les exemples suivants :

1. Faites en sorte que votre source contienne à la fois la valeur du champ et le nom de l’entité cible correspondante.

   • Si tous les enregistrements sont mappés à la même entité cible, assurez-vous que l’une des conditions suivantes est présente :
     • Vos données sources comportent une colonne qui stocke le nom de l’entité cible.
     • Vous avez ajouté une colonne supplémentaire dans la source de l’activité de copie pour définir l’entité cible.
   • Si différents enregistrements sont mappés à des entités cibles différentes, assurez-vous que vos données sources contiennent une colonne qui stocke le nom de l’entité cible correspondante.

2. Mappez la valeur et les colonnes de référence d’entité de la source au récepteur. La colonne de référence d’entité doit être mappée à une colonne virtuelle avec le modèle d’affectation de noms spécial {lookup_field_name}@EntityReference. La colonne n’existe pas réellement dans Dynamics. Elle est utilisée pour indiquer que cette colonne est la colonne de métadonnées du champ de recherche multicible donné.

Supposons, par exemple, que la source comporte les deux colonnes suivantes :

• La colonne CustomerField de type GUID, qui est la valeur de clé primaire de l’entité cible dans Dynamics.
• La colonne Target de type String, qui est le nom logique de l’entité cible.

Supposons également que vous souhaitez copier ces données dans le champ de l’entité Dynamics du récepteur CustomerField de type Customer.

Dans le mappage de colonne de copie-activité, mappez les deux colonnes comme suit :

• CustomerField pour CustomerField. Ce mappage est le mappage de champs normal.
• Cible pour CustomerField@EntityReference. La colonne du récepteur est une colonne virtuelle représentant la référence d’entité. Saisissez les noms de champs dans un mappage, car ils ne s’affichent pas en important des schémas.

Si tous vos enregistrements sources sont mappés à la même entité cible et que vos données sources ne contiennent pas le nom de l’entité cible, voici un raccourci : dans la source de l’activité de copie, ajoutez une colonne supplémentaire. Nommez la nouvelle colonne à l’aide du modèle {lookup_field_name}@EntityReference, définissez la valeur sur le nom de l’entité cible, puis poursuivez le mappage de colonne comme d’habitude. Si vos noms de colonne source et récepteur sont identiques, vous pouvez également ignorer le mappage de colonnes explicite, car l’activité de copie par défaut mappe les colonnes par nom.

Écriture de données dans un champ de recherche via des clés alternatives

Pour écrire des données dans un champ de recherche en utilisant des colonnes de clés alternatives, suivez ces instructions et ces exemples :

1. Vérifiez que votre source contient toutes les colonnes clés de recherche.

2. Les colonnes clés alternatives doivent être mappées à la colonne avec le modèle de nommage spécial {lookup_field_name}@{alternate_key_column_name}. La colonne n’existe pas dans Dynamics. Elle est utilisée pour indiquer que cette colonne est utilisée pour rechercher l’enregistrement dans l’entité cible.

3. Accédez à l’onglet Mappage dans la transformation du récepteur des flux de données de mappage. Sélectionnez la clé alternative comme colonne de sortie sous le champ Recherche. La valeur qui la suit indique les colonnes clés de cette clé alternative.

   

4. Une fois sélectionnée, les colonnes clés alternatives s’affichent automatiquement en dessous.

   

5. Mappez vos colonnes d’entrée à gauche avec les colonnes de sortie.

   

Propriétés du mappage de flux de données

Lors de la transformation de données dans le flux de données de mappage, vous pouvez lire et écrire des données dans les tables Dynamics. Pour plus d’informations, consultez la transformation de la source et la transformation du récepteur dans le flux de données de mappage. Vous pouvez choisir d’utiliser un jeu de données Dynamics ou un jeu de données inlined en tant que type de source et de récepteur.

Transformation de la source

Le tableau ci-dessous répertorie les propriétés prises en charge par Dynamics. Vous pouvez modifier ces propriétés sous l’onglet Options de la source.

Exemple de script source Dynamics

Lorsque vous utilisez un jeu de données Dynamics comme type de source, le script de flux de données associé est le suivant :

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

Si vous utilisez un jeu de données inlined, le script de flux de données associé est le suivant :

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

Transformation du récepteur

Le tableau ci-dessous répertorie les propriétés prises en charge par un récepteur Dynamics. Vous pouvez modifier ces propriétés sous l’onglet Options du récepteur.

Exemple de script de récepteur Dynamics

Lorsque vous utilisez un jeu de données Dynamics comme type de récepteur, le script de flux de données associé est le suivant :

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

Si vous utilisez un jeu de données inlined, le script de flux de données associé est le suivant :

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

Propriétés de l’activité Lookup

Pour en savoir plus sur les propriétés, consultez Activité Lookup.

Contenu connexe

Consultez les magasins de données pris en charge pour obtenir la liste des magasins de données pris en charge en tant que sources et récepteurs par l’activité de copie.