Démarrage rapide de l’API Drive pour les développeurs

Ce guide présente le chemin le plus sûr pour passer de « Je veux une intégration » à un appel fonctionnel de l’API Drive. Vous allez créer un jeton restreint, répertorier les espaces Drive, importer un fichier et créer un lien de partage public avec une date d’expiration.

1. Créer un jeton Drive

Ouvrez Agents IA et API → Jetons → Créer un jeton. Donnez-lui un nom clair, par exemple drive-report-uploader. Sélectionnez uniquement les portées requises par votre workflow.

Pour ce guide, utilisez :

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

N’incluez pas de portées de purge pour une première intégration. Réservez la suppression définitive à un jeton de maintenance distinct.

Copiez le jeton immédiatement après sa création. TrekMail n’affiche sa valeur en clair qu’une fois et ne stocke qu’un hachage sécurisé.

2. Définir l’URL de base et le jeton

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

Chaque requête utilise le même en-tête bearer :

-H "Authorization: Bearer $TREKMAIL_API_TOKEN"

3. Répertorier les espaces Drive disponibles

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

La réponse inclut le Drive du compte et tous les espaces Drive de boîtes aux lettres visibles par le jeton. Utilisez account pour le Drive du compte dans les exemples suivants.

4. Créer un dossier

Les opérations d’écriture doivent inclure une clé d’idempotence. Si votre réseau relance la requête, TrekMail peut renvoyer le résultat initial plutôt que créer des doublons.

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"}'

Enregistrez l’ID du dossier renvoyé.

5. Importer un fichier

L’API REST sépare la négociation de l’import du transfert du fichier. Commencez par initialiser :

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 renvoie les instructions d’import. Envoyez les octets à l’URL d’import renvoyée, puis appelez :

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 '{}'

Si vous utilisez MCP, privilégiez drive_file_upload. Cet outil regroupe les étapes d’initialisation, de transfert, de finalisation et d’annulation.

6. Créer un lien de partage

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 publique renvoyée est la seule occasion où le jeton brut du lien est affiché. Enregistrez-la maintenant si vous devez l’envoyer plus tard.

7. Vérifier la piste d’audit

Ouvrez Agents IA et API → Journal d’audit et filtrez par jeton. Vous devriez voir la création du dossier, l’import, la finalisation et la création du lien de partage. C’est le moyen le plus rapide de confirmer que votre intégration utilise le jeton et les portées attendus.

Liste de contrôle pour la production

• Utilisez un jeton par intégration.
• Accordez séparément la lecture, l’écriture et le partage; excluez la purge des workflows quotidiens.
• Ajoutez une expiration et des limites de téléchargement aux liens publics.
• Utilisez une clé d’idempotence lorsque la documentation de l’endpoint ou la spécification OpenAPI l’exige. Dans ce flux, cela inclut la création du dossier, l’initialisation de l’import et la création du lien de partage.
• Révoquez les jetons de test après le développement.

Articles connexes

• Présentation de l’API Drive
• Automatiser l’import de fichiers avec l’API Drive
• Guide de l’API et de MCP pour les liens de partage