Zum Hauptinhalt springen

So funktioniert Drive

Diese Seite erklärt das Drive-Modell und die Mechanik hinter jeder Drive-Operation: wie Dateien und Ordner in einen Baum nesten, wie Zugriff und Teilnehmerrollen wirken, wie Browsen und Suche sich verhalten, wie Downloads per signierter URL funktionieren und der dreistufige Multipart-Upload-Flow im Detail. Für eine schnelle Orientierung und Copy-Paste-Beispiele beginnen Sie mit der Drive-Einführung.

Das Drive-Modell​

Drive hält zwei Arten von Einträgen:

  • Dateien — hochgeladene Dokumente, Bilder, Videos und andere binäre Inhalte. Jede hat mimeType und size.
  • Ordner — Container, die Dateien und andere Ordner gruppieren.

Einträge nesten über eine parentId und bauen einen dateisystemartigen Baum:

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

Einträge ohne Parent sitzen an der Drive-Wurzel.

Zugriffsmodell​

Zugriff folgt Besitz und Freigabe. Mit einem Personal Access Token liefert die API nur Einträge, die der authentifizierte Benutzer besitzt oder die mit ihm geteilt wurden. Geteilte Teilnehmer tragen eine Rolle, die steuert, was sie tun dürfen:

  • admin — voller Zugriff, inklusive Teilnehmer verwalten.
  • member — kann hochladen, herunterladen, Ordner anlegen und Inhalte ändern.
  • viewer — nur Lesezugriff (Metadaten ansehen und Dateien herunterladen).

Browsen und Suche​

  • Tree — durchläuft die Hierarchie breadth-first. parentId weglassen für Root-Einträge oder eine Ordner-ID für deren Teilbaum übergeben; Tiefe mit depth steuern (1–10, Standard 3). Jeder Knoten hat ein Flag hasChildren für lazy-loading Explorer; die Antwort ist auf 500 Einträge begrenzt (mit nextParentIds zur Fortsetzung bei Truncation).
  • Search — Volltextsuche über zugängliche Einträge per q, optional mit sortBy, sortOrder und limit (1–50, Standard 20).
  • Get file — liefert Metadaten für eine einzelne Datei oder einen Ordner.

Dateien herunterladen​

Rufen Sie den …/download-Endpunkt der Datei auf, um eine zeitlich begrenzte signierte URL ({ "url": "…" }) zu erhalten. Holen Sie die Datei mit einem einfachen HTTP-GET gegen diese URL. Downloads gelten für Dateien, nicht für Ordner.

Ordner anlegen​

POST mit name, optional mit parentId, um den Ordner in einen anderen zu nesten. Die Antwort ist der neue Ordner-Eintrag.

Dateien hochladen (Multipart-Flow)​

Uploads nutzen einen S3-artigen Multipart-Flow, sodass Dateien jeder Größe zuverlässig hochgeladen werden, indem sie in Parts aufgeteilt und direkt an den Speicher gehen. Es gibt drei API-Aufrufe; die eigentlichen Part-Bytes werden per PUT direkt an den Speicher gesendet, nicht über Copera.

Schritt 1 — Start​

POST der Datei-Metadaten, um den Upload zu beginnen:

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

Die Antwort liefert eine uploadId und einen fileKey. Beide sind für die nächsten beiden Schritte erforderlich.

Schritt 2 — Presigned URLs holen​

POST mit uploadId, fileKey und parts — der Anzahl der Parts, die Sie hochladen wollen (eine Zahl, kein Array):

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

Sie erhalten ein Array von { signedUrl, PartNumber }. Laden Sie jeden Chunk per HTTP-PUT an seine signedUrl hoch und erfassen Sie den Header ETag, den der Speicher für jeden Part zurückgibt.

Schritt 3 — Finalize​

POST mit uploadId, fileKey und den gesammelten Parts, um die Datei zusammenzusetzen und den Drive-Eintrag zu erzeugen:

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

Die Antwort ist der erzeugte Datei-Eintrag.

hinweis

Achten Sie auf die Groß-/Kleinschreibung. Request-Bodies verwenden kleingeschriebenes uploadId, partNumber und eTag. Die Presigned-URLs-Antwort verwendet signedUrl und PartNumber (großes P). Der ETag jedes Parts kommt aus den Response-Headern des Storage-PUT — Sie geben ihn in Finalize als eTag zurück.

tipp

Wenn Sie keine feingranulare Kontrolle brauchen, führt drive upload der CLI den gesamten Flow für Sie aus, inklusive Verzeichnis-Uploads.

Authentifizierung & Scope​

Drive-Endpunkte erfordern ein Personal Access Token (cp_pat_) mit dem Scope access_drive. Ein Token ohne Scope erhält 403. Siehe Authentifizierung.

Referenz​