Leia antes:
../conectores.md(mapa de estados) efichas.md(índice das fichas).
What it is#
Reads CSV, JSON and XLSX files from a Dropbox folder (OAuth2 with refresh token) and loads them into the Bronze layer; Parquet is detected and loaded directly.
Supported ingestion modes:
- Nós buscamos — Nós buscamos os dados na sua fonte.
What it's for#
Bringing Dropbox data into your datalake and making it available to the Bronze/Silver/Gold layers, BI models and the natural language question wizard.
When to use / when not to use#
Use when you need to consolidate this source into the datalake on a scheduled basis, with isolation per workspace.
Remember that the first run with a real credential is followed by our team before the connector is fully released.
Plan and permissions#
- Plan: core product (connectors are part of all plans; the limit is the number of sources in the plan).
- Access: requires an active workspace — with billing overdue, suspended or canceled, the run is blocked.
- Shutdown: the ingestion run can be temporarily turned off (maintenance or incident). When that happens, the UI shows the resource is unavailable at the moment.
Prerequisites#
- A Dropbox account with access to the data you want to ingest.
- In the Dropbox App Console, create an app (Scoped access) with the files.content.read permission and authorize it in your account with token_access_type=offline to obtain a refresh token. Provide the folder, the App key (Client ID), the App secret and the refresh token; secrets are encrypted and never shown again.
Credentials#
Authentication method: OAuth 2.0 (client id/secret + refresh token). All secrets are encrypted (AES-256-GCM) and never shown again. If authorization expires, just reconnect — the source and history are preserved.
Sensitive fields. They are encrypted (AES-256-GCM) and never appear in the connection config, in the pipeline definition, in exports or in the DAG. By default the encrypted value is stored in the database; moving this connection's credential to an external credential vault is an explicit choice, made per connection after saving — see ../../administracao/credenciais-e-rotacao.md.
- Client Secret (
clientSecret) - Refresh token (
refreshToken) — Issued when authorizing the app with token_access_type=offline. Does not expire until revoked.
Secrets are never re-displayed and are redacted in any error/log (raw token, URL-encoded and in JSON).
Form fields#
| Campo | Rótulo | Tipo | Obrigatório | Observação |
|---|---|---|---|---|
pasta | Pasta | texto | não | Caminho a partir da raiz do Dropbox. Cada subpasta NÃO é lida (só o nível informado); arquivos agrupam pelo nome. |
clientId | Client ID | texto | sim | App key do aplicativo criado no App Console do Dropbox. |
clientSecret 🔒 | Client Secret | senha/segredo | sim | segredo (cifrado; cofre externo opcional) |
refreshToken 🔒 | Refresh token | senha/segredo | sim | segredo (cifrado; cofre externo opcional); Emitido ao autorizar o app com token_access_type=offline. Não expira até ser revogado. |
Step-by-step#
- No menu Dados → Conexões, use Nova conexão.
- Escolha Dropbox no catálogo.
- Preencha os campos do formulário (veja a tabela acima).
- Use Testar conexão. O resultado vem separado em três capacidades, cada uma com OK, Falhou, Não se aplica ou Não testado. Nesta ficha elas significam: Rede — o endpoint do serviço de armazenamento é alcançável a partir do servidor da aplicação; Autenticação — a credencial do formulário (chave de acesso ou conta de serviço, não usuário e senha) foi aceita; Leitura — foi possível listar os objetos do bucket/container sob o prefixo informado (a contagem exibida é de objetos visíveis, não de tabelas).
- Use Salvar conexão. Salvar NÃO inicia ingestão nenhuma.
- No cartão da conexão, use Montar extração (ou vá em Orquestração → Pipelines e use Conectar fonte). O pipeline aponta para a conexão salva — a credencial não é copiada.
- Na revisão, Publicar (agenda desligada) cria a versão 1 sem executar nada. Depois, Ativar agenda e Executar agora são ações separadas.
Example — connection test#
Example configuration (all values are fictitious; secrets are masked):
# Exemplo sintético (valores fictícios — não são credenciais reais)
pasta = <pasta>
clientId = exemplo-client-id-ficticio
clientSecret = •••••• (cifrado — nunca exibido)
refreshToken = •••••• (cifrado — nunca exibido)Expected result#
Testar conexão returns the count of visible objects under the provided prefix. After the first load, the content of those files appears in the Bronze layer of your workspace, ready for the pipeline.
Limits and costs#
- Pagination: hard cap per run (default 10,000 pages / 5,000,000 rows); loop-guard.
- SaaS load: default
batchSize5,000,maxRows200,000 per resource. - Estimated volume: ~1 GB/month (catalog estimate, not measured).
- Cost: the extraction itself is not charged by the platform; the Bronze load consumes datalake processing (billable).
Security#
- Scope by workspace: each customer reads and writes only to their own datalake (
<prefixo>_bronze/_silver/_gold); there is never leakage between workspaces. - Encrypted secrets: sensitive material is encrypted with AES-256-GCM before being written. The external credential vault is optional and enabled per connection; without it the encrypted value stays in the database. Changing the value here DOES NOT revoke the credential at the source.
- Redaction: all errors/logs are passed through secret redaction (raw, URL-encoded and in JSON).
- Production does not fake: a path that would land in mock triggers the production guard (explicit failure instead of simulating success).
Common errors#
- Authentication failed — this connector's credential is NOT a user/password: it is an access key (or service account). Check the pair provided in the form and whether it is still active in the provider.
- Listing denied — the credential authenticates but cannot list the bucket. Grant bucket listing and object read under the prefix; read-only without listing is not enough because the pipeline needs to discover which files exist.
- Bucket/prefix does not exist or is empty — check the exact bucket name and prefix (folder). A prefix with no objects returns zero visible objects, not an error.
- File in unsupported format — object storage carries files; the pipeline must be able to read the content (CSV, JSON or Parquet). An object in another format is ignored or fails the load, depending on the pipeline policy.
Troubleshooting#
- Use Testar conexão to isolate credential/network issues before scheduling.
- Monitor runs in the connector observability (error rate, p50/p95, freshness).
- A schema change at the source is signaled by schema drift (new column = info; removed column/type change = attention).
Related#
../conectores.md— connector catalog by state../ingestao-incremental-backfill.md— full, incremental by watermark, backfill and checkpoint../pipeline-medalhao.md— Bronze/Silver/Gold layers and quality../agendamento-retry-dlq.md— scheduling, retry/backoff and DLQ../custo-limites-seguranca.md— cost, caps and workspace security
Última revisão: 2026-10-04. Ficha gerada automaticamente do catálogo de conectores do produto.