Scorri le pagine dei risultati file dell'API REST

Gli elenchi di file usano pagine numeriche con offset. GET /api/files non restituisce token di continuazione, cursori o valori per la pagina successiva da salvare.

Richiesta e risposta

Chiama GET /api/files?workspace_id=wks_…&folder_id=fld_…&page=1&per_page=100. Ometti folder_id per la radice dello spazio di lavoro. page vale 1 per impostazione predefinita; per_page vale 100 ed è ricondotto a 10 o 500 se fuori da questi limiti. Le pagine sono limitate a 10.000.000, le frazioni arrotondate per difetto e i valori malformati sostituiti da valori predefiniti.

La risposta contiene folders, files suddivisi in pagine, breadcrumbs, i valori risolti workspace_id e folder_id, can_lock, can_hide, folder_view_only e pagination.

Passaggi

1. Mantieni invariati spazio di lavoro, cartella, filtro, ricerca e ordinamento durante la scansione e scegli un valore per_page tra 10 e 500.
2. Richiedi page=1, verifica che la risposta contenga ok:true e registra pagination.page, per_page, total_files e total_pages.
3. Elabora ogni elemento di files usando il suo id stabile; considera l’array folders come contesto delle cartelle, non come parte del conteggio della pagina di file.
4. Incrementa il numero di pagina e ripeti la stessa query finché la pagina restituita non coincide con pagination.total_pages.
5. Elimina i duplicati degli ID file ed evita caricamenti, spostamenti o eliminazioni contemporanei quando la scansione deve rappresentare un’esportazione stabile.
6. Confronta il numero di ID unici elaborati con l’insieme dei risultati visibili, conservando eventuali errori di pagina 403, 404, 429 o 503 per il recupero.

Dettagli della paginazione

pagination.total_files conta i file, non le cartelle. total_pages è almeno 1 anche quando nessun file corrisponde. Poiché la paginazione usa limit e offset, le modifiche durante la scansione possono spostare righe tra le pagine; eliminare i duplicati in base all’ID evita elaborazioni doppie ma non può ricostruire un’istantanea storica.

L’endpoint supporta gli ETag nelle risposte. Una richiesta condizionale può restituire HTTP 304 se l’elenco serializzato è invariato.

Usa una chiave Sola lettura o Accesso completo con REST abilitato e un ruolo che possieda access_files. Solo caricamento viene rifiutato con This credential's scope is 'upload' and cannot perform GET /api/files. Le chiavi vincolate a cartelle non possono usare questa route REST.

Risultato previsto

Il client visita le pagine da 1 a total_pages, elabora una sola volta ogni ID file visibile per la query scelta e non aspetta un campo di continuazione che l’API non restituisce.

Guide correlate

• Elenca i file con l’API
• Gestisci gli errori API