Automação de uploads de arquivos com a API do Drive

A automação de uploads é um dos fluxos de trabalho mais úteis da API do Drive. Relatórios, faturas, exportações geradas, PDFs assinados e anexos de suporte podem chegar à pasta correta do TrekMail Drive sem a necessidade de arrastar e soltar manualmente.

O padrão seguro é simples: verifique o armazenamento, crie ou escolha uma pasta, inicie o upload, transfira os bytes, conclua o upload e registre uma trilha de auditoria útil.

Escopos recomendados

Para uploads no Drive da conta, comece com:

• drive:account:read
• drive:account:write

Para uploads no Drive de uma caixa postal, use:

• drive:mailbox:read
• drive:mailbox:write

Evite escopos de compartilhamento e exclusão permanente, a menos que o mesmo fluxo de trabalho realmente precise deles. Se a tarefa de upload também criar links públicos, adicione o escopo de compartilhamento correspondente.

Verificações preliminares

Antes de enviar um arquivo grande, chame o endpoint de resumo do armazenamento ou uso do espaço. Sua integração deve tratar "cota excedida" como um resultado comercial normal, não como uma falha do aplicativo.

Uma boa automação também verifica se a pasta de destino existe. Caso não exista, crie-a com uma chave de idempotência para que novas tentativas não gerem pastas duplicadas.

Fluxo de upload REST

1. Envie POST /api/v1/drive/spaces/{space}/uploads:initiate com nome e tamanho do arquivo, ID opcional da pasta e tipo MIME.
2. Envie os bytes do arquivo para a URL de upload ou para as URLs de upload em várias partes retornadas.
3. Envie POST /api/v1/drive/uploads/{file}:complete após a transferência ser concluída com sucesso.
4. Se a transferência falhar, chame POST /api/v1/drive/uploads/{file}:abort para liberar a reserva rapidamente.

Use uma Idempotency-Key na solicitação de início, que reserva capacidade de upload. Use uma chave estável para cada arquivo lógico, como invoice-2026-05-001-upload. Não presuma que todos os endpoints de upload posteriores repetem resultados idempotentes; guarde o ID de arquivo retornado e verifique seu estado antes de tentar novamente a conclusão ou cancelar uma transferência.

Fluxo de upload MCP

Para agentes, prefira uma única ferramenta:

drive_file_upload(space="account", local_path="/exports/report.pdf", folder_id=42)

O wrapper MCP cuida da negociação do upload, transferência, conclusão e cancelamento em caso de erro. Há ferramentas de baixo nível para lógica de transferência personalizada, mas a maioria dos fluxos de trabalho não precisa delas.

Convenções de nomes e pastas

Use nomes previsíveis para que as pessoas possam navegar pelo Drive posteriormente:

• Reports/2026/05/monthly-summary.pdf
• Clients/Acme/contracts/acme-renewal-2026.pdf
• Invoices/2026/INV-2026-0042.pdf

Se um agente enviar versões repetidas, inclua carimbos de data e hora ou rótulos de versão. Evite ocultar o significado enviando final.pdf toda semana.

Tratamento de falhas

Planeje estes casos:

Após o upload

Se o arquivo se destinar a uma entrega externa, crie um link de compartilhamento com prazo de validade e limite de downloads. Se for interno, mantenha-o como um arquivo normal do Drive. De qualquer forma, consulte Agentes de IA e API → Log de auditoria para confirmar o token e a sequência de ações.