Automatizzare il caricamento di file con l’API Drive

L’automazione dei caricamenti è uno dei flussi di lavoro più utili dell’API Drive. Report, fatture, esportazioni generate, PDF firmati e allegati di assistenza possono arrivare nella cartella corretta di TrekMail Drive senza trascinamento manuale.

Il modello sicuro è semplice: controlla lo spazio, crea o scegli una cartella, avvia il caricamento, trasferisci i byte, completa il caricamento e scrivi una traccia di audit utile.

Ambiti consigliati

Per i caricamenti nel Drive dell’account, inizia con:

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

Per i caricamenti nel Drive di una casella, usa:

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

Evita gli ambiti di condivisione ed eliminazione definitiva, a meno che lo stesso flusso ne abbia davvero bisogno. Se l’attività crea anche link pubblici, aggiungi l’ambito di condivisione corrispondente.

Controlli preliminari

Prima di caricare un file grande, chiama l’endpoint di riepilogo dello spazio o del suo utilizzo. L’integrazione deve trattare "quota superata" come un normale risultato operativo, non come un arresto anomalo.

Una buona automazione controlla anche che la cartella di destinazione esista. In caso contrario, creala con una chiave di idempotenza affinché i nuovi tentativi non producano duplicati.

Flusso di caricamento REST

1. Invia POST /api/v1/drive/spaces/{space}/uploads:initiate con nome e dimensione del file, ID facoltativo della cartella e tipo MIME.
2. Invia i byte del file all’URL di caricamento restituito o agli URL multipart.
3. Invia POST /api/v1/drive/uploads/{file}:complete dopo il completamento del trasferimento.
4. Se il trasferimento non riesce, chiama POST /api/v1/drive/uploads/{file}:abort per liberare rapidamente la prenotazione.

Usa una Idempotency-Key per la richiesta iniziale che riserva la capacità. Usa una chiave stabile per ogni file logico, come invoice-2026-05-001-upload. Non presumere che ogni endpoint successivo riproduca risultati idempotenti; conserva l’ID del file restituito e controllane lo stato prima di ritentare il completamento o annullare un trasferimento.

Flusso di caricamento MCP

Per gli agenti, preferisci un solo strumento:

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

Il wrapper MCP gestisce negoziazione, trasferimento, completamento e annullamento in caso di errore. Sono disponibili strumenti di basso livello per logiche personalizzate, ma la maggior parte dei flussi non ne ha bisogno.

Convenzioni per nomi e cartelle

Usa nomi prevedibili per consentire alle persone di esplorare Drive in seguito:

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

Se un agente carica più versioni, includi timestamp o etichette di versione. Evita di nascondere il significato caricando final.pdf ogni settimana.

Gestione degli errori

Pianifica questi casi:

Dopo il caricamento

Se il file è destinato all’esterno, crea un link di condivisione con scadenza e limite di download. Se è interno, lascialo come normale file Drive. In entrambi i casi, controlla Agenti IA e API → Registro di audit per confermare token e sequenza di azioni.