Aller au contenu principal

Comment fonctionne le Drive

Cette page explique le modèle drive et les mécaniques derrière chaque opération Drive : comment fichiers et dossiers s'imbriquent en arbre, comment fonctionnent l'accès et les rôles de participants, comment se comportent la navigation et la recherche, comment fonctionnent les téléchargements par URL signée, et le flux d'upload multipart en trois étapes en détail. Pour une orientation rapide et des exemples à copier-coller, commencez par l'introduction Drive.

Le modèle drive​

Drive contient deux types d'éléments :

  • Fichiers — documents, images, vidéos et autres contenus binaires envoyés. Chacun a un mimeType et une size.
  • Dossiers — conteneurs qui regroupent des fichiers et d'autres dossiers.

Les éléments s'imbriquent via un parentId, construisant un arbre de type système de fichiers :

Project Assets (folder)
├── Designs (folder)
│   ├── logo.png
│   └── banner.jpg
└── report.pdf

Les éléments sans parent se trouvent à la racine du drive.

Modèle d'accès​

L'accès suit la propriété et le partage. Avec un Personal Access Token, l'API ne renvoie que les éléments que l'utilisateur authentifié possède ou qui lui ont été partagés. Les participants partagés portent un rôle qui régit ce qu'ils peuvent faire :

  • admin — accès complet, y compris la gestion des participants.
  • member — peut envoyer, télécharger, créer des dossiers et modifier le contenu.
  • viewer — accès en lecture seule (voir les métadonnées et télécharger les fichiers).

Parcourir et rechercher​

  • Tree — parcourt la hiérarchie en largeur d'abord. Omettez parentId pour les éléments de niveau racine, ou passez un id de dossier pour son sous-arbre ; contrôlez la profondeur avec depth (1–10, défaut 3). Chaque nœud a un flag hasChildren pour les explorateurs en chargement paresseux, et la réponse est plafonnée à 500 éléments (avec nextParentIds pour continuer en cas de troncature).
  • Search — recherche full-text dans les éléments accessibles par q, avec sortBy, sortOrder et limit optionnels (1–50, défaut 20).
  • Get file — renvoie les métadonnées d'un fichier ou dossier unique.

Télécharger des fichiers​

Appelez l'endpoint …/download du fichier pour obtenir une URL signée à durée limitée ({ "url": "…" }). Récupérez le fichier avec un GET HTTP simple contre cette URL. Les téléchargements s'appliquent aux fichiers, pas aux dossiers.

Créer des dossiers​

POST un name, avec un parentId optionnel pour imbriquer le dossier dans un autre. La réponse est le nouvel élément dossier.

Envoyer des fichiers (flux multipart)​

Les uploads utilisent un flux multipart de style S3, afin que les fichiers de toute taille s'envoient de façon fiable en se découpant en parties qui vont directement vers le stockage. Il y a trois appels d'API ; les octets des parties sont PUT directement vers le stockage, pas via Copera.

Étape 1 — Démarrer​

POST les métadonnées du fichier pour commencer l'upload :

{
  "fileName": "report.pdf",
  "fileSize": 5242880,
  "mimeType": "application/pdf",
  "parentId": "<optional folder id>"
}

La réponse vous donne un uploadId et un fileKey. Les deux sont requis par les deux étapes suivantes.

Étape 2 — Obtenir des URLs pré-signées​

POST l'uploadId, le fileKey, et parts — le nombre de parties que vous avez l'intention d'envoyer (un compte, pas un tableau) :

{ "uploadId": "<uploadId>", "fileKey": "<fileKey>", "parts": 3 }

Vous obtenez un tableau de { signedUrl, PartNumber }. Envoyez chaque chunk avec un HTTP PUT vers son signedUrl, et capturez l'en-tête ETag que le stockage renvoie pour chaque partie.

Étape 3 — Finaliser​

POST l'uploadId, le fileKey, et les parties collectées pour assembler le fichier et créer l'enregistrement Drive :

{
  "uploadId": "<uploadId>",
  "fileKey": "<fileKey>",
  "parts": [
    { "partNumber": 1, "eTag": "<etag-1>" },
    { "partNumber": 2, "eTag": "<etag-2>" },
    { "partNumber": 3, "eTag": "<etag-3>" }
  ]
}

La réponse est l'élément fichier créé.

note

Attention à la casse. Les corps de requête utilisent uploadId, partNumber et eTag en minuscules. La réponse des URLs pré-signées utilise signedUrl et PartNumber (P majuscule). L'ETag de chaque partie vient des en-têtes de réponse du PUT de stockage — vous le repassez en finalize comme eTag.

astuce

Si vous n'avez pas besoin d'un contrôle fin, le drive upload de la CLI exécute tout ce flux pour vous, y compris les envois de répertoires.

Authentification et scope​

Les endpoints drive exigent un Personal Access Token (cp_pat_) avec le scope access_drive. Un token sans ce scope obtient un 403. Voir Authentification.

Référence​