使用 Azure 数据工厂或 Azure Synapse Analytics 在 Dynamics 365 (Microsoft Dataverse) 或 Dynamics CRM 中复制和转换数据

适用于：Azure 数据工厂 Azure Synapse Analytics

本文概述了如何使用 Azure 数据工厂或 Synapse 管道中的复制活动在 Dynamics 365 (Microsoft Dataverse) 或 Dynamics CRM 之间复制数据，并使用数据流在 Dynamics 365 (Microsoft Dataverse) 或 Dynamics CRM 中转换数据. 有关详细信息，请阅读 Azure 数据工厂和 Azure Synapse Analytics 简介文章。

支持的功能

以下活动支持此连接器：

① Azure 集成运行时 ② 自承载集成运行时

如需复制活动支持将其用作源和接收器的数据存储的列表，请参阅支持的数据存储表。

此 Dynamics 连接器支持联机的和本地的 Dynamics 版本 7-9。 更具体地说：

• 版本 7 映射到 Dynamics CRM 2015。
• 版本 8 映射到 Dynamics CRM 2016 和早期版 Dynamics 365。
• 版本 9 映射到较新版 Dynamics 365。

请参阅下表，了解各种 Dynamics 版本和产品支持的身份验证类型和配置。

具体而言，对于 Dynamics 365，支持以下应用程序类型：

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

此连接器不支持其他应用程序类型，如“财务”、“运营”和“人才”。

此 Dynamics 连接器基于 Dynamics XRM 工具构建。

先决条件

若要将此连接器与 Microsoft Entra 服务主体身份验证配合使用，必须在 Dataverse 或 Dynamics 中设置服务器到服务器 (S2S) 身份验证。 先在 Microsoft Entra ID 中注册应用程序用户（服务主体）。 可在此处了解如何执行此操作。 在应用程序注册期间，需要在 Dataverse 或 Dynamics 中创建该用户并授予权限。 可以直接授予这些权限，也可以通过将应用程序用户添加到已在 Dataverse 或 Dynamics 中为其授予了这些权限的团队来间接授权。 可在此处详细了解如何将应用程序用户设置为使用 Dataverse 进行身份验证。

开始

若要使用管道执行复制活动，可以使用以下工具或 SDK 之一：

• 复制数据工具
• Azure 门户
• .NET SDK
• Python SDK
• Azure PowerShell
• REST API
• Azure Resource Manager 模板

使用 UI 创建 Dynamics 365 (Microsoft Dataverse) 或 Dynamics CRM 的链接服务

使用以下步骤在 Azure 门户 UI 中创建一个到 Dynamics 365 的链接服务。

1. 浏览到 Azure 数据工厂或 Synapse 工作区中的“管理”选项卡，并选择“链接服务”，然后单击“新建”：

   • Azure 数据工厂
   • Azure Synapse

   

2. 搜索 Dynamics 或 Dataverse，然后选择 Dynamics 365 (Microsoft Dataverse) 或 Dynamics CRM 连接器。

   

   

3. 配置服务详细信息、测试连接并创建新的链接服务。

   

连接器配置详细信息

以下部分提供了有关各属性的详细信息，这些属性用于定义特定于 Dynamics 的实体。

链接服务属性

Dynamics 链接服务支持以下属性。

联机 Dynamics 365 和 Dynamics CRM

示例：使用 Microsoft Entra 服务主体和密钥身份验证的联机 Dynamics

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

示例：使用 Microsoft Entra 服务主体和证书身份验证的联机 Dynamics

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

示例：使用 Office 365 身份验证的联机 Dynamics

{
    "name": "DynamicsLinkedService",
    "properties": {
        "type": "Dynamics",
        "typeProperties": {
            "deploymentType": "Online",
            "serviceUri": "https://<organization-name>.crm[x].dynamics.com",
            "authenticationType": "Office365",
            "username": "test@contoso.partner.onmschina.cn",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

示例：使用用户分配的托管标识身份验证的联机 Dynamics

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

带有 IFD 的本地 Dynamics 365 和 Dynamics CRM

与 Dynamics Online 进行比较的更多属性是 hostName 和 port。

示例：带有 IFD、使用 Active Directory 身份验证的本地 Dynamics

{
    "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.partner.onmschina.cn",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

数据集属性

有关可用于定义数据集的各部分和属性的完整列表，请参阅数据集一文。 本部分提供 Dynamics 数据集支持的属性列表。

支持使用以下属性从/向 Dynamics 复制数据：

示例

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

复制活动属性

有关可用于定义活动的各部分和属性的完整列表，请参阅管道一文。 本部分提供 Dynamics 源和接收器类型支持的属性列表。

将 Dynamics 用作源类型

为了从 Dynamics 复制数据，复制活动的 source 节支持以下属性：

示例

"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 实体，但可能无法提供最佳性能。 你可以通过在复制活动设置中调整组合来调整性能。

示例

"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：这是指组织内的用户团队。

确保提供的值对应于上述选项之一，以避免在数据转换期间出错。

例如，假设源包含下面的两个列：

• 类型为 GUID 的 CustomerField 列，它是 Dynamics 中目标实体的主键值。
• 类型为 String 的 Target 列，它是目标实体的逻辑名称。

另外假设你希望将此类数据复制到类型为 Customer 的接收器 Dynamics 实体字段 CustomerField。

在复制活动列映射中，如下所述映射这两个列：

• 将 CustomerField 映射到 CustomerField。 此映射是标准字段映射。
• 将 Target 映射到 CustomerField@EntityReference。 接收器列是表示实体引用的虚拟列。 请在映射中输入此类字段名称，因为不可通过导入架构来显示它们。

如果所有源记录都映射到同一目标实体，并且源数据不包含目标实体架构名称，下面是一个快捷方式：在复制活动源中，添加另一列。 使用模式 {lookup_field_name}@EntityReference 命名新列，将值设置为目标实体名称，然后按常规方式进行列映射。 如果源和接收器列名称相同，则还可跳过显式列映射，因为默认情况下，复制活动按名称映射列。

通过备用键将数据写入查找字段

若要使用备用键列将数据写入查找字段，请按照本指南和示例操作：

映射数据流属性

在映射数据流中转换数据时，可以从 Dynamics 中的表读取数据以及将数据写入表中。 有关详细信息，请参阅映射数据流中的源转换和接收器转换。 可以选择使用 Dynamics 数据集或内联数据集作为源和接收器类型。

源转换

下表列出了 Dynamics 支持的属性。 可以在“源选项”选项卡中编辑这些属性。

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

查找活动属性

若要了解有关属性的详细信息，请参阅“查找”活动。

相关内容

有关复制活动支持作为源和接收器的数据存储的列表，请参阅支持的数据存储。