Ordner und Dateien über die REST-API auflisten
Rufen Sie GET /api/files mit Lesezugriff auf. Blättern Sie durch einen Workspace oder Ordner und unterscheiden Sie Zugriffs-, Sperr-, Sichtbarkeits- und Berechtigungsfehler.
Zuletzt geprüft
Screenshots zeigen die englische Oberfläche.
Listen Sie mit GET https://api.dosya.dev/api/files sichtbare Ordner und Dateien an einer Stelle im Workspace auf. Die Antwort enthält Metadaten, Pfadnavigation, Berechtigungen und Dateiseiten. Sie liefert keine Dateibytes und erstellt keinen Freigabelink.
Zugangsdaten und Zugriff
Erstellen Sie einen API-Schlüssel mit Nur lesbar oder Vollzugriff und unter Protokolle erlaubter REST API. Binden Sie den gewünschten Workspace, wenn andere nicht auflistbar sein sollen. Gewöhnliche API-Schlüssel mit Ordneranker werden über REST abgelehnt. Nutzen Sie hier eine Workspace-Bindung ohne Ordneranker.
Für den API-Schlüssel gelten höchstens die Zugriffsberechtigungen des Kontos, mit dem er erstellt wurde. Das Konto muss weiterhin Mitglied im Workspace sein. Die Rolle muss access_files erlauben. Ordnerbeschränkungen, Regeln für verborgene Ordner, vollständige Sperren und die Mitgliedschaft gelten vor der Ausgabe.
Ein API-Schlüssel mit Nur Upload kann diesen GET-Endpunkt nicht aufrufen. Die Ablehnung nennt genau die Aktion: This credential's scope is 'upload' and cannot perform GET /api/files.

Schritte
Hinterlegen Sie das Geheimnis vertraulich. Nutzen Sie eine von GET /api/workspaces gelieferte Workspace-ID:
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 ist Pflicht. Ohne diesen Wert kommt workspace_id is required. Ohne folder_id beginnt die Route am Workspace-Stammordner. Bei einem ordnerbeschränkten Konto beginnt sie am zugewiesenen Stammordner des Mitglieds.
Die erfolgreiche JSON-Antwort enthält:
folders: Metadaten direkter Unterordner an der aktuellen Stelle.files: aktuelle Dateimetadatenseite mit IDs für weitere Dateirouten.breadcrumbs: Ordnernamen vom Stamm zum aktuellen Unterordner.workspace_idund die aufgelöstefolder_id.can_lock,can_hideundfolder_view_onlyfür aktuelle Rolle und Ordnerzustand.pagination.page,per_page,total_filesundtotal_pages.
Ordner und Dateien stehen in getrennten Arrays. total_files und total_pages beschreiben die Dateiseite, nicht die Zahl der Unterordner.

Unterordner auflisten oder nach Namen filtern
Geben Sie eine bekannte Ordner-ID an, um dessen direkte Inhalte aufzulisten:
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'
q wird an den Rändern gekürzt und ohne Groß-/Kleinschreibung mit Namen verglichen. Platzhalterzeichen gelten als Suchtext, nicht als rohe SQL-Muster. Nennt ein beschränktes Mitglied ausdrücklich einen Ordner außerhalb seines Teilbaums, kommt HTTP 403 mit This folder is outside the folder you're confined to.
Sortierschlüssel: name, size, created, modified, taken, type, extension, version, uploader, region, origin, shares und comments. Nutzen Sie einen Sortierschlüssel mit dir=asc oder dir=desc. Auch newest, oldest, largest und smallest sind erlaubt. Unbekannte Eingaben liefern neueste Einträge zuerst.
Alle Dateiseiten abrufen
Standard sind 100 Einträge je Seite. per_page wird auf 10–500 begrenzt. page beginnt bei 1. Fahren Sie fort, bis die gelieferte Seite pagination.total_pages erreicht:
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
Dateien können sich zwischen Versatzseiten ändern. Vermeiden Sie für einen stabilen Export gleichzeitiges Umbenennen, Hochladen und Löschen. Entfernen Sie doppelte Einträge anhand der Datei-ID.
Zugriffs- und Sperrantworten verstehen
| Antwort | Bedeutung und nächster Schritt |
|---|---|
401, Not authenticated oder Ungültigkeitsmeldung | Vollständiges Bearer-Token wiederherstellen. Gültigkeit und Widerruf prüfen. |
403, This API key is not permitted to use the api surface | API-Schlüssel mit erlaubter REST API erstellen. |
403, Not a member of this workspace | Workspace-ID prüfen und Mitgliedschaft wiederherstellen. Ein API-Schlüssel verleiht keine Mitgliedschaft. |
403, You don't have access to the files page | Der Rolle fehlt access_files. Einen Workspace-Admin um Anpassung bitten. |
403 mit error: "folder_locked" und lock_mode: "full_lock" | Ordner berechtigt entsperren und dessen aktuelles ut-Token senden, wenn die Integration gesperrte Ordner unterstützt. |
404, Folder not found | Ordner für diesen Anfragenden nicht vorhanden, auch bei verborgenem Ordner oder verborgenem übergeordnetem Ordner. Daraus keine verborgenen Inhalte ableiten. |
Verborgene Dateien und Ordner fehlen in normalen Ergebnissen, sofern keine Berechtigung zur Verwaltung verborgener Inhalte besteht. Ein view_only-Ordner ist weiterhin auflistbar. folder_view_only: true lässt Clients Downloadaktionen ausblenden.
Erwartetes Ergebnis
Jede Anfrage liefert HTTP 200 nur mit Ordnern und Dateien, die das erstellende Konto an dieser Stelle sehen darf. Das Durchblättern bis pagination.total_pages liefert alle zugänglichen Dateien, ohne Bytes herunterzuladen oder den Workspace zu ändern.
Weitere Anleitungen
War diese Anleitung hilfreich?
Bewertungen werden geladen …
Beim Abstimmen speichern wir ein notwendiges Abstimmungs-Cookie bis zu 180 Tage. So können Sie Ihre Antwort ändern.
Fragen und Antworten
Stellen Sie Fragen zu den Schritten dieser Anleitung. Fragen werden vor der Veröffentlichung geprüft.
Veröffentlichen Sie in Fragen keine Kontodaten, Zugangsdaten oder privaten Dateien. Nutzen Sie privaten Support für solche Angaben.
Fragen werden geladen …
Melden Sie sich bei Ihrem dosya-Konto an, um eine Frage zu stellen.