Usa le richieste condizionate

Le richieste condizionali ti permettono di far dipendere un'operazione dallo stato corrente del file di destinazione, quindi la richiesta ha effetto solo se il file si trova nello stato che ti aspetti. Questo ti permette di evitare trasferimenti sprecati, di evitare aggiornamenti persi da parte di autori concorrenti e di creare o cancellare file in modo sicuro.

Files API 3.0 supporta i quattro standard intestazioni condizionali HTTP provenienti dall'RFC 9110.

If-Modified-Since e If-Unmodified-Since si applicano solo alle operazioni di lettura (GET e HEAD). Non sono supportate né in upload né in fase di eliminazione.

Quando la condizione non è soddisfatta, il server non esegue l'operazione e restituisce uno dei seguenti stati:

• 304 Not Modified, quando una richiesta GET o HEAD con If-None-Match o If-Modified-Since fallisce. Conferma che la tua copia cache è ancora valida, quindi non c'è bisogno di inviare di nuovo il file.
• 412 Precondition Failed, quando qualsiasi altra condizione fallisce. L’operazione di lettura, caricamento o cancellazione non viene eseguita.

Validatori: ETag e Last-Modified

Una richiesta condizionale confronta un validator che fornisci con quello attuale del file. L'API Files restituisce entrambi i validatori come intestazioni di risposta, così puoi catturarli e usarli in una richiesta successiva:

• ETag: un identificatore opaco per il contenuto attuale del file. Memorizza il valore esatto restituito dal server, comprese le virgolette circostanti, e invialo invariato. Non eseguire il parsing di essa o costruirla.
• Last-Modified: la data dell'ultima modifica del file, come data HTTP.

Entrambi i validatori vengono restituiti nelle risposte GET e HEAD. ETag viene inoltre restituito su PUT e nella risposta multipart complete-upload.

Last-Modified ha una precisione di un secondo. If-Modified-Since e If-Unmodified-Since non possono rilevare diversi cambiamenti fatti nello stesso secondo, quindi non affidarti a loro per un controllo preciso della concorrenza. Usare ETag con If-Match o If-None-Match invece.

Letture condizionali

Su GET e HEAD, tutte e quattro le intestazioni condizionali vengono rispettate. L'uso più comune è la rivalidazione della cache: hai una copia precedentemente scaricata e vuoi che il server invii di nuovo i byte solo se sono stati modificati.

Invia If-None-Match con la ETag della copia memorizzata nella cache, o If-Modified-Since con l'ultima volta che l'hai recuperata. Se il file rimane invariato, il server restituisce 304 Not Modified senza corpo e tu continui a usare la copia nella cache. Se è cambiato, il server torna 200 OK con i nuovi contenuti.

Per rivalidare un file memorizzato nella cache, invia il relativo ETag e scarica il corpo solo se il file è cambiato:

GET /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

304 Not Modified

Gli altri due header di read affermano la condizione opposta. If-Match restituisce il file solo se il suo ETag corrisponde ancora, e altrimenti restituisce 412. If-Unmodified-Since lo restituisce solo se il file non è cambiato dall'ora specificata, e altrimenti restituisce 412.

Puoi inviare al massimo due header condizionali in un'operazione di lettura. Le richieste che superano il limite non sono supportate. Quando ne invii due, la loro precedenza segue la RFC 9110.

operazioni di scrittura condizionate

Su PUT, puoi usare If-None-Match e If-Match per tutelare un caricamento rispetto allo stato corrente del file:

• If-None-Match: * salva il file solo se non esiste già. Questo garantisce che il caricamento non sovrascriva accidentalmente un altro upload, facendo perdere i suoi dati, il che è una variante del problema dell'aggiornamento perso. Se un file esiste già nel percorso, la richiesta restituisce 412 Precondition Failed.
• If-Match: <etag> Previene il problema dell'aggiornamento perso. Controlla che il caricamento non sovrascriva un'altra modifica apportata da quando hai recuperato il file. Il caricamento ha successo solo se il ETag corrente del file corrisponde a quello che fornisci. Altrimenti, la richiesta restituisce 412 Precondition Failed. Se non esiste alcun file sul percorso, la richiesta restituisce 404.

Per creare un file solo se non esiste già, invia If-None-Match: *:

PUT /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-None-Match: *
Content-Type: application/octet-stream
<binary data>

200 OK

Per sovrascrivere un file solo se è ancora la versione che hai recuperato l'ultima volta, invia il suo ETag con If-Match:

PUT /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Content-Type: application/octet-stream
<binary data>

200 OK

Le seguenti forme non sono supportate su PUT: un elenco di ETag, If-Match: *, If-None-Match con uno specifico ETag, If-Modified-Since e If-Unmodified-Since.

Per un caricamento multiparte, invia l'intestazione condizionale nella chiamata initiate-upload. Files API lo memorizza e lo valuta al completamento del caricamento, quindi la condizione si applica al file assemblato finale. Puoi usare le stesse due intestazioni come su PUT: If-None-Match: * e If-Match: <etag>. Le intestazioni condizionali nella chiamata complete-upload o abort-upload stessa non sono supportate.

Cancellazioni condizionali

DELETE è idempotente. L'eliminazione di un file che non esiste restituisce comunque 204 No Content. Questo rende la pulizia semplice, ma un semplice DELETE non può dirti se hai rimosso la versione che intendevi. Per rendere un'eliminazione condizionale, invia If-Match:

• If-Match: <etag> elimina il file solo se il suo ETag corrente corrisponde a quello che fornisci. Se un altro utente ha modificato il file dopo averlo recuperato, la richiesta restituisce 412 Precondition Failed invece di rimuovere la sua modifica. Se il file non esiste più, la richiesta restituisce 404.
• If-Match: * Cancella il file solo se esiste. La richiesta restituisce 204 se il file esisteva e 404 se no.

DELETE /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

204 No Content

Le restanti intestazioni condizionali (If-None-Match, If-Unmodified-Since e DELETE) non sono supportate su If-Modified-Since.