Scarica un file con l'API REST

Scarica un file archiviato con l’API REST in due richieste: ottieni un URL temporaneo autorizzato da GET /api/files/{file_id}/download-url, poi usa quell’URL per scaricare il file dallo spazio di archiviazione. La risposta che concede l’accesso è in JSON, non contiene i byte del file e non è un reindirizzamento. Mantieni privato l’URL: chiunque lo possieda può scaricare l’oggetto autorizzato fino alla scadenza.

Scegli un file che puoi scaricare

Usa una chiave API Sola lettura o Accesso completo con API REST abilitato. Se necessario, creala in Profilo → Chiavi API → Crea una chiave API, poi salva il token completo prima di uscire dalla schermata che lo mostra una sola volta. Un vincolo allo spazio di lavoro può limitare la chiave; una normale chiave vincolata a una cartella viene rifiutata da questo protocollo.

Usa GET /api/files?workspace_id=WORKSPACE_ID per trovare l’ID di un file. Aggiungi folder_id per cercare in una cartella specifica. Il file scelto deve appartenere a uno spazio di lavoro di cui sei membro, rientrare negli eventuali limiti di accesso del membro, essere visibile e consentire il download. Il tuo ruolo deve permettere l’accesso alla pagina dei file e download_files; poter vedere l’anteprima non basta.

Passaggi: richiedi e usa l’autorizzazione

Imposta DOSYA_API_KEY senza renderla pubblica e sostituisci il segnaposto del file qui sotto. Questo esempio Bash usa curl e Python 3, salva l’autorizzazione in un file con permessi privati e non stampa l’URL firmato:

set -e
umask 077
DOSYA_FILE_ID='REPLACE_WITH_FILE_ID'
DOSYA_GRANT_FILE=$(mktemp)
curl --fail-with-body --silent --show-error \
  "https://api.dosya.dev/api/files/$DOSYA_FILE_ID/download-url" \
  -H "Authorization: Bearer $DOSYA_API_KEY" \
  -o "$DOSYA_GRANT_FILE"
python3 - "$DOSYA_GRANT_FILE" <<'PYTHON'
import json, sys
from urllib.request import urlopen
grant = json.load(open(sys.argv[1]))
with urlopen(grant["url"]) as response, open("dosya-download.bin", "wb") as output:
    while chunk := response.read(1024 * 1024):
        output.write(chunk)
from pathlib import Path
actual = Path("dosya-download.bin").stat().st_size
if actual != grant["size"]:
    raise SystemExit(f"Size mismatch: received {actual}, expected {grant['size']}")
print("Downloaded", grant["name"], "bytes:", actual, "region:", grant["region"])
PYTHON
rm -f "$DOSYA_GRANT_FILE"

Se la richiesta di autorizzazione non va a buon fine, fermati invece di leggere un vecchio file JSON. L’esempio Python richiede Python 3.8 o successivo. Scrive in dosya-download.bin; prima di rieseguirlo scegli un nuovo nome di output locale se vuoi conservare un download precedente.

Una risposta di autorizzazione 200 contiene esattamente i campi necessari: url, size in byte, name e region. Questa route non include ok: true. Usa url così come viene restituito, con tutti i parametri di firma, senza allegare la chiave API dosya alla richiesta allo spazio di archiviazione. L’autorizzazione verifica i tuoi diritti; lo spazio di archiviazione usa la firma dell’URL.

Confronta la dimensione scaricata con size. Per una verifica più solida dell’integrità, confronta il digest SHA-256 calcolato in locale con quello di una fonte attendibile: nome o lunghezza uguali non bastano a dimostrare che i contenuti siano identici. Conserva l’identità del file o della versione scelta insieme al risultato della verifica.

Durata dell’URL, versioni e conteggio

Parametro della query	Comportamento supportato
ttl	Secondi interi; il valore predefinito è 300 secondi (5 minuti). I valori positivi sono limitati a 3600 secondi (1 ora). Se manca, non è valido o non è positivo, viene usato 300.
version	Un numero di versione positivo seleziona la revisione archiviata corrispondente; omettilo per il file corrente. Una versione valida ma inesistente restituisce 404 Version not found.
region	Regione prevista facoltativa. Se non corrisponde, restituisce 404 File not found; non reindirizza il file in una nuova posizione.
ut	Token di sblocco valido per il file con blocco completo di questo utente, quando richiesto. Non aggira i controlli su ruolo o visibilità.

Per esempio, /api/files/FILE_ID/download-url?version=1&ttl=3600 richiede la prima versione con un URL valido un’ora. La versione iniziale di un file mai modificato è supportata anche se non esiste una voce tra le versioni precedenti. Usa numeri interi positivi espliciti: un valore version malformato non è un modo affidabile per scegliere una revisione.

La scadenza conta sia per il primo GET sia per le successive richieste Range. Per un programma di download o un lettore multimediale di lunga durata, richiedi un TTL adeguato entro il limite di un’ora. Se lo spazio di archiviazione rifiuta un URL scaduto, ottieni una nuova autorizzazione con una credenziale ancora autorizzata; modificare i parametri di scadenza del vecchio URL invalida la firma.

La quota di byte scaricabili applicabile alla credenziale o al piano viene ridotta dell’intera dimensione della versione scelta al rilascio dell’autorizzazione, anche se non scarichi nulla o leggi solo un intervallo. Autorizzazioni rilasciate più volte possono quindi consumare la quota più volte. Conserva nella cache privata un’autorizzazione non scaduta per il lavoro previsto, invece di richiedere un nuovo URL per ogni blocco. Un evento del registro di controllo registra il rilascio, non prova che un destinatario abbia ricevuto tutti i byte.

Diagnostica un download non disponibile

Stato ed errore	Significato e soluzione
401, Invalid or expired API key	Sostituisci il token mancante, revocato o scaduto prima di richiedere un’altra autorizzazione.
403, Access denied	Non sei membro dello spazio di lavoro del file.
403, This file is outside the folder you're confined to	Il limite di accesso alle cartelle del membro esclude questo file.
403, You don't have download permission	Chiedi a un amministratore il permesso di download; quello di anteprima non lo sostituisce.
403, This file is view-only and cannot be downloaded	Rispetta il blocco che consente solo la visualizzazione; questo endpoint non fornirà i byte scaricabili.
403, This file is locked. Enter the lock password to access it.	Ottieni un token di sblocco valido tramite la procedura autorizzata, poi invia ut.
403, Invalid or expired unlock token. Please re-enter the password.	Ripeti lo sblocco autorizzato; il vecchio token non è più valido.
404, File not found	Controlla ID e regione facoltativa. I contenuti nascosti e gli elementi antenati bloccati restituiscono intenzionalmente la stessa risposta dei contenuti mancanti.
429 con Retry-After	Attendi per il numero di secondi indicato; il limite di richieste o di byte scaricabili di una chiave può rifiutare l’autorizzazione prima che esista un URL.
500, Download failed: …	Impossibile firmare l’URL. Conserva l’errore privo di dati sensibili e riprova più tardi; non pubblicare nei log dettagli dello spazio di archiviazione o credenziali.

Un file con blocco completo può essere sbloccato con POST /api/files/{file_id}/unlock e il JSON {"password":"REPLACE_WITH_LOCK_PASSWORD"}. Il unlock_token restituito è valido per un’ora, appartiene a chi effettua la chiamata e non rimuove il blocco. Questa POST richiede accesso completo: una chiave REST di sola lettura non può chiamarla. Per il passaggio con password usa una credenziale con accesso completo autorizzata separatamente o l’app dopo aver effettuato l’accesso, poi mantieni privato il token. Evita di indovinare ripetutamente la password; i tentativi di sblocco sono limitati.

I controlli di accesso precedono la firma dell’URL: appartenenza allo spazio di lavoro, accesso alla pagina dei file, limiti del membro, permesso di download, contenuti nascosti e blocchi degli elementi antenati, blocco del file stesso, versione scelta e quota di byte. Un’autorizzazione scaduta non elimina il file archiviato e il download non crea un link di condivisione né avvisa un destinatario scelto.

Proteggi la copia scaricata e l’URL

Revocare la chiave API impedisce nuove autorizzazioni autenticate, ma non revoca un URL di archiviazione già rilasciato; attendi la scadenza del suo breve TTL. Evita di inserire URL firmati in screenshot, segnalazioni, log delle query o analisi. Non eseguire comandi con il tracciamento della shell attivo in presenza di segreti.

Il file locale è ora una copia separata sotto il tuo controllo. Eliminare o modificare il file nel cloud non rimuove la copia scaricata. Dopo l’uso elimina il file temporaneo dell’autorizzazione e conserva i dati scaricati con i permessi richiesti dal loro contenuto.

Risultato previsto

L’output locale contiene la versione scelta del file e ha la dimensione indicata nell’autorizzazione. Il file archiviato resta nel suo spazio di lavoro; l’URL temporaneo concede l’accesso solo per la sua durata e una copia scaricata resta disponibile indipendentemente da essa.

Guide correlate

• Autenticazione API REST ed elenco degli spazi di lavoro
• Gestisci la credenziale usata per le autorizzazioni di download