Copiare e trasformare dati in Dynamics 365 (Microsoft Dataverse) o Dynamics CRM usando Azure Data Factory o Azure Synapse Analytics

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Questo articolo spiega come usare un'attività Copy nelle pipeline di Azure Data Factory o Synapse per copiare dati da/in Dynamics 365 (Microsoft Dataverse) o Dynamics CRM e usare un flusso di dati per trasformare dati in Dynamics 365 (Microsoft Dataverse) o Dynamics CRM. Per altre informazioni, leggere gli articoli introduttivi Azure Data Factory e Azure Synapse Analytics.

Funzionalità supportate

Il connettore è supportato per le attività seguenti:

① Azure Integration Runtime ② Runtime di integrazione self-hosted

Per un elenco di archivi dati supportati da un'attività Copy come origini o sink, vedere la tabella Archivi dati supportati.

Questo connettore Dynamics supporta le versioni da 7 a 9 di Dynamics sia online che in locale. In particolare:

• La versione 7 esegue il mapping a Dynamics CRM 2015.
• La versione 8 esegue il mapping a Dynamics CRM 2016 e alla versione iniziale di Dynamics 365.
• La versione 9 esegue il mapping alla versione successiva di Dynamics 365.

Fare riferimento alla seguente tabella delle configurazioni e dei tipi di autenticazione supportati per le versioni e i prodotti Dynamics.

Per Dynamics 365 in particolare, sono supportati i tipi di applicazioni seguenti:

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

Questo connettore non supporta altri tipi di applicazioni come Finance, Operations e Talent.

Questo connettore Dynamics si basa su strumenti Dynamics XRM.

Prerequisiti

Per usare questo connettore con l'autenticazione dell'entità servizio Microsoft Entra, è necessario configurare l'autenticazione da server a server (S2S) in Dataverse o Dynamics. Registrare prima l'utente dell'applicazione (entità servizio) in Microsoft Entra ID. Questa operazione à descritta qui. Durante la registrazione dell'applicazione, sarà necessario creare l'utente in Dataverse o Dynamics e concedere le autorizzazioni. Queste autorizzazioni possono essere concesse direttamente o indirettamente aggiungendo l'utente dell'applicazione a un team a cui sono state concesse le autorizzazioni in Dataverse o Dynamics. Per altre informazioni su come configurare un utente dell'applicazione per l'autenticazione con Dataverse, vedere qui.

Operazioni preliminari

Per eseguire l'attività di copia con una pipeline, è possibile usare uno degli strumenti o SDK seguenti:

• Strumento Copia dati
• Il portale di Azure
• .NET SDK
• SDK di Python
• Azure PowerShell
• API REST
• Modello di Azure Resource Manager

Creare un servizio collegato a Dynamics 365 (Microsoft Dataverse) o Dynamics CRM usando l'interfaccia utente

Usare la procedura seguente per creare un servizio collegato a Dynamics 365 nell'interfaccia utente del portale di Azure.

1. Passare alla scheda Gestisci nell'area di lavoro di Azure Data Factory o Synapse e selezionare Servizi collegati, quindi fare clic su Nuovo:

   • Azure Data Factory
   • Azure Synapse

   

2. Cercare Dynamics o Dataverse e selezionare il connettore Dynamics 365 (Microsoft Dataverse) o Dynamics CRM.

   

   

3. Configurare i dettagli del servizio, testare la connessione e creare il nuovo servizio collegato.

   

Dettagli di configurazione del connettore

Le sezioni seguenti riportano informazioni dettagliate sulle proprietà che vengono usate per definire entità specifiche di Dynamics.

Proprietà del servizio collegato

Per il servizio collegato di Dynamics sono supportate le proprietà seguenti.

Dynamics 365 e Dynamics CRM online

Esempio: Dynamics online che usa l'entità servizio Microsoft Entra o l'autenticazione tramite chiave

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

Esempio: Dynamics online che usa l'entità servizio Microsoft Entra o l'autenticazione tramite certificato

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

Esempio: Dynamics online che usa l'autenticazione di 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"
        }
    }
}

Esempio: Dynamics online che usa l'autenticazione tramite identità gestita assegnata dall'utente

{
    "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 e Dynamics CRM locale con IFD

Proprietà aggiuntive rispetto a Dynamics online sono hostName e port.

Esempio: Dynamics locale con IFD usando l'autenticazione di 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"
        }
    }
}

Proprietà del set di dati

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione dei set di dati, vedere l'articolo Set di dati. Questa sezione presenta un elenco delle proprietà supportate dal set di dati Dynamics.

Per copiare dati da/in Dynamics, sono supportate le proprietà seguenti:

Esempio

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

Proprietà dell'attività di copia

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, vedere l'articolo sulle pipeline. Questa sezione presenta un elenco delle proprietà supportate dai tipi di origine e di sink Dynamics.

Dynamics come tipo di origine

Per copiare dati da Dynamics, la sezione source dell'attività Copy supporta le proprietà seguenti:

Esempio

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

Esempio di query 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 come tipo di sink

Per copiare dati da Dynamics, la sezione sink dell'attività Copy supporta le proprietà seguenti:

Per Dynamics 365 online, è previsto un limite di 52 chiamate batch simultanee per organizzazione. Se tale limite viene superato, viene generata un'eccezione "Server occupato" prima che venga eseguita la prima richiesta. Mantenere writeBatchSize a 10 o a un valore inferiore per evitare tale limitazione delle chiamate simultanee.

La combinazione ottimale di writeBatchSize e parallelCopies dipende dallo schema dell'entità. Gli elementi dello schema includono il numero di colonne, le dimensioni delle righe e il numero di plug-in, flussi di lavoro o attività del flusso di lavoro associate a tali chiamate. L'impostazione predefinita di writeBatchSize (10) × parallelCopies (10) è quella consigliata in base al servizio Dynamics. Questo valore funziona per la maggior parte delle entità Dynamics, anche se potrebbe non offrire prestazioni ottimali. È possibile ottimizzare le prestazioni regolando la combinazione nelle impostazioni di attività di copia.

Esempio

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

Recupero di dati dalle visualizzazioni

Per recuperare dati da visualizzazioni Dynamics, è necessario ottenere la query salvata della visualizzazione e usare la query per ottenere i dati.

Esistono due entità che archiviano diversi tipi di visualizzazione: "query salvata" archivia la visualizzazione di sistema e "query utente" archivia la visualizzazione utente. Per ottenere le informazioni delle visualizzazioni, fare riferimento alla query FetchXML seguente e sostituire "TARGETENTITY" con savedquery o userquery. Ogni tipo di entità ha più attributi disponibili che è possibile aggiungere alla query in base alle esigenze. Altre informazioni sull'entità savedquery e sull'entità userquery.

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

È anche possibile aggiungere filtri per filtrare le visualizzazioni. Ad esempio, aggiungere il filtro seguente per ottenere una visualizzazione denominata "My Active Accounts" nell'entità account.

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

Mapping dei tipi di dati per Dynamics

Quando si copiano dati da Dynamics, la tabella seguente mostra i mapping da tipi di dati Dynamics a tipi di dati provvisori all'interno del servizio. Per informazioni sul modo in cui l'attività Copy esegue il mapping a uno schema di origine e il tipo di dati esegue il mapping a un sink, vedere Mapping dello schema e del tipo di dati.

Configurare il tipo di dati provvisorio corrispondente in una struttura del set di dati basata sul tipo di dati Dynamics di origine usando la tabella di mapping seguente:

Scrittura di dati in un campo di ricerca

Per scrivere dati in un campo di ricerca con più destinazioni, ad esempio Customer e Owner, seguire le indicazioni e l'esempio riportati di seguito:

1. Impostare l'origine in modo che contenga sia il valore del campo che il nome dell'entità di destinazione corrispondente.

   • Se tutti i record eseguono il mapping alla stessa entità di destinazione, verificare una delle condizioni seguenti:
     • I dati di origine hanno una colonna che archivia il nome dell'entità di destinazione.
     • È stata aggiunta una colonna aggiuntiva nell'origine dell'attività Copy per definire l'entità di destinazione.
   • Se record diversi eseguono il mapping a entità di destinazione diverse, accertarsi che i dati di origine includano una colonna che archivia il nome dell'entità di destinazione corrispondente.

2. Eseguire il mapping sia del valore che delle colonne di riferimento entità dall'origine al sink. È necessario eseguire il mapping della colonna di riferimento entità a una colonna virtuale con il modello di denominazione speciale {lookup_field_name}@EntityReference. La colonna non esiste effettivamente in Dynamics. Viene usata per indicare che questa colonna è la colonna di metadati del campo di ricerca multitarget specificato.

Impostazione del campo Proprietario

Quando si imposta il campo Proprietario in Dynamics 365 (Microsoft Dataverse) o Dynamics CRM, è importante fornire un riferimento valido. Le opzioni valide per sono @EntityReference :

• systemuser: si riferisce a un singolo utente all'interno del sistema.
• team: si riferisce a un team di utenti all'interno dell'organizzazione.

Assicurarsi che il valore fornito corrisponda a una di queste opzioni per evitare errori durante la trasformazione dei dati.

Si supponga, ad esempio, che l'origine includa queste due colonne:

• Colonna CustomerField di tipo GUID, che è il valore della chiave primaria dell'entità di destinazione in Dynamics.
• Colonna Target di tipo String, che è il nome logico dell'entità di destinazione.

Si supponga, inoltre, di voler copiare tali dati nel campo entità Dynamics sink CustomerField di tipo Customer.

Nel mapping delle colonne dell'attività Copy, eseguire il mapping delle due colonne nel modo seguente:

• CustomerField a CustomerField. Questo mapping è il mapping dei campi normale.
• Target a CustomerField@EntityReference. La colonna sink è una colonna virtuale che rappresenta il riferimento entità. Immettere tali nomi di campo in un mapping, perché non verranno visualizzati importando schemi.

Se tutti i record di origine eseguono il mapping alla stessa entità di destinazione e i dati di origine non contengono il nome dell'entità di destinazione, una scorciatoia è possibile: nell'origine dell'attività Copy aggiungere una colonna aggiuntiva. Assegnare il nome alla nuova colonna usando il modello {lookup_field_name}@EntityReference, impostare il valore sul nome dell'entità di destinazione, quindi procedere con il mapping delle colonne come di consueto. Se i nomi delle colonne di origine e sink sono identici, è anche possibile ignorare il mapping esplicito delle colonne perché l'attività Copy per impostazione predefinita esegue il mapping delle colonne in base al nome.

Scrittura di dati in un campo di ricerca tramite chiavi alternative

Per scrivere dati in un campo di ricerca usando colonne chiave alternative, seguire le indicazioni e l'esempio riportati di seguito:

1. Accertarsi che l'origine contenga tutte le colonne chiave di ricerca.

2. Le colonne chiave alternative devono essere mappate alla colonna con il modello di denominazione speciale {lookup_field_name}@{alternate_key_column_name}. La colonna non esiste in Dynamics. Viene usata per indicare che questa colonna viene usata per cercare il record nell'entità di destinazione.

3. Passare alla scheda Mapping nella trasformazione sink dei flussi di dati per mapping. Selezionare la chiave alternativa come colonne di output nel campo di ricerca. Il valore dopo indica le colonne chiave di questa chiave alternativa.

   

4. Dopo la selezione, le colonne chiave alternative verranno visualizzate automaticamente in basso.

   

5. Eseguire il mapping delle colonne di input a sinistra con le colonne di output.

   

Proprietà del flusso di dati per mapping

Quando vengono trasformati dati in un flusso di dati per mapping, è possibile leggere da e scrivere in tabelle in Dynamics. Per altre informazioni, vedere la trasformazione origine e la trasformazione sink nei flussi di dati per mapping. È possibile scegliere di usare un set di dati Dynamics o un set di dati inline come tipo di origine e sink.

Trasformazione origine

La tabella seguente elenca le proprietà supportate da Dynamics. È possibile modificare queste proprietà nella scheda Opzioni origine.

Esempio di script di origine Dynamics

Quando si usa il set di dati Dynamics come tipo di origine, lo script del flusso di dati associato è:

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

Se si usa un set di dati inline, lo script del flusso di dati associato è:

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

Trasformazione sink

La tabella seguente elenca le proprietà supportate dal sink Dynamics. È possibile modificare queste proprietà nella scheda Opzioni sink.

Esempio di script di sink Dynamics

Quando si usa il set di dati Dynamics come tipo di sink, lo script del flusso di dati associato è:

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

Se si usa un set di dati inline, lo script del flusso di dati associato è:

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

Proprietà dell'attività Lookup

Per informazioni dettagliate sulle proprietà, vedere Attività di ricerca.

Contenuto correlato

Per un elenco di archivi dati supportati dall'attività Copy come origini e sink, vedere Archivi dati supportati.