> 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/fr/storage-vsan/nas-volume-browser-api.md). # Référence de l’API du navigateur de volumes NAS ## Vue d’ensemble {% hint style="info" %} **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 {% endhint %} 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 ```json { "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 ```json { "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 ``` {% hint style="danger" %} **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. {% endhint %} **Sans `?fields=id,status,result`:** ```json { "id": "9a00434b882b9933512cc9d3abfd557a182d8fd3", "query": "get-dir", "status": "complete", "command": "" } ``` **Avec `?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"} ] } ``` ### 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 : ```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" } ] ``` ### 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 : ```json { "id": "8cb12559b689f5a52472bd8882dde1c095b2ab64", "status": "complete", "result": [] } ``` ## Exemples ### cURL ```bash # É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 ```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 {% hint style="warning" %} **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 {% endhint %} ### 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](/run-the-platform/nas/overview.md) * [Volumes locaux NAS](/run-the-platform/nas/nas-local-volumes.md) * [Clés API](/run-the-platform/system-administration/api-keys.md) ## Retour {% hint style="info" %} **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](/support-and-services.md). {% 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/fr/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.