Skip to main content
O conector Google Drive lê os arquivos das pastas do Drive que você configura, 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 Drive.

​
Capacidades

  • Knowledge. O texto de arquivos PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), CSV, Markdown e HTML é enviado como documento, com nome, caminho da pasta e link para abrir o arquivo no Drive.
  • Permissão da fonte. O compartilhamento de cada arquivo é lido no Drive e guardado junto com o documento. No modo “Espelhar a fonte”, cada pessoa encontra nas buscas só os arquivos que ela pode abrir no Drive.
  • Drives compartilhados. Pastas dentro de um drive compartilhado são lidas da mesma forma que pastas de um Meu Drive.
O conector não alimenta o Data Catalog nem o Memory: os arquivos vão só para o Knowledge.

​
Recursos disponíveis

​
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”, com Exigir login na fonte como prova de identidade marcado, cada usuário precisa vincular a própria conta de Google Drive antes de ver o conteúdo. Sem essa opção, a Strattum assume que a pessoa usa no Google o mesmo e-mail que usa na Strattum.

​
Como a fonte define acesso

No Google Drive, cada arquivo tem a própria lista de compartilhamento. Um arquivo pode ser compartilhado com uma pessoa, com um Grupo do Google, com todo um domínio do Google Workspace ou com qualquer pessoa que tenha o link.

​
Como a Strattum traduz o acesso

Para cada arquivo, o conector lê a lista de compartilhamento e grava os leitores assim: O domínio da sua empresa é o do Admin do Workspace impersonado. Sem esse campo, todo arquivo compartilhado com um domínio fica sem leitor. Os membros de cada grupo são lidos à parte, no Google Workspace, com o admin impersonado. Assim, quem está num grupo com acesso ao arquivo encontra o arquivo. A regra é tudo ou nada por arquivo. Se um único compartilhamento do arquivo não pode ser traduzido, a lista inteira é descartada e o arquivo não entra no Knowledge. Por exemplo: um relatório compartilhado com três pessoas e também com “qualquer pessoa com o link” não é indexado. No vínculo de conta, a pessoa entra com a conta Google. A Strattum confere que o e-mail é verificado e que a conta pertence ao mesmo domínio do Google Workspace do admin impersonado. Uma conta Gmail pessoal não vincula.

​
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 o e-mail da pessoa na Strattum é diferente do e-mail no Google e ela não vinculou a conta, ou quando os membros do grupo não puderam ser lidos. O arquivo continua visível para os outros leitores. Um arquivo sem nenhum leitor não é indexado em nenhum dos dois modos, inclusive em “Aberto”. Ele é registrado como não indexado, com o motivo “Permissões não puderam ser resolvidas com segurança”.

​
Quando a permissão é atualizada

A lista de compartilhamento é lida no mesmo sync em que o arquivo é lido. Numa sincronização incremental, o conector só relê arquivos cuja data de modificação no Drive 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 sincronização completa. Os membros dos grupos são relidos por uma rotina própria, a cada 10 minutos por padrão. Se um grupo não pode ser lido, a rotina não grava nada naquela rodada e mantém a última lista conhecida.

​
Pré-requisitos

  • Um projeto no Google Cloud com a Google Drive API habilitada.
  • Uma Service Account nesse projeto e uma chave JSON dela.
  • Acesso da Service Account às pastas, com papel Editor. Com papel Leitor, o Drive recusa a leitura do compartilhamento (403), e os arquivos da pasta não entram no Knowledge.
  • Para ler compartilhamentos com o domínio, os membros de grupos e o vínculo de conta: um administrador do Google Workspace para impersonar e um super administrador para autorizar a delegação em todo o domínio.
  • Para o modo “Espelhar a fonte” com vínculo de conta: um cliente OAuth do Google, de onde saem o Client ID e o Client Secret.

​
Autenticação e escopos

O conector se autentica com a chave JSON de uma Service Account. Todos os escopos são de leitura. Com o Admin do Workspace impersonado preenchido, todas as chamadas ao Drive são feitas em nome desse admin. Nesse caso, autorize os dois primeiros escopos na delegação em todo o domínio.
1

Habilite a Google Drive API

No Google Cloud Console, acesse APIs & Services > Library, pesquise Google Drive API e clique em Enable. Se você vai usar grupos, habilite também a Admin SDK API.
2

Crie a Service Account

Acesse IAM & Admin > Service Accounts e clique em Create Service Account. Dê um nome, como strattum-drive-reader. Não é preciso atribuir papéis do IAM.
3

Gere a chave JSON

Clique no e-mail da Service Account, abra a aba Keys, clique em Add key > Create new key, escolha JSON e clique em Create. O arquivo é baixado uma única vez. Se a criação for bloqueada pela política iam.disableServiceAccountKeyCreation, um administrador da organização no Google Cloud precisa liberar o projeto.
4

Compartilhe as pastas

No Google Drive, compartilhe cada pasta com o e-mail da Service Account (formato nome@projeto.iam.gserviceaccount.com), com papel Editor. Copie o ID de cada pasta: é o trecho da URL depois de folders/.
5

Autorize a delegação em todo o domínio

Opcional, para domínio, grupos e vínculo. No Admin Console do Google Workspace, como super administrador, acesse Security > Access and data control > API controls > Manage Domain Wide Delegation e clique em Add new. Informe o Client ID da Service Account e os escopos drive.readonly e admin.directory.group.member.readonly da tabela acima.

​
Configuração no Console

1

Preencha a conexão

Nome do Conector (Opcional): um nome para identificar esta instância.Service Account JSON (Obrigatório): cole o conteúdo do arquivo JSON ou clique em Carregar arquivo. O Console confere se o JSON é de uma Service Account.Admin do Workspace impersonado (opcional) (Opcional): o e-mail de um administrador do Google Workspace, como admin@suaempresa.com. Ele define o domínio da instância e é necessário para compartilhamentos com o domínio, membros de grupos e vínculo de conta.Clique em Testar Conexão. O Console só avança depois de um teste bem-sucedido. O teste confere a chave da Service Account. As pastas são conferidas na primeira sincronização.
2

Selecione as pastas

Pastas do Drive (Obrigatório): os IDs das pastas, separados por vírgula. As subpastas entram automaticamente. O Console aceita salvar sem pastas, mas a sincronização fica aguardando configuração até existir pelo menos uma.
3

Defina a frequência

Frequência de Sincronização (Obrigatório): o recomendado é A cada 6h (recomendado). Também há opções prontas, de 10 minutos a semanal, e Personalizado, para informar uma Expressão Cron. Os horários são em UTC.
4

Configure acesso e visibilidade

Quem pode usar este conector (Obrigatório): “Todos os usuários” ou “Apenas times específicos”. Na segunda opção, selecione os Times com acesso.Comportamento dos dados (Obrigatório): “Aberto” ou “Espelhar a fonte”.Exigir login na fonte como prova de identidade (Quando selecionado “Espelhar a fonte”): marque para que cada usuário vincule a conta Google.URL de autenticação, Client ID e Client Secret (Quando selecionado o login na fonte, obrigatórios): os dados do cliente OAuth. No Google, a URL é sempre https://accounts.google.com/o/oauth2/v2/auth.Escopos (Opcional): o conector pede openid email quando o campo fica vazio.

​
Como a sincronização funciona

O agendamento recomendado roda a cada 6 horas. A cada execução, o conector confere cada pasta configurada antes de ler. A sincronização para com erro se uma pasta não está acessível para a Service Account, está na lixeira, é um atalho ou é um arquivo, ou se todas as pastas estão vazias. Leitura. O conector percorre cada pasta e as subpastas, 100 itens por página. A primeira execução lê tudo. As seguintes leem só os arquivos com data de modificação no Drive (modifiedTime) posterior à última execução. Cada arquivo. O conector baixa o arquivo, extrai o texto e lê o compartilhamento. Um arquivo fica fora do Knowledge quando:
  • o formato não é suportado;
  • tem mais de 50 MB;
  • o texto não pôde ser extraído, como num PDF protegido por senha;
  • não tem texto, como num PDF escaneado;
  • o compartilhamento não pôde ser traduzido (veja “Permissões”).
Um arquivo que falhou por erro de download ou de leitura é tentado de novo nas próximas execuções, até 3 vezes. Depois disso, ele só volta a ser lido quando for modificado no Drive. Arquivos removidos. Arquivo apagado ou tirado das pastas só sai do Knowledge numa sincronização completa, em que todas as pastas são lidas de novo. Numa execução comum, ele permanece. Se alguma pasta falha durante uma sincronização completa, nada é removido naquela execução.

​
API da fonte

O conector usa a Google Drive API v3 pela biblioteca oficial do Google, e a Admin SDK Directory API para os membros de grupos. Rate limits. Limite da API: o Drive conta cotas em unidades, 1.000.000 por minuto por projeto e 325.000 por minuto por usuário. Uma listagem custa 100 unidades, uma leitura de metadados 5 e um download 200. Estourar a cota devolve 403 (“User rate limit exceeded”) ou 429 (documentação). Comportamento do conector: as chamadas são feitas uma de cada vez, e o conector não repete a chamada que recebe 403 ou 429. A falha interrompe a leitura, e a plataforma refaz a extração inteira até 3 vezes, depois de 1, 2 e 4 minutos. A leitura do compartilhamento que falha não é repetida: o arquivo fica sem leitor naquela execução e volta a ser tentado nas seguintes, até 3 vezes. Referência oficial: https://developers.google.com/workspace/drive/api/reference/rest/v3

​
Limitações conhecidas

  • Arquivos nativos do Google (Documentos, Planilhas e Apresentações Google) não são lidos. Só entram arquivos enviados ao Drive em PDF, Word, Excel, PowerPoint, CSV, Markdown ou HTML.
  • O formato Word antigo (.doc) não é suportado.
  • PDF escaneado (só imagem) não tem texto extraído, porque não há OCR.
  • PDF protegido por senha não é lido.
  • Em arquivos Word, cabeçalhos, rodapés e caixas de texto não são extraídos. Em PowerPoint, imagens e vídeos não são extraídos. Em Excel, fórmulas sem valor calculado salvo ficam vazias.
  • Arquivos com mais de 50 MB não são lidos.
  • Arquivo compartilhado com “qualquer pessoa com o link” ou com outro domínio não é indexado, mesmo que também esteja compartilhado com pessoas da empresa.
  • Se a Service Account só tem papel Leitor, o Drive não entrega o compartilhamento e os arquivos não são indexados. Para arquivos em Meu Drive, o papel Editor na pasta é o caminho suportado hoje.
  • Uma mudança de compartilhamento que não altera a data de modificação do arquivo no Drive só chega ao Knowledge quando o arquivo for editado ou na próxima sincronização completa.
  • Arquivo apagado no Drive continua no Knowledge até uma sincronização completa.
  • Pelo Console, a seleção é só por pasta. Não há como escolher arquivos avulsos.
  • Pessoas e grupos são identificados pelo e-mail. Se um admin troca o e-mail de uma pessoa ou de um grupo no Workspace, o acesso antigo deixa de casar até a próxima leitura do arquivo.
  • Uma pasta configurada precisa ser acessível pela Service Account. Pastas compartilhadas só por link não são lidas.

​
Troubleshooting

​
Próximos passos

Knowledge

Veja como buscar nos documentos que o conector envia.

Data Catalog

Conheça os outros conectores que alimentam o catálogo com tabelas.
No ambiente local, as credenciais do conector também são cadastradas pelo Console (veja Desenvolvimento local). A chave fica no cofre de credenciais da instância, e não no .env.Ao executar a classe do conector direto, fora do Console, a chave pode vir destas variáveis: