Solução de problemas de ingestão do Microsoft Dynamics 365

info

Visualização

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

Esta página fornece orientações para a resolução de problemas comuns com o conector Microsoft Dynamics 365 no LakeFlow Connect.

Problemas com o Azure Synapse Link

O Synapse Link não está exportando dados.

Sintomas:

• Nenhuma pasta aparece no seu contêiner ADLS Gen2 após configurar o Synapse Link.
• Os registros de data e hora das pastas pararam de ser atualizados.
• A execução do pipeline falha com erros do tipo "Nenhum dado encontrado".

Possíveis causas:

• A conexão Synapse Link está pausada ou interrompida.
• As permissões account de armazenamento Azure estão incorretas.
• As tabelas selecionadas não estão configuradas para exportação.
• O Synapse Link encontrou um erro durante a exportação.

par:

1. Verificar o status do Synapse Link:

   • Faça login no Power Apps.
   • Acesse o Azure Synapse Link no seu ambiente.
   • Verifique se sua conexão exibe o status "Ativo".
   • Se houver uma pausa, selecione "Retomar" para reiniciar a exportação.

2. Verificar permissões de armazenamento:

   • No portal Azure , navegue até sua account de armazenamento.
   • Selecione Controle de Acesso (IAM) .
   • Verifique se a identidade do administrador Synapse Link possui a função de Colaborador de Dados do Blob de Armazenamento .
   • Caso esteja faltando, adicione a atribuição de função.

3. Verificar configuração da tabela:

   • No Power Apps, selecione sua conexão Synapse Link.
   • Analise a lista de tabelas selecionadas.
   • Verifique se as tabelas que você deseja importar estão incluídas.
   • Adicione as tabelas que faltam e aguarde a exportação inicial (5 a 15 minutos).

4. Analisar logs Synapse Link:

   • No Power Apps, selecione sua conexão Synapse Link.
   • Selecione visualizar logs ou história .
   • Procure por mensagens de erro que indiquem falhas na exportação.
   • Corrija erros específicos (por exemplo, cota de armazenamento, permissões).

Erro FILE_PATH_DOES_NOT_EXIST

Sintomas:

• A execução do pipeline falha com o erro FILE_PATH_DOES_NOT_EXIST .
• O conector não consegue encontrar os arquivos esperados no ADLS Gen2.
• O erro indica pastas ou caminhos de arquivo ausentes.

Possíveis causas:

• A opção "Ativar atualização incremental da estrutura de pastas" não está habilitada na configuração do Synapse Link.
• O conector espera uma estrutura de pastas específica que não existe.

par:

1. Ativar estrutura de pastas para atualizações incrementais:

   • No Power Apps, edite sua conexão do Synapse Link.
   • Selecione Avançado para exibir as configurações avançadas.
   • Ative a opção "Atualizar estrutura de pastas incrementalmente" .
   • Salve a configuração.
   • Aguarde até que Synapse Link regenere a estrutura de pastas (isso pode levar várias horas para conjuntos de dados grandes).

2. Verificar a estrutura de pastas:

   • No portal Azure , navegue até sua account de armazenamento e contêiner ADLS Gen2.
   • Verifique se as pastas da tabela agora contêm subpastas com carimbo de data/hora (por exemplo, 2025-12-19T10-30-00-000Z).
   • Essas pastas com registro de data e hora contêm as atualizações incrementais necessárias para o conector.

3. Tente novamente o pipeline:

   • Após habilitar a estrutura de pastas incremental, execute seu pipeline novamente.
   • O conector agora deverá encontrar arquivos nos locais esperados.

O Synapse Link está configurado, mas os arquivos não estão aparecendo.

Sintomas:

• O Synapse Link mostra o status "Ativo", mas nenhum arquivo CSV aparece no seu contêiner ADLS Gen2.
• A execução do pipeline falha com a mensagem "Nenhum dado encontrado" ou erros de formato de arquivo.

Possíveis causas:

• O Synapse Link está configurado para exportar dados no formato Parquet em vez do formato CSV.
• A opção Conectar ao seu espaço de trabalho Azure Synapse Analytics está selecionada, o que força a exportação Parquet .

par:

1. Verificar formato de arquivo no ADLS Gen2:

   • No portal Azure , navegue até sua account de armazenamento e contêiner ADLS Gen2.
   • Abra uma pasta com tabelas e verifique as extensões dos arquivos.
   • Se os arquivos tiverem a extensão .parquet em vez de .csv, o formato está incorreto.

2. Reconfigure o Synapse Link para exportação em CSV:

   • O conector do Dynamics 365 suporta apenas o formato CSV. Você precisa reconfigurar o Synapse Link.
   • No Power Apps, edite ou recrie sua conexão do Synapse Link.
   • Desmarque a caixa de seleção "Conectar-se ao seu espaço de trabalho Azure Synapse Analytics .
   • Isso garante que os dados sejam exportados em formato CSV em vez de Parquet.
   • Salve a configuração e aguarde o Synapse Link reexportar os dados (isso pode levar várias horas para conjuntos de dados grandes).

3. Verifique se os arquivos CSV foram criados:

   • Após a reconfiguração, verifique seu contêiner ADLS Gen2.
   • Confirme se as novas pastas contêm .csv arquivos.
   • Assim que os arquivos CSV aparecerem, tente executar o pipeline novamente.

Número da versão ausente no changelog do Synapse Link

Sintomas:

• A execução do pipeline falha com erros do tipo "Campo VersionNumber não encontrado".
• A ingestão incremental não funciona.
• Somente refresh completa é bem-sucedida.

Possíveis causas:

• O Synapse Link não está configurado para exportar registros de alterações.
• A opção "Alterar seguir" não está habilitada para tabelas.
• A versão do Synapse Link está desatualizada.

par:

1. Habilitar alteração:

   • No Power Apps, edite sua conexão do Synapse Link.
   • Certifique-se de que a opção "Ativar acompanhamento de alterações" esteja selecionada.
   • Salve o arquivo e aguarde o Synapse Link regenerar as exportações (até 30 minutos).

2. Verificar arquivos de changelog:

   • No portal do Azure, navegue até o seu contêiner ADLS Gen2.
   • Abra uma pasta de tabela e localize a subpasta SynapseLink .
   • Abra um arquivo de changelog recente (CSV ou JSON).
   • Verifique se o arquivo contém uma coluna VersionNumber .
   • Caso esteja faltando, entre em contato com o suporte Microsoft para habilitar o acompanhamento de alterações.

3. Atualizar link do Synapse:

   • Verifique se você está usando o Azure Synapse Link para Dataverse versão 1.0 ou posterior.
   • Versões mais antigas podem não suportar VersionNumber.
   • Atualize o Synapse Link para a versão mais recente, se necessário.

4. Realize uma refresh completa:

   • Se a opção de acompanhamento de alterações não puder ser ativada, você só poderá usar o modo refresh completa.
   • Note que refresh completa recarrega todos os dados a cada execução, o que é mais lento e mais custoso.

Problemas de autenticação

A autenticação do ID Entra falha

Sintomas:

• A criação do pipeline falha com erros de "Falha na autenticação".
• O teste de conexão falha no Explorador de Catálogo.
• A execução do pipeline falha com erros "401 Não Autorizado".

Possíveis causas:

• ID tenant , ID do cliente ou segredo do cliente incorretos.
• Segredo do cliente expirou.
• O aplicativo não possui as permissões necessárias.
• Escopo especificado incorretamente.

par:

1. Verificar parâmetros de autenticação:

   • No portal do Azure, navegue até Microsoft Entra ID > Registros de aplicativos .

   • Localize seu aplicativo e verifique:

     • O ID da aplicação (cliente) corresponde à sua configuração de conexão.
     • O ID do diretório (tenant) corresponde à sua configuração de conexão.

   • Copie os valores corretos e atualize sua conexão, se necessário.

2. Verificar expiração do segredo do cliente:

   • Em sua aplicação, selecione Certificados e segredos .
   • Verifique se a sua chave secreta não expirou.
   • Se estiver expirado, crie um novo segredo:
     • Selecione + Nova chave secreta do cliente .
     • Insira uma descrição e um período de validade.
     • Copie o valor secreto.
     • Atualize sua conexão com o novo segredo.

3. Verificar escopo:

   • Certifique-se de que sua conexão esteja usando o escopo correto: https://storage.azure.com/.default
   • Este escopo concede acesso ao Armazenamento do Azure, não ao Dynamics 365 diretamente.

4. Testar conexão:

   • No Explorador de Catálogo, navegue até sua conexão.
   • Selecione Testar conexão para verificar a autenticação.
   • Caso o teste falhe, revise a mensagem de erro para obter orientações específicas.

Não é possível acessar o armazenamento ADLS Gen2.

Sintomas:

• A execução do pipeline falha com erros "403 Proibido" ou "Acesso negado".
• O teste de conexão foi bem-sucedido, mas o pipeline falhou.
• Algumas tabelas funcionam, mas outras não.

Possíveis causas:

• O aplicativo Entra ID não possui a função de Colaborador de Dados do Blob de Armazenamento.
• A atribuição de função está definida para o contêiner ou caminho errado.
• Restrições de rede bloqueiam o acesso.
• As regras do firewall account de armazenamento bloqueiam o acesso Databricks .

par:

1. Verificar atribuição de função:

   • No portal Azure , navegue até sua account de armazenamento.
   • Selecione Controle de Acesso (IAM) .
   • Selecione as atribuições de função .
   • Verifique se o seu aplicativo Entra ID possui a função de Colaborador de Dados do Storage Blob .
   • Verifique se o Escopo está definido para toda a account de armazenamento, e não para um contêiner específico.

2. Adicionar função em falta:

   • Selecionar + Adicionar > Adicionar atribuição de função .
   • Pesquisar por Contribuidor de Dados do Blob de Armazenamento .
   • Selecione Avançar e adicione sua aplicação.
   • Selecione Revisar + atribuir .
   • Aguarde de 5 a 10 minutos para que as alterações de permissão sejam propagadas.

3. Verifique as restrições de rede:

   • Na sua account de armazenamento, selecione Rede .
   • Verifique se o acesso à rede pública está habilitado em todas as redes ou inclui os intervalos de IP do Databricks.
   • Se estiver usando um endpoint privado, certifique-se de que Databricks possa rotear para ele.

4. Revisar regras do firewall:

   • Em Rede , revise as configurações do Firewall .
   • Adicione os endereços IP do Databricks à lista de permissões, se necessário.
   • Como alternativa, habilite a opção "Permitir que o serviço Azure esteja na lista de serviços confiáveis" .

Questões de entidades virtuais

Entidades virtuais não aparecem na descoberta de esquema.

Sintomas:

• Entidades virtuais não aparecem ao listar tabelas.
• A criação do pipeline falha com erros de "Tabela não encontrada" para entidades virtuais.
• Somente tabelas nativas do Dataverse podem ser detectadas.

Possíveis causas:

• As entidades virtuais não estão configuradas nem sincronizadas.
• O Synapse Link não está exportando entidades virtuais.
• Os nomes das entidades virtuais não correspondem à configuração da tabela.

par:

1. Verificar a configuração da entidade virtual:

   • No centro de administração do Power Platform, navegue até o seu ambiente.
   • Acesse Configurações > produto > recurso .
   • Verifique se a fonte de dados da entidade virtual está habilitada.
   • Verifique se suas entidades virtuais de F&O estão configuradas e ativas.

2. Aguarde a sincronização:

   • Entidades virtuais podem levar até 15 minutos para sincronizar após a configuração.
   • Aguarde até 30 minutos para que as entidades virtuais apareçam no Dataverse.
   • Verifique novamente após o período de sincronização.

3. Verifique se o Synapse Link inclui entidades virtuais:

   • No Power Apps, edite sua conexão do Synapse Link.
   • Analise as tabelas selecionadas.
   • Certifique-se de que as entidades virtuais estejam incluídas na lista de exportação.
   • Adicione as entidades virtuais que faltam e salve.

4. Verificar nomes de entidades virtuais:

   • Os nomes lógicos das entidades virtuais podem diferir dos nomes das tabelas de F&O.
   • No Power Apps, acesse Tabelas e localize suas entidades virtuais.
   • Copie o nome lógico exato e use-o na configuração do seu pipeline.

Alterações no esquema da entidade virtual não refletidas

Sintomas:

• Novas colunas em F&O não aparecem nas tabelas Delta de destino.
• A execução do pipeline foi bem-sucedida, mas os dados estão incompletos.
• Avisos de desvio de esquema nos logs do pipeline.

Possíveis causas:

• Os metadados da entidade virtual não foram atualizados no Dataverse.
• Synapse Link usando esquema em cache.
• evolução do esquema limitações para entidades virtuais.

par:

1. Atualizar metadados da entidade virtual:

   • No centro de administração do Power Platform, navegue até o seu ambiente.
   • Acesse as configurações de entidades virtuais .
   • Selecione "Atualizar metadados" para as entidades virtuais afetadas.
   • Aguarde até 30 minutos para que os metadados sejam sincronizados.

2. Recriar exportação do Synapse Link:

   • No Power Apps, edite sua conexão do Synapse Link.
   • Remova a entidade virtual afetada da lista de exportação.
   • Salve o arquivo e aguarde 5 minutos.
   • Adicione a entidade virtual de volta à lista de exportação.
   • Salve o arquivo e aguarde a conclusão da exportação inicial.

3. Realize uma refresh completa:

   • Alterações no esquema de entidades virtuais geralmente exigem uma refreshcompleta.
   • Interrompa seu pipeline.
   • Exclua as tabelas Delta de destino para as entidades virtuais afetadas.
   • Reinicie o pipeline para recriar as tabelas com o esquema atualizado.

evolução do esquema issues

Alterações no tipo de dados causam falhas no pipeline.

Sintomas:

• A execução do pipeline falha com erros de "Incompatibilidade de tipo" ou "Não é possível converter".
• A ingestão é interrompida após uma atualização ou alteração de configuração do D365.
• As mensagens de erro fazem referência a colunas e tipos de dados específicos.

Possíveis causas:

• O tipo de dados da coluna foi alterado no D365 (por exemplo, de strings para inteiros).
• A tabela Delta de destino possui um esquema antigo incompatível com os novos dados.
• O Synapse Link exporta dados em um novo formato, mas a tabela de destino espera o formato antigo.

par:

1. Identifique a coluna alterada:

   • Analise logs de erros pipeline para encontrar a coluna e a tabela afetadas.

   • No Power Apps, verifique a definição da tabela para o tipo de dados atual da coluna.

   • Compare com o esquema da sua tabela Delta de destino:

     SQL

     DESCRIBE main.d365_data.tablename;

2. Realize uma refresh completa:

   • Alterações no tipo de dados exigem uma refreshcompleta para recriar as tabelas.

   • Interrompa o pipeline afetado.

   • Excluir a tabela de destino:

     SQL

     DROP TABLE IF EXISTS main.d365_data.tablename;

   • Reinicie o pipeline para recriar a tabela com o novo esquema.

3. Prevenir problemas futuros:

   • Coordene com o administrador do D365 antes de fazer alterações no esquema.
   • Teste primeiro as alterações de esquema em um ambiente que não seja de produção.
   • Atualização completa do programa durante janelas de manutenção.

importante

O conector do Dynamics 365 não lida automaticamente com alterações no tipo de dados. É necessário realizar uma refresh completa para atualizar os esquemas das tabelas. Consulte as limitações para obter detalhes.

Renomeações de colunas não são tratadas corretamente.

Sintomas:

• As colunas renomeadas aparecem como novas colunas com valores NULL.
• Os dados da coluna antiga foram perdidos.
• As tabelas de destino contêm nomes de colunas antigos e novos.

Possíveis causas:

• O conector trata a renomeação de colunas como operações de exclusão e adição.
• Não há migração automática de dados do nome de coluna antigo para o novo.

par:

1. Antes da renomeação:

   • Se possível, coordene com o administrador do D365 para realizar uma refresh completa antes de renomear o sistema.
   • Isso preserva os dados históricos no novo nome da coluna.

2. Após a renomeação:

   • Execute uma refreshcompleta para recarregar todos os dados com os novos nomes das colunas.
   • Os dados históricos preencherão a nova coluna.

3. Migração manual (caso refresh completa não seja viável):

   • Se não for possível realizar uma refresh completa, migre os dados manualmente:

     SQL

     -- Copy data from old column to new column
     UPDATE main.d365_data.tablename
     SET new_column_name = old_column_name
     WHERE new_column_name IS NULL AND old_column_name IS NOT NULL;
     
     -- Drop old column after verification
     ALTER TABLE main.d365_data.tablename DROP COLUMN old_column_name;

dica

Para minimizar interrupções, planeje a renomeação de colunas durante janelas de manutenção programadas e execute uma atualização completa imediatamente após.

Problemas de desempenho

A sincronização inicial está demorando muito.

Sintomas:

• O processo de execução no pipeline dura horas sem ser concluído.
• A sincronização inicial foi mais lenta do que o esperado.
• O pipeline atinge o tempo limite ou falha durante a primeira execução.

Possíveis causas:

• Grande volume de dados nas tabelas de origem.
• Exportação lenta do Synapse Link.
• Limitações de largura de banda da rede.
• Muitas tabelas em um único pipeline.

par:

1. Comece com menos tabelas:

   • Crie um pipeline com um pequeno subconjunto de tabelas (5 a 10 tabelas).
   • Verifique se o pipeline funciona corretamente.
   • Adicione mais tabelas incrementalmente após a validação inicial.

2. Aguarde a exportação do Synapse Link:

   • Verifique se o Synapse Link concluiu a exportação inicial antes de executar o pipeline.
   • No portal do Azure, verifique se todas as pastas de tabelas contêm arquivos de dados.
   • A exportação inicial Synapse Link pode levar horas para conjuntos de dados grandes.

3. Dividir em vários dutos:

   • Em vez de um único pipeline com 100 tabelas, crie 5 pipelines com 20 tabelas cada.
   • Fluxo de execução em paralelo ou sequencial, com base na disponibilidade de recursos.
   • Essa abordagem reduz o tempo de execução individual do pipeline.

4. Monitorar a largura de banda do Azure:

   • Verifique as métricas do Armazenamento do Azure para identificar limitações de largura de banda ou restrições de fluxo.
   • Se a sua conexão estiver limitada, aumente o nível account de armazenamento ou adicione mais capacidade de rede.

Atualizações incrementais lentas

Sintomas:

• A execução incremental pipeline está demorando mais do que o esperado.
• o desempenho do pipeline se degrada com o tempo.
• Um alto volume de alterações causa atrasos.

Possíveis causas:

• Arquivos de changelog grandes.
• Acúmulo excessivo de pastas no ADLS Gen2.
• Alterações frequentes criam muitas pastas pequenas.

par:

1. Aumente a frequência de execução pipeline :

   • Se os registros de alterações forem extensos, o pipeline de execução deve ser executado com mais frequência.
   • Arquivos de changelog menores e mais frequentes são processados mais rapidamente do que arquivos grandes.
   • Em ambientes de alta volatilidade, a execução deve ser feita a cada 5 a 15 minutos, em vez de a cada hora.

2. Analisar a frequência de exportação do Synapse Link:

   • No Power Apps, verifique seu programa de exportação Synapse Link.
   • O Synapse Link cria pastas em intervalos regulares (normalmente a cada 5 a 15 minutos).
   • Alinhar a execução pipeline com a frequência de exportação Synapse Link.

3. Limpe as pastas de exportação antigas:

   • Configure políticas de ciclo de vida em sua account de armazenamento para excluir exportações antigas.
   • Retenha apenas as exportações dos últimos 7 a 30 dias, com base nas suas necessidades de recuperação.
   • Isso reduz o número de pastas que o conector precisa verificar.

4. Reduzir o volume de troco:

   • Analise os processos do D365 que geram atualizações de alta frequência.
   • Realiza atualizações em lotes sempre que possível para reduzir eventos de mudança individuais.
   • Considere se todas as atualizações precisam ser registradas (algumas podem ser temporárias).

problemas de qualidade de dados

Registros ausentes após a ingestão

Sintomas:

• A contagem de linhas nas tabelas de destino não corresponde à das tabelas de origem.
• Registros específicos ausentes nas tabelas de destino.
• Lacunas intermitentes nos dados.

Possíveis causas:

• Exportação do Synapse Link incompleta.
• O pipeline ignorou pastas devido a erros.
• Filtragem ou permissões no sistema de origem.
• Excluir registros não exportados pelo Synapse Link.

par:

1. Comparar a quantidade de registros:

   • Verificar a contagem de linhas no D365:

     SQL

     -- In D365/Dataverse
     SELECT COUNT(*) FROM account;

   • Verificar a contagem de linhas na tabela Delta de destino:

     SQL

     -- In Databricks
     SELECT COUNT(*) FROM main.d365_data.account;

   • Identifique a magnitude da discrepância.

2. Verificar se o link do Synapse está completo:

   • No ADLS Gen2, verifique se todas as pastas de tabelas possuem pastas com carimbo de data/hora recente.
   • Procure por lacunas nos registros de data e hora das pastas que possam indicar exportações perdidas.
   • Caso existam interrupções, o Synapse Link pode ter parado temporariamente.

3. Verificar filtragem:

   • Algumas tabelas do D365 possuem filtros de segurança que restringem a visualização de registros.
   • Verifique se sua account do serviço Synapse Link tem permissão para visualizar todos os registros.
   • Verifique se os filtros de propriedade do registro ou de unidade de negócios se aplicam.

4. Realize uma refresh completa:

   • Se os registros estiverem constantemente faltando, execute uma refreshcompleta.
   • Isso recarrega todos os dados e garante a integridade dos mesmos.
   • Compare as contagens novamente após a refresh completa.

5. Verificar o tratamento de exclusões:

   • Caso registros ausentes tenham sido excluídos no D365, verifique as exclusões exportadas pelo Synapse Link.
   • No Power Apps, verifique as configurações Synapse Link para excluir acompanhamento.
   • Se as exclusões não forem exportadas, os registros excluídos não serão refletidos nas tabelas de destino.

Metadados do anexo incompletos

Sintomas:

• As tabelas de anexos (por exemplo, annotation, attachment) têm dados ausentes ou incompletos.
• Nomes de arquivos ou metadados incorretos.

Possíveis causas:

• O Synapse Link não exporta tabelas de anexos.
• As permissões de anexos restringem a visibilidade.
• Os dados dos anexos estão armazenados em tabelas diferentes.

par:

1. Verifique se as tabelas de anexos foram exportadas:

   • No Power Apps, verifique sua conexão com o Synapse Link.

   • Certifique-se de que as tabelas relacionadas aos anexos estejam incluídas:

     • annotation (para notas e anexos de arquivos)
     • attachment (para anexos email )
     • activitymimeattachment (para anexos de atividades)

   • Adicione as tabelas que faltam e aguarde a exportação.

2. Verifique as permissões do anexo:

   • Verifique se sua account do serviço Synapse Link tem permissão para ler registros de anexos.
   • Alguns anexos podem ser restritos por funções de segurança.
   • Ajuste as permissões, se necessário.

3. Entenda a limitação de metadados:

   • O conector do Dynamics 365 ingere metadados de anexos, não o conteúdo dos arquivos.
   • Para download arquivos, utilize a API Web do Dynamics 365 separadamente.
   • Consulte as limitações para obter detalhes.

4. Metadados de anexos da consulta:

   • Verifique se você está consultando os campos de anexo corretos:

     SQL

     SELECT
       annotationid,
       objectid,
       subject,
       filename,
       filesize,
       mimetype,
       documentbody  -- Usually NULL; binary content not ingested
     FROM main.d365_data.annotation;

Suporte adicional

Se você não conseguir resolver os problemas usando este guia:

1. Coletar diagnósticos:

   • ID do pipeline e registros de data e hora de execução.
   • Mensagens de erro completas dos logs pipeline .
   • logs e status Azure Synapse Link.
   • Capturas de tela de mensagens de erro ou configurações.

2. Verifique se há problemas conhecidos:

   • Analise as limitações para problemas conhecidos.
   • Verifique as notas sobre a versão Databricks para atualizações recentes.

3. Criar um ticket de suporte:

   • Na sua workspace, acesse Ajuda > Contatar o suporte .
   • Selecione Suporte Técnico e forneça as seguintes informações:
     • Descrição clara do problema.
     • os passos para reproduzir o problema.
     • Toda a informação de diagnóstico recolhida acima.
     • Impacto e urgência da questão.

4. Forneça seu feedback:

   • Para a versão Beta, compartilhe seu feedback com a equipe da sua account Databricks .
   • Reporte erros, solicitações de recursos ou problemas de documentação.

O Synapse Link está configurado, mas não estou vendo os arquivos.

Primeiro, confirme se os arquivos estão gravados em formato CSV usando o Synapse Link (e não em Parquet). Para isso, desmarque a caixa de seleção " Conectar-se ao seu espaço de trabalho Azure Synapse Analytics ao criar o link para o Azure Synapse Link.

Erro de credenciais/login

Experimente os seguintes scripts de depuração:

Confirme se o ID do cliente e o segredo do cliente estão funcionando corretamente:

Python

%pip install azure-storage-blob azure-identity azure-storage-file-datalake
%restart_python

# Required libraries
from azure.identity import ClientSecretCredential
from azure.storage.blob import BlobServiceClient


# --- Your Azure Credentials and Storage Details ---
# Replace the placeholder values with your actual information


# Entra ID (Azure Active Directory) details
tenant_id = "<tenant-id>"
client_id = "<client-id>"
client_secret = "<client-secret>"


# Azure Storage details
storage_account_name = "<storage-account>"
container_name = "<container-name>"


# --- Script to List Folders ---


# Construct the Blob Storage URL
storage_account_url = f"https://{storage_account_name}.blob.core.windows.net"


# 1. Authenticate using the service principal
# The ClientSecretCredential object will handle the OAuth 2.0 flow
try:
   credential = ClientSecretCredential(tenant_id, client_id, client_secret)
except Exception as e:
   print(f"Error creating credential: {e}")
   # You may want to stop execution if credentials are not valid
   dbutils.notebook.exit("Failed to create credentials")


# 2. Create a BlobServiceClient
# This client is the main entry point for interacting with the Blob service
try:
   blob_service_client = BlobServiceClient(account_url=storage_account_url, credential=credential)
except Exception as e:
   print(f"Error creating BlobServiceClient: {e}")
   dbutils.notebook.exit("Failed to create BlobServiceClient")


# 3. Get a client for the specific container
try:
   container_client = blob_service_client.get_container_client(container_name)
except Exception as e:
   print(f"Error getting container client for '{container_name}': {e}")
   dbutils.notebook.exit("Failed to get container client")


# 4. List the "folders" in the container
# Folders in Blob Storage are virtual and are represented by prefixes in blob names.
# This code iterates through the blobs and extracts the top-level directory names.
try:
   blob_list = container_client.list_blobs()
   folder_list = set()


   for blob in blob_list:
       if "/" in blob.name:
           folder_name = blob.name.split('/')[0]
           folder_list.add(folder_name)


   # Print the list of unique folder names
   if folder_list:
       print(f"Folders found in container '{container_name}':")
       for folder in sorted(list(folder_list)):
           print(folder)
   else:
       print(f"No folders found in container '{container_name}'.")


except Exception as e:
   print(f"An error occurred while listing blobs: {e}")

Confirme se a conexão com o Unity Catalog consegue enviar o access token:

Python

import requests
import json
import os


# --- Databricks Notebook Context and API Token Retrieval ---
# This section securely retrieves the necessary API token from your Databricks environment
# to interact with Unity Catalog.
notebook_context = dbutils.notebook.entry_point.getDbutils().notebook().getContext()
WORKSPACE_URL = notebook_context.apiUrl().get()
API_TOKEN = notebook_context.apiToken().get()
# --- Unity Catalog Connection Configuration ---
# IMPORTANT: Replace with the name of your Unity Catalog external connection to ADLS Gen2.
# This connection must be configured in Unity Catalog and granted necessary permissions
# to access your Azure Data Lake Storage Gen2 account.
# Example: CONNECTION_NAME = "my_adls_gen2_connection"
CONNECTION_NAME = "<uc-connection-name>"
def get_uc_connection_access_token(connection_name: str, api_token: str) -> str:
   """
   Retrieves the access token for a Unity Catalog external connection to ADLS Gen2.
   """
   url = f"{WORKSPACE_URL}/api/2.1/unity-catalog/foreign-credentials"
   body = '{{"securables": [{{"type": "CONNECTION", "full_name": "{}"}}]}}'.format(
       connection_name
   )
   headers = {
       "Authorization": "Bearer {}".format(api_token),
       "Content-Type": "application/json",
   }
   response = requests.post(url=url, headers=headers, data=body)
   response.raise_for_status() # Raise an exception for HTTP errors (e.g., 401, 403, 404)

   print(response.json())


   credentials = response.json()["securable_to_credentials"][0]["credentials"]["foreign_credential"]["options"]["options"]
   access_token = credentials["access_token"]
   return access_token
 print(get_uc_connection_access_token(CONNECTION_NAME, API_TOKEN))


Verify we are able to list container contents using UC connection

import requests
import json
import os
from datetime import datetime, timedelta
from azure.core.credentials import AccessToken, TokenCredential
from azure.storage.filedatalake import DataLakeServiceClient


notebook_context = dbutils.notebook.entry_point.getDbutils().notebook().getContext()
WORKSPACE_URL = notebook_context.apiUrl().get()
API_TOKEN = notebook_context.apiToken().get()


CONNECTION_NAME = "<uc-connection-name>"
storage_account_name = "<storage-account-name>"
container_name = "<container-name>"
# --- Custom Credential Object for Azure SDK ---
class StaticTokenCredential(TokenCredential):
   """
   A simple credential class to wrap an existing access token for Azure SDKs.
   The expiration is set arbitrarily for the SDK's internal logic;
   your token's real expiry is governed by its issuer.
   """
   def __init__(self, token: str):
       self._token = AccessToken(token, expires_on=(datetime.now() + timedelta(hours=1)).timestamp())
   def get_token(self, *scopes, **kwargs) -> AccessToken:
       return self._token
# ==================== Main Logic to List Top-Level Folders ====================
try:
   # --- Input Validation ---
   if CONNECTION_NAME == "<YOUR_UNITY_CATALOG_CONNECTION_NAME>":
       raise ValueError("Please update 'CONNECTION_NAME' with the name of your Unity Catalog connection.")
   if storage_account_name == "<YOUR_STORAGE_ACCOUNT_NAME>":
       raise ValueError("Please update 'storage_account_name' with your Azure Storage Account Name.")
   if container_name == "<YOUR_CONTAINER_NAME>":
       raise ValueError("Please update 'container_name' with your ADLS Gen2 Container Name.")
   print(f"Retrieving access token from Unity Catalog connection: '{CONNECTION_NAME}'...")
   access_token_string = get_uc_connection_access_token(CONNECTION_NAME, API_TOKEN)
   print("Access token retrieved successfully.")
   # 1. Initialize the DataLakeServiceClient using the retrieved token
   account_url = f"https://{storage_account_name}.dfs.core.windows.net"
   credential = StaticTokenCredential(access_token_string)
   datalake_service_client = DataLakeServiceClient(account_url=account_url, credential=credential)
   file_system_client = datalake_service_client.get_file_system_client(file_system=container_name)

   print(f"\nSuccessfully connected to ADLS Gen2 container: '{container_name}' in storage account: '{storage_account_name}'.")

   # 2. Get and print only the top-level directories
   print("\n--- Listing Top-Level Folders ---")

   all_paths = file_system_client.get_paths(path="/")


   for path in all_paths:
     print(path.name)
except Exception as e:
   print(f"An unexpected error occurred during execution.")
   print(f"Error details: {e}")

Erro: The selected storage account has restricted network access...

The selected storage account has restricted network access. To proceed, please setup an enterprise policy and connect it to your Dataverse environment. Once done, please enable the 'Select Enterprise Policy with Managed Service Identity' option below.

Isso pode acontecer quando o local de preparação do ADLS está protegido por um firewall e o Dataverse não consegue acessá-lo. Siga as instruções em "Usar identidades gerenciais para Azure com o armazenamento do seu data lake Azure " na documentação Microsoft para configurar uma identidade gerencial (anteriormente identidade gerencial de serviço) para acessar seus dados.

Erro: FILE_PATH_DOES_NOT_EXIST

Isso geralmente acontece quando a opção "Ativar atualização incremental da estrutura de pastas" não foi ativada durante a configuração do Synapse Link. Como resultado, o conector não encontra o arquivo onde esperava.