Копирование и преобразование данных в Dynamics 365 (Microsoft Dataverse) или Dynamics CRM с помощью Azure Data Factory или Azure Synapse Analytics

ПРИМЕНИМО К: Azure Data Factory Azure Synapse Analytics

В этой статье описывается, как использовать действие копирования в конвейерах Azure Data Factory или Synapse для копирования данных из Dynamics 365 (Microsoft Dataverse) или Dynamics CRM и использования потока данных для преобразования данных в Dynamics 365 ( Microsoft Dataverse) или Dynamics CRM. Дополнительные сведения см. в статьях Azure Data Factory и Azure Synapse Analytics.

Поддерживаемые возможности

Этот соединитель поддерживается для действий, указанных ниже.

(1) Azure среды выполнения интеграции (2) локальная среда выполнения интеграции

Список хранилищ данных, поддерживаемых действием копирования в качестве источников и приемников, приведен в таблице Поддерживаемые хранилища данных.

Этот соединитель Dynamics поддерживает Dynamics версии 7–9 для сети и локальной среды. В частности:

• Версия 7 сопоставляется с Dynamics CRM 2015.
• Версия 8 сопоставляется с Dynamics CRM 2016 и ранней версией Dynamics 365.
• Версия 9 сопоставляется с более поздней версией Dynamics 365.

Ознакомьтесь со следующей таблицей поддерживаемых типов проверки подлинности и конфигураций для Dynamics версий и продуктов.

В частности, для Dynamics 365 поддерживаются следующие типы приложений:

• Dynamics 365 для продаж
• Dynamics 365 для службы клиентов
• Dynamics 365 для службы полей
• Dynamics 365 для автоматизации проектных услуг
• Dynamics 365 для маркетинга

Этот соединитель не поддерживает другие типы приложений, такие как Finance, Operations и Talent.

Этот соединитель Dynamics создан на основе инструментов Dynamics XRM.

Prerequisites

Чтобы использовать этот соединитель с проверкой подлинности с помощью служебного принципала Microsoft Entra, необходимо настроить сервер-серверную (S2S) проверку подлинности в Dataverse или Dynamics. Сначала зарегистрируйте пользователя приложения (субъект-службу) в Microsoft Entra ID. Здесь можно узнать, как это сделать. Во время регистрации приложения необходимо создать этого пользователя в Dataverse или Dynamics и предоставить разрешения. Эти разрешения можно предоставить напрямую или косвенно, добавив пользователя приложения в команду, которая была предоставлена разрешения в Dataverse или Dynamics. Дополнительные сведения о том, как настроить пользователя приложения для проверки подлинности с помощью Dataverse, можно найти здесь.

Get started

Для выполнения действия копирования с конвейером можно использовать один из следующих средств или пакетов SDK:

• Средство копирования данных
• портал Azure
• SDK .NET
• пакет SDK Python
• Azure PowerShell
• REST API
• шаблон Azure Resource Manager

Создание связанной службы для Dynamics 365 (Microsoft Dataverse) или Dynamics CRM с помощью пользовательского интерфейса

Выполните следующие действия, чтобы создать связанную службу для Dynamics 365 в пользовательском интерфейсе портала Azure.

1. Перейдите на вкладку Manage в рабочей области Azure Data Factory или Synapse и выберите связанные службы, а затем выберите New:

   • Фабрика данных Azure
   • Azure Synapse

   

2. Найдите Dynamics или Dataverse и выберите соединитель Dynamics 365 (Microsoft Dataverse) или Dynamics CRM.

   

   

3. Настройте сведения о службе, проверьте подключение и создайте связанную службу.

   

Сведения о конфигурации соединителя

В следующих разделах содержатся сведения о свойствах, которые используются для определения сущностей, относящихся к Dynamics.

Свойства подключенной службы

Следующие свойства поддерживаются для связанной службы Dynamics.

Dynamics 365 и Dynamics CRM online

Пример: Dynamics Online с использованием объекта-службы Microsoft Entra и проверки подлинности с помощью ключа

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

Пример: использование Dynamics в Интернете с помощником службы Microsoft Entra и аутентификацией по сертификатам

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

Пример: Dynamics в Сети с помощью проверки подлинности 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 Online с помощью аутентификации управляемой идентичности, назначенной пользователем

{
    "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 и Dynamics CRM в локальной среде с IFD

Дополнительные свойства, сравнимые с Dynamics online, это hostName и port.

Пример: Dynamics локально с IFD и аутентификацией 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"
        }
    }
}

Свойства набора данных

Полный список разделов и свойств, доступных для определения наборов данных, см. в статье о наборах данных. В этом разделе представлен список свойств, поддерживаемых Dynamics набором данных.

Для копирования данных из и в Dynamics поддерживаются следующие свойства:

Example

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

Свойства Copy activity

Полный список разделов и свойств, доступных для определения действий, см. в статье Конвейеры. В этом разделе представлен список свойств, поддерживаемых Dynamics типами источников и приемников.

Dynamics в качестве типа источника

Чтобы скопировать данные из Dynamics, раздел источник действия копирования поддерживает следующие свойства:

Example

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

Образец запроса FetchXML

<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 в качестве типа приемника

Чтобы скопировать данные в Dynamics, в разделе sink действия копирования поддерживаются следующие свойства:

Для Dynamics 365 в Сети существует ограничение 52 одновременных пакетных вызовов для каждой организации. Если это ограничение превышено, исключение "Сервер занят" выдается до того, как будет выполнен первый запрос. Сохраняйте значение writeBatchSize равным 10 или меньше, чтобы избежать такого регулирования количества одновременных вызовов.

Оптимальное сочетание writeBatchSize и parallelCopies зависит от схемы сущности. К элементам схемы относятся: количество столбцов, размер строк и количество подключаемых модулей, рабочих процессов или действий рабочего процесса, привязанных к этим вызовам. Параметр по умолчанию writeBatchSize (10) × parallelCopies (10) является рекомендацией в соответствии со службой Dynamics. Это значение работает для большинства Dynamics сущностей, хотя это может не обеспечить лучшую производительность. Вы можете настроить производительность путем корректировки комбинации в настройках активности копирования.

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

При выборе эластичных таблиц в модуле назначения операции копирования сопоставление столбцов поддерживает partitionid. Столбец исходных данных можно сопоставить с столбцом приемника partitionid . Если не сопоставлено, значение первичного ключа используется в качестве значения по умолчанию для столбца partitionid .

partitionid можно использовать в альтернативных ключах Dataverse или сценариях первичного ключа в пути записи. Каждая эластичная таблица partitionid содержит системно-определённый столбец и имеет альтернативный ключ KeyForNoSqlEntityWithPKPartitionId, который объединяет первичный ключ таблицы со столбцом partitionid. Дополнительные сведения см. в этой статье.

Получение данных из представлений

Чтобы получить данные из представлений Dynamics, необходимо получить сохраненный запрос представления и использовать запрос для получения данных.

Существует два сущности, которые хранят разные типы представления: "сохраненный запрос" хранит системное представление и "запрос пользователя" сохраняет представление пользователя. Для получения сведений о представлениях обратитесь к следующему запросу FetchXML и замените "TARGETENTITY" на savedquery или userquery. Для каждого типа сущности имеются дополнительные доступные атрибуты, которые можно добавить в запрос в соответствии с потребностями. Подробнее о сущности savedquery и сущности userquery.

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

Кроме того, можно добавить фильтры для фильтрации представлений. Например, добавьте нижеуказанный фильтр, чтобы получить представление "Мои активные учетные записи" в сущности учетной записи.

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

Сопоставление типов данных для Dynamics

При копировании данных из Dynamics в следующей таблице показаны сопоставления типов данных из Dynamics с промежуточными типами данных в службе. Сведения о том, как действие копирования сопоставляется с исходной схемой и как карта типа данных сопоставляется с приемником, см. в разделе "Схемы и сопоставления типов данных".

Настройте соответствующий промежуточный тип данных в структуре набора данных, основанной на вашем исходном типе данных Dynamics, используя следующую таблицу сопоставления.

Запись данных в поле поиска

Чтобы записать данные в поле поиска с несколькими целевыми объектами, такими как Customer и Owner, следуйте указаниям и см. пример.

Задание поля "Владелец"

При настройке поля "Владелец" в Dynamics 365 (Microsoft Dataverse) или Dynamics CRM важно указать действительную ссылку. Допустимые параметры для @EntityReference:

• systemuser: это относится к отдельному пользователю в системе.
• team: это относится к группе пользователей в организации.

Убедитесь, что указанное значение соответствует одному из этих параметров, чтобы избежать ошибок во время преобразования данных.

Например, предположим, что источник содержит следующие два столбца:

• CustomerField столбец типа GUID, являющийся основным ключевым значением целевой сущности в Dynamics.
• Target, столбец типа String, который является логическим именем целевой сущности.

Кроме того, предполагается, что вы хотите скопировать такие данные в поле сущности приемника Dynamics CustomerField типа Customer.

При сопоставлении столбцов действия копирования сопоставьте два столбца как указано ниже.

• CustomerField в CustomerField. Это сопоставление является обычным сопоставлением полей.
• Target в CustomerField@EntityReference. Столбец приемника — это виртуальный столбец, представляющий ссылку на сущность. Введите соответствующие имена полей в сопоставлении, поскольку они не будут отображаться при импорте схем.

Если все ваши исходные записи соответствуют одной и той же целевой сущности, а исходные данные не содержат имя схемы целевой сущности, вот как можно упростить задачу: в источнике операции копирования добавьте дополнительный столбец. Назовите новый столбец с помощью шаблона {lookup_field_name}@EntityReference, установите значение в поле имени целевой сущности, затем выполните обычное сопоставление столбцов. Если имена столбцов источника и приемника идентичны, можно пропустить явное сопоставление столбцов, поскольку действие копирования по умолчанию сопоставляет столбцы по имени.

Запись данных в поле подстановки с помощью альтернативных ключей

Чтобы записать данные в поле подстановки с помощью альтернативных ключевых столбцов, следуйте приведенным ниже рекомендациям и примеру:

Свойства потока данных для сопоставления

При преобразовании данных в потоках данных сопоставления, вы можете считывать и записывать данные в таблицы Dynamics. Дополнительные сведения см. в описаниях преобразования источника и преобразования приемника в разделе, посвященном потокам данных для сопоставления. Вы можете использовать набор данных Dynamics или набор данных inline в качестве типа источника и приемника.

Преобразование источника

В таблице ниже перечислены свойства, поддерживаемые Dynamics. Изменить эти свойства можно на вкладке Source options (Параметры источника).

Пример исходного скрипта Dynamics

При использовании набора данных Dynamics в качестве исходного типа используемый скрипт потока данных будет:

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

Если используется встроенный набор данных, связанный сценарий потока данных будет следующим:

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

Преобразование приемника

В таблице ниже перечислены свойства, поддерживаемые приемником Dynamics. Эти свойства можно изменить на вкладке Параметры приемника.

Пример скрипта приемника Dynamics

При использовании набора данных Dynamics в качестве типа приемника данных соответствующий скрипт потока данных:

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

Если используется встроенный набор данных, связанный сценарий потока данных будет следующим:

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

Свойства действия поиска

Подробные сведения об этих свойствах см. в статье Действие поиска.

Связанный контент

Для списка хранилищ данных, поддерживаемых операцией копирования в качестве источников и приемников, см. раздел Поддерживаемые хранилища данных.