API-Referenz für den NAS-Volume-Browser

Wie Sie die VergeOS-volume_browser-API verwenden, um NAS-Volume-Inhalte programmgesteuert zu durchsuchen, einschließlich des asynchronen Job-Workflows, des Abrufens von Ergebnissen und der Fehlerbehebung bei häufigen Problemen.

Überblick

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

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

{
  "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

{
  "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

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.

Ohne ?fields=id,status,result:

{
  "id": "9a00434b882b9933512cc9d3abfd557a182d8fd3",
  "query": "get-dir",
  "status": "complete",
  "command": ""
}

Mit ?fields=id,status,result:

{
  "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:

[
  {
    "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:

{
  "id": "8cb12559b689f5a52472bd8882dde1c095b2ab64",
  "status": "complete",
  "result": []
}

Beispiele

cURL

# 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

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

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

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
• Lokale NAS-Volumes
• API-Schlüssel

Feedback

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.