Automatiser le téléversement de fichiers avec l’API Drive
Automatisez les téléversements Drive avec des clés d’idempotence, le contrôle du quota, les envois multiparties, les outils MCP et la gestion des échecs.
Détails de l’article
Type, difficulté, forfaits et date de dernière mise à jour.
▼
Détails de l’article
Type, difficulté, forfaits et date de dernière mise à jour.
- Type
- Référence
- Difficulté
- Intermédiaire
- Forfaits
- Starter · Pro · Agency · + Drive Add-on
- Dernière mise à jour
- 10 sept. 2026
L’automatisation des téléversements est l’un des flux de travail les plus utiles de l’API Drive. Les rapports, factures, exportations générées, PDF signés et pièces jointes d’assistance peuvent arriver dans le bon dossier TrekMail Drive sans glisser-déposer manuel.
La méthode sûre est simple : vérifiez le stockage, créez ou choisissez un dossier, lancez le téléversement, transférez les octets, terminez le téléversement et consignez une piste d’audit utile.
Portées recommandées
Pour les téléversements dans le Drive du compte, commencez par :
drive:account:readdrive:account:write
Pour les téléversements dans le Drive d’une boîte aux lettres, utilisez :
drive:mailbox:readdrive:mailbox:write
Évitez les droits de partage et de purge, sauf si le même flux de travail en a réellement besoin. Si la tâche de téléversement crée aussi des liens publics, ajoutez le droit de partage correspondant.
Vérifications préalables
Avant de téléverser un fichier volumineux, appelez l’endpoint de résumé du stockage ou d’utilisation de l’espace. Votre intégration doit traiter le « quota dépassé » comme un résultat métier normal et non comme un plantage.
Une bonne automatisation vérifie également que le dossier de destination existe. Sinon, créez-le avec une clé d’idempotence afin que les nouvelles tentatives ne créent pas de dossiers en double.
Flux de téléversement REST
- Envoyez
POST /api/v1/drive/spaces/{space}/uploads:initiateavec le nom et la taille du fichier, l’ID facultatif du dossier et le type MIME. - Envoyez les octets du fichier à l’URL de téléversement ou aux URL multiparties renvoyées.
- Envoyez
POST /api/v1/drive/uploads/{file}:completeune fois le transfert réussi. - Si le transfert échoue, appelez
POST /api/v1/drive/uploads/{file}:abortpour libérer rapidement la réservation.
Utilisez une Idempotency-Key pour la demande d’initialisation, qui réserve la capacité de téléversement. Utilisez une clé stable par fichier logique, telle que invoice-2026-05-001-upload. Ne supposez pas que chaque endpoint de téléversement ultérieur reproduit les résultats idempotents. Conservez l’ID de fichier renvoyé et vérifiez son état avant de retenter la finalisation ou d’annuler un transfert.
Flux de téléversement MCP
Pour les agents, privilégiez un seul outil :
drive_file_upload(space="account", local_path="/exports/report.pdf", folder_id=42)
L’enveloppe MCP gère la négociation du téléversement, le transfert, la finalisation et l’annulation en cas d’erreur. Des outils de bas niveau sont disponibles pour une logique de transfert personnalisée, mais la plupart des flux de travail n’en ont pas besoin.
Conventions de nommage et de dossiers
Utilisez des noms prévisibles pour permettre aux utilisateurs de parcourir Drive par la suite :
Reports/2026/05/monthly-summary.pdfClients/Acme/contracts/acme-renewal-2026.pdfInvoices/2026/INV-2026-0042.pdf
Si un agent téléverse plusieurs versions, ajoutez des horodatages ou des étiquettes de version. Évitez de masquer le sens en téléversant final.pdf chaque semaine.
Gestion des échecs
Prévoyez les cas suivants :
| Problème | Réponse suggérée |
|---|---|
| Il manque un droit au jeton | Arrêtez et demandez un jeton doté du droit Drive manquant |
| Quota dépassé | Indiquez l’utilisation actuelle et ajoutez un lien vers la documentation du stockage ou du module complémentaire |
| URL de téléversement expirée | Actualisez les parties ou recommencez le téléversement |
| Échec du réseau pendant le transfert | Annulez la réservation et recommencez avec la même clé d’idempotence logique |
| Dossier introuvable | Répertoriez de nouveau l’arborescence; ne créez la destination que si le flux de travail l’autorise |
Après le téléversement
Si le fichier est destiné à une livraison externe, créez un lien de partage avec une date d’expiration et un plafond de téléchargements. S’il est interne, conservez-le comme fichier Drive normal. Dans les deux cas, consultez Agents IA et API → Journal d’audit pour confirmer le jeton et la séquence d’actions.
Articles connexes
Articles similaires
Accédez aux guides voisins qui prolongent votre démarche.