> ## Documentation Index > Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt > Use this file to discover all available pages before exploring further. # Google Drive > Lê arquivos de pastas do Google Drive com uma Service Account, extrai o texto e envia os documentos para o Knowledge com a permissão de cada arquivo. 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. | | | | - | - | | **Status** | Beta | | **Conteúdo** | Documentos | | **Autenticação** | Service Account do Google Cloud | | **Permissões** | Por item | | **Sincronização** | Incremental | | **Última revisão** | 24/09/2026 | ## 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 | Recurso | O que contém | Carga | Cursor | Destino | Permissão por item | | - | - | - | - | - | - | | `documents` | Um registro por arquivo das pastas configuradas e das subpastas: nome, tipo, caminho da pasta, donos, datas de criação e modificação, tamanho, link e o texto extraído | Incremental | `modified_at` | Knowledge | Sim | ## 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: | Modo | Quem vê | | - | - | | Aberto | Quem puder usar este conector vê todos os registros. As permissões da fonte são ignoradas. | | Espelhar a fonte | Cada pessoa vê apenas os registros que a própria fonte libera para ela. | 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: | Compartilhamento no Drive | O que a Strattum grava | | - | - | | Uma pessoa | a pessoa, pelo e-mail dela | | Um Grupo do Google | o grupo, pelo e-mail do grupo | | O domínio da sua empresa | todos que podem usar este conector | | Qualquer pessoa com o link | o arquivo inteiro fica sem leitor | | Outro domínio | o arquivo inteiro fica sem leitor | 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. | Escopo ou permissão | Para quê | | - | - | | `https://www.googleapis.com/auth/drive.readonly` | Listar pastas, ler metadados, baixar arquivos e ler o compartilhamento de cada arquivo | | `https://www.googleapis.com/auth/admin.directory.group.member.readonly` | Ler os membros dos Grupos do Google que têm acesso a arquivos. Exige delegação em todo o domínio e o admin impersonado | | `openid email` | Vínculo de conta: confirmar o e-mail e o domínio de cada usuário. Vale para o cliente OAuth, não para a Service Account | 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. | Método e caminho | Usado para | Recurso | | - | - | - | | `about().get` | Testar se a API responde com a credencial | Nenhum | | `files().get` | Conferir cada pasta configurada e montar o caminho de pastas de cada arquivo | `documents` | | `files().list` | Listar arquivos e subpastas de cada pasta | `documents` | | `files().get_media` | Baixar o conteúdo de cada arquivo | `documents` | | `permissions().list` | Ler o compartilhamento de cada arquivo | Permissões | | `members().list` | Ler os membros de cada Grupo do Google com acesso a arquivos | Permissões | **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](https://developers.google.com/workspace/drive/api/guides/limits)). 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](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 | Mensagem ou sintoma | Causa | O que fazer | | - | - | - | | "Este JSON não parece ser uma Service Account válida (esperado: "type": "service\_account")" | O JSON colado é de outro tipo de credencial, como um cliente OAuth | Gere uma chave JSON da Service Account em **IAM & Admin** > **Service Accounts** | | "JSON da Service Account inválido — verifique o formato" | O conteúdo colado não é um JSON válido | Use **Carregar arquivo** com o arquivo baixado do Google Cloud | | "Credenciais da Service Account inválidas" | A chave foi apagada ou a Service Account foi desativada | Gere uma nova chave e cole-a de novo | | "Erro ao conectar ao Google Drive: ..." | A Google Drive API não está habilitada no projeto, ou outro erro da API | Habilite a Google Drive API e teste de novo | | A sincronização não começa e o log diz `Google Drive is not finished being configured` | Nenhuma pasta foi informada | Preencha **Pastas do Drive** | | A sincronização falha com `Google Drive connection test failed` | Uma pasta não é acessível para a Service Account, está na lixeira, é um atalho ou é um arquivo, ou todas estão vazias | Veja no log o motivo por pasta. Para atalho, o log mostra o ID da pasta de destino que deve ser usado | | Arquivo não aparece no Knowledge, com o motivo "Permissões não puderam ser resolvidas com segurança" | A Service Account só tem papel **Leitor**, o arquivo tem link público ou foi compartilhado com outro domínio, ou é compartilhado com o domínio sem admin impersonado | Dê papel **Editor** à Service Account, remova o link público ou preencha **Admin do Workspace impersonado** | | Arquivo do Google Docs, Sheets ou Slides não aparece | Arquivos nativos do Google não são lidos | Exporte o arquivo para PDF, Word, Excel ou PowerPoint na mesma pasta | | PDF não aparece no Knowledge | O PDF é escaneado ou protegido por senha | Envie uma versão com texto selecionável e sem senha | | Um usuário não vê nada no modo "Espelhar a fonte" | O e-mail dele na Strattum difere do e-mail no Google e ele não vinculou a conta, ou o acesso dele vem de um grupo cujos membros não puderam ser lidos | Peça ao usuário para vincular a conta e confira a delegação do escopo `admin.directory.group.member.readonly` | | O vínculo da conta Google falha | A conta é um Gmail pessoal, o e-mail não é verificado, a conta é de outro domínio ou o **Admin do Workspace impersonado** está vazio | Use uma conta do mesmo Google Workspace do admin impersonado e confira o campo no conector | ## Próximos passos > **[Knowledge](https://docs.strattum.ai/knowledge/overview.md)** > > Veja como buscar nos documentos que o conector envia. > **[Data Catalog](https://docs.strattum.ai/data-catalog/overview.md)** > > Conheça os outros conectores que alimentam o catálogo com tabelas. > **Desenvolvimento local** > > No ambiente local, as credenciais do conector também são cadastradas pelo Console (veja [Desenvolvimento local](https://docs.strattum.ai/data-pipelines/local-development.md)). 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: > > | Variável | Descrição | Exemplo | > | - | - | - | > | `GCP_SERVICE_ACCOUNT_JSON` | Conteúdo do JSON da Service Account ou caminho para o arquivo | `{"type":"service_account",...}` | > | `GOOGLE_APPLICATION_CREDENTIALS` | Caminho para o arquivo JSON, usado quando a variável anterior está vazia | `/caminho/para/service-account.json` | > | `GDRIVE_USE_DOMAIN_ADMIN_ACCESS` | `true` para ler o compartilhamento como administrador do domínio. Vale só para drives compartilhados e exige o admin impersonado | `true` | > > ```bash theme={null} > GCP_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"meu-projeto",...}' > GDRIVE_USE_DOMAIN_ADMIN_ACCESS=true > ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.