Sposta un file in sicurezza tramite l'API REST

PUT /api/files/:id/move cambia la cartella padre di un file senza modificarne ID o versioni. Invia folder_id come ID della cartella di destinazione o null per la radice dello spazio di lavoro. Aggiungi name solo se la stessa richiesta atomica deve anche rinominare il file.

Prima di iniziare

• Usa una chiave API REST con accesso completo; le chiavi di sola lettura o solo caricamento non possono spostare file.
• Il tuo ruolo nello spazio di lavoro deve includere upload_files. Una richiesta che fornisce anche name richiede rename_files.
• Registra l’ID del file, la cartella attuale e la cartella di destinazione. Per testare l’automazione scegli un file sacrificabile.
• La destinazione deve appartenere allo stesso spazio di lavoro ed essere visibile a chi effettua la chiamata.

Passaggi

1. Leggi prima il file e la destinazione. Registra l’ID del file, la cartella padre attuale e l’ID esatto della destinazione prima di inviare la modifica.
2. Prepara il JSON con la destinazione: {"folder_id":"folder_destination"}. Usa {"folder_id":null} per la radice oppure aggiungi "name":"renamed.pdf" per spostare e rinominare insieme.
3. Invia PUT /api/files/file_id/move con Authorization: Bearer $DOSYA_API_KEY e Content-Type: application/json. Se perdi la risposta, non riprovare alla cieca.
4. Verifica che la risposta sia HTTP 200 e leggi { "ok": true, "name": "…" }. Un 400 può indicare che il file è già in quella cartella, 403 un rifiuto per permesso o blocco, 404 nasconde una risorsa non disponibile e 409 segnala un conflitto di nome nella stessa cartella.
5. Invia GET /api/files/file_id e verifica che lo stesso ID riporti il folder_id previsto e l’eventuale nuovo nome. Usa X-D1-Bookmark se restituito dalla modifica, ma solo per ordinare le letture basate su D1; i metadati del contenuto del file possono provenire dal repository dello spazio di lavoro.
6. Elenca sia la cartella padre precedente sia quella di destinazione se le operazioni successive dipendono dalla presenza del file. Continua solo quando l’ID è assente dalla prima e presente nella destinazione.

Risultato previsto

L’API restituisce 200 con ok: true; una lettura dei metadati specifica della route mostra l’ID originale del file nella cartella padre scelta. Se hai anche rinominato il file, il risultato verificato mostra il nome fornito.

Risoluzione dei problemi

La richiesta restituisce 409. Scegli un name diverso oppure risolvi il conflitto con l’elemento esistente nella destinazione prima di riprovare.

La richiesta restituisce 403. Controlla upload_files, aggiungi rename_files per rinominare il file e verifica lo stato del blocco. Cambiare l’ambito della chiave API non aggira un ruolo o un blocco dello spazio di lavoro.

La risposta è andata persa. Leggi il file prima di inviare un’altra modifica. La route di spostamento non ha una chiave di idempotenza; se il file è nella destinazione prevista, la prima richiesta è già stata applicata.

Guide correlate

• Usa le operazioni sulle cartelle
• Guida rapida all’API REST