Usa le chiavi di idempotenza per i caricamenti API

L’idempotenza di dosya si applica alla route PUT /api/upload/file per il caricamento con una sola richiesta. Invia un valore UUID v4 in X-Dosya-Idempotency-Key; le route di sessione multipart prevedono la ripresa per numero di parte.

Prima di iniziare

• Genera un nuovo UUID v4 per un singolo caricamento logico e conservalo con il processo fino alla verifica del risultato.
• Mantieni invariati spazio di lavoro, cartella, nome file originale e Content-Length nei tentativi: questi valori formano l’impronta della richiesta.
• Prima di abilitare i tentativi automatici, verifica che il corpo della richiesta possa essere inviato di nuovo.

Passaggi

1. Crea un UUID v4 come 3fa85f64-5717-4562-b3fc-2c963f66afa6 e associalo al percorso locale di origine e alla destinazione prevista.
2. Invia PUT /api/upload/file?file_name=report.pdf&folder_id=folder_id con Content-Length esatto, chiave bearer, corpo e X-Dosya-Idempotency-Key.
3. Quando ricevi la risposta HTTP 201, conserva la ricevuta del file restituita. Il server conserva il record di idempotenza completato per 86.400 secondi, quindi un tentativo corrispondente può recuperare la risposta.
4. Dopo un errore di trasporto dall’esito incerto, ripeti la richiesta identica con la stessa chiave. HTTP 200 con X-Dosya-Idempotent-Replay: true significa che dosya ha restituito il risultato precedente senza creare un secondo file.
5. Se ricevi HTTP 409 con Retry-After: 5, un’altra richiesta corrispondente è ancora in corso. Attendi e riprova; la titolarità di un’operazione in corso abbandonata può essere assunta da un altro processo dopo 600 secondi.
6. Se ricevi 409 con codice idempotency_key_reused, fermati. La chiave era associata a spazio di lavoro, cartella, nome file originale o lunghezza dichiarata diversi; genera una nuova chiave solo per un caricamento logico davvero nuovo.

Risultato previsto

Il primo caricamento accettato restituisce 201. Una ripetizione identica restituisce lo stesso risultato logico con stato 200 e intestazione di ripetizione, mentre una richiesta con un’impronta diversa viene rifiutata senza creare dati dall’esito incerto.

Risoluzione dei problemi

Il corpo non può essere inviato di nuovo. Salvalo in un file temporaneo prima di inviare la richiesta oppure disabilita i tentativi automatici.

La risposta è 409 senza il codice di riutilizzo. Rispetta Retry-After: 5; non creare una nuova chiave mentre l’operazione originale potrebbe ancora terminare.

I byte del file sono cambiati ma la lunghezza no. Usa X-Dosya-Sha256 per verificare l’integrità e una nuova chiave di idempotenza per il nuovo caricamento logico.

Guide correlate

• Carica tramite API
• Guida rapida all’API REST