Referência do conector do Microsoft Dynamics 365
Esta referência cobre autenticação, comportamento de cursor e esquema, tipos de dados Dataverse suportados, evolução do esquema e parâmetros de pipeline para o conector Microsoft Dynamics 365 no Lakeflow Connect.
Parâmetros de autenticação
O conector do Dynamics 365 usa a autenticação OAuth do Microsoft Entra ID (anteriormente Azure Active Directory). Para obter detalhes, consulte Como o conector acessa os dados do D365?
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 |
|---|---|---|
| Seu ID tenant Microsoft Entra ID (ID do diretório) |
|
| O ID do aplicativo (cliente) do seu aplicativo Entra ID |
|
| O valor secreto do cliente criado para o seu aplicativo Entra ID. |
|
| O nome da sua accountde armazenamento ADLS Gen2. |
|
| O contêiner onde o Synapse Link exporta dados. |
|
| O escopo OAuth para acesso ao Armazenamento do Azure |
|
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
versionnumberao 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. versionnumberDeve 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.
Formato de exportação de origem
O Azure Synapse Link pode exportar dados do Dataverse para o ADLS Gen2 no formato CSV ou Parquet . O conector do Dynamics 365 suporta ambos e detecta automaticamente qual formato o Synapse Link gravou, portanto, você não precisa especificar o formato de exportação na definição do pipeline. O formato é determinado pela sua configuração do Synapse Link. A exportação como Parquet requer a conexão de um workspace do Azure Synapse Analytics (consulte Configurar uma fonte de dados Parquet para ingestão do Microsoft Dynamics 365), enquanto a exportação CSV utiliza a configuração padrão (consulte Configurar fonte de dados para ingestão do Microsoft Dynamics 365).
- CSV : O Synapse Link grava arquivos CSV diretamente no ADLS Gen2 sem um workspace do Azure Synapse Analytics.
- Parquet : a ingestão de Parquet está em Beta. O Synapse Link grava cada tabela como uma tabela Delta no formato Parquet em
<profileRoot>/deltalake/<tableName>/. Este caminho requer um workspace do Azure Synapse Analytics e um pool do Apache Spark, e o Databricks o recomenda para instâncias grandes ou de alto volume.
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.
Evolução do esquema para ingestão de CSV
Visualização
Esse recurso está na Prévia privada. Para experimentar, fale com o seu contato no Databricks.
A evolução do esquema mantém automaticamente suas tabelas Delta de destino sincronizadas à medida que o esquema do Dataverse de origem muda, incluindo adições, exclusões e renomeações de colunas do Azure Synapse Link.
Pré-requisitos
- A evolução do esquema é opcional durante a Private Preview. Para habilitá-lo para seu pipeline, fale com seu contato no Databricks.
- A Service Principal da conexão deve ter a função Colaborador de Dados de Blob de Armazenamento na account de armazenamento ADLS Gen2. A evolução do esquema grava o ponto de verificação do esquema de volta no seu armazenamento, portanto, qualquer função que conceda apenas permissão de leitura não funcionará. Uma conexão somente leitura falha com um erro solicitando que você conceda acesso de gravação ou desabilite a evolução do esquema. Para a configuração da conexão, consulte Criar uma conexão do Dynamics 365.
Como as alterações de esquema são aplicadas
Uma atualização de pipeline lê com um esquema único e fixo durante toda a sua duração, portanto, o conector começa uma nova atualização para captar um esquema alterado. Cada alteração de esquema na origem é aplicada da seguinte forma:
- A atualização ingere os dados exportados até, mas não incluindo, o ponto onde o esquema muda, e faz o commit dele.
- A atualização é cancelada e o conector registra o novo esquema.
- Uma nova atualização começa no ponto em que o esquema foi alterado e continua a partir daí com o novo esquema.
Cada alteração de esquema no histórico de exportação repete este ciclo, portanto, um backlog que abrange várias alterações de esquema leva várias atualizações para ser processado. O conector reinicia as atualizações para você; nenhuma ação é necessária.
A reinicialização foi projetada para que os dados não sejam duplicados nem perdidos. Cada atualização faz commit apenas dos dados lidos antes da alteração, e a próxima atualização é retomada no ponto em que a anterior parou.
Como essas reinicializações são esperadas, uma atualização cancelada após uma alteração no esquema de origem não é uma falha. O pipeline relata um evento de alteração de esquema que nomeia a tabela afetada, juntamente com quaisquer novas colunas.
Alterações com e sem suporte
A evolução do esquema lida com as seguintes mudanças de esquema de origem:
Alterar | Suportado |
|---|---|
Adição de coluna | Suportado |
Exclusão de coluna | Suportado |
Renomeação de coluna | Suportado |
Adição de tabela | Suportado |
Remoção de tabela | Suportado |
Remover uma coluna e, posteriormente, adicionar novamente uma coluna com o mesmo nome | Não suportado |
Remover uma tabela e, posteriormente, adicionar novamente uma tabela com o mesmo nome | Não suportado |
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 |
|---|---|---|
|
| O comprimento máximo foi preservado como metadados. |
|
| |
|
| |
|
| |
|
| Precisão e escala preservadas |
|
| |
|
| Armazenado como decimal com 4 casas decimais |
|
| |
|
| Informações de fuso horário preservadas |
|
| |
|
| O Spark não possui um tipo |
|
| Armazenado como representação em strings |
|
| GUID key estrangeira armazenado como strings |
|
| Valor inteiro, não rótulo |
|
| Valores inteiros separados por vírgulas |
|
| URL ou metadados, não dados binários. |
|
| Apenas metadados, não o conteúdo do arquivo. |
Tipos de dados complexos
Alguns tipos do Dataverse exigem tratamento especial:
Tipo Dataverse | Ingerido como | Como lidar com isso |
|---|---|---|
| Códigos inteiros | join com a tabela |
| Strings GUID | Faça um join com a tabela referenciada para obter dados relacionados |
| Strings de números inteiros separados por vírgulas, como | Analise a string para extrair valores individuais |
Os exemplos a seguir analisam um conjunto de opções de seleção múltipla, primeiro dividindo os valores separados por vírgula em um array e, em seguida, explodindo-os em linhas separadas:
-- 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 : Fluxo de credenciais do cliente OAuth 2.0
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
Como o conector aplica cada alteração detectada depende do tipo de SCD que você escolhe para o pipeline, e se as exclusões chegam ao Databricks depende da sua configuração do Synapse Link.
Detecção de mudanças
O conector detecta todas as alterações dos changelogs do Synapse Link. Ele trata a presença de um registro em um changelog como uma inserção, um versionnumber alterado como uma atualização e um marcador de exclusão como uma exclusão. Os marcadores de exclusão aparecem apenas se o Synapse Link estiver configurado para exportar exclusões.
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).
A consulta a uma tabela de destino retorna uma linha por registro, refletindo apenas seu estado mais recente:
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.
A consulta de uma tabela de destino retorna todas as versões de cada registro. __START_AT e __END_AT delimitam a janela na qual cada versão estava atual, e a versão ativa tem um NULL __END_AT e __CURRENT definido como true:
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
Quando o Synapse Link exporta como Parquet, os checkpoints Delta mais antigos são compactados periodicamente em novos, o que pode tornar algumas versões de registros históricos indisponíveis para processamento. Para pipelines SCD tipo 2, isso pode produzir uma história incompleta, mas não causa perda de dados: o pipeline sempre reflete o snapshot mais recente de cada registro corretamente, e apenas algumas versões intermediárias podem estar ausentes. Para reduzir a chance de uma história incompleta, o Databricks recomenda executar o pipeline com uma frequência maior do que uma vez a cada 24 horas, o que reduz a janela na qual a compactação pode descartar alterações históricas.
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
Esses parâmetros devem ser especificados para que o pipeline seja executado.
Parâmetro | Tipo | Descrição | Exemplo |
|---|---|---|---|
| String | Deve ser |
|
| String | Nome da sua conexão Unity Catalog |
|
| String | Nome do esquema lógico do Synapse Link, normalmente |
|
| String | Nome lógico da tabela D365, com uma entrada por objeto |
|
| String | Unity Catalog |
|
| String | Esquema Unity Catalog de destino |
|
| String |
|
|
Parâmetros opcionais
Esses parâmetros podem ser definidos opcionalmente ao criar seu pipeline.
Parâmetro | Tipo | Descrição | Exemplo |
|---|---|---|---|
| Objeto | Configurações por tabela, como a seleção de colunas | Consulte a seleção de colunas. |
Exemplo de configuração de pipeline
Este é um exemplo de uma configuração completa de 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="objects",
source_table="account",
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).
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 oferece ajuste limitado, pois o Synapse Link controla a própria exportação. O que você pode controlar é a quantidade de dados que cada pipeline move e como você distribui as tabelas entre os pipelines.
Seleção de coluna
Selecionar apenas as colunas necessárias reduz a transferência de dados do ADLS Gen2, os custos de armazenamento no Delta Lake e o tempo de processamento da query. Consulte seleção de coluna para obter detalhes de configuração.
Agrupamento de tabelas
Agrupe tabelas que se comportam de forma semelhante, para que a programação de um pipeline atenda a tudo o que está nele: tabelas relacionadas juntas para facilitar o gerenciamento, e tabelas com padrões de atualização semelhantes juntas para que você possa programar cada pipeline para corresponder ao seu volume de alterações. Dê às tabelas de alto volume seus próprios pipelines, para que uma única tabela grande não torne o restante mais lento.
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.