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.

REST-Dateiliste: von Workspace-ID und lesendem API-Schlüssel über seitenweise Metadaten zur Prüfung der Zugriffsgrenzen.
Listen Sie einen bekannten Workspace-Stammordner auf, folgen Sie den Seiten und prüfen Sie, dass gesperrte oder verborgene Inhalte nicht ausgegeben werden. Screenshot in voller Größe öffnen.

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_id und die aufgelöste folder_id.
  • can_lock, can_hide und folder_view_only für aktuelle Rolle und Ordnerzustand.
  • pagination.page, per_page, total_files und total_pages.

Ordner und Dateien stehen in getrennten Arrays. total_files und total_pages beschreiben die Dateiseite, nicht die Zahl der Unterordner.

dosya-API-Schlüsselberechtigung Nur lesbar zum Auflisten von Ordner- und Dateimetadaten über REST.
**Nur lesbar** reicht zum Auflisten aus. Dieselben Zugangsdaten können keine Inhalte hochladen, verschieben, freigeben oder löschen. Screenshot in voller Größe öffnen.

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

AntwortBedeutung und nächster Schritt
401, Not authenticated oder UngültigkeitsmeldungVollständiges Bearer-Token wiederherstellen. Gültigkeit und Widerruf prüfen.
403, This API key is not permitted to use the api surfaceAPI-Schlüssel mit erlaubter REST API erstellen.
403, Not a member of this workspaceWorkspace-ID prüfen und Mitgliedschaft wiederherstellen. Ein API-Schlüssel verleiht keine Mitgliedschaft.
403, You don't have access to the files pageDer 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 foundOrdner 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.

    Ergebnis vor einem neuen Versuch prüfen

    Nutzen Sie diese Prüfungen, wenn Sie ein Ergebnis genauer kontrollieren möchten.