Tham chiếu API NAS Volume Browser

Cách sử dụng API volume_browser của VergeOS để duyệt nội dung ổ đĩa NAS bằng chương trình, bao gồm quy trình tác vụ không đồng bộ, thăm dò kết quả và khắc phục sự cố thường gặp.

Tổng quan

Các điểm chính

• API volume_browser là bất đồng bộ - tạo một job, rồi thăm dò kết quả
• Bạn phải bao gồm ?fields=id,status,result khi thăm dò, nếu không kết quả sẽ không được trả về
• Dùng chuỗi rỗng "" cho đường dẫn thư mục gốc (không /)
• VM dịch vụ NAS phải đang chạy để duyệt các volume

Tham số volume_browser API cung cấp khả năng duyệt hệ thống tệp cho các volume NAS. Điều này hữu ích cho tự động hóa, tích hợp và xây dựng các công cụ quản lý tệp tùy chỉnh.

Điều kiện tiên quyết

• Một dịch vụ NAS đang chạy với ít nhất một volume trực tuyến
• Quyền truy cập API với quyền phù hợp
• Mã định danh khóa SHA1 của volume (tìm trong URL bảng điều khiển volume hoặc API)

Cách hoạt động

Duyệt một volume là quy trình hai bước:

1. POST sang /api/v4/volume_browser để tạo một job duyệt
2. GET sang /api/v4/volume_browser/{job_id}?fields=id,status,result để thăm dò kết quả

Bước 1: Tạo yêu cầu duyệt

Endpoint

POST /api/v4/volume_browser

Phần thân yêu cầu

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

Tham chiếu trường

Trường	Loại	Bắt buộc	Mô tả
volume	chuỗi	Có	Khóa volume (mã định danh băm SHA1)
query	chuỗi	Có	Loại thao tác: get-dir, đổi tên, delete, dán
params	đối tượng	Có	Tham số truy vấn (xem bên dưới)

Đối tượng tham số

Trường	Loại	Mô tả
dir	chuỗi	Đường dẫn thư mục để duyệt. Dùng "" cho thư mục gốc.
limit	số nguyên	Số mục tối đa trả về (ví dụ, 1000)
offset	số nguyên/null	Vị trí offset phân trang, null cho trang đầu tiên
filter.extensions	chuỗi	Lọc theo phần mở rộng tệp (chuỗi rỗng cho tất cả)
volume	chuỗi	Khóa volume (phải khớp với cấp cao nhất volume)
sort	chuỗi	Trường sắp xếp (chuỗi rỗng cho mặc định)

Phản hồi

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

Tham số $key trường chứa ID job cần cho việc thăm dò.

Bước 2: Thăm dò kết quả

Endpoint

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

Quan trọng: Yêu cầu trường result

Tham số result trường là KHÔNG được trả về theo mặc định. Bạn phải yêu cầu rõ ràng bằng ?fields=id,status,result. Nếu không có tham số này, bạn sẽ chỉ nhận được thông tin trạng thái.

Nếu không có ?fields=id,status,result:

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

Với ?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"}
  ]
}

Giá trị trạng thái

ô	Mô tả
running	Job vẫn đang xử lý
complete	Job hoàn tất thành công
error	Job thất bại (kiểm tra result để xem thông báo lỗi)

Chiến lược thăm dò

1. POST để tạo job
2. Chờ 200-500ms
3. GET với ?fields=id,status,result
4. Nếu status == "running", chờ và thử lại (tối đa 30 lần)
5. Nếu status == "complete", xử lý kết quả
6. Nếu status == "error", xử lý lỗi

Định dạng kết quả

Khi status là complete, thì result trường chứa một mảng các mục tệp/thư mục:

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

Các trường mục

Trường	Loại	Mô tả
name	chuỗi	Tên tệp hoặc thư mục
n_name	chuỗi	Tên chuẩn hóa (chữ thường)
size	số nguyên	Kích thước tính bằng byte
date	số nguyên	Thời gian sửa đổi (dấu thời gian Unix)
type	chuỗi	"file" hoặc "directory"

Thư mục trống

Đối với thư mục trống, result sẽ là một mảng rỗng:

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

Ví dụ

cURL

# Bước 1: Tạo job duyệt
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"')

# Bước 2: Thăm dò kết quả (QUAN TRỌNG: bao gồm tham số 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"
    }

    # Bước 1: Tạo job duyệt
    payload = {
        "volume": volume_key,
        "query": "get-dir",
        "params": {
            "dir": path,  # Dùng "" cho thư mục gốc
            "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"]

    # Bước 2: Thăm dò kết quả
    for _ in range(30):
        time.sleep(0.5)

        # QUAN TRỌNG: Yêu cầu rõ ràng trường 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"Browse failed: {data.get('result')}")

    raise TimeoutError("Browse operation timed out")

Khắc phục sự cố

Các sự cố thường gặp

Trường result trống hoặc bị thiếu

• Bạn phải bao gồm ?fields=id,status,result trong yêu cầu GET của bạn
• Nếu không có tham số này, chỉ thông tin trạng thái được trả về

"VM must be in running state to issue a query"

• VM dịch vụ NAS không đang chạy
• Đi tới NAS > NAS Services và khởi động dịch vụ

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

• Dịch vụ NAS của volume không tồn tại hoặc đã bị xóa
• Xác minh volume được liên kết với một dịch vụ NAS hợp lệ

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

• ID job rỗng trong yêu cầu thăm dò
• Đảm bảo bạn trích xuất $key đúng cách từ phản hồi POST

Các lỗi thường gặp

1. Sử dụng path thay vì dir - Trường được đặt tên là dir, không phải path
2. Gửi params dưới dạng chuỗi JSON - Trường params phải là một đối tượng, không phải chuỗi được mã hóa JSON
3. Thiếu các trường params - Tất cả các trường trong đối tượng params đều được mong đợi
4. Quên ?fields=id,status,result - Nếu không có điều này, sẽ không có dữ liệu tệp nào được trả về

Yêu cầu

• VM dịch vụ NAS phải đang chạy để duyệt các volume
• Volume phải ở trạng thái trực tuyến (đã được gắn)
• Người dùng phải có quyền đọc trên volume

Tài nguyên bổ sung

• Tổng quan NAS
• Các volume cục bộ NAS
• Khóa API

Phản hồi

Cần trợ giúp?

Nếu bạn cần thêm hỗ trợ hoặc có bất kỳ câu hỏi nào về bài viết này, vui lòng đừng ngần ngại liên hệ với Đội ngũ Hỗ trợ VergeOS.