帮你快速理解、总结文档立即下载
文档中心>智能媒资托管>业务级 API 文档>目录或相簿操作接口>列出目录或相簿

列出目录或相簿

最近更新时间：2026-08-18 20:40:02
我的收藏

本页目录：

功能描述

用于列出目录或相簿内容。
说明：
目录内容的列出顺序为：首先按照字典序列出子目录，随后根据上传时间列出媒体库中的媒体资源，或根据文件名列出文件库的文件资源。

请求

请求示例

GET /api/v1/directory/{LibraryId}/{SpaceId}/{DirPath}?page={Page}&page_size={PageSize}&order_by={OrderBy}&order_by_type={OrderByType}&filter={DirectoryFilter}&access_token={AccessToken}&user_id={UserId}&with_content_cas={WithContentCas}&prefix={Prefix}&start_name={StartName}

请求参数

请求参数
描述
类型
是否必选
LibraryId
媒体库 ID，在媒体托管控制台创建媒体库后获取，请参见 创建媒体库
String
是
SpaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则为具体 ID，获取请参见 创建租户空间
String
是
DirPath
目录路径或相簿名，对于多级目录，使用斜杠(/)分隔，例如 foo/bar；对于根目录，该参数留空。
String
否
Marker
用于顺序列出分页的标识，不能与 page 和 page_size 参数同时使用
String
否
Limit
用于顺序列出分页时本地列出的项目数限制，不能与 page 和 page_size 参数同时使用
String
否
Page
分页码，默认第一页，不能与 marker 和 limit 参数同时使用
String
否
PageSize
分页大小，默认20，不能与 marker 和 limit 参数同时使用
String
否
OrderBy
排序字段，按名称排序为 name，按修改时间排序为 modificationTime，按文件大小排序为 size，按创建时间排序为 creationTime，按照文件对应的本地创建时间排序为 localCreationTime，按照文件对应的本地修改时间排序为 localModificationTime
String
否
OrderByType
排序方式，升序为 asc，降序为 desc
String
否
DirectoryFilter
筛选方式，不传返回全部，onlyDir 只返回文件夹，onlyFile 只返回文件
String
否
SortType
排序方式，不传则文件和文件夹单独排序，先返回文件夹，后返回文件。union 文件和文件夹统一排序
String
否
WithInode
0或1，是否返回 inode，即文件目录 ID，默认不返回
String
否
WithFavoriteStatus
0或1，是否返回收藏状态，默认不返回
String
否
AccessToken
访问令牌，对于公有读媒体库或租户空间，可不指定该参数，否则必须指定该参数，获取请参见 生成访问令牌
String
否
UserId
用户身份识别，当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份，详情请参见 生成访问令牌
String
否
WithContentCas
0或1，是否返回文件内容的 Cas 标识，可选，默认不返回
String
否
Prefix
名称前缀过滤，筛选 name 以指定前缀开头的子目录和文件。可选参数，仅在 order_by 为 name 时生效，其他排序字段下传此参数会返回错误
String
否
StartName
筛选 name 大于指定值的子目录和文件（大于，不包含等于），用于翻页游标。可选参数，仅在 order_by 为 name 时生效，其他排序字段下传此参数会返回错误，可与 Prefix 组合使用
String
否

请求体

该请求无请求体。

响应

响应码

获取成功，返回 HTTP 200 OK。

响应体

application/json
响应体示例：
{
  "path": [ "foo", "bar" ],
  "nextMarker": 1013,
  "fileCount": 10,
  "subDirCount": 8,
  "totalNum":18,
  "localSync": {
    "syncId": 4,
    "strategy": "local_to_cloud",
    "isSyncRootFolder": true,
    "syncUserId": "123"
  },
  "contents": [
      {
          "name": "sub-dir1",
          "path":["xxx","xxx"],
          "type": "dir",
          "creationTime": "2020-09-22T07:43:01.000Z",
          "modificationTime": "2020-09-22T07:43:01.000Z",
          "versionId":2, 
          "localSync": {
            "syncId": 4,
            "strategy": "local_to_cloud",
            "syncUserId": "",
            "isSyncRootFolder": false,
          },
          "authorityList": {
              "canView": false,
              "canPreview": false,
              "canDownload": false,
              "canUpload": false,
              "canDelete": false,
              "canModify": false,
              "canAuthorize": false,
              "canShare": false
          }
      },
      {
          "name": "sub-dir2",
          "type": "dir",
          "creationTime": "2020-09-22T07:43:14.000Z",
          "modificationTime": "2020-09-22T07:43:14.000Z"
      },
      {
          "name": "file1.jpg",
          "type": "file",
          "creationTime": "2020-09-22T07:44:45.000Z",
          "modificationTime": "2020-09-22T07:44:45.000Z",
          "contentType": "image/jpg",
          "size": "1048576",
          "eTag": "xxx",
          "crc64": "xxx",
          "authorityList": {
              "canView": false,
              "canPreview": false,
              "canDownload": false,
              "canUpload": false,
              "canDelete": false,
              "canModify": false,
              "canAuthorize": false,
              "canShare": false
          },
          "metaData": {
              "x-smh-meta-foo": "bar"
          },
          "previewByDoc": true,
          "previewByCI": true,
          "previewAsIcon": true,
          "fileType": "powerpoint",
      },
      {
          "name": "file2.docx",
          "type": "file",
          "creationTime": "2020-09-22T07:46:08.000Z",
          "modificationTime": "2020-09-22T07:46:08.000Z",
          "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingm",
          "size": "1048576",
          "eTag": "xxx",
          "crc64": "xxx",
          "metaData": {
              "x-smh-meta-foo": "bar"
          },
          "previewByDoc": true,
          "previewByCI": true,
          "previewAsIcon": true,
          "fileType": "powerpoint",
      }
  ],
  "authorityList": {
      "canView": false,
      "canPreview": false,
      "canDownload": false,
      "canUpload": false,
      "canDelete": false,
      "canModify": false,
      "canAuthorize": false,
      "canShare": false,
      "canPreviewSelf": false,
      "canDownloadSelf": false
  }
}
响应体字段说明：
响应参数
描述
类型
path
返回当前请求的目录结构，如果当前请求的是根目录，则该字段为空数组
Array
fileCount
当前目录中的文件数（不包含孙子级）
Int
subDirCount
当前目录中的子目录数（不包含孙子级）
Int
totalNum
当前目录中的所有文件和子目录数量（不包含孙子级）
Int
nextMarker
用于顺序列出分页的标识
String/Int
contents
目录或相簿内的具体内容
Array
contents 中具体参数如下：
响应参数
描述
类型
name
目录或相簿名或文件名
String
path
文件具体目录
String
inode
文件目录 ID
String
versionId
版本号
String
type
条目类型：
dir：目录或相簿。
file：文件，仅用于文件类型媒体库。
image：图片，仅用于媒体类型媒体库。
video：视频，仅用于媒体类型媒体库。
symlink：符号链接。
String
creationTime
ISO 8601格式的日期与时间字符串，表示目录或相簿的创建时间或文件的上传时间，例如 2020-10-14T10:17:57.953Z
String
modificationTime
文件最近一次被覆盖的时间，或者目录内最近一次增删子目录或文件的时间
String
contentType
媒体类型
String
size
文件大小，为了避免数字精度问题
String
eTag
文件 ETag
String
isFavorite
是否被收藏，当 WithFavoriteStatus = 1时返回
Boolean
crc64
文件的 CRC64-ECMA182 校验值
String
metaData
文件元数据信息
String
previewByDoc
是否可通过 WPS 预览
Boolean
previewByCI
是否可通过万象预览
Boolean
previewAsIcon
是否可用预览图作为 icon
Boolean
fileType
文件类型：Excel、PowerPoint 等
String
category
文件分类，比如 image、video、doc 等
String
labels
简易文件标签
Array
localCreationTime
文件对应的本地创建时间
String
localModificationTime
文件对应的本地修改时间
String
contentCas
文件内容的 Cas 标识
String

错误码

该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。
中国站