ls-列出目录内容--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

请输入

文件系统操作

ls-列出目录内容

概述

/api/v1/fs/ls 接口用于列出 OpenViking 文件系统中的目录内容，支持简单路径列表、递归列出子目录等多种输出模式。

前置条件

完成 API 鉴权说明页面的 API Key 获取后，可调用本接口列出目录内容。

请求接口

URI	/api/v1/fs/ls	统一资源标识符
请求方法	GET	客户端请求类型
请求头	Authorization: Bearer	Bearer Token 鉴权

请求参数

参数	类型	必选	默认值	备注
uri	string	是	--	Viking URI 要列出内容的目录 URI。
simple	bool	否	false	仅返回 URI 列表为 `true` 时仅返回条目的 URI，不包含其他元信息。
recursive	bool	否	false	递归列出为 `true` 时递归列出所有子目录内容。
output	string	否	`agent`	输出格式 `agent` 或 `original`。
abs_limit	int	否	256	摘要长度限制 `agent` 输出中的摘要长度限制。
show_all_hidden	bool	否	false	是否显示隐藏文件像 `-a` 一样包含隐藏文件。
node_limit	int	否	1000	最大返回节点数限制返回的目录条目数量。
limit	int	否	None	node_limit 的别名与 `node_limit` 功能相同。

响应消息

字段	参数说明
status	请求状态，成功为 `"ok"`，失败为 `"error"`
result	成功时返回的条目数组，每个条目包含以下字段（`simple=true` 时仅返回 URI 字符串数组）
result[].uri	文件或目录的 Viking URI
result[].size	大小（字节）
result[].isDir	是否为目录，目录为 `true`，文件为 `false`
result[].modTime	修改时间（如 `"04:26:42"`）
result[].abstract	目录摘要信息，文件通常为空字符串
result[].rel_path	相对路径（仅在 `recursive=true` 时返回）
telemetry	遥测信息，通常为 `null`
error	失败时返回的错误对象
error.code	错误码字符串，常见值见下表
error.message	可读的错误描述

常见错误码：

error.code	说明
UNAUTHENTICATED	缺少或无效的 API Key
PERMISSION_DENIED	权限不足
INVALID_ARGUMENT	无效参数
INVALID_URI	无效的 Viking URI 格式
NOT_FOUND	资源未找到

完整示例

示例一：基本目录列表

curl -X GET "https://xxx/api/v1/fs/ls?uri=viking://resources/" \
  -H "X-Api-Key: your-api-key"

执行成功返回：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ok",
    "result": [
        {
            "uri": "viking://resources/docs/",
            "size": 0,
            "isDir": true,
            "modTime": "04:26:42",
            "abstract": "目录摘要信息"
        }
    ],
    "error": null,
    "telemetry": null
}

示例二：简单路径列表

curl -X GET "https://xxx/api/v1/fs/ls?uri=viking://resources/&simple=true" \
  -H "X-Api-Key: your-api-key"

执行成功返回：

{
    "status": "ok",
    "result": [
        "viking://resources/conversation-export.md"
    ],
    "error": null,
    "telemetry": null
}

示例三：递归列出目录

curl -X GET "https://xxx/api/v1/fs/ls?uri=viking://resources/&recursive=true" \
  -H "X-Api-Key: your-api-key"

执行成功返回：

{
    "status": "ok",
    "result": [
        {
            "uri": "viking://resources/docs/",
            "size": 0,
            "isDir": true,
            "modTime": "03:25:26",
            "rel_path": "docs",
            "abstract": "目录摘要信息"
        },
        {
            "uri": "viking://resources/docs/readme.md",
            "size": 4011,
            "isDir": false,
            "modTime": "04:22:05",
            "rel_path": "docs/readme.md",
            "abstract": ""
        }
    ],
    "error": null,
    "telemetry": null
}

最近更新时间：2026.05.26 11:19:26

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

示例一：基本目录列表 #

示例二：简单路径列表 #

示例三：递归列出目录 #

示例一：基本目录列表

示例二：简单路径列表

示例三：递归列出目录