Copiar e transformar dados no Dynamics 365 (Microsoft Dataverse) ou no Dynamics CRM usando o Azure Data Factory ou o Azure Synapse Analytics

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como usar uma atividade Cópia em pipelines do Azure Data Factory ou do Azure Synapse para copiar dados de/para o Dynamics 365 (Microsoft Dataverse) ou o Dynamics CRM e usar um fluxo de dados para transformar dados no Dynamics 365 (Microsoft Dataverse) ou no Dynamics CRM. Para saber mais, leia os artigos de introdução do Azure Data Factory e do Azure Synapse Analytics.

Funcionalidades com suporte

Este conector é compatível com as seguintes atividades:

① Runtime de integração do Azure ② Runtime de integração auto-hospedada

Para obter uma lista de armazenamentos de dados para os quais a atividade Copy dá suporte como origens e coletores, confira a tabela Armazenamentos de dados com suporte.

Esse conector do Dynamics dá suporte ao Dynamics das versões 7 a 9 para uso online e local. Mais especificamente:

• A versão 7 é equivalente ao Dynamics CRM 2015.
• A versão 8 é equivalente ao Dynamics CRM 2016 e à versão anterior do Dynamics 365.
• A versão 9 é equivalente à versão mais recente do Dynamics 365.

Veja a tabela a seguir de tipos de autenticação e configurações com suporte para versões e produtos do Dynamics.

Para o Dynamics 365 especificamente, os seguintes tipos de aplicativos são compatíveis:

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

Esse conector não dá suporte a outros tipos de aplicativos, como Finance, Operations e Talent.

Esse conector do Dynamics é criado com base nas ferramentas do Dynamics XRM.

Pré-requisitos

Para usar esse conector com a autenticação de entidade de serviço do Microsoft Entra, você precisará de configurar a autenticação de servidor-para-servidor (S2S) no Dataverse ou no Dynamics. Primeiro, registre o usuário do aplicativo (Entidade de Serviço) no Microsoft Entra ID. Você pode descobrir como fazer isso aqui. Durante o registro do aplicativo, você precisará criar esse usuário no Dataverse ou no Dynamics e conceder permissões. Essas permissões podem ser concedidas direta ou indiretamente adicionando o usuário do aplicativo a uma equipe que recebeu permissões no Dataverse ou no Dynamics. Você pode encontrar mais informações sobre como configurar um usuário do aplicativo para autenticar com o Dataverse aqui.

Introdução

Para executar a atividade de Cópia com um pipeline, será possível usar as ferramentas ou os SDKs abaixo:

• A ferramenta Copiar Dados
• O portal do Azure
• O SDK do .NET
• O SDK do Python
• PowerShell do Azure
• A API REST
• O modelo do Azure Resource Manager

Criar um serviço vinculado para o Dynamics 365 (Microsoft Dataverse) ou Dynamics CRM usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado Dynamics 365 na interface do usuário do portal do Azure.

1. Navegue até a guia Gerenciar no workspace do Azure Data Factory ou do Synapse, selecione Serviços Vinculados e clique em Novo:

   • Azure Data Factory
   • Azure Synapse

   

2. Pesquise o Dynamics ou o Dataverse e selecione o conector do Dynamics 365 (Microsoft Dataverse) ou do Dynamics CRM.

   

   

3. Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

   

Detalhes da configuração do conector

As seções que se seguem fornecem detalhes sobre as propriedades que são usadas para definir entidades específicas do Dynamics.

Propriedades do serviço vinculado

As propriedades a seguir têm suporte no serviço vinculado do Dynamics.

Dynamics 365 e Dynamics CRM Online

Exemplo: Dynamics Online usando a entidade de serviço do Microsoft Entra e a autenticação por chave

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

Exemplo: Dynamics Online usando a entidade de serviço do Microsoft Entra e a autenticação de certificado

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

Exemplo: Dynamics Online usando a autenticação do 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"
        }
    }
}

Exemplo: usar a autenticação de identidade gerenciada atribuída pelo usuário

{
    "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 local com IFD

Propriedades adicionais que se comparam com o Dynamics Online são hostName e port.

Exemplo: Dynamics on-premises com IFD usando autenticação do 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"
        }
    }
}

Propriedades do conjunto de dados

Para obter uma lista completa das seções e propriedades disponíveis para definir os conjuntos de dados, confira o artigo sobre Conjuntos de Dados. Esta seção fornece uma lista das propriedades com suporte pelo conjunto de dados do Dynamics.

Para copiar dados bidirecionalmente no Dynamics, há suporte para as seguintes propriedades:

Exemplo

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

Propriedades da atividade de cópia

Para obter uma lista completa das seções e propriedades disponíveis para definir atividades, confia o artigo Pipelines. Esta seção fornece uma lista das propriedades com suporte pela fonte e tipos de coletor do Dynamics.

Dynamics como um tipo de fonte

Para copiar dados do Dynamics, a seção de origem da atividade Copy dá suporte às seguintes propriedades:

Exemplo

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

Exemplo de consulta 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 como um tipo de coletor

Para copiar dados para o Dynamics, a seção de coletor da atividade Copy dá suporte às seguintes propriedades:

Para o Dynamics 365 online, há um limite de 52 chamadas simultâneas de lote por organização. Se esse limite for excedido, uma falha de "Servidor Ocupado" será gerada antes que a primeira solicitação seja executada. Mantenha writeBatchSize em 10 ou menos para evitar essa limitação de chamadas simultâneas.

A combinação ideal de writeBatchSize e parallelCopies depende do esquema da entidade. Os elementos de esquema incluem o número de colunas, o tamanho da linha e o número de plug-ins, os fluxos de trabalho ou as atividades de fluxo de trabalho conectadas a essas chamadas. A configuração padrão de writeBatchSize (10) × parallelCopies (10 é a recomendação de acordo com o serviço do Dynamics. Esse valor funciona para a maioria das entidades do Dynamics, embora possa não fornecer o melhor desempenho. Você pode ajustar o desempenho ajustando a combinação em suas configurações de atividade de cópia.

Exemplo

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

Como recuperar dados de exibições

Para recuperar dados de exibições do Dynamics, você precisará obter a consulta salva da exibição e usar a consulta para obter os dados.

Há duas entidades que armazenam diferentes tipos de exibição: a "consulta salva" armazena a exibição do sistema e a "consulta do usuário" armazena a exibição do usuário. Para obter as informações das exibições, veja a consulta FetchXML a seguir e substitua "TARGETENTITY" por savedquery ou userquery. Cada tipo de entidade tem mais atributos disponíveis que você poderá adicionar à consulta de acordo com suas necessidades. Saiba mais sobre entidade savedquery e a entidade userquery.

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

Você também pode adicionar filtros para filtrar as exibições. Por exemplo, adicione o filtro a seguir para obter uma exibição chamada "Minhas Contas Ativas" na entidade de conta.

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

Mapeamento de tipo de dados para Dynamics

Durante a cópia de dados do Dynamics, a tabela a seguir mostra os mapeamentos dos tipos de dados do Dynamics para os tipos de dados provisórios no serviço. Para saber como a atividade Copy é mapeada para um esquema de origem e um tipo de dados é mapeado para um coletor, confira Mapeamentos de tipo de dados e esquema.

Configure o tipo de dados provisórios correspondente em uma estrutura de conjunto de dados com base no tipo de dados de origem do Dynamics usando a seguinte tabela de mapeamento:

Como gravar dados em um campo de pesquisa

Para gravar dados em um campo de pesquisa com vários destinos, como Cliente e Proprietário, siga estas diretrizes e o exemplo:

1. Faça com que a fonte contenha o valor do campo e o nome da entidade de destino correspondente.

   • Se todos os registros forem mapeados para a mesma entidade de destino, garanta uma das seguintes condições:
     • Os dados de origem têm uma coluna que armazena o nome da entidade de destino.
     • Você adicionou uma coluna extra na origem da atividade Copy para definir a entidade de destino.
   • Se diferentes registros forem mapeados para diferentes entidades de destino, verifique se os dados de origem têm uma coluna que armazena o nome da entidade de destino correspondente.

2. Mapeie as colunas de valor e de referência da entidade da origem para o coletor. A coluna da entidade de referência precisa ser mapeada para uma coluna virtual com o padrão de nomenclatura especial {lookup_field_name}@EntityReference. Na verdade, a coluna não existe no Dynamics. Ela é usada para indicar que essa coluna é a coluna de metadados do campo de pesquisa de vários destinos fornecido.

Por exemplo, suponha que a origem tenha estas duas colunas:

• A coluna CustomerField do tipo GUID, que é o valor da chave primária da entidade de destino no Dynamics.
• A coluna Target do tipo String, que é o nome lógico da entidade de destino.

Além disso, suponha que você deseje copiar esses dados para o campo de entidade CustomerField do coletor do Dynamics do tipo Customer.

No mapeamento de coluna da atividade de cópia, mapeie as duas colunas da seguinte maneira:

• CustomerField para CustomerField. Esse mapeamento é o mapeamento de campo normal.
• Target para CustomerField@EntityReference. A coluna do coletor é uma coluna virtual que representa a referência de entidade. Insira esses nomes de campo em um mapeamento, pois eles não serão exibidos pela importação de esquemas.

Se todos os seus registros de origem forem mapeados para a mesma entidade de destino e os dados de origem não contiverem o nome da entidade de destino, use este atalho: na origem da atividade Copy, adicione uma coluna extra. Nomeie a nova coluna usando o padrão {lookup_field_name}@EntityReference, defina o valor com o nome da entidade de destino e continue com o mapeamento de coluna como de costume. Se os nomes de coluna de origem e do coletor forem idênticos, você também poderá ignorar o mapeamento de coluna explícito, pois a atividade Copy, por padrão, mapeia as colunas por nome.

Gravar dados em um campo de pesquisa por meio de chaves alternativas

Para gravar dados em um campo de pesquisa usando colunas de chaves alternativas, siga estas diretrizes e exemplos:

1. Verifique se a fonte contém todas as colunas de chaves de pesquisa.

2. As colunas de chaves alternativas devem ser mapeadas para a coluna com o padrão de nomenclatura especial {lookup_field_name}@{alternate_key_column_name}. A coluna não existe no Dynamics. Ele é usado para indicar que a coluna é usada para pesquisar o registro na entidade de destino.

3. Acesse a guia Mapeamento na transformação do coletor de fluxos de dados de mapeamento. Selecione a chave alternativa como colunas de saída no campo de pesquisa. O valor posterior indica as colunas de chaves dessa chave alternativa.

   

4. Depois de selecionadas, as colunas de chaves alternativas serão exibidas automaticamente abaixo.

   

5. Mapeie suas colunas de entrada à esquerda com as colunas de saída.

   

Mapeamento de propriedades de fluxo de dados

Ao transformar dados no fluxo de dados de mapeamento, é possível ler e gravar em tabelas no Dynamics. Para obter mais informações, confira transformação de origem e transformação do coletor nos fluxos de dados de mapeamento. Você pode optar por usar um conjunto de dados do Dynamics ou um conjunto de dados embutido como origem e tipo de coletor.

Transformação de origem

A tabela abaixo lista as propriedades com suporte do Dynamics. Você pode editar essas propriedades na guia Opções de origem.

Exemplo de script de origem do Dynamics

Quando você usa o conjunto de dados do Dynamics como tipo de origem, o script de fluxo de dados associado é:

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 você usar um conjuntos de dados embutido, o script de fluxo de dados associado será:

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

Transformação de coletor

A tabela abaixo lista as propriedades compatíveis com o coletor do Dynamics. Você pode editar essas propriedades na guia Opções do coletor.

Exemplo de script de coletor do Dynamics

Quando você usa o conjunto de dados do Dynamics como tipo de coletor, o script de fluxo de dados associado é:

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

Se você usar um conjuntos de dados embutido, o script de fluxo de dados associado será:

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

Pesquisar propriedades de atividade

Para saber mais detalhes sobre as propriedades, confira Atividade de pesquisa.

Conteúdo relacionado

Para obter uma lista de armazenamentos de dados que a atividade Copy suporta, como fontes e coletores, consulte Armazenamentos de dados com suporte.