Capacidades
- Descobre os schemas, as tabelas e as colunas do Lakehouse e publica tudo no Data Catalog. Você escolhe lá quais tabelas a plataforma expõe.
- Lê as linhas no OneLake a cada consulta, com as credenciais do aplicativo. Nada é gravado no lake da Strattum, e nenhum SQL endpoint, warehouse ou Spark do Fabric é acionado.
- Expõe cada tabela selecionada na consulta SQL governada (
run_sql) comofed__fabric__{schema}__{table}, já filtrada pela permissão. - Alimenta o grafo do Memory quando a ontologia mapeia uma tabela como fonte
fed/fabric__{schema}__{table}. O Memory lê só as linhas novas pela coluna de watermark. - Lê os papéis do workspace e as roles de segurança do OneLake e grava em cada tabela a lista de quem pode lê-la.
Recursos disponíveis
Os recursos são dinâmicos: existem depois que o conector descobre as tabelas do seu Lakehouse. Cada tabela vira um recurso com o nome{schema}__{table}. Num Lakehouse sem schemas, as tabelas aparecem sob o schema dbo.
O conector ignora o schema
information_schema. Ele também deixa de fora:
- Tabelas cujo schema ou nome contém
__, porque o separador do nome do recurso ficaria ambíguo. - Tabelas que geram o mesmo nome de recurso sem diferenciar maiúsculas, como
Pedidosepedidos. Todas as envolvidas saem. - Tabelas cujo local de armazenamento não é a pasta da própria tabela no Lakehouse configurado.
Permissões (ACL)
Os dados não são copiados. A permissão é lida na fonte a cada consulta e aplicada ao resultado. Em Comportamento dos dados, o padrão é “Espelhar a fonte”: cada pessoa vê apenas o que a própria fonte libera para ela. No modo “Aberto”, quem puder usar o conector vê todo o resultado. Esse padrão vale quando nenhuma escolha foi salva para o conector. O assistente do Console começa com “Aberto” marcado, então o modo que vale é o que estiver selecionado ao salvar. No Fabric, a consulta lê as linhas na origem e aplica a lista de acesso que a execução de metadados gravou em cada tabela. Essa lista é relida a cada execução, de 10 em 10 minutos por padrão. No modo “Espelhar a fonte”, marque Exigir login na fonte como prova de identidade. O Microsoft Entra identifica cada pessoa por um ID interno (um GUID), e a Strattum só liga esse ID a uma pessoa depois que ela vincula a conta Microsoft.Como a fonte define acesso
No Fabric, os papéis de workspaceAdmin, Member e Contributor leem todos os dados do Lakehouse. O papel Viewer não lê dados sozinho. Ele precisa de uma role de segurança do OneLake, que concede leitura de tabelas, schemas ou pastas a usuários e grupos do Entra ID.
Como a Strattum traduz o acesso
A cada execução de metadados, o conector lê uma vez as atribuições de papel do workspace e uma vez as roles de segurança do Lakehouse. Com elas, grava em cada tabela selecionada a lista de quem pode lê-la:- Usuários e grupos com papel
Admin,MemberouContributorentram na lista de todas as tabelas. - Cada role do OneLake com leitura entra na lista das tabelas cuja pasta o caminho dela cobre. Valem
*,Tables/*,Tables,Tables/{schema},Tables/{schema}/*e o caminho da própria tabela. - Um caminho sem curinga cobre tudo o que está abaixo dele, comparando pasta por pasta:
Tables/dbocobreTables/dbo/clientese não cobreTables/dbo2. Um caminho emFiles/nunca cobre uma tabela. - Um usuário vira
user:{conector}:{object id}e um grupo viragroup:{conector}:{object id}, com o object id do Entra ID. Quando a role não informa se o membro é usuário ou grupo, o conector pergunta ao Microsoft Graph. - Um papel atribuído ao tenant inteiro (
EntireTenant) libera a tabela para todos que podem usar o conector. - Os membros de cada grupo, inclusive de grupos aninhados, são lidos no Microsoft Graph.
Quando a identidade não é encontrada
No modo “Espelhar a fonte”, a tabela não aparece para quem não vinculou a conta Microsoft, nem para quem não está na lista dela. Uma tabela com a lista vazia não aparece para ninguém. Se a permissão de uma tabela nunca foi lida com sucesso, a tabela fica oculta até a próxima leitura dar certo. Ela nunca fica aberta por falta de leitura.Quando a permissão é atualizada
A permissão é lida na mesma execução que atualiza os metadados, de 10 em 10 minutos por padrão. Uma mudança de papel ou de role no Fabric vale a partir da execução seguinte, mesmo que nenhuma linha da tabela mude. Se a leitura das permissões falha, o conector mantém a última lista lida com sucesso por até 24 horas, contadas a partir dessa leitura. Depois disso, a tabela fica oculta até uma leitura dar certo. Desde a primeira falha, a execução termina com um aviso que diz quanto tempo falta. A associação entre os grupos do Entra ID e as pessoas da Strattum é atualizada num passo à parte, de 10 em 10 minutos e depois de cada execução do conector.Pré-requisitos
- Um Lakehouse do Microsoft Fabric numa capacidade ativa. Com a capacidade pausada, o OneLake recusa todas as leituras.
- Um aplicativo registrado no Microsoft Entra ID, com um client secret.
- Esse aplicativo com o papel Membro (
Member) no workspace do Lakehouse. A leitura dos papéis do workspace exigeMemberou superior. - Duas configurações de tenant do Fabric habilitadas: Service principals can call Fabric public APIs e Users can access data stored in OneLake with apps external to Fabric.
- Permissões de aplicação do Microsoft Graph
GroupMember.Read.AlleDirectory.Read.All, com consentimento do administrador. - Para que cada pessoa veja só o que o Fabric libera para ela: um aplicativo do Entra ID para o login, com redirect URI do tipo Web e a permissão delegada
User.Read.
Autenticação e escopos
O conector usa o fluxo client credentials do Entra ID com um único tenant. Os valorescommon, organizations e consumers são recusados. O ID do workspace e o ID do Lakehouse precisam ser GUIDs.
1
Registre o aplicativo no Entra ID
Crie o registro do aplicativo e gere um client secret. Anote o ID do tenant, o Client ID, o valor do segredo e a data de validade dele. Copie o Valor do segredo, que é diferente do ID do segredo.
2
Conceda as permissões do Graph
Em Permissões de API, adicione as permissões de aplicação
GroupMember.Read.All e Directory.Read.All do Microsoft Graph e conceda o consentimento do administrador.3
Habilite as configurações do tenant no Fabric
Em OneLake catalog > Govern > Configurations > Tenant settings, habilite Service principals can call Fabric public APIs e Users can access data stored in OneLake with apps external to Fabric. Se a primeira estiver liberada só para grupos de segurança, inclua o aplicativo num desses grupos.
4
Adicione o aplicativo ao workspace
No workspace do Lakehouse, adicione o aplicativo com o papel Membro (
Member).5
Copie os IDs do workspace e do Lakehouse
Abra o Lakehouse no portal do Fabric. Na URL, o GUID depois de
/groups/ é o ID do workspace e o GUID depois de /lakehouses/ é o ID do Lakehouse.6
Prepare o login de cada pessoa
Este passo só é necessário para “Espelhar a fonte”. No aplicativo que fará o login, vá em Authentication e adicione um redirect URI do tipo Web com o endereço público do serviço de identidade da sua instalação seguido de
/v1/links/callback. Adicione a permissão delegada User.Read do Microsoft Graph. O Client ID e um client secret desse aplicativo entram no passo Permissionamento do Console.Configuração no Console
1
Abra o assistente
No menu lateral, clique em Conectores, depois em Nova Conexão e selecione Microsoft Fabric.
2
Conexão
Nome do Conector (Opcional): padrão
Microsoft Fabric.Tenant (Directory ID) (Obrigatório): o GUID ou o domínio do tenant do Entra ID.Client ID (Obrigatório): o ID do aplicativo registrado, que precisa ser Membro do workspace.Client secret (Obrigatório): o valor do segredo gerado no aplicativo.ID do workspace (Obrigatório): o GUID do workspace.ID do Lakehouse (Obrigatório): o GUID do Lakehouse.Validade do client secret (opcional) (Opcional): a data em que o segredo expira. A Strattum avisa quando faltam 14 dias ou menos e quando a data passa.Clique em Testar Conexão. O teste obtém o token, lista os schemas, lê uma tabela do primeiro schema e depois tenta ler os papéis do workspace. O resultado aparece em uma de três cores:- Vermelho: os dados não podem ser lidos. O assistente não avança.
- Amarelo: o aplicativo lê os dados, mas não lê os papéis do workspace, ou o segredo está perto de vencer ou já venceu.
- Verde: tudo foi lido.
3
Sincronização
Frequência de Sincronização (Obrigatório): de quanto em quanto tempo o conector relê tabelas, colunas e permissões. A recomendada é a cada 10 minutos. As consultas sempre leem os dados na origem, qualquer que seja a frequência. Veja Frequência de sync.
4
Permissionamento
Quem pode usar este conector (Obrigatório): “Todos os usuários” ou “Apenas times específicos”. Times com acesso (Quando selecionado): os times liberados, obrigatório com “Apenas times específicos”.Comportamento dos dados (Obrigatório): “Aberto” ou “Espelhar a fonte”. O assistente abre com “Aberto” marcado, e é esse o modo que fica salvo se você não mudar. “Aberto” mostra todas as tabelas a quem pode usar o conector. Escolha “Espelhar a fonte” para que cada pessoa veja só as tabelas que o Fabric libera para ela.Exigir login na fonte como prova de identidade (Opcional, só em “Espelhar a fonte”): marcada, pede os dados do aplicativo de login.URL de autenticação (Opcional): em branco, a Strattum monta
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize com o tenant da conexão.Client ID e Client Secret (Quando selecionado): os do aplicativo de login. Na edição, deixar em branco mantém os valores salvos.Escopos (Opcional): em branco, vale openid profile User.Read.5
Revisão
Revise e salve. Depois, escolha no Data Catalog quais tabelas expor. Sem nenhuma seleção salva, todas as tabelas descobertas ficam disponíveis.
Como a sincronização funciona
O conector não copia linhas. Ele trabalha em dois ritmos:
Cada execução de metadados segue estes passos:
- Lê as credenciais cadastradas no Console. Não existe credencial por variável de ambiente.
- Avisa se a validade informada para o client secret passou ou está a 14 dias ou menos.
- Descobre o Lakehouse na API Delta do OneLake: schemas, depois tabelas, depois colunas, seguindo a paginação.
- Aplica a seleção feita no Data Catalog.
- Lê as permissões e grava a lista de acesso de cada tabela selecionada.
- Publica o resultado e avisa o Memory, mas só quando a ontologia aplicada mapeia alguma tabela do Fabric.
TIMESTAMP reconhecida ou escolhida, a tabela é lida inteira a cada leitura. Você ajusta a coluna e o campo Avança por no card Configuração da sincronização da tabela, no Data Catalog. O padrão de Avança por é “Tempo de execução”.
O que acontece quando algo some ou falha na fonte:
- Uma linha apagada no Lakehouse some das consultas na hora, porque elas leem a origem. No grafo, a verificação de remoções compara as chaves da tabela com as do grafo a cada 6 horas por padrão. Em tabelas com mais de 1.000.000 de linhas, essa verificação não roda por padrão.
- Uma tabela selecionada que sai do Lakehouse, ou muda de nome, deixa de ser publicada. A execução avisa enquanto ela continuar selecionada.
- Uma tabela cuja descrição falha numa execução mantém os dados da execução anterior. Se não houver execução anterior, ela fica de fora até a próxima.
- Se a descoberta não encontra nenhuma tabela e a execução anterior tinha tabelas, nada é publicado e o estado anterior fica. Isso costuma indicar papel removido ou capacidade pausada.
API da fonte
Rate limits. Limite da API: a API REST do Fabric aplica uma cota por identidade, numa janela fixa de 60 segundos. Para as APIs de plataforma, a cota é de 500 chamadas por minuto, e algumas APIs têm limites próprios. Acima dela, o Fabric responde 429 com o cabeçalho
Retry-After. O Microsoft Graph também responde 429 com Retry-After, com limites que variam por cenário. A Microsoft não publica um limite numérico para a API Delta do OneLake. Cada leitura no OneLake consome unidades de capacidade (CU) da capacidade do Fabric.
Comportamento do conector: na API Delta do OneLake, ele pede 100 itens por página e usa timeout de 30 segundos por chamada. Diante de um 429, espera o Retry-After (até 60 segundos, ou 1 segundo sem o cabeçalho) e faz até 3 tentativas. Se a descoberta falha, a execução a repete duas vezes, após 15 e 60 segundos. Na API REST do Fabric e no getByIds, faz até 3 tentativas, esperando o Retry-After (até 60 segundos, ou 5 sem o cabeçalho). As duas listas de permissão são lidas uma vez por execução, e os tokens ficam em cache até 2 minutos antes de expirar. Na leitura de membros de grupo, o Graph é chamado de novo até 5 vezes após um 429 ou 503, respeitando o Retry-After.
Referência oficial: Throttling nas APIs REST do Fabric, Throttling no Microsoft Graph, API Delta do OneLake e Segurança de dados do OneLake.
Limitações conhecidas
- Cada ambiente aceita um conector Fabric, e cada conector lê um Lakehouse. Itens Warehouse e vários Lakehouses no mesmo ambiente não fazem parte desta versão.
- O workspace e o Lakehouse não mudam depois da criação. Para trocar a fonte, remova o conector e crie outro.
- Com a capacidade do Fabric pausada, o OneLake recusa todas as leituras. As consultas falham, o Data Catalog mostra que a origem não pôde ser lida e a execução de metadados falha ou mantém o estado anterior, até a capacidade voltar.
- No modo “Espelhar a fonte”, só vê os dados quem vinculou a conta Microsoft. Sem Exigir login na fonte como prova de identidade, ninguém vê. O vínculo aceita só contas do tenant configurado.
- Uma role do OneLake com segurança de linha ou de coluna numa tabela não libera essa tabela para os membros dela, porque a plataforma ainda não aplica essas restrições. Os papéis
Admin,MembereContributornão são afetados. - Service principals, identidades gerenciadas e membros por permissão de item (
fabricItemMembers) não são mapeados. Isso inclui quem lê o Lakehouse pela roleDefaultReader, que libera quem tem a permissãoReadAll. - Um usuário com o papel
Viewersó vê uma tabela se uma role do OneLake a conceder a ele ou a um grupo dele. - Uma mudança de permissão no Fabric só vale na execução de metadados seguinte, até 10 minutos depois no padrão.
- A amostra de linhas do Data Catalog não passa pela lista de acesso da tabela. Ela depende só da permissão de leitura do catálogo no Console.
- Tabelas com
__no schema ou no nome, tabelas cujo nome coincide com outro sem diferenciar maiúsculas e tabelas com ponto no schema ou no nome não são publicadas. - Num Lakehouse sem schemas, o OneLake guarda as tabelas em
Tables/{table}. Se a API não informar o local de uma tabela, o conector assumeTables/dbo/{table}, que está errado nesse caso, e registra um aviso. - Uma tabela cujo local de armazenamento fica fora da pasta dela no Lakehouse configurado, como um atalho para outro armazenamento, não é lida.
- Só uma coluna
TIMESTAMPserve de watermark. Uma colunaTIMESTAMP_NTZnão serve, e o grafo relê a tabela inteira. - Colunas cujo nome começa com
acl_ficam ocultas nas consultas, porque esse prefixo é reservado da plataforma. - No grafo, a verificação de remoções não roda por padrão em tabelas com mais de 1.000.000 de linhas.
- O client secret do Entra expira e não se renova sozinho. Informe a validade na conexão e troque o segredo antes da data.
Troubleshooting
Próximos passos
Data Catalog
Escolha as tabelas do Lakehouse que a plataforma expõe.
Memory
Mapeie as tabelas na ontologia para alimentar o grafo.
Desenvolvimento local
Desenvolvimento local
O conector não lê credenciais de variáveis de ambiente: cadastre a conexão pelo Console. Três variáveis do Veja Desenvolvimento local.
.env mudam o comportamento de fontes federadas e do vínculo de conta.