Referencia de la API del explorador de volúmenes NAS

Cómo usar la API volume_browser de VergeOS para explorar programáticamente el contenido de volúmenes NAS, incluido el flujo de trabajo de tareas asíncronas, la sondeo de resultados y la solución de problemas comunes.

Resumen

Puntos clave

• La API volume_browser es asíncrona - cree un trabajo y luego consulte los resultados
• Usted debe incluir ?fields=id,status,result al consultar o el resultado no se devolverá
• Use una cadena vacía "" para la ruta del directorio raíz (no /)
• La VM del servicio NAS debe estar en ejecución para explorar los volúmenes

El volume_browser La API proporciona capacidades de exploración del sistema de archivos para volúmenes NAS. Esto es útil para la automatización, las integraciones y la creación de herramientas personalizadas de gestión de archivos.

Requisitos previos

• Un servicio NAS en ejecución con al menos un volumen en línea
• Acceso a la API con los permisos adecuados
• El identificador de clave SHA1 del volumen (se encuentra en la URL del panel del volumen o en la API)

Cómo funciona

Explorar un volumen es un proceso de dos pasos:

1. POST a /api/v4/volume_browser para crear un trabajo de exploración
2. GET a /api/v4/volume_browser/{job_id}?fields=id,status,result para consultar los resultados

Paso 1: Crear una solicitud de exploración

Punto final

POST /api/v4/volume_browser

Cuerpo de la solicitud

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

Referencia de campos

Campo	Tipo	Obligatorio	Descripción
volume	cadena	Sí	Clave del volumen (identificador hash SHA1)
query	cadena	Sí	Tipo de operación: get-dir, rename, delete, paste
params	objeto	Sí	Parámetros de consulta (ver abajo)

Objeto de parámetros

Campo	Tipo	Descripción
dir	cadena	Ruta del directorio a explorar. Use "" para la raíz.
limit	entero	Número máximo de entradas a devolver (p. ej., 1000)
offset	entero/null	Desplazamiento de paginación, null para la primera página
filter.extensions	cadena	Filtrar por extensiones de archivo (cadena vacía para todas)
volume	cadena	Clave del volumen (debe coincidir con el nivel superior volume)
sort	cadena	Campo de ordenación (cadena vacía para el valor predeterminado)

Respuesta

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

El $key el campo contiene el ID del trabajo necesario para la consulta.

Paso 2: Consultar los resultados

Punto final

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

Crítico: Solicite el campo result

El result el campo es NO se devuelve de forma predeterminada. Debe solicitarlo explícitamente con ?fields=id,status,result. Sin este parámetro, solo recibirá información de estado.

Sin ?fields=id,status,result:

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

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

Valores de estado

Estado	Descripción
running	El trabajo sigue procesándose
complete	El trabajo finalizó correctamente
error	El trabajo falló (consulte result para ver el mensaje de error)

Estrategia de consulta

1. Haga una solicitud POST para crear el trabajo
2. Espere 200-500 ms
3. Haga una solicitud GET con ?fields=id,status,result
4. Si status == "running", espere y vuelva a intentarlo (hasta 30 intentos)
5. Si status == "complete", procese el resultado
6. Si status == "error", gestione el error

Formato del resultado

Cuando status es complete, el result campo contiene una matriz de entradas de archivo/directorio:

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

Campos de la entrada

Campo	Tipo	Descripción
name	cadena	Nombre del archivo o directorio
n_name	cadena	Nombre normalizado (minúsculas)
size	entero	Tamaño en bytes
date	entero	Hora de modificación (marca de tiempo Unix)
type	cadena	"file" o "directory"

Directorios vacíos

Para directorios vacíos, result será una matriz vacía:

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

Ejemplos

cURL

# Paso 1: Crear trabajo de exploración
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"')

# Paso 2: Consultar resultados (IMPORTANTE: incluya el parámetro 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"
    }

    # Paso 1: Crear trabajo de exploración
    payload = {
        "volume": volume_key,
        "query": "get-dir",
        "params": {
            "dir": path,  # Use "" para la raíz
            "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"]

    # Paso 2: Consultar resultados
    for _ in range(30):
        time.sleep(0.5)

        # IMPORTANTE: solicite explícitamente el campo 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"La exploración falló: {data.get('result')}")

    raise TimeoutError("La operación de exploración agotó el tiempo de espera")

Resolución de problemas

Problemas comunes

El campo result está vacío o falta

• Debe incluir ?fields=id,status,result en su solicitud GET
• Sin este parámetro, solo se devuelve información de estado

"La VM debe estar en estado en ejecución para emitir una consulta"

• La VM del servicio NAS no se está ejecutando
• Vaya a NAS > Servicios NAS e inicie el servicio

"Error getting volumes VM service: No such file or directory"

• El servicio NAS del volumen no existe o fue eliminado
• Verifique que el volumen esté asociado con un servicio NAS válido

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

• ID de trabajo vacío en la solicitud de consulta
• Asegúrese de extraer $key correctamente de la respuesta POST

Errores comunes

1. Usando ruta en lugar de dir - El campo se llama dir, no ruta
2. Enviar los parámetros como cadena JSON - El params campo debe ser un objeto, no una cadena codificada en JSON
3. Faltan campos de params - Se esperan todos los campos del objeto params
4. Olvidar ?fields=id,status,result - Sin esto, no se devuelven datos de archivo

Requisitos

• La VM del servicio NAS debe estar en ejecución para explorar los volúmenes
• El volumen debe estar en línea (montado)
• El usuario debe tener permisos de lectura sobre el volumen

Recursos adicionales

• Descripción general de NAS
• Volúmenes locales de NAS
• Claves de API

Comentarios

¿Necesitas ayuda?

Si necesita más ayuda o tiene alguna pregunta sobre este artículo, no dude en ponerse en contacto con el equipo de soporte de VergeOS.