Elenca cartelle e file con l'API REST

Usa GET https://api.dosya.dev/api/files per elencare cartelle e file visibili in una posizione dello spazio di lavoro. La richiesta restituisce metadati, percorso di navigazione, permessi e paginazione dei file; non restituisce byte né crea un link di condivisione.

Credenziali e accesso richiesti

Crea una chiave API Sola lettura o Accesso completo con API REST consentito in Protocolli. Vincolala allo spazio di lavoro previsto se l’integrazione non deve elencarne altri. Le normali chiavi API vincolate a cartelle sono rifiutate su REST: per questo endpoint usa un vincolo allo spazio di lavoro senza vincoli alle cartelle.

La chiave limita l’account che l’ha creata. L’account deve comunque essere membro dello spazio di lavoro e il suo ruolo deve avere il permesso access_files. Limiti sulle cartelle, regole per cartelle nascoste, blocchi completi e appartenenza allo spazio di lavoro sono verificati prima di restituire l’elenco.

Una chiave Solo caricamento non può chiamare questo endpoint GET. Il rifiuto nomina l’operazione esatta: This credential's scope is 'upload' and cannot perform GET /api/files.

Passaggi

Imposta il segreto in privato e usa un ID dello spazio di lavoro restituito da GET /api/workspaces:

read -r -s -p 'API key: ' DOSYA_API_KEY
printf '\n'
export DOSYA_API_KEY
export DOSYA_WORKSPACE_ID='ws_REPLACE_ME'

curl --fail-with-body --silent --show-error --get \
  'https://api.dosya.dev/api/files' \
  -H "Authorization: Bearer $DOSYA_API_KEY" \
  --data-urlencode "workspace_id=$DOSYA_WORKSPACE_ID" \
  --data-urlencode 'page=1' \
  --data-urlencode 'per_page=100' \
  --data-urlencode 'sort=name' \
  --data-urlencode 'dir=asc' \
  -o files-page-1.json

python3 -m json.tool files-page-1.json

workspace_id è obbligatorio; se lo ometti, la route restituisce workspace_id is required. Senza folder_id, la route elenca la radice dello spazio di lavoro o quella consentita al membro se l’account umano è limitato a una cartella.

La risposta JSON contiene:

• folders: metadati delle sottocartelle della posizione corrente.
• files: pagina corrente di metadati dei file, inclusi gli ID usati dalle successive route dei file.
• breadcrumbs: etichette delle cartelle dalla radice a quella corrente quando si elenca una sottocartella.
• workspace_id e folder_id risolto.
• can_lock, can_hide e folder_view_only per il ruolo corrente di chi chiama e lo stato della cartella.
• pagination.page, per_page, total_files e total_pages.

Cartelle e file sono array separati. total_files e total_pages descrivono la pagina dei file, non il numero di sottocartelle.

Elenca una sottocartella o filtra per nome

Passa l’ID di una cartella nota per elencarne le sottocartelle e i file diretti:

DOSYA_FOLDER_ID='fld_REPLACE_ME'
curl --fail-with-body --silent --show-error --get \
  'https://api.dosya.dev/api/files' \
  -H "Authorization: Bearer $DOSYA_API_KEY" \
  --data-urlencode "workspace_id=$DOSYA_WORKSPACE_ID" \
  --data-urlencode "folder_id=$DOSYA_FOLDER_ID" \
  --data-urlencode 'q=invoice' \
  --data-urlencode 'page=1' \
  --data-urlencode 'per_page=100'

Gli spazi iniziali e finali vengono rimossi da q, che viene confrontato con i nomi senza distinzione tra maiuscole e minuscole. I caratteri jolly speciali sono trattati come testo di ricerca, non come pattern SQL grezzi. Un membro limitato che specifica una cartella fuori dal sottoalbero consentito riceve This folder is outside the folder you're confined to con HTTP 403.

Chiavi di ordinamento supportate: name, size, created, modified, taken, type, extension, version, uploader, region, origin, shares e comments. Usa dir=asc o dir=desc con una chiave semplice. Sono accettati anche i valori precedenti newest, oldest, largest e smallest. Un ordinamento sconosciuto mostra prima i più recenti.

Recupera tutte le pagine dei file

La dimensione predefinita della pagina è 100. per_page viene limitato a 10–500 e page parte da 1. Continua finché la pagina restituita raggiunge pagination.total_pages:

import json, os, urllib.parse, urllib.request

base = 'https://api.dosya.dev/api/files'
workspace = os.environ['DOSYA_WORKSPACE_ID']
key = os.environ['DOSYA_API_KEY']
page = 1

while True:
    query = urllib.parse.urlencode({
        'workspace_id': workspace,
        'page': page,
        'per_page': 500,
        'sort': 'name',
        'dir': 'asc',
    })
    req = urllib.request.Request(base + '?' + query,
        headers={'Authorization': 'Bearer ' + key})
    with urllib.request.urlopen(req) as response:
        body = json.load(response)
    for item in body['files']:
        print(item['id'], item['name'], item['size_bytes'])
    if page >= body['pagination']['total_pages']:
        break
    page += 1

I file possono cambiare tra pagine basate su offset. Per un’esportazione stabile evita rinomine, caricamenti ed eliminazioni concorrenti durante l’esecuzione e deduplica le righe raccolte per ID file.

Interpreta le risposte di accesso e blocco

Risposta	Significato e azione successiva
401, Not authenticated o testo di chiave non valida	Ripristina il token bearer completo e verifica scadenza o revoca.
403, This API key is not permitted to use the api surface	Crea una chiave la cui selezione dei protocolli includa REST API.
403, Not a member of this workspace	Verifica l’ID dello spazio di lavoro e ripristina l’appartenenza; una chiave non può concederla.
403, You don't have access to the files page	Il ruolo corrente non ha access_files; chiedi a un amministratore dello spazio di lavoro di modificarlo.
403 con error: "folder_locked" e lock_mode: "full_lock"	Sblocca la cartella con una procedura autorizzata e fornisci il token ut corrente se l’integrazione supporta cartelle bloccate.
404, Folder not found	La cartella non esiste per chi effettua la richiesta, anche se è nascosta o sotto un antenato nascosto. Non dedurre contenuti nascosti dalla risposta.

File e cartelle nascosti vengono rimossi dai risultati ordinari, salvo che chi effettua la richiesta abbia il permesso di gestire contenuti nascosti. Una cartella view_only può comunque essere elencata e la risposta imposta folder_view_only: true affinché i client possano nascondere le azioni di download.

Risultato previsto

Ogni richiesta restituisce HTTP 200 con solo cartelle e file che il proprietario della credenziale può vedere nella posizione richiesta. Seguendo pagination.total_pages si ottiene l’insieme dei file accessibili senza scaricare byte o modificare lo spazio di lavoro.

Guide correlate

• Inizia con l’API REST
• Scegli una chiave API abilitata alla lettura
• Gestisci errori e paginazione API