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

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Questo articolo illustra come usare un'attività di copia in Azure Data Factory copiare dati da e in Microsoft Dynamics 365 e Microsoft Dynamics CRM. Si basa sull'articolo di panoramica dell'attività di copia che presenta una panoramica generale di un'attività di copia.

Funzionalità supportate

Questo connettore è supportato per le attività seguenti:

È possibile copiare dati da Dynamics 365 (Microsoft Dataverse) o Dynamics CRM in qualsiasi archivio dati sink supportato. È anche possibile copiare dati da qualsiasi archivio dati di origine supportato in Dynamics 365 (Microsoft Dataverse) o Dynamics CRM. Per un elenco degli archivi dati supportati da un'attività di copia come origini e sink, vedere la tabella Archivi dati supportati.

Nota

A partire da novembre 2020, Common Data Service è stato rinominato microsoft Dataverse. Questo articolo è stato aggiornato per riflettere la terminologia più recente.

Questo connettore Dynamics supporta le versioni di Dynamics da 7 a 9 sia online che locali. Più in particolare:

  • La versione 7 è mappata a Dynamics CRM 2015.
  • La versione 8 è mappata a Dynamics CRM 2016 e alla versione precedente di Dynamics 365.
  • La versione 9 è mappata alla versione successiva di Dynamics 365.

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

Versioni di Dynamics Tipi di autenticazione Esempi di servizi collegati
Dataverse

Dynamics 365 Online

Dynamics CRM Online
Azure Active Directory servizio (Azure AD)

Office 365
Autenticazione di Dynamics Online Azure AD'entità servizio o di Office 365
Dynamics 365 locale con distribuzione con connessione Internet (IFD)

Dynamics CRM 2016 locale con IFD

Dynamics CRM 2015 locale con IFD
IFD Dynamics in locale con l'autenticazione IFD e IFD

Importante

Se il tenant e l'utente sono configurati Azure Active Directory per l'accesso condizionale e/o Multi-Factor Authentication, non sarà possibile usare il tipo di autenticazione di Office 365. In queste situazioni, è necessario usare un'Azure Active Directory (Azure AD) dell'entità servizio.

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 applicazione, ad esempio Finance, Operations e Talent.

Suggerimento

Per copiare dati da Dynamics 365 Finance and Operations, è possibile usare il connettore Dynamics AX.

Questo connettore Dynamics è basato sugli strumenti di Dynamics XRM.

Prerequisiti

Per usare questo connettore Azure AD'autenticazione dell'entità servizio, è necessario configurare l'autenticazione da server a server (S2S) in Dataverse o Dynamics. Registrare prima l'utente dell'applicazione (entità servizio) in Azure Active Directory. Per informazioni su come eseguire questa operazione, vedere. Durante la registrazione dell'applicazione sarà necessario creare l'utente in Dataverse o Dynamics e concedere le autorizzazioni. Tali 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. Altre informazioni su come configurare un utente dell'applicazione per l'autenticazione con Dataverse sono disponibili qui.

Introduzione

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

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

Proprietà del servizio collegato

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

Dynamics 365 e Dynamics CRM online

Proprietà Descrizione Obbligatoria
type La proprietà type deve essere impostata su "Dynamics", "DynamicsCrm" o "CommonDataServiceForApps".
deploymentType Il tipo di distribuzione dell'istanza di Dynamics. Il valore deve essere "Online" per Dynamics online.
serviceUri URL del servizio dell'istanza di Dynamics, lo stesso a cui si accede dal browser. Un esempio è "https:// <organization-name> .crm[x].dynamics.com".
authenticationType Il tipo di autenticazione per la connessione a un server Dynamics. I valori validi sono "AADServicePrincipal" e "Office365".
servicePrincipalId ID client dell'applicazione Azure AD client. Sì quando l'autenticazione è "AADServicePrincipal"
servicePrincipalCredentialType Tipo di credenziale da usare per l'autenticazione dell'entità servizio. I valori validi sono "ServicePrincipalKey" e "ServicePrincipalCert". Sì quando l'autenticazione è "AADServicePrincipal"
servicePrincipalCredential Credenziale dell'entità servizio.

Quando si usa "ServicePrincipalKey" come tipo di credenziale, può essere una stringa servicePrincipalCredential che Azure Data Factory viene crittografata durante la distribuzione del servizio collegato. Oppure può essere un riferimento a un segreto in Azure Key Vault.

Quando si usa "ServicePrincipalCert" come credenziale, servicePrincipalCredential deve essere un riferimento a un certificato in Azure Key Vault.
Sì quando l'autenticazione è "AADServicePrincipal"
username Nome utente per la connessione a Dynamics. Sì quando l'autenticazione è "Office365"
password Password per l'account utente specificato come nome utente. Contrassegnare questo campo con "SecureString" per archiviarlo in modo sicuro in Data Factory o fare riferimento a un segreto archiviato in Azure Key Vault. Sì quando l'autenticazione è "Office365"
connectVia Runtime di integrazione da usare per la connessione all'archivio dati. Se non viene specificato alcun valore, la proprietà usa il runtime di integrazione di Azure predefinito. No

Nota

Il connettore Dynamics in precedenza usava la proprietà facoltativa organizationName per identificare l'istanza online di Dynamics CRM o Dynamics 365. Anche se tale proprietà continua a funzionare, è consigliabile specificare la nuova proprietà serviceUri per ottenere prestazioni migliori per l'individuazione dell'istanza.

Esempio: Dynamics Online con l'Azure AD'entità servizio e l'autenticazione della 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 Azure AD'entità servizio e l'autenticazione del 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 con 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"
        }
    }
}

Dynamics 365 e Dynamics CRM locale con IFD

Le proprietà aggiuntive che si confrontano con Dynamics Online sono hostName e port.

Proprietà Descrizione Obbligatoria
type La proprietà type deve essere impostata su "Dynamics", "DynamicsCrm" o "CommonDataServiceForApps". Sì.
deploymentType Il tipo di distribuzione dell'istanza di Dynamics. Il valore deve essere "OnPremisesWithIfd" per Dynamics locale con IFD. Sì.
hostName Nome host del server Dynamics locale. Sì.
port Porta del server Dynamics locale. No. Il valore predefinito è 443.
organizationName Il nome organizzazione dell'istanza di Dynamics. Sì.
authenticationType Tipo di autenticazione per la connessione al server Dynamics. Specificare "Ifd" per Dynamics locale con IFD. Sì.
username Nome utente per la connessione a Dynamics. Sì.
password Password per l'account utente specificato per il nome utente. È possibile contrassegnare questo campo con "SecureString" per archiviarlo in modo sicuro Data Factory. Oppure è possibile archiviare una password in Key Vault e consentire all'attività di copia di eseguire il pull da qui quando esegue la copia dei dati. Per altre informazioni, vedere Archiviare le credenziali nell'insieme di credenziali delle chiavi. Sì.
connectVia Runtime di integrazione da usare per la connessione all'archivio dati. Se non viene specificato alcun valore, la proprietà usa il runtime di integrazione di Azure predefinito. No

Esempio: Dynamics locale con IFD usando l'autenticazione IFD

{
    "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": "Ifd",
            "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 e in Dynamics, sono supportate le proprietà seguenti:

Proprietà Descrizione Obbligatoria
type La proprietà type del set di dati deve essere impostata su "DynamicsEntity", "DynamicsCrmEntity" o "CommonDataServiceForAppsEntity".
entityName Il nome logico dell'entità da recuperare. No per l'origine se l'origine dell'attività è specificata come "query" e sì per il sink

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 origine dell'attività di copia supporta le proprietà seguenti:

Proprietà Descrizione Obbligatoria
type La proprietà type dell'origine dell'attività di copia deve essere impostata su "DynamicsSource", "DynamicsCrmSource" o "CommonDataServiceForAppsSource".
query FetchXML è un linguaggio di query proprietario usato in Dynamics online e in locale. Vedere l'esempio seguente. Per altre informazioni, vedere Compilare query con FetchXML. No se entityName nel set di dati è specificato

Nota

La colonna della chiave primaria verrà sempre copiata anche se la proiezione della colonna configurata nella query FetchXML non la contiene.

Importante

  • Quando si copiano dati da Dynamics, il mapping esplicito delle colonne da Dynamics al sink è facoltativo. È tuttavia consigliabile usare il mapping per garantire un risultato di copia deterministico.
  • Quando Data Factory importa uno schema nell'interfaccia utente di creazione, lo deduce. A tale scopo, esegue il campionamento delle prime righe dal risultato della query Dynamics per inizializzare l'elenco delle colonne di origine. In tal caso, le colonne senza valori nelle prime righe vengono omesse. Lo stesso comportamento si applica alle esecuzioni di copia se non è presente alcun mapping esplicito. È possibile esaminare e aggiungere altre colonne nel mapping, che vengono rispettate durante il runtime di copia.

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 in Dynamics, la sezione sink dell'attività di copia supporta le proprietà seguenti:

Proprietà Descrizione Obbligatoria
type La proprietà type del sink dell'attività di copia deve essere impostata su "DynamicsSink", "DynamicsCrmSink" o "CommonDataServiceForAppsSink". Sì.
writeBehavior Comportamento dell'azione di scrittura dell'operazione. Il valore deve essere "Upsert".
alternateKeyName Nome della chiave alternativa definito nell'entità per eseguire un upsert. No.
writeBatchSize Conteggio delle righe di dati scritti da Dynamics in ogni batch. No. Il valore predefinito è 10.
ignoreNullValues Indica se ignorare i valori Null dai dati di input diversi dai campi chiave durante un'operazione di scrittura.

I valori validi sono TRUE e FALSE:
  • TRUE: lasciare invariati i dati nell'oggetto di destinazione quando si esegue un'operazione di upsert o aggiornamento. Inserire un valore predefinito definito quando si esegue un'operazione di inserimento.
  • FALSE: aggiorna i dati nell'oggetto di destinazione a un valore Null quando si esegue un'operazione di upsert o aggiornamento. Inserire un valore Null quando si esegue un'operazione di inserimento.
No. Il valore predefinito è FALSE.
maxConcurrentConnections Limite superiore di connessioni simultanee stabilite all'archivio dati durante l'esecuzione dell'attività. Specificare un valore solo quando si desidera limitare le connessioni simultanee. No

Nota

Il valore predefinito sia per il sink writeBatchSize che per l'attività di copia parallelCopies per il sink Dynamics è 10. Di conseguenza, 100 record vengono inviati simultaneamente per impostazione predefinita a Dynamics.

Per Dynamics 365 Online è previsto un limite di due chiamate batch simultanee per ogni organizzazione. Se tale limite viene superato, viene generata un'eccezione "Server occupato" prima dell'esecuzione della prima richiesta. Mantenere writeBatchSize su 10 o meno 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 collegati a tali chiamate. L'impostazione predefinita di writeBatchSize (10) × parallelCopies (10) è la raccomandazione 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 viste

Per recuperare i dati dalle visualizzazioni dynamics, è necessario ottenere la query salvata della vista e usare la query per ottenere i dati.

Esistono due entità che archiviano tipi diversi di vista: "query salvata" archivia la vista di sistema e "query utente" archivia la visualizzazione utente. Per ottenere le informazioni sulle viste, 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 proprie necessità. 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 vista denominata "Account attivi personali" 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 dai tipi di dati di Dynamics Data Factory tipi di dati provvisori. Per informazioni sul mapping di un'attività di copia a uno schema di origine e di un tipo di dati a un sink, vedere Mapping di schemi e tipi di dati.

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

Tipo di dati di Dynamics Tipo di dati provvisorio di Data Factory Supportato come origine Supportato come sink
AttributeTypeCode.BigInt long
AttributeTypeCode.Boolean Booleano
AttributeType.Customer GUID ✓ (vedere le linee guida)
AttributeType.DateTime Datetime
AttributeType.Decimal Decimal
AttributeType.Double Double
AttributeType.EntityName Stringa
AttributeType.Integer Int32
AttributeType.Lookup GUID ✓ (vedere le linee guida)
AttributeType.ManagedProperty Booleano
AttributeType.Memo Stringa
AttributeType.Money Decimal
AttributeType.Owner GUID ✓ (vedere le linee guida)
AttributeType.Picklist Int32
AttributeType.Uniqueidentifier GUID
AttributeType.String Stringa
AttributeType.State Int32
AttributeType.Status Int32

Nota

I tipi di dati Di Dynamics AttributeType.CalendarRules, AttributeType.MultiSelectPicklist e AttributeType.PartyList non sono supportati.

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 queste indicazioni ed esempi:

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

    • Se tutti i record sono mappati alla stessa entità di destinazione, verificare una delle condizioni seguenti:
      • I dati di origine hanno una colonna in cui è archiviato il nome dell'entità di destinazione.
      • È stata aggiunta una colonna aggiuntiva nell'origine dell'attività di copia per definire l'entità di destinazione.
    • Se record diversi sono mappati a entità di destinazione diverse, assicurarsi che i dati di origine siano in una colonna in cui è archiviato il nome dell'entità di destinazione corrispondente.
  2. Eseguire il mapping delle colonne value e entity-reference dall'origine al sink. È necessario eseguire il mapping della colonna entity-reference a una colonna virtuale con il modello di denominazione speciale {lookup_field_name}@EntityReference . La colonna non esiste effettivamente in Dynamics. Viene usato per indicare che questa colonna è la colonna di metadati del campo di ricerca multitarget specificato.

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

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

Si supponga anche di voler copiare tali dati nel campo dell'entità Dynamics sink CustomerField di tipo Customer.

Nel mapping delle colonne di attività di copia eseguire il mapping delle due colonne come indicato di seguito:

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

Mapping delle colonne dei campi di ricerca dynamics

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

Dynamics lookup-field con aggiunta di una colonna entity-reference

Proprietà dell'attività Lookup

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

Passaggi successivi

Per un elenco degli archivi dati in Data Factory come origini e sink, vedere Archivi dati supportati.