Vai al contenuto principale

Come funziona Drive

Questa pagina spiega il modello drive e le meccaniche dietro ogni operazione Drive: come file e cartelle si annidano in un albero, come funzionano accesso e ruoli participant, come si comportano browsing e search, come funzionano i download via signed URL e il flusso multipart a tre passi in dettaglio. Per un orientamento rapido ed esempi copy-paste, parti dall'introduzione Drive.

Il modello drive​

Drive contiene due tipi di item:

  • Files — documenti caricati, immagini, video e altri contenuti binari. Ciascuno ha un mimeType e un size.
  • Folders — contenitori che raggruppano file e altre cartelle.

Gli item si annidano tramite un parentId, costruendo un albero simile a un file system:

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

Gli item senza parent stanno alla root del drive.

Modello di accesso​

L'accesso segue ownership e sharing. Con un Personal Access Token, l'API restituisce solo gli item che l'utente autenticato possiede o che gli sono stati condivisi. I participant condivisi portano un ruolo che governa cosa possono fare:

  • admin — accesso completo, inclusa la gestione dei participant.
  • member — può caricare, scaricare, creare cartelle e modificare contenuti.
  • viewer — accesso read-only (vedere metadati e scaricare file).
  • Tree — percorre la gerarchia breadth-first. Ometti parentId per gli item a livello root, oppure passa un folder id per il suo subtree; controlla la profondità con depth (1–10, default 3). Ogni nodo ha un flag hasChildren per explorer lazy-loading, e la response è limitata a 500 item (con nextParentIds per continuare quando è troncata).
  • Search — full-text search sugli item accessibili per q, con sortBy, sortOrder e limit opzionali (1–50, default 20).
  • Get file — restituisce i metadati di un singolo file o cartella.

Scaricare file​

Chiama l'endpoint …/download del file per ottenere un signed URL a tempo limitato ({ "url": "…" }). Scarica il file con un semplice HTTP GET contro quell'URL. I download si applicano ai file, non alle cartelle.

Creare cartelle​

POST un name, con un parentId opzionale per annidare la cartella dentro un'altra. La response è il nuovo folder item.

Caricare file (flusso multipart)​

Gli upload usano un flusso multipart in stile S3, così file di qualsiasi dimensione si caricano in modo affidabile dividendoli in parti che vanno direttamente allo storage. Ci sono tre chiamate API; i byte delle parti vengono PUT direttamente allo storage, non attraverso Copera.

Passo 1 — Start​

POST i metadati del file per iniziare l'upload:

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

La response ti dà un uploadId e un fileKey. Entrambi sono richiesti dai due passi successivi.

Passo 2 — Ottieni presigned URL​

POST l'uploadId, il fileKey e parts — il numero di parti che intendi caricare (un conteggio, non un array):

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

Ricevi un array di { signedUrl, PartNumber }. Carica ogni chunk con un HTTP PUT al suo signedUrl e cattura l'header ETag che lo storage restituisce per ogni parte.

Passo 3 — Finalize​

POST l'uploadId, il fileKey e le parti raccolte per assemblare il file e creare il record Drive:

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

La response è il file item creato.

nota

Attenzione al casing. I body di request usano uploadId, partNumber e eTag in minuscolo. La response dei presigned-URL usa signedUrl e PartNumber (P maiuscola). L'ETag di ogni parte arriva dagli header della response PUT allo storage — lo ripassi in finalize come eTag.

suggerimento

Se non ti serve un controllo fine-grained, drive upload della CLI esegue l'intero flusso per te, inclusi gli upload di directory.

Autenticazione e scope​

Gli endpoint Drive richiedono un Personal Access Token (cp_pat_) con lo scope access_drive. Un token senza lo scope ottiene un 403. Vedi Autenticazione.

Riferimento​