Referência do conector do Microsoft Dynamics 365

info

Visualização

Este recurso está em Pré-visualização Pública.

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

Parâmetros de autenticação

O conector do Dynamics 365 usa a autenticação OAuth Microsoft Entra ID (anteriormente Azure Active Directory) para acessar Azure Data Lake Storage (ADLS) Gen2, de onde Azure Synapse Link exporta os dados.

Campos de autenticação obrigatórios

Ao criar uma conexão Unity Catalog para o D365, forneça estes parâmetros:

Parâmetro	Descrição	Exemplo
`tenant_id`	Seu ID tenant Microsoft Entra ID (ID do diretório)	`12345678-1234-1234-1234-123456789abc`
`client_id`	O ID do aplicativo (cliente) do seu aplicativo Entra ID	`87654321-4321-4321-4321-cba987654321`
`client_secret`	O valor secreto do cliente criado para o seu aplicativo Entra ID.	`abc123~xyz789...`
`storage_account_name`	O nome da sua accountde armazenamento ADLS Gen2.	`d365storage`
`container_name`	O contêiner onde o Synapse Link exporta dados.	`d365-export`
`scope`	O escopo OAuth para acesso ao Armazenamento do Azure	`https://storage.azure.com/.default`

Campo do cursor

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

Comportamento do cursor

Fonte : O Synapse Link gera automaticamente valores VersionNumber ao exportar alterações.
Formato : Número inteiro que representa a sequência de alterações.
Escopo : Cursor 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 do cursor

Para que a ingestão incremental funcione:

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

Se VersionNumber estiver ausente, a ingestão incremental falhará e você deverá realizar uma refreshcompleta.

Descoberta de esquema

O conector do Dynamics 365 descobre automaticamente os esquemas de tabela a partir dos metadados do Dataverse.

Processo de descoberta

Ao criar um pipeline:

O conector lê arquivos de metadados do Synapse Link do ADLS Gen2.
O conector extrai os esquemas das tabelas dos arquivos JSON de metadados.
Os nomes das colunas, os tipos de dados e a possibilidade de valores nulos são inferidos a partir dos metadados.
As tabelas de destino são criadas com os esquemas descobertos.

Tipos de dados suportados pelo Dataverse

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

Mapeamento de tipo de dados

Tipo Dataverse	Tipo Delta Lake	Notas
strings (linha única)	String	O comprimento máximo foi preservado como metadados.
strings (multilinhas)	String
Número inteiro	Integer
BigInt	Long
Decimal	Decimal	Precisão e escala preservadas
Número de ponto flutuante (Duplo)	double
Dinheiro	DECIMAL(19,4)	Armazenado como decimal com 4 casas decimais
Boolean (Sim/Não)	Booleana
Data e hora	Timestamp	Informações de fuso horário preservadas
Data	Data
Tempo	String	Armazenado como sequências de tempo ISO 8601
Identificador único (GUID)	String	Armazenado como representação em strings
Pesquisa	String	GUID key estrangeira armazenado como strings
Lista de opções (Conjunto de opções)	Integer	Valor inteiro, não rótulo
Lista de seleção múltipla	String	Valores inteiros separados por vírgulas
Imagem	String	URL ou metadados, não dados binários.
Arquivo	String	Apenas metadados, não o conteúdo do arquivo.

Tipos de dados complexos

Alguns tipos do Dataverse exigem tratamento especial:

Conjuntos de opções (listas de seleção) : Inseridos como códigos inteiros. Para mapear para rótulo, join com a tabela OptionSetMetadata ou mantenha uma tabela de mapeamento de referência.
Consultas : Ingeridas como strings GUID. Para obter dados relacionados, join com a tabela referenciada.
Conjuntos de opções de seleção múltipla : Ingeridos como strings de números inteiros separados por vírgulas (por exemplo, "1,3,5"). Analise as strings para extrair valores individuais.

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

SQL
-- 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 Dataverse : Versão 9.2 e posteriores
Azure Synapse Link para Dataverse : Versão 1.0 e posteriores
API REST do Armazenamento do Azure : Versão 2021-08-06 e posteriores
Microsoft Entra ID (Azure AD) : Fluxo de credenciais do cliente OAuth 2.0

nota

Versões mais antigas da API podem funcionar, mas não são oficialmente suportadas. Mantenha seus serviços do D365 e Azure atualizados para obter a melhor compatibilidade.

Comportamento de ingestão incremental

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

Detecção de mudanças

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

Comportamento SCD Tipo 1

Para o pipeline SCD Tipo 1 , os registros são atualizados no local sem preservar o histórico. As atualizações sobrescrevem as linhas existentes com base na key primária, e as exclusões removem as linhas (se a opção de exclusão estiver ativada).

Exemplo de estrutura de tabela:

SQL
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 SCD Tipo 2

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

Exemplo de estrutura de tabela:

SQL
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

O tratamento de exclusões depende da sua configuração do Synapse Link:

Exclusões permanentes : Se o Synapse Link exportar registros excluídos, o conector removerá (SCD Tipo 1) ou marcará (SCD Tipo 2) os registros excluídos.
Sem acompanhamento de exclusão : Se Synapse Link não exportar exclusões, os registros excluídos permanecerão nas tabelas de destino até que você execute uma refresh completa.

Verifique se as suas exportações de configuração Synapse Link excluem informações importantes caso precise de acompanhamento preciso de exclusões.

Parâmetros do pipeline

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

Parâmetros obrigatórios

Parâmetro	Tipo	Descrição	Exemplo
`channel`	String	Deve ser `PREVIEW`	`"PREVIEW"`
`connection_name`	String	Nome da sua conexão Unity Catalog	`"d365_connection"`
`source_schema`	String	URL ou ID do ambiente Dataverse	`"https://yourorg.crm.dynamics.com"`
`source_table`	Array[strings]	Lista de nomes lógicos de tabelas do D365	`["account", "contact"]`
`destination_catalog`	String	Unity Catalog	`"main"`
`destination_schema`	String	Esquema Unity Catalog de destino	`"d365_data"`
`scd_type`	String	`SCD_TYPE_1` ou `SCD_TYPE_2`	`"SCD_TYPE_2"`

Parâmetros opcionais

Parâmetro	Tipo	Descrição	Exemplo
`table_configuration`	Objeto	Configurações por tabela (seleção de colunas, etc.)	Consulte a seleção de colunas.

Exemplo de configuração de pipeline

Configuração completa do pipeline usando o SDK do Python:

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

Encontrando nomes lógicos de tabelas

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

Portal do criador do Power Apps : Navegue até Tabelas e view a coluna Nome lógico .
API Dataverse : Consultar metadados usando https://yourorg.api.crm.dynamics.com/api/data/v9.2/EntityDefinitions.
Armazenamento ADLS Gen2 : Liste as pastas no seu contêiner Synapse Link (os nomes das pastas correspondem aos nomes lógicos).

dica

Use nomes lógicos em minúsculas nas configurações do pipeline (por exemplo, "account" em vez de "Account"). O conector diferencia maiúsculas de minúsculas.

Ajuste de desempenho

O conector Dynamics 365 oferece 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 seção de seleção de colunas para obter detalhes sobre a configuração.

Agrupamento de tabelas

Para ambientes com muitas tabelas:

Tabelas relacionadas : Agrupe tabelas relacionadas no mesmo pipeline para facilitar o gerenciamento.
Baseado em volume : Separe as tabelas de alto volume em um pipeline dedicado.
Frequência de atualização : Agrupe tabelas com padrões de atualização semelhantes.

nota

Cada pipeline está limitado a 250 tabelas. Para ambientes maiores, crie vários pipelines.

Solução de problemas

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

Parâmetros de autenticação​

Campos de autenticação obrigatórios​

Campo do cursor​

Comportamento do cursor​

Requisitos do cursor​

Descoberta de esquema​

Processo de descoberta​

Tipos de dados suportados pelo Dataverse​

Mapeamento de tipo de dados​

Tipos de dados complexos​

compatibilidade de versão da API​

Comportamento de ingestão incremental​

Detecção de mudanças​

Comportamento SCD Tipo 1​

Comportamento SCD Tipo 2​

Excluir tratamento​

Parâmetros do pipeline​

Parâmetros obrigatórios​

Parâmetros opcionais​

Exemplo de configuração de pipeline​

Encontrando nomes lógicos de tabelas​

Ajuste de desempenho​

Seleção de coluna​

Agrupamento de tabelas​

Solução de problemas​