Autenticação e Configuração
A integração com o Google Drive fornece capacidades abrangentes de armazenamento e gerenciamento de arquivos por meio da autenticação OAuth 2.0. Os agentes podem interagir com contas pessoais do Drive e Team Drives compartilhados (Shared Drives) em organizações do Google Workspace. A integração suporta todos os principais tipos de arquivos, incluindo documentos, planilhas, apresentações, imagens, vídeos e PDFs.Escopos de API Necessários
- drive: Acesso completo a todos os arquivos no Drive, incluindo Team Drives.
- drive.file: Acesso apenas a arquivos criados ou abertos pelo aplicativo.
- drive.readonly: Acesso somente leitura para visualizar e baixar arquivos.
- drive.metadata: Acesso a metadados de arquivos sem acesso ao conteúdo.
- drive.appdata: Acesso à pasta de dados específica do aplicativo.
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 Drive com metadados (nome, descrição, tipo MIME).
- Baixar Arquivo: Recuperar arquivos para processamento ou análise local.
- Listar Arquivos: Navegar por arquivos e pastas com filtro por nome, tipo, proprietário ou data de modificação.
- Pesquisar Arquivos: Pesquisa em texto completo em nomes e conteúdo de arquivos usando parâmetros de consulta.
- Obter Arquivo: Recuperar metadados detalhados do arquivo, incluindo permissões, proprietários e histórico de versões.
- Atualizar Arquivo: Modificar conteúdo ou metadados do arquivo sem alterar o ID do arquivo.
- Excluir Arquivo: Mover arquivos para a lixeira ou excluir permanentemente.
- Restaurar Arquivo: Recuperar arquivos da lixeira.
- Exportar Arquivo: Converter arquivos do Google Workspace para formatos padrão (Docs para PDF, Sheets para Excel, etc.).
Gerenciamento de Pastas
- Criar Pasta: Criar novas pastas com nomes personalizados para organização.
- Mover Arquivo: Realocar arquivos entre pastas atualizando referências de pai.
- Copiar Arquivo: Duplicar arquivos com novos nomes ou em locais diferentes.
- Listar Conteúdo da Pasta: Recuperar todos os arquivos dentro de uma pasta específica.
- Obter Caminho da Pasta: Determinar a hierarquia de caminho completo para qualquer pasta.
Compartilhamento e Permissões
- Compartilhar Arquivo: Gerar links de compartilhamento com permissões configuráveis (visualizar, comentar, editar).
- Criar Permissão: Conceder acesso a usuários ou grupos específicos para arquivos.
- Atualizar Permissão: Modificar permissões de acesso existentes.
- Remover Permissão: Revogar acesso de usuários ou links de compartilhamento.
- Listar Permissões: Visualizar todos os usuários e grupos com acesso a um arquivo.
- Definir Expiração do Link: Configurar expiração automática para links de compartilhamento.
- Restringir Download: Impedir que visualizadores baixem, imprimam ou copiem conteúdo.
Operações Avançadas
- Obter Metadados do Arquivo: Recuperar data de criação, data de modificação, tamanho, proprietário, tipo MIME e miniatura.
- Monitorar Arquivo: Configurar notificações para alterações em arquivos (webhooks).
- Obter Revisões do Arquivo: Acessar histórico de versões e restaurar versões anteriores.
- Adicionar Comentário: Publicar comentários em arquivos do Google Docs, Sheets e Slides.
- Operações em Lote: Realizar múltiplas operações de arquivo em uma única chamada de API.
Opções de Configuração
- Pasta Padrão: Definir o local padrão de upload para uma pasta específica ou Team Drive.
- Limite de Tamanho do Arquivo: Configurar o tamanho máximo de upload (limite da API é 5GB por arquivo).
- Incluir Arquivos na Lixeira: Se deve incluir arquivos na lixeira nos resultados de listagem/pesquisa.
- Suporta Team Drives: Ativar acesso a Team Drives (Shared Drives) em contas do Workspace.
- Corpus: Escopo de pesquisa - Drive do usuário, Team Drives ou todos os domínios.
Casos de Uso
- Backup de Documentos: Fazer backup automaticamente de arquivos importantes do workspace do projeto para o Drive com controle de versões.
- Organização de Arquivos: Categorizar e mover automaticamente arquivos carregados para pastas apropriadas com base no conteúdo ou metadados.
- Distribuição de Conteúdo: Fazer upload de relatórios, gerar links de compartilhamento e distribuir para stakeholders por e-mail.
- Fluxos de Trabalho Colaborativos: Fazer upload de rascunhos para Team Drives, compartilhar com a equipe, acompanhar comentários e revisões.
- Migração de Dados: Transferir arquivos em massa entre sistemas de armazenamento usando o Drive como intermediário.
- Gerenciamento de Biblioteca de Mídias: Organizar imagens, vídeos e recursos com tagagem de metadados e pesquisa.
- Pipeline de Processamento de Documentos: Baixar arquivos, processar com Python/Node.js, fazer upload dos resultados de volta para o Drive.
Melhores Práticas
- Usar IDs de Arquivo: Sempre referenciar arquivos por ID em vez de nome para evitar ambiguidade com duplicatas.
- Implementar Uploads Resumíveis: Para arquivos >5MB, usar o protocolo de upload resumível para lidar com interrupções.
- Solicitações em Lote: Combinar múltiplas operações para reduzir chamadas de API e melhorar o desempenho.
- Monitorar Cota: Rastrear uso da API em relação aos limites de cota diária (varia por tipo de conta).
- Organizar com Pastas: Usar hierarquias de pastas claras em vez de estrutura plana para grandes coleções de arquivos.
- Definir Permissões Apropriadas: Usar o princípio do menor privilégio ao compartilhar arquivos.
Problemas Comuns e Soluções
- Timeouts de Upload: Para arquivos grandes, usar upload resumível e implementar lógica de retentativa.
- Permissão Negada: Verificar se o usuário concedeu o escopo drive durante o OAuth. Verificar propriedade e permissões do arquivo.
- Arquivos Duplicados: O Drive permite múltiplos arquivos com o mesmo nome. Usar pesquisa por ID ou incluir a pasta pai nas consultas.
- Limite de Taxa: Implementar backoff exponencial para retentativas. Considere armazenar em cache metadados frequentemente acessados.