> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Drive

> Configure o conector Google Drive para ingerir documentos e planilhas na plataforma strattum.ai.

<Note>
  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](/data-pipelines/quickstart).
</Note>

## 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

<CardGroup cols={2}>
  <Card title="Projeto no Google Cloud" icon="google">
    Um projeto ativo no [Google Cloud Console](https://console.cloud.google.com) para criar a Service Account.
  </Card>

  <Card title="Google Drive API habilitada" icon="plug">
    A Google Drive API precisa estar habilitada no projeto. O passo a passo está abaixo.
  </Card>
</CardGroup>

***

## Variáveis de ambiente

Adicione a variável abaixo ao arquivo `.env` (veja o guia de [configuração local](/data-pipelines/local-development#2-configurar-variáveis-de-ambiente)):

| 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",...}` |

```bash theme={null}
# 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
```

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

***

## Como criar uma Service Account

<Steps>
  <Step title="Acesse o Google Cloud Console">
    Abra [console.cloud.google.com](https://console.cloud.google.com) e faça login com uma conta Google com permissão de administrador no projeto.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Habilite a Google Drive API">
    Acesse **APIs & Services → Library**, pesquise por `Google Drive API` e clique em **Enable**.

    <Tip>
      Se a API já aparecer como habilitada, pule esta etapa.
    </Tip>
  </Step>

  <Step title="Acesse IAM & Admin → Service Accounts">
    No menu lateral, acesse **IAM & Admin → Service Accounts** e clique em **Create Service Account**.
  </Step>

  <Step title="Preencha os dados da Service Account">
    Dê um nome descritivo (ex: `strattum-drive-reader`) e uma descrição opcional. Clique em **Create and Continue**.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.

    <Tip>
      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:

      ```bash theme={null}
      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.
    </Tip>
  </Step>

  <Step title="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**.

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

  <Step title="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`.

    ```bash theme={null}
    GCP_SERVICE_ACCOUNT_JSON='cole aqui o conteúdo completo do arquivo JSON'
    ```
  </Step>
</Steps>

***

## 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:

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

| 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.                                               |

<Note>
  Para ambientes com requisitos de segurança mais rigorosos, considere [Workload Identity Federation](https://cloud.google.com/iam/docs/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).
</Note>

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Guia de desenvolvimento local" icon="terminal" href="/data-pipelines/local-development">
    Configure o ambiente local completo com Prefect, worker e Docker Compose.
  </Card>

  <Card title="Quickstart — Data Pipelines" icon="rocket" href="/data-pipelines/quickstart">
    Ative conectores via Console strattum.ai sem precisar de ambiente local.
  </Card>
</CardGroup>