> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/knowledge-base/de/storage-vsan/nas-volume-browser-api.md). # API-Referenz des NAS-Volume-Browsers ## Überblick {% hint style="info" %} **Wichtige Punkte** * Die volume\_browser-API ist **asynchron** - einen Job erstellen, dann auf Ergebnisse abfragen * Sie **muss** einschließen `?fields=id,status,result` beim Abfragen, sonst wird das Ergebnis nicht zurückgegeben * Verwenden Sie einen leeren String `""` für den Pfad des Stammverzeichnisses (nicht `/`) * Die NAS-Service-VM muss ausgeführt werden, um Volumes zu durchsuchen {% endhint %} Der `volume_browser` Die API bietet Dateisystem-Browserfunktionen für NAS-Volumes. Dies ist nützlich für Automatisierung, Integrationen und den Aufbau benutzerdefinierter Dateiverwaltungstools. ## Voraussetzungen * Ein laufender NAS-Dienst mit mindestens einem Online-Volume * API-Zugriff mit entsprechenden Berechtigungen * Der SHA1-Schlüsselbezeichner des Volumes (zu finden in der Volume-Dashboard-URL oder API) ## So funktioniert es Das Durchsuchen eines Volumes ist ein zweistufiger Prozess: 1. **POST** zu `/api/v4/volume_browser` um einen Browse-Job zu erstellen 2. **GET** zu `/api/v4/volume_browser/{job_id}?fields=id,status,result` um nach Ergebnissen abzufragen ## Schritt 1: Eine Browse-Anfrage erstellen ### Endpunkt ``` POST /api/v4/volume_browser ``` ### Anfragetext ```json { "volume": "62db5fcd888082246b9346c0e65311334d91ed2c", "query": "get-dir", "params": { "dir": "", "limit": 1000, "offset": null, "filter": { "extensions": "" }, "volume": "62db5fcd888082246b9346c0e65311334d91ed2c", "sort": "" } } ``` ### Feldreferenz | Feld | Typ | Erforderlich | Beschreibung | | -------- | ------ | ------------ | ----------------------------------------------------- | | `volume` | string | Ja | Volumenschlüssel (SHA1-Hash-Bezeichner) | | `query` | string | Ja | Operationstyp: `get-dir`, `rename`, `delete`, `paste` | | `params` | Objekt | Ja | Abfrageparameter (siehe unten) | ### Params-Objekt | Feld | Typ | Beschreibung | | ------------------- | ------------- | ----------------------------------------------------------------------------- | | `dir` | string | Verzeichnispfad zum Durchsuchen. Verwenden Sie `""` für das Stammverzeichnis. | | `limit` | ganze Zahl | Maximale Anzahl der zurückzugebenden Einträge (z. B. 1000) | | `offset` | Ganzzahl/null | Paginierungs-Offset, `null` für die erste Seite | | `filter.extensions` | string | Nach Dateiendungen filtern (leerer String für alle) | | `volume` | string | Volumenschlüssel (muss mit der obersten Ebene übereinstimmen `volume`) | | `sort` | string | Sortierfeld (leerer String für Standard) | ### Antwort ```json { "location": "/v4/volume_browser/9a00434b882b9933512cc9d3abfd557a182d8fd3", "dbpath": "volume_browser/9a00434b882b9933512cc9d3abfd557a182d8fd3", "$row": 1, "$key": "9a00434b882b9933512cc9d3abfd557a182d8fd3" } ``` Der `$key` enthält die Job-ID, die zum Abfragen benötigt wird. ## Schritt 2: Auf Ergebnisse abfragen ### Endpunkt ``` GET /api/v4/volume_browser/{job_id}?fields=id,status,result ``` {% hint style="danger" %} **Wichtig: Fordern Sie das Result-Feld an** Der `result` Feld ist **standardmäßig NICHT zurückgegeben**. Sie müssen es ausdrücklich mit `?fields=id,status,result`. Ohne diesen Parameter erhalten Sie nur Statusinformationen. {% endhint %} **Ohne `?fields=id,status,result`:** ```json { "id": "9a00434b882b9933512cc9d3abfd557a182d8fd3", "query": "get-dir", "status": "complete", "command": "" } ``` **Mit `?fields=id,status,result`:** ```json { "id": "9a00434b882b9933512cc9d3abfd557a182d8fd3", "status": "complete", "result": [ {"name": "documents", "size": 4096, "date": 1706120819, "type": "directory"}, {"name": "file.txt", "size": 1024, "date": 1769198797, "type": "file"} ] } ``` ### Statuswerte | Status | Beschreibung | | --------------- | -------------------------------------------------------------- | | `running` | Der Job wird noch verarbeitet | | `abgeschlossen` | Job erfolgreich abgeschlossen | | `Fehler` | Job fehlgeschlagen (prüfen Sie `result` auf die Fehlermeldung) | ### Abfragestrategie ``` 1. POST, um den Job zu erstellen 2. 200-500 ms warten 3. GET mit ?fields=id,status,result 4. Wenn status == "running", warten und erneut versuchen (bis zu 30 Versuche) 5. Wenn status == "complete", das Ergebnis verarbeiten 6. Wenn status == "error", den Fehler behandeln ``` ## Ergebnisformat Wenn `status` ist `abgeschlossen`, das `result` Feld enthält ein Array von Datei-/Verzeichniseinträgen: ```json [ { "name": "document.pdf", "n_name": "document.pdf", "size": 102400, "date": 1769136871, "type": "file" }, { "name": "images", "n_name": "images", "size": 4096, "date": 1769197982, "type": "directory" } ] ``` ### Eintragsfelder | Feld | Typ | Beschreibung | | -------- | ---------- | -------------------------------------- | | `name` | string | Datei- oder Verzeichnisname | | `n_name` | string | Normalisierter Name (kleingeschrieben) | | `size` | ganze Zahl | Größe in Bytes | | `date` | ganze Zahl | Änderungszeitpunkt (Unix-Zeitstempel) | | `type` | string | `"file"` oder `"directory"` | ### Leere Verzeichnisse Für leere Verzeichnisse, `result` wird ein leeres Array sein: ```json { "id": "8cb12559b689f5a52472bd8882dde1c095b2ab64", "status": "complete", "result": [] } ``` ## Beispiele ### cURL ```bash # Schritt 1: Browse-Job erstellen JOB_ID=$(curl -s -X POST "https://your-vergeos.example.com/api/v4/volume_browser" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \\ -d '{ "volume": "62db5fcd888082246b9346c0e65311334d91ed2c", "query": "get-dir", "params": { "dir": "", "limit": 1000, "offset": null, "filter": {"extensions": ""}, "volume": "62db5fcd888082246b9346c0e65311334d91ed2c", "sort": "" } }' | jq -r '."$key"') # Schritt 2: Auf Ergebnisse abfragen (WICHTIG: fields-Parameter einschließen) sleep 1 curl -s "https://your-vergeos.example.com/api/v4/volume_browser/${JOB_ID}?fields=id,status,result" \ -H "Authorization: Bearer $TOKEN" | jq ``` ### Python ```python import requests import time def browse_volume(base_url, token, volume_key, path=""): headers = { "Authorization": f"Bearer {token}", "Content-Type": "application/json" } # Schritt 1: Browse-Job erstellen payload = { "volume": volume_key, "query": "get-dir", "params": { "dir": path, # Verwenden Sie "" für das Stammverzeichnis "limit": 1000, "offset": None, "filter": {"extensions": ""}, "volume": volume_key, "sort": "" } } response = requests.post( f"{base_url}/api/v4/volume_browser", headers=headers, json=payload, verify=False ) job_id = response.json()["$key"] # Schritt 2: Auf Ergebnisse abfragen for _ in range(30): time.sleep(0.5) # WICHTIG: Das result-Feld ausdrücklich anfordern response = requests.get( f"{base_url}/api/v4/volume_browser/{job_id}?fields=id,status,result", headers=headers, verify=False ) data = response.json() if data["status"] == "complete": return data.get("result") or [] elif data["status"] == "error": raise Exception(f"Browse fehlgeschlagen: {data.get('result')}") raise TimeoutError("Zeitüberschreitung der Browse-Operation") ``` ## Fehlerbehebung {% hint style="warning" %} **Häufige Probleme** **Result-Feld ist leer oder fehlt** * Sie müssen `?fields=id,status,result` in Ihrer GET-Anfrage angeben * Ohne diesen Parameter werden nur Statusinformationen zurückgegeben **"VM muss sich im laufenden Zustand befinden, um eine Abfrage auszuführen"** * Die NAS-Service-VM wird nicht ausgeführt * Navigieren Sie zu NAS > NAS Services und starten Sie den Dienst **"Fehler beim Abrufen des Volumes-VM-Dienstes: Keine solche Datei oder kein solches Verzeichnis"** * Der NAS-Dienst des Volumes existiert nicht oder wurde gelöscht * Vergewissern Sie sich, dass das Volume einem gültigen NAS-Dienst zugeordnet ist **"Ressource '/v4/volume\_browser/' nicht gefunden"** * Leere Job-ID in der Abfrageanfrage * Stellen Sie sicher, dass Sie `$key` korrekt aus der POST-Antwort extrahieren {% endhint %} ### Häufige Fehler 1. **Die Verwendung von `path` anstelle von `dir`** - Das Feld heißt `dir`, nicht `path` 2. **Parameter als JSON-String senden** - Das `params` Feld muss ein Objekt sein, kein JSON-kodierter String 3. **Fehlende Params-Felder** - Alle Felder im Params-Objekt werden erwartet 4. **Vergessen `?fields=id,status,result`** - Ohne dies werden keine Dateidaten zurückgegeben ## Anforderungen * Die NAS-Service-VM muss ausgeführt werden, um Volumes zu durchsuchen * Das Volume muss online sein (eingehängt) * Der Benutzer muss Leseberechtigungen für das Volume haben ## Zusätzliche Ressourcen * [NAS-Übersicht](/run-the-platform/nas/overview.md) * [Lokale NAS-Volumes](/run-the-platform/nas/nas-local-volumes.md) * [API-Schlüssel](/run-the-platform/system-administration/api-keys.md) ## Feedback {% hint style="info" %} **Brauchen Sie Hilfe?** Wenn Sie weitere Unterstützung benötigen oder Fragen zu diesem Artikel haben, zögern Sie bitte nicht, sich an das [VergeOS-Support-Team](broken://spaces/RDqjqiAbPZD7nK9rjfqU/pages/8c8d3dd8447f3e6289926e29d315a800b2153b50). {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/knowledge-base/de/storage-vsan/nas-volume-browser-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.