Google Drive

Este guia cobre a configuração do conector Google Drive para desenvolvimento local. Para ativar o conector via Console strattum.ai, consulte o Quickstart de Data Pipelines.

Visão geral

O conector Google Drive ingere arquivos de pastas compartilhadas na infraestrutura strattum.ai. A carga é feita em Full Refresh a cada ciclo de sincronização.

Tipo de arquivo	Suportado
Google Docs	Sim
Google Sheets	Sim
PDFs	Sim
Outros formatos (DOCX, XLSX, imagens)	Não

Pré-requisitos

Projeto no Google Cloud

Um projeto ativo no Google Cloud Console para criar a Service Account.

Google Drive API habilitada

A Google Drive API precisa estar habilitada no projeto. O passo a passo está abaixo.

Variáveis de ambiente

Adicione a variável abaixo ao arquivo .env (veja o guia de configuração local):

Variável	Descrição	Exemplo
`GCP_SERVICE_ACCOUNT_JSON`	Conteúdo do arquivo JSON da Service Account (inline) ou caminho para o arquivo	`{"type":"service_account",...}`

# Opção 1: conteúdo inline (recomendado para ambientes containerizados)
GCP_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"meu-projeto",...}'

# Opção 2: caminho para o arquivo JSON
GCP_SERVICE_ACCOUNT_JSON=/caminho/para/service-account.json

Nunca comite o arquivo .env nem o arquivo JSON da Service Account no repositório. Certifique-se que ambos estão listados no .gitignore.

Como criar uma Service Account

Acesse o Google Cloud Console

Abra console.cloud.google.com e faça login com uma conta Google com permissão de administrador no projeto.

Selecione ou crie um projeto

No seletor de projeto no topo da página, escolha o projeto existente ou clique em New Project para criar um novo.

Habilite a Google Drive API

Acesse APIs & Services → Library, pesquise por Google Drive API e clique em Enable.

Se a API já aparecer como habilitada, pule esta etapa.

Acesse IAM & Admin → Service Accounts

No menu lateral, acesse IAM & Admin → Service Accounts e clique em Create Service Account.

Preencha os dados da Service Account

Dê um nome descritivo (ex: strattum-drive-reader) e uma descrição opcional. Clique em Create and Continue.

Pule a etapa de atribuição de roles

Não é necessário atribuir roles do IAM — as permissões serão concedidas diretamente via compartilhamento de pasta no Google Drive. Clique em Continue e depois em Done.

Gere e baixe a chave JSON

Na lista de Service Accounts, clique na conta recém-criada. Acesse a aba Keys → Add Key → Create new key, selecione o formato JSON e clique em Create. O arquivo será baixado automaticamente.

Se você receber o erro “Criação de chaves de conta de serviço desativada” com a política iam.disableServiceAccountKeyCreation, isso significa que sua organização Google Cloud bloqueia a criação de chaves por padrão (configuração de segurança recomendada pelo Google). Para desbloquear, um administrador com o papel Administrador de políticas da organização (roles/orgpolicy.policyAdmin) precisa executar:

gcloud org-policies delete iam.disableServiceAccountKeyCreation \
  --organization=SEU_ORG_ID

Para descobrir o ORGANIZATION_ID, execute gcloud organizations list. Após desbloquear, tente gerar a chave novamente.

Compartilhe a pasta do Drive com a Service Account

No Google Drive, clique com o botão direito na pasta que deseja ingerir e selecione Compartilhar. Adicione o e-mail da Service Account (visível na lista de Service Accounts, no formato nome@projeto.iam.gserviceaccount.com) com permissão de Visualizador.

Apenas os arquivos dentro de pastas compartilhadas com a Service Account serão ingeridos. Pastas não compartilhadas permanecem invisíveis ao conector.

Configure a variável de ambiente

Copie o conteúdo do arquivo JSON baixado e defina a variável GCP_SERVICE_ACCOUNT_JSON no seu .env.

GCP_SERVICE_ACCOUNT_JSON='cole aqui o conteúdo completo do arquivo JSON'

Segurança e rotação de chaves

A chave JSON da Service Account é uma credencial de longa duração que contém uma chave privada RSA. Se vazada, concede acesso até ser manualmente deletada. Siga estas práticas:

Chaves de Service Account nunca expiram automaticamente. Trate-as como senhas críticas.

Prática	Descrição
Rotação periódica	Gere uma nova chave a cada 90 dias, atualize a variável `GCP_SERVICE_ACCOUNT_JSON` e delete a chave anterior em IAM & Admin → Service Accounts → Keys.
Secrets manager	Em produção, armazene a chave em um gerenciador de secrets (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager) em vez de variáveis de ambiente em texto plano.
Escopo mínimo	A Service Account não deve ter roles IAM além do necessário. As permissões de acesso ao Drive são controladas exclusivamente pelo compartilhamento de pastas.
Nunca comitar	Adicione `*.json` e `.env` ao `.gitignore`. Nunca envie chaves para repositórios, mesmo privados.
Monitoramento	Ative logs de auditoria no Google Cloud Console em IAM & Admin → Audit Logs para rastrear o uso da Service Account.

Para ambientes com requisitos de segurança mais rigorosos, considere Workload Identity Federation — uma alternativa que elimina completamente a necessidade de armazenar chaves, usando tokens de curta duração (~1h) trocados automaticamente com a identidade nativa da sua cloud (AWS IAM, Azure Managed Identity).

Visão geral

Bancos de dados

CRM & SaaS

Financeiro

Documentos

Analytics

Referência

Visão geral

Pré-requisitos

Projeto no Google Cloud

Google Drive API habilitada

Variáveis de ambiente

Como criar uma Service Account

Segurança e rotação de chaves

Próximos passos

Guia de desenvolvimento local

Quickstart — Data Pipelines

​Visão geral

​Pré-requisitos

Projeto no Google Cloud

Google Drive API habilitada

​Variáveis de ambiente

​Como criar uma Service Account

​Segurança e rotação de chaves

​Próximos passos

Guia de desenvolvimento local

Quickstart — Data Pipelines

Visão geral

Pré-requisitos

Variáveis de ambiente

Como criar uma Service Account

Segurança e rotação de chaves

Próximos passos