Guida all'API Files

I file (chiamati risorse in alcuni schemi) contengono le evidenze allegate alle Schede: immagini, PDF, documenti e artefatti di scansione. Un file può essere allegato direttamente a una Scheda oppure usato come valore di un campo di tipo risorsa.

Sono disponibili due modalità di caricamento: una semplice richiesta POST singola per i file di piccole dimensioni e il protocollo tus ripristinabile per quelli di grandi dimensioni. Schemi completi: riferimento API.

Panoramica degli endpoint

Operazione	Metodo e percorso
Caricamento semplice	POST /api/v1/files
Caricamento ripristinabile (tus)	POST /api/v1/files/upload, quindi PATCH /api/v1/files/upload/{id}
Finalizzazione dei caricamenti tus	POST /api/v1/files/finalize
Download	GET /api/v1/files/{resource_id}/download
URL firmati	POST /api/v1/files/urls
Ricerca dei file	GET /api/v1/files/search
Elenco dei file (cursore)	GET /api/v1/files
Elenco dei file di una Scheda	GET /api/v1/threads/{thread_id}/files

Le richieste relative ai file richiedono un’appartenenza attuale al Team selezionato, che deve appartenere all’organizzazione selezionata. Questo vale sia per le persone sia per i Service Account. Il caricamento in una Scheda richiede l’accesso in modifica; i caricamenti privati devono essere destinati a una Scheda e richiedono l’autorizzazione a gestirne le risorse private. I file non allegati sono leggibili dal Team proprietario solo quando non sono privati.

Caricamento semplice

Per i file che possono essere gestiti agevolmente da una singola richiesta, invia una richiesta POST multipart/form-data con file e le destinazioni facoltative dell’allegato. La risposta include la risorsa creata con un URL firmato:

curl

curl -fsS "$APID_URL/api/v1/files" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -F "file=@inspection-report.pdf" \
  -F "threadId=$THREAD_ID"

TypeScript

const resources = await client.files.upload({
  file,               // a File
  threadId,           // optional: attach to a Thread
  // fieldId,         // optional: attach as a field value
  // isPrivate: true, // optional
});

fieldId allega il file come valore di un campo di tipo risorsa; isPrivate ne limita la visibilità.

Caricamento ripristinabile (tus)

I file di grandi dimensioni utilizzano il protocollo di caricamento ripristinabile tus 1.0 in /api/v1/files/upload, seguito da una chiamata di finalizzazione che trasforma il caricamento completato in un registro della risorsa. Il flusso è: caricamento → finalizzazione → già allegato oppure allegato tramite i campi.

1. Crea il caricamento. Invia una richiesta POST con le intestazioni tus; i valori di Upload-Metadata sono codificati in base64 e filename è obbligatorio (fieldId, threadId e isPrivate sono facoltativi):

   curl -i -X POST "$APID_URL/api/v1/files/upload" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Length: 52428800" \
     -H "Upload-Metadata: filename $(printf 'video.mp4' | base64),threadId $(printf %s "$THREAD_ID" | base64)"
   # → 201 Created
   # → Location: …/api/v1/files/upload/<upload-id>

   Conserva <upload-id> restituito in Location per la finalizzazione. La risposta finale fornisce l’ID permanente della risorsa, che può essere diverso. Dichiara la Scheda, il campo e il livello di privacy previsti al momento della creazione; non possono essere modificati durante la finalizzazione. Upload-Length deve essere un numero di byte positivo e noto.

2. Invia i byte (operazione ripristinabile: richieste PATCH ripetute proseguono da Upload-Offset):

   curl -i -X PATCH "$APID_URL/api/v1/files/upload/$UPLOAD_ID" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Offset: 0" \
     -H "Content-Type: application/offset+octet-stream" \
     --data-binary @video.mp4

   Le richieste di caricamento tollerano pause di inattività più lunghe. Per riprendere dopo un’interruzione, invia una richiesta HEAD allo stesso URL per leggere il valore corrente di Upload-Offset, quindi invia una richiesta PATCH a partire da tale posizione. Qualsiasi libreria client tus 1.0, ad esempio tus-js-client, gestisce questo protocollo al posto tuo.

3. Finalizza. I caricamenti diventano registri delle risorse solo dopo la finalizzazione:

   curl -fsS "$APID_URL/api/v1/files/finalize" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Content-Type: application/json" \
     -d '{
       "threadId": "'"$THREAD_ID"'",
       "requests": [
         { "resId": "'"$UPLOAD_ID"'", "filename": "video.mp4", "size": 52428800 }
       ]
     }'

   POST /api/v1/files/finalize accetta più caricamenti contemporaneamente; ogni elemento della richiesta usa l’ID del caricamento tus come resId, insieme a filename e size (fieldId e isPrivate sono facoltativi). Il nome del file, le dimensioni, la Scheda, il campo e il livello di privacy devono corrispondere alla richiesta di creazione del caricamento. Usa la stessa identità autenticata e lo stesso contesto di organizzazione/Team per la creazione, i blocchi di dati, le richieste HEAD e DELETE e la finalizzazione. Le sessioni di caricamento scadono sette giorni dopo la creazione. Possono essere finalizzati solo i caricamenti completati.

   Se si ripete una finalizzazione identica entro tale intervallo, vengono restituite le risorse originali con nuovi URL firmati. Un batch deve contenere esclusivamente nuovi caricamenti completati oppure esclusivamente caricamenti già finalizzati. I caricamenti finalizzati non possono essere modificati con PATCH né terminati tramite tus.

Nota

Gli endpoint tus utilizzano il protocollo di comunicazione tus anziché JSON, quindi sono riportati solo sinteticamente nel riferimento API. Il comportamento descritto sopra è definito dalla configurazione tus del server (/upload e /upload/{id} sotto /api/v1/files).

Download e URL firmati

• GET /api/v1/files/{resource_id}/download — reindirizza a un URL firmato per il file.
• POST /api/v1/files/urls?ids=<id>&ids=<id> — genera URL firmati di breve durata per l’accesso diretto all’archiviazione degli oggetti; usali quando un browser o un sistema a valle deve accedere ai byte senza passare attraverso un proxy.

Attenzione

Gli URL firmati scadono. Memorizza gli ID delle risorse, mai gli URL firmati: richiedi nuovamente gli URL quando ti serve un accesso aggiornato.

Ricerca ed elenchi

Sono disponibili due modalità di interrogazione:

• GET /api/v1/files/search — ricerca indicizzata per pagina con q, threadId, mimeFilters e includeArchived.
• GET /api/v1/files — elenco con paginazione tramite cursore (cursor, pageSize; includeArchived è obbligatorio), filtrato per threadId o createdBy.

Per i file nel contesto di una singola Scheda, usa preferibilmente GET /api/v1/threads/{thread_id}/files (consulta la guida alle Schede).

Pagine correlate

• Guida all’API Threads — allegare file ai campi e alle miniature delle Schede
• Modello principale — posizione dei file nel dominio
• Riferimento API — dettagli completi su parametri e schemi