Référence de l’API du navigateur de volume NAS

Comment utiliser l’API volume_browser de VergeOS pour parcourir de manière programmatique le contenu des volumes NAS, y compris le flux de travail des tâches asynchrones, l’interrogation des résultats et le dépannage des problèmes courants.

Vue d’ensemble

Points clés

• L'API volume_browser est asynchrone - créer une tâche, puis interroger les résultats
• Vous doit inclure ?fields=id,status,result lors de l'interrogation, sinon le résultat ne sera pas renvoyé
• Utilisez une chaîne vide "" pour le chemin du répertoire racine (pas /)
• La VM du service NAS doit être en cours d'exécution pour parcourir les volumes

Le volume_browser L'API fournit des capacités de navigation du système de fichiers pour les volumes NAS. C'est utile pour l'automatisation, les intégrations et la création d'outils personnalisés de gestion de fichiers.

Prérequis

• Un service NAS en cours d'exécution avec au moins un volume en ligne
• Accès à l'API avec les autorisations appropriées
• L'identifiant de clé SHA1 du volume (trouvé dans l'URL du tableau de bord du volume ou via l'API)

Fonctionnement

Parcourir un volume est un processus en deux étapes :

1. POST à /api/v4/volume_browser pour créer une tâche de parcours
2. GET à /api/v4/volume_browser/{job_id}?fields=id,status,result pour interroger les résultats

Étape 1 : Créer une demande de parcours

Point de terminaison

POST /api/v4/volume_browser

Corps de la requête

{
  "volume": "62db5fcd888082246b9346c0e65311334d91ed2c",
  "query": "get-dir",
  "params": {
    "dir": "",
    "limit": 1000,
    "offset": null,
    "filter": {
      "extensions": ""
    },
    "volume": "62db5fcd888082246b9346c0e65311334d91ed2c",
    "sort": ""
  }
}

Référence des champs

Champ	Type	Obligatoire	Description
volume	chaîne	Oui	Clé du volume (identifiant de hachage SHA1)
query	chaîne	Oui	Type d'opération : get-dir, rename, delete, paste
params	objet	Oui	Paramètres de requête (voir ci-dessous)

Objet params

Champ	Type	Description
dir	chaîne	Chemin du répertoire à parcourir. Utilisez "" pour la racine.
limite	entier	Nombre maximal d'entrées à renvoyer (par ex. 1000)
offset	entier/null	Décalage de pagination, null pour la première page
filter.extensions	chaîne	Filtrer par extensions de fichier (chaîne vide pour toutes)
volume	chaîne	Clé du volume (doit correspondre au niveau supérieur volume)
tri	chaîne	Champ de tri (chaîne vide pour la valeur par défaut)

Réponse

{
  "location": "/v4/volume_browser/9a00434b882b9933512cc9d3abfd557a182d8fd3",
  "dbpath": "volume_browser/9a00434b882b9933512cc9d3abfd557a182d8fd3",
  "$row": 1,
  "$key": "9a00434b882b9933512cc9d3abfd557a182d8fd3"
}

Le $key le champ contient l'ID de la tâche nécessaire pour l'interrogation.

Étape 2 : Interroger les résultats

Point de terminaison

GET /api/v4/volume_browser/{job_id}?fields=id,status,result

Important : demander le champ Result

Le result le champ est NON renvoyé par défaut. Vous devez explicitement le demander avec ?fields=id,status,result. Sans ce paramètre, vous ne recevrez que des informations de statut.

Sans ?fields=id,status,result:

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

Avec ?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"}
  ]
}

Valeurs de statut

tuile	Description
running	La tâche est encore en cours de traitement
complete	La tâche s'est terminée avec succès
error	La tâche a échoué (vérifiez result pour le message d'erreur)

Stratégie d'interrogation

1. POST pour créer la tâche
2. Attendre 200 à 500 ms
3. GET avec ?fields=id,status,result
4. Si status == "running", attendez et réessayez (jusqu'à 30 tentatives)
5. Si status == "complete", traitez le résultat
6. Si status == "error", gérez l'erreur

Format du résultat

Lorsque status est complete, le result champ contient un tableau d'entrées fichier/répertoire :

[
  {
    "name": "document.pdf",
    "n_name": "document.pdf",
    "size": 102400,
    "date": 1769136871,
    "type": "file"
  },
  {
    "name": "images",
    "n_name": "images",
    "size": 4096,
    "date": 1769197982,
    "type": "directory"
  }
]

Champs de l'entrée

Champ	Type	Description
name	chaîne	Nom du fichier ou du répertoire
n_name	chaîne	Nom normalisé (en minuscules)
size	entier	Taille en octets
date	entier	Heure de modification (horodatage Unix)
type	chaîne	file ou directory

Répertoires vides

Pour les répertoires vides, result sera un tableau vide :

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

Exemples

cURL

# Étape 1 : Créer une tâche de parcours
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"')

# Étape 2 : Interroger les résultats (IMPORTANT : inclure le paramètre fields)
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"
    }

    # Étape 1 : Créer une tâche de parcours
    payload = {
        "volume": volume_key,
        "query": "get-dir",
        "params": {
            "dir": path,  # Utilisez "" pour la racine
            "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"]

    # Étape 2 : Interroger les résultats
    for _ in range(30):
        time.sleep(0.5)

        # IMPORTANT : demander explicitement le champ result
        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"Le parcours a échoué : {data.get('result')}")

    raise TimeoutError("Délai d'attente de l'opération de parcours dépassé")

Dépannage

Problèmes courants

Le champ result est vide ou manquant

• Vous devez inclure ?fields=id,status,result dans votre requête GET
• Sans ce paramètre, seules les informations de statut sont renvoyées

"La VM doit être à l'état en cours d'exécution pour effectuer une requête"

• La VM du service NAS n'est pas en cours d'exécution
• Accédez à NAS > NAS Services et démarrez le service

"Erreur lors de l'obtention du service VM des volumes : Aucun fichier ou dossier de ce type"

• Le service NAS du volume n'existe pas ou a été supprimé
• Vérifiez que le volume est associé à un service NAS valide

"Resource '/v4/volume_browser/' not found"

• ID de tâche vide dans la requête d'interrogation
• Assurez-vous d'extraire $key correctement à partir de la réponse POST

Erreurs courantes

1. Utiliser path au lieu de dir - Le champ s'appelle dir, et non path
2. Envoi des paramètres sous forme de chaîne JSON - Le params champ doit être un objet, et non une chaîne encodée en JSON
3. Champs manquants dans params - Tous les champs de l'objet params sont attendus
4. Oublier ?fields=id,status,result - Sans cela, aucune donnée de fichier n'est renvoyée

Exigences

• La VM du service NAS doit être en cours d'exécution pour parcourir les volumes
• Le volume doit être en ligne (monté)
• L'utilisateur doit avoir des autorisations de lecture sur le volume

Ressources supplémentaires

• Vue d'ensemble du NAS
• Volumes locaux NAS
• Clés API

Retour

Besoin d’aide ?

Si vous avez besoin d’aide supplémentaire ou si vous avez des questions concernant cet article, n’hésitez pas à contacter l’équipe de support VergeOS.