Microsoft 365 (SharePoint)

O conector Microsoft 365 lê os arquivos das bibliotecas de documentos dos sites do SharePoint que você seleciona, extrai o texto de cada um e envia os documentos para o Knowledge. Cada documento carrega a lista de pessoas e grupos que podem abri-lo no SharePoint.

​

Capacidades

• Knowledge. O texto de arquivos PDF, Word (.docx), CSV e Markdown é enviado como documento, com nome, caminho (site, biblioteca e pastas) e link para abrir o arquivo no SharePoint.
• Permissão da fonte. A permissão de cada arquivo é lida no SharePoint e guardada junto com o documento. No modo “Espelhar a fonte”, cada pessoa encontra nas buscas só os arquivos que ela pode abrir.
• Todas as bibliotecas do site. De cada site selecionado, o conector lê todas as bibliotecas de documentos, não só a padrão.

O conector não alimenta o Data Catalog nem o Memory: os arquivos vão só para o Knowledge.

​

Recursos disponíveis

Cada biblioteca tem o próprio cursor. Uma biblioteca nova é lida inteira.

​

Permissões (ACL)

O conector lê a permissão de cada item na fonte e a guarda junto com o dado. Em Comportamento dos dados, você escolhe entre dois modos: No modo “Espelhar a fonte”, marque Exigir login na fonte como prova de identidade. O Microsoft 365 identifica cada pessoa por um id próprio, não pelo e-mail, então a Strattum só reconhece quem se autenticou no Microsoft 365.

​

Como a fonte define acesso

No SharePoint, cada arquivo tem a própria lista de acesso. Ela reúne o que foi concedido direto no arquivo e o que ele herda da pasta, da biblioteca e do site. Uma concessão pode ser a uma pessoa, a um grupo do Microsoft Entra, a um grupo do SharePoint do site ou a um link de compartilhamento.

​

Como a Strattum traduz o acesso

Para cada arquivo, o conector lê a lista de acesso no Microsoft Graph e grava os leitores assim: A regra é tudo ou nada por arquivo. Se uma única concessão não pode ser traduzida, a lista inteira é descartada. Por exemplo: um relatório compartilhado com três pessoas e também com um link de compartilhamento fica sem leitor. Os membros de cada grupo do Entra são lidos à parte, no Microsoft Graph, com a mesma App Registration. Grupos dentro de grupos entram na lista. Assim, quem está num grupo com acesso ao arquivo encontra o arquivo, desde que tenha vinculado a conta. No vínculo de conta, o login acontece no endereço do tenant da conexão. A conta precisa existir no diretório desse tenant, convidados incluídos.

​

Quando a identidade não é encontrada

No modo “Espelhar a fonte”, quem não casa com nenhum leitor do arquivo não o encontra nas buscas. Isso acontece quando a pessoa não vinculou a conta Microsoft. Também acontece quando o acesso dela vem de um grupo cujos membros não puderam ser lidos. Um único grupo que falha na leitura, por exemplo porque falta a permissão GroupMember.ReadBasic.All, faz a Strattum manter a lista de membros anterior de todos os grupos da conexão naquela rodada. Um arquivo sem nenhum leitor não é indexado no modo “Espelhar a fonte”. Ele aparece como não indexado, com o motivo “Permissões não puderam ser resolvidas com segurança”. No modo “Aberto”, o arquivo é indexado mesmo sem leitores.

​

Quando a permissão é atualizada

A lista de acesso é lida no mesmo sync em que o arquivo é lido, com uma chamada ao Graph por arquivo. Numa sincronização incremental, o conector só relê arquivos cuja data de modificação (lastModifiedDateTime) mudou desde a última execução. Se o compartilhamento muda e a data de modificação não, o documento mantém a permissão antiga até o arquivo ser editado ou até a próxima verificação completa. Se a leitura da permissão de um arquivo falha no modo “Espelhar a fonte”, a biblioteca não avança a data de corte e o arquivo é tentado de novo na execução seguinte. Os membros dos grupos são relidos por uma rotina própria, a cada 10 minutos por padrão.

​

Pré-requisitos

• Um tenant Microsoft 365 com sites do SharePoint.
• Uma App Registration no Microsoft Entra (antigo Azure AD) com as permissões de aplicação Sites.Read.All e Files.Read.All do Microsoft Graph, com consentimento de administrador.
• O Tenant ID, o Client ID e um Client Secret dessa App Registration.
• Para o modo “Espelhar a fonte” com grupos: a permissão de aplicação GroupMember.ReadBasic.All, ou uma superior, na mesma App Registration.
• Para exigir login na fonte: um aplicativo do Entra ID com a permissão delegada User.Read, de onde saem o Client ID e o Client Secret do login. Eles são informados à parte da credencial da conexão.
• No Console, permissão para editar conectores e, para definir o acesso, permissão em configurações de ACL.

​

Autenticação e escopos

O conector age como a própria aplicação, sem um usuário. Ele pede um token ao Microsoft Entra pelo fluxo client credentials, com o escopo https://graph.microsoft.com/.default, então vale o que o administrador consentiu na App Registration. Permissões delegadas não servem para a conexão.

​

Configuração no Console

​

Como a sincronização funciona

O agendamento recomendado roda a cada 6 horas. A cada execução, o conector abre cada site selecionado, lista as bibliotecas dele e percorre as pastas, 200 itens por página, até o 10º nível de subpastas. Uma execução tem o limite de 2 horas. Leitura. A primeira execução lê todas as bibliotecas dos sites selecionados. As seguintes leem só os arquivos com data de modificação no SharePoint (lastModifiedDateTime) posterior à última execução de cada biblioteca. As pastas são sempre percorridas, porque a data de uma pasta não muda quando um arquivo dentro dela muda. Só a versão atual de cada arquivo é lida. Cada arquivo. O documento é identificado pelo ID da biblioteca e do arquivo no SharePoint, e não pelo nome. Um arquivo editado e salvo mantém o ID, e o Knowledge troca o conteúdo antigo pelo novo, sem duplicar. Um arquivo apagado e enviado de novo, mesmo com o mesmo nome, ganha outro ID e entra como documento novo. Um arquivo fica fora do Knowledge quando:

• o formato não é suportado;
• tem mais de 50 MB;
• é um arquivo vazio, ou não tem texto, como um PDF escaneado;
• o download ou a leitura do texto falhou, como num PDF protegido por senha;
• no modo “Espelhar a fonte”, a permissão não pôde ser traduzida (veja “Permissões”).

A data de corte de uma biblioteca só avança quando a execução leu a biblioteca inteira, sem erro de pasta, de download, de leitura ou de permissão. Com erro, a execução seguinte lê a mesma janela de novo. Um arquivo grande demais não segura a data de corte, porque ele continuaria grande na próxima vez. Arquivos removidos. A sincronização incremental não remove documentos. Uma vez por dia, na Janela de manutenção (padrão 03:00 no fuso configurado no servidor, ou UTC), o conector faz uma verificação completa: lê todos os sites selecionados e remove do Knowledge os arquivos que não existem mais no SharePoint. O mesmo vale para os arquivos de um site que você tira da seleção. Se algum site ou biblioteca falha nessa leitura, ou se há pastas além do 10º nível, nada é removido naquele dia. O horário é ajustado em Editar > Sincronização > Janela de manutenção. Casos e prazos de cada mudança estão em Atualização e remoção de documentos.

​

API da fonte

O conector usa o Microsoft Graph v1.0. A autenticação passa pelo Microsoft Entra, com a biblioteca MSAL. Rate limits. Limite da API: o SharePoint e o OneDrive medem o uso do Graph em unidades de recurso, por aplicativo e por tenant. Baixar um arquivo custa 1 unidade, listar uma pasta custa 2 e toda chamada de permissões custa 5. Por arquivo, o conector faz um download e uma leitura de permissões. Estourar o limite devolve 429 ou 503 com o cabeçalho Retry-After. Os valores padrão dependem do número de licenças do tenant e a Microsoft pode mudá-los (documentação): Comportamento do conector: as chamadas são feitas uma de cada vez. Ao receber 429 ou 503, o conector espera o tempo do cabeçalho Retry-After, até 60 segundos. Sem o cabeçalho, espera 2 segundos e dobra a cada tentativa, também até 60. Depois de 5 repetições, a falha segue para o item: uma pasta que não lista é pulada, um arquivo que não baixa fica de fora e uma permissão que não lê deixa o arquivo sem leitor. Nos três casos, a biblioteca não avança a data de corte (no modo “Aberto”, a permissão não lida não a segura). Outros erros HTTP, como 401 e 403, não são repetidos. Se a extração falha por inteiro, a plataforma a refaz até 3 vezes, depois de 1, 2 e 4 minutos. Referência oficial: https://learn.microsoft.com/en-us/graph/api/resources/driveitem

​

Limitações conhecidas

• Só entram arquivos PDF, Word (.docx), CSV e Markdown. Excel, PowerPoint, o formato Word antigo (.doc), imagens e outros tipos são ignorados, sem aviso e sem aparecer na lista de documentos ignorados.
• Arquivos com mais de 50 MB não são lidos.
• PDF escaneado (só imagem) não tem texto extraído, porque não há OCR. PDF protegido por senha ou corrompido não é lido.
• Em arquivos Word, cabeçalhos e rodapés não são extraídos.
• Arquivo vazio (0 bytes) é ignorado.
• O histórico de versões do SharePoint não é indexado. Só a versão atual de cada arquivo entra no Knowledge.
• Arquivo apagado no SharePoint continua no Knowledge até a próxima verificação completa da Janela de manutenção.
• Uma mudança de permissão que não altera a data de modificação do arquivo só chega ao Knowledge na próxima verificação completa.
• No modo “Espelhar a fonte”, um arquivo com concessão a um grupo do SharePoint do site, a um link de compartilhamento ou a um aplicativo não é indexado. No modo “Aberto”, ele é indexado.
• No modo “Espelhar a fonte”, quem não vinculou a conta Microsoft não encontra nenhum arquivo. A Strattum não deduz a pessoa pelo e-mail.
• Se a leitura dos membros de um único grupo do Entra falha, nenhuma lista de membros é atualizada naquela rodada.
• Os campos de filtro de pastas e de profundidade não existem no Console. Subpastas além do 10º nível não são lidas.
• Uma biblioteca informada por ID aparece com o caminho começando em OneDrive, sem o nome do site.
• A lista de sites do Console não inclui os sites pessoais do OneDrive. Um OneDrive só entra pelo campo IDs de bibliotecas.
• A conexão usa permissões de aplicação. Permissões delegadas, por usuário, não são o fluxo suportado.
• O client secret expira. Quando isso acontece, a sincronização falha até você gerar outro segredo e informá-lo em Editar > Conexão, junto com o Tenant ID e o Client ID.

​

Troubleshooting

​

Próximos passos

Desenvolvimento local

No ambiente local, as credenciais do conector são cadastradas pelo Console (veja Desenvolvimento local). O segredo fica no cofre de credenciais da instância, e não no .env.A sincronização lê estas chaves de credencial do conector:

Chave	Descrição	Exemplo
M365_TENANT_ID	GUID ou domínio do tenant	contoso.onmicrosoft.com
M365_CLIENT_ID	Application (client) ID da App Registration	00000000-0000-0000-0000-000000000000
M365_CLIENT_SECRET	Value do client secret
M365_SELECTED_SITES	IDs ou hostnames dos sites, em lista JSON ou separados por vírgula	["contoso.sharepoint.com:/sites/intranet"]
M365_SELECTED_DRIVES	IDs de bibliotecas ou unidades	["b!abc..."]
M365_INCLUDE_FOLDERS	Prefixos de pasta a incluir, no formato Site/Biblioteca/pasta. Vazio inclui tudo	["Intranet/Documents/contratos"]
M365_EXCLUDE_FOLDERS	Prefixos de pasta a excluir, no mesmo formato. Vazio não exclui nada	["Intranet/Documents/arquivo-morto"]
M365_MAX_DEPTH	Níveis máximos de subpastas. O padrão é 10	10

O Console não preenche M365_INCLUDE_FOLDERS, M365_EXCLUDE_FOLDERS nem M365_MAX_DEPTH. Quem executa a classe do conector direto, fora do Console, pode passá-los a authenticate() como include_folders, exclude_folders e max_depth.