Autenticação e Configuração
A integração com o Dropbox usa autenticação OAuth 2.0 com a abordagem de Acesso Escopado. As organizações devem criar um Aplicativo Dropbox no Console de Aplicativos Dropbox e configurar as permissões apropriadas. A integração suporta tanto contas pessoais do Dropbox quanto contas de equipe do Dropbox Business. Os agentes podem acessar arquivos no Dropbox do usuário ou em pastas compartilhadas da equipe com a devida autorização.Permissões e Escopos Necessários
- files.content.write: Fazer upload e modificar conteúdo de arquivos.
- files.content.read: Baixar e ler conteúdo de arquivos.
- files.metadata.write: Criar pastas, mover, renomear e excluir arquivos.
- files.metadata.read: Visualizar metadados de arquivos e pastas.
- sharing.write: Criar e modificar links de compartilhamento.
- sharing.read: Visualizar configurações de compartilhamento existentes.
- team_data.member: Acessar conteúdo de pastas da equipe (Dropbox Business).
Operações Disponíveis
Com todas as permissões necessárias configuradas, o toolkit permite as seguintes operações:Operações de Arquivos
- Fazer Upload de Arquivo: Fazer upload de arquivos do workspace do agente para o Dropbox com versionamento automático.
- Baixar Arquivo: Recuperar arquivos para processamento local com suporte a downloads parciais.
- Mover Arquivo: Realocar arquivos entre pastas com resolução automática de conflitos.
- Copiar Arquivo: Duplicar arquivos no mesmo local ou em um local diferente.
- Excluir Arquivo: Remover arquivos (podem ser recuperados da lixeira por 30 dias).
- Restaurar Arquivo: Recuperar arquivos excluídos ou restaurar versões anteriores.
- Obter Metadados do Arquivo: Recuperar detalhes do arquivo, incluindo tamanho, data de modificação e hash de conteúdo.
- Pesquisar Arquivos: Pesquisa em texto completo em nomes de arquivos e conteúdo (onde suportado).
- Obter Miniatura: Gerar miniaturas de pré-visualização para imagens e documentos.
Gerenciamento de Pastas
- Criar Pasta: Criar novas pastas com hierarquias aninhadas.
- Listar Pasta: Navegar pelo conteúdo da pasta com suporte a paginação.
- Mover Pasta: Realocar estruturas de pastas inteiras.
- Copiar Pasta: Duplicar pastas com todo o conteúdo.
- Excluir Pasta: Remover pastas e todo o conteúdo.
- Obter Metadados da Pasta: Recuperar propriedades e estatísticas da pasta.
Operações de Compartilhamento
- Criar Link Compartilhado: Gerar links de compartilhamento públicos ou protegidos por senha.
- Listar Links Compartilhados: Visualizar todos os links de compartilhamento ativos para arquivos e pastas.
- Revogar Link Compartilhado: Desativar links de compartilhamento para impedir acesso futuro.
- Atualizar Configurações do Link: Modificar permissões e datas de expiração dos links.
- Criar Pasta Compartilhada: Compartilhar pastas com usuários ou equipes específicas.
- Adicionar Membro à Pasta: Convidar usuários para colaborar em pastas compartilhadas.
- Remover Membro da Pasta: Revogar acesso de colaboradores de pastas compartilhadas.
- Definir Expiração do Link: Configurar datas de expiração automáticas dos links.
- Definir Senha do Link: Proteger links com autenticação por senha.
Operações Avançadas
- Obter Revisões do Arquivo: Acessar histórico de versões de arquivos (até 30 dias ou mais com histórico estendido).
- Operações em Lote: Realizar múltiplas operações de arquivo em uma única chamada de API.
- Sessão de Upload: Fazer upload de arquivos grandes (>150MB) usando sessões de upload fragmentado.
- Download em ZIP: Baixar múltiplos arquivos como um arquivo compactado.
- Obter Uso de Espaço: Verificar uso de armazenamento da conta e espaço disponível.
- Operações de Documentos Paper: Criar e editar documentos do Dropbox Paper.
Funcionalidades do Dropbox Business
- Acesso a Pastas da Equipe: Acessar e gerenciar pastas da equipe.
- Gerenciamento de Membros: Listar membros da equipe e suas permissões.
- Operações Administrativas: Realizar tarefas administrativas (requer permissões de administrador).
Opções de Configuração
- Pasta Padrão: Definir o local padrão de upload no Dropbox.
- Resolução de Conflitos: Escolher o comportamento para conflitos de nomes de arquivo (renomear automaticamente, sobrescrever, falhar).
- Tamanho do Bloco: Configurar o tamanho do bloco de upload para arquivos grandes (padrão 4MB).
- Permissões do Link: Permissões padrão para links de compartilhamento (somente visualização, edição).
- Exclusão Automática: Excluir automaticamente arquivos locais após upload bem-sucedido.
Casos de Uso
- Armazenamento de Arquivos: Fazer backup de documentos e dados importantes do workspace do agente na nuvem.
- Automação de Backup: Agendar backups automáticos de arquivos críticos no Dropbox.
- Compartilhamento de Arquivos: Gerar links de compartilhamento para relatórios, documentos ou conjuntos de dados para acesso de stakeholders.
- Fluxos de Trabalho Colaborativos: Fazer upload de arquivos em pastas compartilhadas da equipe para colaboração.
- Distribuição de Documentos: Distribuir relatórios gerados para múltiplos destinatários via links compartilhados.
- Migração de Dados: Transferir arquivos entre sistemas de armazenamento usando o Dropbox como intermediário.
- Controle de Versões: Aproveitar o versionamento automático do Dropbox para gerenciamento de documentos.
- Biblioteca de Mídias: Armazenar e organizar imagens, vídeos e recursos de mídia.
Melhores Práticas
- Usar Identificadores de Caminho: Referenciar arquivos por caminho (case-insensitive) para estabilidade.
- Uploads Fragmentados: Sempre usar sessões de upload para arquivos maiores que 150MB.
- Solicitações em Lote: Agrupar múltiplas operações para reduzir chamadas de API (até 1.000 operações por lote).
- Monitorar Limites de Taxa: O Dropbox impõe limites de taxa; implemente backoff exponencial para retentativas.
- Expiração de Links: Definir datas de expiração em links de compartilhamento para conteúdo sensível.
- Organizar Pastas: Usar hierarquias de pastas claras para manter os arquivos organizados.
- Verificar Espaço: Verificar o armazenamento disponível antes de uploads grandes para evitar falhas.
Limites de Taxa e Cotas
A API do Dropbox impõe limitação de taxa com base no tipo de aplicativo e no nível da conta. Limites padrão: 40 requisições/segundo para usuários individuais. Operações em lote contam como uma única requisição. Monitore respostas HTTP 429 e implemente lógica de retentativa com backoff exponencial (sugerido: 1s, 2s, 4s, 8s).Problemas Comuns e Soluções
- Caminho Não Encontrado: Verifique a ortografia e o caso do caminho (os caminhos do Dropbox são case-insensitive, mas preservam o caso).
- Espaço Insuficiente: Verifique o armazenamento da conta antes de uploads. Atualize o plano se necessário.
- Limite de Taxa Excedido: Implemente backoff exponencial e considere usar operações em lote.
- Timeout de Upload: Use sessões de upload fragmentado para arquivos grandes para lidar com interrupções de rede.
- Permissão Negada: Verifique se os escopos OAuth incluem as permissões necessárias para a operação.