> 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/es/storage-vsan/nas-volume-browser-api.md).

# Referencia de la API del explorador de volúmenes NAS

## Resumen

{% hint style="info" %}
**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
  {% endhint %}

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

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

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

{% hint style="danger" %}
**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.
{% endhint %}

**Sin `?fields=id,status,result`:**

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

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

### 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:

```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"
  }
]
```

### 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:

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

## Ejemplos

### cURL

```bash
# 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

```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

{% hint style="warning" %}
**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
  {% endhint %}

### 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](/run-the-platform/nas/overview.md)
* [Volúmenes locales de NAS](/run-the-platform/nas/nas-local-volumes.md)
* [Claves de API](/run-the-platform/system-administration/api-keys.md)

## Comentarios

{% hint style="info" %}
**¿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](https://app.gitbook.com/o/FpusSnrkRHyZiVEsXf9X/s/yj8JovQN0DuGOoi1frJ7/support-and-services).
{% 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/es/storage-vsan/nas-volume-browser-api.md?ask=<question>&goal=<endgoal>
```

`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.