Copiare i dati da e in Dynamics 365 (Common Data Service) o Dynamics CRM usando Azure Data FactoryCopy data from and to Dynamics 365 (Common Data Service) or Dynamics CRM by using Azure Data Factory

Questo articolo illustra come usare l'attività di copia in Azure Data Factory per copiare dati da e in Microsoft Dynamics 365 o Microsoft Dynamics CRM.This article outlines how to use Copy Activity in Azure Data Factory to copy data from and to Microsoft Dynamics 365 or Microsoft Dynamics CRM. Si basa sull'articolo di panoramica dell'attività di copia che presenta informazioni generali sull'attività di copia.It builds on the Copy Activity overview article that presents a general overview of Copy Activity.

Funzionalità supportateSupported capabilities

Questo connettore è supportato per le attività seguenti:This connector is supported for the following activities:

È possibile copiare dati da Dynamics 365 (Common Data Service) o Dynamics CRM in qualsiasi archivio dati di sink supportato.You can copy data from Dynamics 365 (Common Data Service) or Dynamics CRM to any supported sink data store. È anche possibile copiare dati da qualsiasi archivio dati di origine supportato a Dynamics 365 (Common Data Service) o Dynamics CRM.You also can copy data from any supported source data store to Dynamics 365 (Common Data Service) or Dynamics CRM. Per un elenco degli archivi dati supportati come origini o sink dall'attività di copia, vedere la tabella relativa agli archivi dati supportati.For a list of data stores supported as sources or sinks by the copy activity, see the Supported data stores table.

Questo connettore Dynamics supporta Dynamics versione 7. x a 9. x sia in linea che in locale.This Dynamics connector supports Dynamics version 7.x to 9.x for both online or on-premises. Più in particolare,More specifically,

  • La versione 7. x è mappata a Dynamics CRM 2015Version 7.x maps to Dynamics CRM 2015
  • La versione 8. x è mappata a Dynamics CRM 2016 e alla prima versione di Dynamics 365Version 8.x maps to Dynamics CRM 2016 and the early version of Dynamics 365
  • La versione 9. x è mappata alla versione più recente di Dynamics 365Version 9.x maps to the later version of Dynamics 365

Fare riferimento alla seguente tabella sui tipi di autenticazione supportati e sulle configurazioni per le rispettive versioni/prodotti Dynamics.Refer to the following table on the supported authentication types and configurations for respective Dynamics versions/products. IFD è l'acronimo di Internet Facing Deployment (distribuzione con connessione Internet).(IFD is short for internet-facing deployment.)

Versioni di DynamicsDynamics versions Tipi di autenticazioneAuthentication types Esempi di servizi collegatiLinked service samples
Dynamics 365 OnlineDynamics 365 online
Dynamics CRM OnlineDynamics CRM Online
Office365Office365 Dynamics online + autenticazione di Office365Dynamics online + Office365 auth
Dynamics 365 locale con IFDDynamics 365 on-premises with IFD
Dynamics CRM 2016 locale con IFDDynamics CRM 2016 on-premises with IFD
Dynamics CRM 2015 locale con IFDDynamics CRM 2015 on-premises with IFD
IFDIFD Dynamics locale con IFD + autenticazione IFDDynamics on-premises with IFD + IFD auth

Per Dynamics 365 in particolare, sono supportati i tipi di applicazioni seguenti:For Dynamics 365 specifically, the following application types are supported:

  • Dynamics 365 for SalesDynamics 365 for Sales
  • Dynamics 365 for Customer ServiceDynamics 365 for Customer Service
  • Dynamics 365 for Field ServiceDynamics 365 for Field Service
  • Dynamics 365 for Project Service AutomationDynamics 365 for Project Service Automation
  • Dynamics 365 for MarketingDynamics 365 for Marketing

Altri tipi di applicazioni, ad esempio Finance and Operations, Talent e così via non sono supportati da questo connettore.Other application types e.g. Finance and Operations, Talent, etc. are not supported by this connector.

Questo connettore Dynamics si basa sugli strumenti di Dynamics XRM.This Dynamics connector is built on top of Dynamics XRM tooling.

Suggerimento

Per copiare dati da Dynamics 365 for Finance and Operations, è possibile usare il connettore di Dynamics AX.To copy data from Dynamics 365 Finance and Operations, you can use the Dynamics AX connector.

Attività inizialiGet started

È possibile usare l'attività di copia con una pipeline tramite uno degli strumenti o degli SDK seguenti.You can use one of the following tools or SDKs to use the copy activity with a pipeline. Per istruzioni dettagliate, selezionare un collegamento:Select a link for step-by-step instructions:

Le sezioni seguenti riportano informazioni dettagliate sulle proprietà che vengono usate per definire entità di Data Factory specifiche per Dynamics.The following sections provide details about properties that are used to define Data Factory entities specific to Dynamics.

Proprietà del servizio collegatoLinked service properties

Per il servizio collegato di Dynamics sono supportate le proprietà seguenti.The following properties are supported for the Dynamics linked service.

Dynamics 365 e Dynamics CRM OnlineDynamics 365 and Dynamics CRM Online

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà type deve essere impostata su Dynamics.The type property must be set to Dynamics. YesYes
deploymentTypedeploymentType Il tipo di distribuzione dell'istanza di Dynamics.The deployment type of the Dynamics instance. Deve essere "Online" per Dynamics online.It must be "Online" for Dynamics online. Yes
serviceUriserviceUri URL del servizio dell'istanza di Dynamics, ad esempio https://adfdynamics.crm.dynamics.com.The service URL of your Dynamics instance, e.g. https://adfdynamics.crm.dynamics.com. Yes
authenticationTypeauthenticationType Il tipo di autenticazione per la connessione a un server Dynamics.The authentication type to connect to a Dynamics server. Specificare "Office365" per Dynamics online.Specify "Office365" for Dynamics online. YesYes
userNameusername Specificare il nome utente per la connessione a Dynamics.Specify the user name to connect to Dynamics. Yes
passwordpassword Specificare la password dell'account utente specificato per il nome utente.Specify the password for the user account you specified for username. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro in Azure Data Factory oppure fare riferimento a un segreto archiviato in Azure Key Vault.Mark this field as a SecureString to store it securely in Data Factory, or reference a secret stored in Azure Key Vault. Yes
connectViaconnectVia Runtime di integrazione da usare per la connessione all'archivio dati.The integration runtime to be used to connect to the data store. Se non specificato, viene usato il runtime di integrazione di Azure predefinito.If not specified, it uses the default Azure Integration Runtime. No per l'origine, Sì per il sink se il servizio collegato all'origine non dispone di un runtime di integrazioneNo for source, Yes for sink if the source linked service doesn't have an integration runtime

Nota

Connettore di Dynamics che permette di usare la proprietà facoltativa "organizationName" per identificare l'istanza di Dynamics CRM/365 Online.The Dynamics connector used to use optional "organizationName" property to identify your Dynamics CRM/365 Online instance. Durante l'esecuzione, viene consigliato di specificare invece la nuova proprietà "serviceUri" per ottenere prestazioni migliori per l'individuazione dell'istanza.While it keeps working, you are suggested to specify the new "serviceUri" property instead to gain better performance for instance discovery.

Esempio: Dynamics Online con l'autenticazione di Office365Example: Dynamics online using Office365 authentication

{
    "name": "DynamicsLinkedService",
    "properties": {
        "type": "Dynamics",
        "description": "Dynamics online linked service using Office365 authentication",
        "typeProperties": {
            "deploymentType": "Online",
            "serviceUri": "https://adfdynamics.crm.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 IFDDynamics 365 and Dynamics CRM on-premises with IFD

Proprietà aggiuntive rispetto a Dynamics online sono "hostName" e "port".Additional properties that compare to Dynamics online are "hostName" and "port".

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà type deve essere impostata su Dynamics.The type property must be set to Dynamics. YesYes
deploymentTypedeploymentType Il tipo di distribuzione dell'istanza di Dynamics.The deployment type of the Dynamics instance. Deve essere "OnPremisesWithIfd" per Dynamics locale con IFD.It must be "OnPremisesWithIfd" for Dynamics on-premises with IFD. YesYes
hostNamehostName Nome host del server Dynamics locale.The host name of the on-premises Dynamics server. Yes
portport Porta del server Dynamics locale.The port of the on-premises Dynamics server. No, il valore predefinito è 443No, default is 443
organizationNameorganizationName Il nome organizzazione dell'istanza di Dynamics.The organization name of the Dynamics instance. Yes
authenticationTypeauthenticationType Tipo di autenticazione per la connessione al server Dynamics.The authentication type to connect to the Dynamics server. Specificare "Ifd" per Dynamics locale con IFD.Specify "Ifd" for Dynamics on-premises with IFD. YesYes
userNameusername Specificare il nome utente per la connessione a Dynamics.Specify the user name to connect to Dynamics. YesYes
passwordpassword Specificare la password dell'account utente specificato per il nome utente.Specify the password for the user account you specified for username. È possibile scegliere di contrassegnare questo campo come SecureString per archiviarlo in modo sicuro in Azure Data Factory o archiviare la password in Azure Key Vault e consentire all'attività di copia di eseguire il pull da tale posizione durante l'esecuzione della copia dei dati. Per altre informazioni, vedere Archiviare le credenziali in Azure Key Vault.You can choose to mark this field as a SecureString to store it securely in ADF, or store password in Azure Key Vault and let the copy activity pull from there when performing data copy - learn more from Store credentials in Key Vault. Yes
connectViaconnectVia Runtime di integrazione da usare per la connessione all'archivio dati.The integration runtime to be used to connect to the data store. Se non specificato, viene usato il runtime di integrazione di Azure predefinito.If not specified, it uses the default Azure Integration Runtime. No per l'origine, Sì per il sinkNo for source, Yes for sink

Esempio: Dynamics locale con IFD e autenticazione IFDExample: Dynamics on-premises with IFD using IFD authentication

{
    "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 datiDataset properties

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione dei set di dati, vedere l'articolo Set di dati.For a full list of sections and properties available for defining datasets, see the Datasets article. Questa sezione presenta un elenco delle proprietà supportate dal set di dati Dynamics.This section provides a list of properties supported by Dynamics dataset.

Per copiare dati da e in Dynamics, impostare la proprietà type del set di dati su DynamicsEntity.To copy data from and to Dynamics, set the type property of the dataset to DynamicsEntity. Sono supportate le proprietà seguenti.The following properties are supported.

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà type del set di dati deve essere impostata su DynamicsEntity.The type property of the dataset must be set to DynamicsEntity. Yes
entityNameentityName Il nome logico dell'entità da recuperare.The logical name of the entity to retrieve. No per l'origine (se nell'origine dell'attività è specificato "query"), Sì per il sinkNo for source (if "query" in the activity source is specified), Yes for sink

Importante

  • Quando si copiano dati da Dynamics, la sezione "Structure" è facoltativa ma altamente riordinata nel set di dati di Dynamics per garantire un risultato di copia deterministica.When you copy data from Dynamics, the "structure" section is optional but highly recommanded in the Dynamics dataset to ensure a deterministic copy result. Definisce il nome di colonna e il tipo di dati per i dati di Dynamics da copiare.It defines the column name and data type for Dynamics data that you want to copy over. Per altre informazioni, vedere Struttura del set di dati e Mapping dei tipi di dati per Dynamics.To learn more, see Dataset structure and Data type mapping for Dynamics.
  • Durante l'importazione dello schema nell'interfaccia utente di creazione, Azure Data Factory deduce lo schema tramite il campionamento delle prime righe dal risultato della query Dynamics per inizializzare la costruzione della struttura, nel qual caso le colonne senza valori verranno omesse.When importing schema in authoring UI, ADF infer the schema by sampling the top rows from the Dynamics query result to initialize the structure construction, in which case columns with no values will be omitted. Lo stesso comportamento si applica alle esecuzioni di copia se non esiste alcuna definizione esplicita della struttura.The same behavior applies to copy executions if there is no explicit structure definition. È possibile rivedere e aggiungere altre colonne nello schema/nella struttura del set di dati Dynamics, come necessario, che verranno rispettate durante il runtime di copia.You can review and add more columns into the Dynamics dataset schema/structure as needed, which will be honored during copy runtime.
  • Quando si copiano dati in Dynamics, la sezione "structure" è facoltativa nel set di dati di Dynamics.When you copy data to Dynamics, the "structure" section is optional in the Dynamics dataset. Le colonne in cui eseguire la copia sono determinate dallo schema dei dati di origine.Which columns to copy into are determined by the source data schema. Se l'origine è un file CSV senza intestazione, nel set di dati di input specificare "structure" con il nome della colonna e il tipo di dati.If your source is a CSV file without a header, in the input dataset, specify the "structure" with the column name and data type. Le colonne vengono mappate ai campi nel file CSV una alla volta in ordine.They map to fields in the CSV file one by one in order.

Esempio:Example:

{
    "name": "DynamicsDataset",
    "properties": {
        "type": "DynamicsEntity",
        "structure": [
            {
                "name": "accountid",
                "type": "Guid"
            },
            {
                "name": "name",
                "type": "String"
            },
            {
                "name": "marketingonly",
                "type": "Boolean"
            },
            {
                "name": "modifiedon",
                "type": "Datetime"
            }
        ],
        "typeProperties": {
            "entityName": "account"
        },
        "linkedServiceName": {
            "referenceName": "<Dynamics linked service name>",
            "type": "linkedservicereference"
        }
    }
}

Proprietà dell'attività di copiaCopy activity properties

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, vedere l'articolo sulle pipeline.For a full list of sections and properties available for defining activities, see the Pipelines article. Questa sezione presenta un elenco delle proprietà supportate dai tipi di origine e di sink Dynamics.This section provides a list of properties supported by Dynamics source and sink types.

Dynamics come tipo di origineDynamics as a source type

Per copiare dati da Dynamics, impostare il tipo di origine nell'attività di copia su DynamicsSource.To copy data from Dynamics, set the source type in the copy activity to DynamicsSource. Nella sezione source dell'attività di copia sono supportate le proprietà seguenti.The following properties are supported in the copy activity source section.

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà type dell'origine dell'attività di copia deve essere impostata su DynamicsSource.The type property of the copy activity source must be set to DynamicsSource. Yes
queryquery FetchXML è un linguaggio di query proprietario usato in Dynamics (online e locale).FetchXML is a proprietary query language that is used in Dynamics (online and on-premises). Vedere l'esempio seguente.See the following example. Per altre informazioni, vedere compilare query con un'FetchXML.To learn more, see Build queries with FetchXML. No (se nel set di dati è specificato "entityName")No (if "entityName" in the dataset is specified)

Nota

La colonna della chiave primaria verrà sempre copiata anche se la proiezione della colonna configurata nella query FetchXML non la contiene.The PK column will always be copied out even if the column projection you configure in the FetchXML query doesn't contain it.

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

Esempio di query FetchXMLSample FetchXML query

<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 sinkDynamics as a sink type

Per copiare dati in Dynamics, impostare il tipo di sink nell'attività di copia su DynamicsSink.To copy data to Dynamics, set the sink type in the copy activity to DynamicsSink. Nella sezione sink dell'attività di copia sono supportate le proprietà seguenti.The following properties are supported in the copy activity sink section.

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà type del sink dell'attività di copia deve essere impostata su DynamicsSink.The type property of the copy activity sink must be set to DynamicsSink. Yes
writebehaviorwriteBehavior Comportamento dell'azione di scrittura dell'operazione.The write behavior of the operation.
Il valore consentito è "Upsert" .Allowed value is "Upsert".
Yes
writeBatchSizewriteBatchSize Conteggio delle righe di dati scritti da Dynamics in ogni batch.The row count of data written to Dynamics in each batch. No (il valore predefinito è 10)No (default is 10)
ignoreNullValuesignoreNullValues Indica se ignorare i valori null dai dati di input (tranne i campi chiave) durante un'operazione di scrittura.Indicates whether to ignore null values from input data (except key fields) during a write operation.
I valori consentiti sono true e false.Allowed values are true and false.
- True: i dati nell'oggetto di destinazione rimangono invariati quando si esegue un'operazione di upsert/aggiornamento.- True: Leave the data in the destination object unchanged when you do an upsert/update operation. Inserire un valore predefinito definito quando si esegue un'operazione di inserimento.Insert a defined default value when you do an insert operation.
- False: i dati nell'oggetto di destinazione vengono aggiornati a NULL quando si esegue un'operazione di upsert/aggiornamento.- False: Update the data in the destination object to NULL when you do an upsert/update operation. Inserire un valore NULL quando si esegue un'operazione di inserimento.Insert a NULL value when you do an insert operation.
No (il valore predefinito è false)No (default is false)

Nota

Il valore predefinito di "writeBatchSize" del sink e di " parallelCopies " per l'attività di copia per il sink di Dynamics è in entrambi i casi 10.The default value of the sink "writeBatchSize" and the copy activity "parallelCopies" for the Dynamics sink are both 10. Pertanto, vengono inviati simultaneamente 100 record a Dynamics.Therefore, 100 records are submitted to Dynamics concurrently.

Per Dynamics 365 online, è previsto un limite di 2 chiamate di batch simultanee per ogni organizzazione.For Dynamics 365 online, there is a limit of 2 concurrent batch calls per organization. Se tale limite viene superato, viene generato un errore "Server occupato" prima che venga eseguita la prima richiesta.If that limit is exceeded, a "Server Busy" fault is thrown before the first request is ever executed. Mantenendo "writeBatchSize" minore o uguale a 10 si evita la limitazione delle richieste di chiamate simultanee.Keeping "writeBatchSize" less or equal to 10 would avoid such throttling of concurrent calls.

La combinazione ottimale di "writeBatchSize" e di "parallelCopies" dipende dallo schema dell'entità, ad esempio numero di colonne, le dimensioni delle righe, il numero di attività di plug-in/flussi di lavoro/flusso di lavoro collegate a tali chiamate e così via. L'impostazione predefinita 10 writeBatchSize * 10 parallelCopies è quella consigliata in base al servizio di Dynamics e che funzionerà per la maggior parte delle entità di Dynamics benché potrebbe non garantire prestazioni ottimali.The optimal combination of "writeBatchSize" and "parallelCopies" depends on the schema of your entity e.g. number of columns, row size, number of plugins/workflows/workflow activities hooked up to those calls, etc. The default setting of 10 writeBatchSize * 10 parallelCopies is the recommendation according to Dynamics service, which would work for most Dynamics entities though may not be best performance. È possibile ottimizzare le prestazioni regolando la combinazione nelle impostazioni di attività di copia.You can tune the performance by adjusting the combination in your copy activity settings.

Esempio: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
            }
        }
    }
]

Mapping dei tipi di dati per DynamicsData type mapping for Dynamics

Quando si copiano dati da Dynamics, vengono usati i mapping seguenti tra i tipi di dati di Dynamics e i tipi di dati provvisori di Data Factory.When you copy data from Dynamics, the following mappings are used from Dynamics data types to Data Factory interim data types. Vedere Mapping dello schema e del tipo di dati per informazioni su come l'attività di copia esegue il mapping dello schema di origine e del tipo di dati al sink.To learn how the copy activity maps the source schema and data type to the sink, see Schema and data type mappings.

Nella struttura del set di dati, configurare il tipo di dati corrispondente di Data Factory in base al tipo di dati di origine di Dynamics usando la tabella di mapping seguente.Configure the corresponding Data Factory data type in a dataset structure based on your source Dynamics data type by using the following mapping table.

Tipo di dati di DynamicsDynamics data type Tipo di dati provvisorio di Data FactoryData Factory interim data type Supportato come origineSupported as source Supportato come sinkSupported as sink
AttributeTypeCode.BigIntAttributeTypeCode.BigInt LongLong
AttributeTypeCode.BooleanAttributeTypeCode.Boolean BooleanBoolean
AttributeType.CustomerAttributeType.Customer GuidGuid
AttributeType.DateTimeAttributeType.DateTime DatetimeDatetime
AttributeType.DecimalAttributeType.Decimal DecimalDecimal
AttributeType.DoubleAttributeType.Double DoubleDouble
AttributeType.EntityNameAttributeType.EntityName StringString
AttributeType.IntegerAttributeType.Integer Int32Int32
AttributeType.LookupAttributeType.Lookup GuidGuid ✓ (associata a destinazione singola)✓ (with single target associated)
AttributeType.ManagedPropertyAttributeType.ManagedProperty BooleanBoolean
AttributeType.MemoAttributeType.Memo StringString
AttributeType.MoneyAttributeType.Money DecimalDecimal
AttributeType.OwnerAttributeType.Owner GuidGuid
AttributeType.PicklistAttributeType.Picklist Int32Int32
AttributeType.UniqueidentifierAttributeType.Uniqueidentifier GuidGuid
AttributeType.StringAttributeType.String StringString
AttributeType.StateAttributeType.State Int32Int32
AttributeType.StatusAttributeType.Status Int32Int32

Nota

I tipi di dati di Dynamics AttributeType. CalendarRules, AttributeType. MultiSelectPicklist e AttributeType. party non sono supportati.The Dynamics data types AttributeType.CalendarRules, AttributeType.MultiSelectPicklist and AttributeType.PartyList aren't supported.

Proprietà attività di ricercaLookup activity properties

Per informazioni dettagliate sulle proprietà, controllare l' attività di ricerca.To learn details about the properties, check Lookup activity.

Passaggi successiviNext steps

Per un elenco degli archivi dati supportati come origini e sink dall'attività di copia in Data Factory, vedere gli archivi dati supportati.For a list of data stores supported as sources and sinks by the copy activity in Data Factory, see Supported data stores.