Completa e verifica un caricamento API

Il completamento multipart trasforma le parti caricate in un record di file. Si applica solo se la creazione della sessione ha restituito un oggetto resumable non nullo; un piccolo caricamento con una sola PUT termina invece sull’URL di caricamento.

Prima del completamento

Carica le parti su PUT /api/upload/:sessionId/part/:partNumber. I numeri delle parti iniziano da 1 e non possono superare total_parts. Prepara ogni corpo, tranne l’ultimo, con l’esatta dimensione part_size restituita; l’ultimo non deve essere vuoto e può essere più corto. La dimensione attuale è 10 MiB e nessun corpo può superare tale limite. Ripetere un numero di parte già accettato restituisce already_uploaded:true con l’ETag archiviato invece di inviare di nuovo i byte.

GET /api/upload/:sessionId/status riporta status, size_bytes, part_size, total_parts, bytes_uploaded, l’array numerico uploaded_parts e has_multipart. Il suo file_id rimane nullo fino al completamento riuscito.

Passaggi

1. Recupera lo stato della sessione e confronta uploaded_parts con ogni numero da 1 a total_parts.
2. Reinvia solo le parti mancanti, rispettando la dimensione esatta part_size delle parti non finali e accettando already_uploaded:true come conferma del successo di un tentativo precedente.
3. Chiama POST /api/upload/:sessionId/complete senza corpo JSON dopo che tutte le parti richieste sono presenti.
4. Salva dalla risposta HTTP 201 file.id, size_bytes effettivo, version, etag, nome, estensione, tipo MIME, regione e ora di creazione.
5. Se perdi la risposta di completamento, richiedi lo stato prima di riprovare; status:"complete" e il suo file_id non nullo permettono di recuperare l’esito.
6. Esegui GET /api/files/:fileId con una credenziale abilitata alla lettura o verifica il risultato in dosya, poi confronta destinazione, nome file e numero effettivo di byte.

Risposte al completamento

Un completamento multipart riuscito restituisce content_hash:null e hash_verified:false. Quel valore booleano significa che le parti assemblate non sono state confrontate con un digest del client; non indica una mancata corrispondenza del checksum.

dosya rifiuta una sessione sconosciuta con Upload session not found. Restituisce No multipart upload in progress - upload at least one part first se non esiste un multipart nello spazio di archiviazione e Only X of Y parts uploaded. Upload remaining parts before completing. per un insieme incompleto. Un completamento ripetuto restituisce 409 Upload session is already complete. Una richiesta di acquisizione scaduta può rispondere Upload session is no longer active - start the upload again.

Una sessione multipart in attesa, in caricamento o fallita diventa idonea alla pulizia dopo 24 ore senza attività; non è garantito un momento preciso per la rimozione. Una successiva inizializzazione può programmare la pulizia e il processo orario di fatturazione esegue un ciclo limitato per le sessioni basate su D1. Quelle basate su Durable Object dipendono dalla successiva attività dei membri; il ciclo di vita dello storage interrompe le sessioni multipart non completate sette giorni dopo l’avvio come tutela aggiuntiva.

Per gli spazi di lavoro basati su D1, il processo di fatturazione rimuove le righe delle sessioni completate e fallite dopo sette giorni: il recupero di una risposta persa tramite lo stato è quindi limitato a tale periodo. Il percorso di pulizia citato non stabilisce lo stesso periodo di conservazione per le sessioni basate su Durable Object; recupera subito una ricevuta persa finché la route di stato trova la sessione. Le righe in attesa hanno una soglia separata di 600 secondi nei percorsi di pulizia e uno slot di trasferimento della credenziale non rinnovato si ripristina dopo 15 minuti. Il completamento libera lo slot. La scrittura finale nello storage e nel database non può essere annullata tramite la sessione; la rimozione successiva usa il normale flusso di cestino e cancellazione definitiva dei file.

Un file attivo con lo stesso nome può essere adottato come nuova versione. Usa un nome di destinazione univoco se serve un file separato.

Risultato previsto

Una risposta HTTP 201 identifica il file completato e riporta i byte conteggiati dalle parti caricate. Una successiva richiesta di stato restituisce status:"complete" e lo stesso identificatore del file.

Guide correlate

• Carica tramite API
• Guida rapida all’API REST