Referência do conector do Microsoft Dynamics 365

Esta página fornece informações de referência técnica para o conector do Microsoft Dynamics 365 no Lakeflow Connect.

Parâmetros de autenticação

O conector do Dynamics 365 usa a autenticação OAuth do Microsoft Entra (antigo Azure Active Directory). Para obter detalhes, consulte Como o conector acessa dados D365?.

Campos de autenticação necessários

Ao criar uma conexão do Catálogo do Unity para D365, forneça estes parâmetros:

Campo de cursor

O conector do Dynamics 365 usa o campo VersionNumber dos logs de alteração do Link do Azure Synapse como o cursor para ingestão incremental.

Comportamento do cursor

• Fonte: o Link do Synapse gera VersionNumber automaticamente valores ao exportar alterações.
• Formato: timestamp inteiro que representa a sequência de alterações.
• Escopo: cursor individual por tabela. Cada tabela mantém sua própria posição de cursor.
• Armazenamento: os cursores são armazenados nos metadados do pipeline e não aparecem nas tabelas Delta de destino.

Requisitos de cursor

Para que a ingestão incremental funcione:

• O Link do Synapse deve exportar os changelogs com o campo VersionNumber.
• VersionNumber deve estar presente em todos os arquivos de registro de alterações.
• As pastas de changelog devem seguir a convenção de nomenclatura baseada no carimbo de data/hora do Link do Synapse.

Se VersionNumber estiver ausente, a ingestão incremental falhará e você deverá executar uma atualização completa.

Descoberta de Esquema

O conector do Dynamics 365 descobre automaticamente esquemas de tabela de metadados do Dataverse.

Processo de descoberta

Ao criar um pipeline:

1. O conector lê arquivos de metadados do ADLS Gen2 do Link do Synapse.
2. O conector extrai esquemas de tabela dos arquivos JSON de metadados.
3. Nomes de coluna, tipos de dados e possibilidade de valor nulo são inferidos a partir dos metadados.
4. As tabelas de destino são criadas com os esquemas descobertos.

Tipos de dados do Dataverse com suporte

O conector do Dynamics 365 mapeia os tipos de dados do Dataverse para os tipos de dados Delta Lake.

Mapeamento de tipo de dados

Tipos de dados complexos

Alguns tipos do Dataverse exigem tratamento especial:

• Conjuntos de opções (listas de seleção): ingeridos como códigos inteiros. Para mapear para rótulos, combine com a tabela OptionSetMetadata ou mantenha uma tabela de mapeamento de referência.
• Consultas: processadas como cadeias de caracteres GUID. Para obter dados relacionados, junte-se à tabela referenciada.
• Conjuntos de opções de seleção múltipla: ingeridos como cadeias de caracteres inteiros separadas por vírgulas (por exemplo, "1,3,5"). Analise a cadeia de caracteres para extrair valores individuais.

Exemplo: analisando conjuntos de opções de seleção múltipla

-- Split comma-separated values into array
SELECT
  accountid,
  accountname,
  SPLIT(industrycodes, ',') AS industry_array
FROM main.d365_data.account;

-- Explode into separate rows
SELECT
  accountid,
  accountname,
  CAST(code AS INT) AS industry_code
FROM main.d365_data.account
LATERAL VIEW EXPLODE(SPLIT(industrycodes, ',')) AS code;

Compatibilidade de versão da API

O conector do Dynamics 365 é compatível com:

• API do Dataverse: versão 9.2 e posterior
• Link do Azure Synapse para Dataverse: versão 1.0 e posterior
• API REST do Armazenamento do Azure: versão 2021-08-06 e posterior
• Microsoft Entra ID: fluxo de credenciais do cliente OAuth 2.0

Comportamento de ingestão incremental

A ingestão incremental do conector do Dynamics 365 segue estas regras:

Detecção de alterações

• Inserções: novos registros detectados por sua presença em logs de alterações.
• Atualizações: registros modificados identificados por alterações em VersionNumber.
• Exclusões: registros excluídos identificados por marcadores de exclusão em changelogs (se exportados pelo Link do Synapse).

Comportamento do SCD Tipo 1

Para pipelines SCD Tipo 1, os registros são atualizados no local sem preservar o histórico. As atualizações substituem as linhas existentes com base na chave primária, e as exclusões removem linhas (se o rastreamento de exclusão estiver habilitado).

Estrutura de tabela de exemplo:

SELECT * FROM main.d365_data.account ORDER BY accountid;

-- Result: Latest state only
-- accountid | accountname | modifiedon
-- 123       | Acme Corp   | 2025-12-03 10:00:00
-- 456       | TechCo      | 2025-12-03 09:30:00

Comportamento do SCD Tipo 2

Para pipelines SCD Tipo 2, todas as alterações são preservadas como novas versões de linha. O conector adiciona __START_AT, __END_ATe __CURRENT colunas para acompanhar o histórico de versão.

Estrutura de tabela de exemplo:

SELECT * FROM main.d365_data.account ORDER BY accountid, __START_AT;

-- Result: All historical versions
-- accountid | accountname | __START_AT          | __END_AT            | __CURRENT
-- 123       | Acme Inc    | 2025-11-01 08:00:00 | 2025-12-03 10:00:00 | false
-- 123       | Acme Corp   | 2025-12-03 10:00:00 | NULL                | true
-- 456       | TechCo      | 2025-12-01 14:00:00 | NULL                | true

Excluir tratamento

Tratamento de exclusão depende da sua configuração no Link do Synapse.

• Exclusões definitivas: se o Link do Synapse exportar registros de exclusão, o conector removerá (SCD Tipo 1) ou marcará (SCD Tipo 2) registros excluídos.
• Sem controle de exclusão: se o Link do Synapse não exportar exclusões, os registros excluídos permanecerão nas tabelas de destino até que você execute uma atualização completa.

Verifique se a configuração do Link do Synapse exporta exclusões para um rastreamento de exclusão preciso.

Parâmetros do pipeline

Ao criar um pipeline de ingestão D365, especifique estes parâmetros:

Parâmetros necessários

Parâmetros opcionais

Configuração de pipeline de exemplo

Conclua a configuração do pipeline usando o SDK do Python:

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.pipelines import IngestionPipelineDefinition

w = WorkspaceClient()

pipeline = w.pipelines.create(
    name="d365_comprehensive_ingestion",
    ingestion_definition=IngestionPipelineDefinition(
        channel="PREVIEW",
        connection_name="d365_connection",
        source_schema="https://contoso.crm.dynamics.com",
        source_table=[
            "account",
            "contact",
            "opportunity",
            "salesorder",
            "systemuser"
        ],
        destination_catalog="main",
        destination_schema="d365_sales",
        scd_type="SCD_TYPE_2",
        table_configuration={
            "account": {
                "columns": [
                    "accountid",
                    "accountnumber",
                    "name",
                    "emailaddress1",
                    "telephone1"
                ]
            }
        }
    )
)

Localizando nomes lógicos de tabela

Para identificar nomes lógicos de tabela para o source_table parâmetro:

1. Power Apps Maker Portal: navegue até Tabelas e visualize a coluna Nome lógico.
2. API do Dataverse: consultar metadados usando https://yourorg.api.crm.dynamics.com/api/data/v9.2/EntityDefinitions.
3. Armazenamento do ADLS Gen2: Listar pastas no contêiner do Link do Synapse (os nomes das pastas correspondem aos nomes lógicos).

Ajuste de desempenho

O conector do Dynamics 365 fornece opções limitadas de ajuste de desempenho:

Seleção de coluna

Selecione apenas as colunas necessárias para reduzir:

• Transferência de dados do ADLS Gen2
• Custos de armazenamento no Delta Lake
• Tempo de processamento da consulta

Consulte a seleção de coluna para obter detalhes de configuração.

Agrupamento de tabelas

Para ambientes com muitas tabelas:

• Tabelas relacionadas: agrupar tabelas relacionadas no mesmo pipeline para facilitar o gerenciamento.
• Baseado em volume: separe tabelas de alto volume em pipelines dedicados.
• Frequência de atualização: agrupar tabelas com padrões de atualização semelhantes.

Resolução de problemas

Para problemas e soluções comuns ao trabalhar com o conector do Dynamics 365, consulte Solucionar problemas de ingestão do Microsoft Dynamics 365.