Crea una sessione di caricamento API REST

Crea una sessione di caricamento solo dopo aver individuato destinazione e limiti della credenziale. La base REST è https://api.dosya.dev/api e le richieste si autenticano con Authorization: Bearer dos_….

Requisiti

Usa una chiave Solo caricamento o Accesso completo abilitata per API REST. Una chiave vincolata a uno spazio di lavoro è compatibile con REST, una vincolata a una cartella no. Le chiavi vincolate a cartelle sono rifiutate prima della route di caricamento.

Un normale caricamento REST richiede sia upload_files sia access_upload nel ruolo dello spazio di lavoro corrente. Solo il gateway SFTP aggira il controllo sulla pagina di caricamento perché la superficie è regolata dal permesso separato access_sftp. dosya può rispondere con You don't have upload permission in this workspace o You don't have access to the upload page se uno dei due controlli del ruolo REST non passa.

Passaggi

1. Scegli lo spazio di lavoro di destinazione e, se il file va in una cartella, registra il suo identificatore fld_….
2. Invia POST /api/upload/init con JSON contenente workspace_id, file_name e il valore in byte file_size; aggiungi folder_id solo per una destinazione diversa dalla radice.
3. Aggiungi mime_type se noto. Il valore predefinito è application/octet-stream; file_id e expected_version servono per la sostituzione intenzionale di una versione, mentre force_multipart deve essere booleano.
4. Controlla nella risposta 201 lo stesso spazio di lavoro, il nome file ripulito, dimensione dichiarata, tipo MIME, estensione, regione e un nuovo session_id.
5. Leggi resumable: null indica di inviare una PUT a upload_url; un oggetto indica di usare i suoi valori part_upload_url, complete_url e status_url.
6. Conserva i dettagli della sessione con lo stato locale del trasferimento e inizia a inviare byte solo dopo aver verificato che destinazione e modalità restituite corrispondano al caricamento previsto.

Regole e limiti della richiesta

Il nome file viene ripulito prima della validazione e può contenere al massimo 255 caratteri. Fornisci un valore numerico accurato per file_size; se lo ometti, viene trattato come zero, mentre un valore negativo viene rifiutato. expected_version, se presente, deve essere un intero non negativo. force_multipart:true richiede un file più grande di zero byte.

I file oltre 50 MiB usano automaticamente multipart. Per un file più piccolo puoi attivarlo con force_multipart:true. Le sessioni multipart usano parti da 10 MiB e riportano total_parts; le normali sessioni più piccole restituiscono resumable:null.

L’inizializzazione controlla anche quota di spazio di archiviazione, dimensione massima del file della credenziale, regole dello spazio di lavoro su estensione e dimensione, spazio per membro, cartella di destinazione, blocchi e concorrenza. Per questo endpoint non esiste un’intestazione Idempotency-Key separata.

Risultato previsto

L’API restituisce HTTP 201 con ok:true, un session_id univoco, upload_url, i dettagli normalizzati del file e un oggetto con le istruzioni multipart oppure resumable:null. La sola creazione della sessione non completa il caricamento del file.

Risoluzione dei problemi

workspace_id is required, file_name is required e file_size must not be negative indicano dati non validi. force_multipart must be a boolean e force_multipart requires a file_size greater than 0 indicano errori di configurazione multipart. Un 403 che menziona un vincolo alla cartella indica che devi ricreare la chiave senza questa restrizione, incompatibile con REST.

Guide correlate

• Carica tramite API
• Guida rapida all’API REST