Guida rapida all’API Drive per sviluppatori

Questa guida mostra il percorso più sicuro da "Voglio un’integrazione" a una chiamata funzionante all’API Drive. Creerai un token ristretto, elencherai gli spazi Drive, caricherai un file e creerai un link pubblico con data di scadenza.

1. Crea un token Drive

Apri Agenti IA e API → Token → Crea token. Assegna al token un nome chiaro, come drive-report-uploader. Seleziona solo gli ambiti necessari al tuo flusso di lavoro.

Per questa guida, usa:

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

Non includere ambiti di eliminazione definitiva nella prima integrazione. Usa un token di manutenzione separato per questa operazione.

Copia il token subito dopo la creazione. TrekMail mostra il testo in chiaro una sola volta e conserva soltanto un hash sicuro.

2. Imposta URL di base e token

export TREKMAIL_BASE_URL="https://trekmail.net"
export TREKMAIL_API_TOKEN="tm_live_your_token"

Ogni richiesta usa la stessa intestazione bearer:

-H "Authorization: Bearer $TREKMAIL_API_TOKEN"

3. Elenca gli spazi Drive disponibili

curl -s "$TREKMAIL_BASE_URL/api/v1/drive/spaces" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN"

La risposta include Drive dell’account e gli spazi Drive delle caselle che il token può vedere. Usa account per Drive dell’account negli esempi successivi.

4. Crea una cartella

Le operazioni di scrittura devono includere una chiave di idempotenza. Se la rete ripete la richiesta, TrekMail può restituire il risultato originale senza creare duplicati.

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/spaces/account/folders" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: folder-$(date +%s)" \
  -d '{"name":"API Uploads","color":"#2563eb"}'

Salva l’ID della cartella restituito.

5. Carica un file

L’API REST separa la negoziazione del caricamento dal trasferimento del file. Prima avvia il caricamento:

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/spaces/account/uploads:initiate" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: upload-report-001" \
  -d '{"name":"report.pdf","size_bytes":123456,"folder_id":42,"client_mime":"application/pdf"}'

TrekMail restituisce le istruzioni. Invia i byte all’URL di caricamento restituito, quindi chiama:

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/uploads/{FILE_ID}:complete" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Se usi MCP, preferisci drive_file_upload. Lo strumento riunisce avvio, trasferimento, completamento e annullamento.

6. Crea un link di condivisione

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/files/{FILE_ID}/share-links" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: share-report-001" \
  -d '{"expires_at":"2026-06-01T00:00:00Z","max_downloads":25}'

L’URL pubblico restituito è l’unico momento in cui viene mostrato il token grezzo del link. Salvalo ora se devi inviarlo in seguito.

7. Controlla la traccia di audit

Apri Agenti IA e API → Log di audit e filtra per token. Dovresti vedere creazione della cartella, caricamento, completamento e creazione del link. È il modo più rapido per confermare che l’integrazione usa il token e gli ambiti previsti.

Lista di controllo per la produzione

• Usa un token per ogni integrazione.
• Concedi lettura, scrittura e condivisione separatamente; escludi l’eliminazione definitiva dai flussi quotidiani.
• Aggiungi scadenza e limiti di download ai link pubblici.
• Usa una chiave di idempotenza quando richiesta dalla documentazione dell’endpoint o dalla specifica OpenAPI. In questo flusso comprende creazione della cartella, avvio del caricamento e creazione del link.
• Revoca i token di test dopo lo sviluppo.