JavaScriptSDK文件增删改查与管理-网盘与相册服务-阿里云

提供文件相关的操作方法，包括文件增删改查，复制，移动等。

说明

请求参数中的 options: IPDSRequestConfig 基于 axios 的 request config 封装，详情请看：AxiosRequestConfig。

listFiles 方法

列举指定目录下的文件或文件夹。

const result = await client.listFiles(params, options)

举例

const {items=[]} = await client.listFiles({
  drive_id:'1001', 
  parent_file_id:'root'
})

参数说明

字段	类型	必选	说明
params	IListFileReq	是	查询参数。
options	IPDSRequestConfig		其它配置项。

IListFileReq

字段	类型	必选	说明
drive_id	string		云盘ID。drive_id和share_id必选其一。
share_id	string		分享ID。drive_id和share_id必选其一。
parent_file_id	string		上级文件目录ID。
fields	string		返回文件字段，返回全部字段传 "*"。不传则只返回基本字段。默认：不传。
url_expire_sec	number		URL有效时间。
video_thumbnail_process	string		视频缩略图处理表达式。请参考图片处理。
image_thumbnail_process	string		图片缩略图处理表达式。请参考图片处理。
image_url_process	string		图片URL处理表达式。请参考图片处理。
limit	number		返回的数量限制。
marker	string		分页标记。
order_by	string		排序字段。
order_direction	string		可选值 'DESC' \| 'ASC'。
starred	boolean		是否收藏。
category	string		类别。
status	string		状态。
type	string		文件类型, 可选 'file' \| 'folder'

IFileItem

字段	类型	必选	说明
action_list	array		权限列表。
category	string		文件类型, 取值：app \| doc \| image \| video \| audio \| zip \| others。
content_hash	string		文件标识。
content_hash_name	string		使用的加密方式。
content_type	string		内容类型。
crc64_hash	string		crc计算的hash值。
created_at	Date	是	创建时间。
creator_id	string	是	创建人ID。
creator_name	string	是	创建人名称。
creator_type	string	是	创建人类型，取值：'group' \| 'user'。
domain_id	string	是	domain ID。
download_url	string		下载URL，文件类型返回。
drive_id	string	是	云盘ID。
description	string		描述信息。
encrypt_mode	string	是	加密模式。
file_extension	string		文件扩展名, 如： `.txt`。
file_id	string	是	文件夹ID。
hidden	boolean	是	是否隐藏。
last_modifier_id	string	是	最后修改人ID。
last_modifier_name	string		最后修改人名称。
last_modifier_type	string		修改人类型，取值：'group' \| 'user'。
labels	string		标签。
location	string		位置。
mime_extension	string		媒体类型扩展名。
mime_type	string		媒体类型。
meta	string		云信息。
name	string	是	文件夹名称。
parent_file_id	string	是	上级目录ID。
punish_flag	number		错误数量。
revision_id	string	是	修订版本。
rapid_upload	boolean		是否秒传。
size	number		文件大小，单位Byte。
starred	boolean	是	是否收藏。
status	string	是	可选值 'available' \| 'uploading'
streams_upload_info			流上传信息。
thumbnail	string		图片和视频文件才有。
type	string	是	文件类型，可选值 'file' \| 'folder'。
trashed	boolean		是否已被移到回收站里。
updated_at	Date	是	更新时间。
user_meta	string
upload_id	string		上传ID。
url	string		原文件URL。

download_url 和 url 的区别：download_url 会增加
Content-Disposition: attachment; filename="filename"
消息头，浏览器会直接下载。URL没有这个消息头，有些文件浏览器会直接打开，比如浏览器支持直接打开的图片，mp4，pdf等。
关于 thumbnail，图片，视频等才有缩略图。

searchFiles 方法

根据条件搜索文件。

const result = await client.searchFiles(params, options, isRecycleBin)

参数说明

字段	类型	必选	说明
params	object	是	搜索相关参数，请查看 ISearchFileReq。
options	IPDSRequestConfig		其它配置项。
isRecycleBin	boolean		回收站搜索传 true，其它传 false，默认为false。

ISearchFileReq

字段	类型	必选	说明
limit	number		返回的数量限制。
query	string	是	筛选条件语句，具体用法请看文件搜索。
drive_id	string	是	云盘ID。
fields	string		返回文件字段，返回全部字段传 "*"。不传则只返回基本字段。默认：不传。
order_by	string		排序字段。
marker	string		分页标记。
url_expire_sec	number		URL 有效时间。默认2小时。
image_thumbnail_process	string		图片缩略图处理表达式。请参考图片处理。
image_url_process	string		图片URL 处理表达式。请参考图片处理。
video_thumbnail_process	string		视频缩略图处理表达式。请参考图片处理。

返回值

字段	类型	必选	说明
result	IListRes	是	返回结果。

IListRes

字段	类型	必选	说明
items	array	是	文件列表，具体项字段请参考 listFiles 方法中的 IFileItem。
next_marker	string		分页标记。

getFile 方法

根据文件ID查询文件信息。

const result = await client.getFile(params, options)

参数说明

字段	类型	必选	说明
params	object	是	查询参数，查看 IGetFileReq 类型。
options	IPDSRequestConfig		其它配置项。

IGetFileReq

字段	类型	必选	说明
drive_id	string		云盘ID。drive_id和share_id必选其一。
share_id	string		分享ID。drive_id和share_id必选其一。
file_id	string		文件ID
fields	string		返回文件字段，返回全部字段传 "*"。不传则只返回基本字段。默认：不传。
url_expire_sec	number		返回的各个 URL 签名的有效时间。
video_thumbnail_process	string		视频缩略图处理表达式。请参考图片处理。
image_thumbnail_process	string		图片缩略图处理表达式。请参考图片处理。
image_url_process	string		图片URL处理表达式。请参考图片处理。

返回值

字段	类型	必选	说明
result	object	是	返回结果，具体请查看 IFileItem 类型。

getFileDownloadUrl

获取文件的 download_url, 在浏览器中打开 download_url 可以直接下载文件。

const result = await client.getFileDownloadUrl(params, options)

举例

const info = await client.getFileDownloadUrl({
  drive_id: '1',
  file_id: 'xxxxx',
})

参数说明：

字段	类型	必选	说明
params	object	是	查询参数，查看 IGetFileDownloadUrlReq 类型。
options	IPDSRequestConfig		其它配置项。

IGetFileDownloadUrlReq

字段	类型	必选	说明
drive_id	string		云盘ID。drive_id和share_id必选其一。
share_id	string		分享ID。drive_id和share_id必选其一。
file_id	string		文件ID。
fields	string		返回文件字段，返回全部字段传 "*"。不传则只返回基本字段。默认：不传。
file_name	string		下载文件名称，即下载时服务端响应头会设置`Content-Disposition: attachment; filename="file_name"`。最长 1024 字符。
expire_sec	number		url有效时间。单位秒。最长 115200 秒，默认为 900 秒。

字段	类型	必选	说明
result	object	是	返回结果，具体请查看 IGetFileDownloadUrlRes 类型。

IGetFileDownloadUrlRes

字段	类型	必选	说明
expiration	string	是	过期时间。
method	string	是	适用的HTTP方法，一般为 GET。
url	string	是	文件下载 URL。
size	number		文件大小，单位Byte。

saveFileContent 方法

保存内容到文件, 或者新建文件。

传入相同文件ID会覆盖，不传文件ID，会被认为是新文件，将根据 check_name_mode 参数执行相应的策略。check_name_mode 默认是 'refuse'。

const result = await client.saveFileContent(params, content, config)

举例

新建空文件

await client.saveFileContent({
  drive_id: '1',
  parent_file_id: 'root',
  name: '未命名.txt',
  content_type: 'text/plain; charset=utf-8',
}, '')

修改已有文件的内容

await client.saveFileContent(fileItem, '修改的内容')

参数说明

字段	类型	必选	说明
params	IGetFileReq	是	文件信息，查看 IGetFileReq 类型。
content	string		文件内容，默认为空 ''。
config	ISaveFileConfig		其他配置。

ISaveFileConfig

字段

类型

必选

说明

check_name_mode

boolean

同名策略配置，取值范围：

auto_rename: 文件名后面增加随机数。

refuse: 抛出 code 为 AlreadyExists 的异常

ignore: 允许同名。

默认 refuse。

如果第一个参数含有 file_id 字段, 则此字段失效。

ignore_rapid

boolean

（主要用来测试）强制不秒传，默认false。

返回值

字段	类型	必选	说明
result	object	是	返回结果，具体请查看 IFileItem 类型

getFileContent 方法

获取文件内容（一般用来读取文本文件内容）。

注意，此方法获取文件内容直接赋值给变量，如果文件太大（太占用内存）不建议使用此方法。

const result = await client.getFileContent(params, options)

参数说明

字段	类型	必选	说明
params	IGetFileReq	是	请求参数。
options	IPDSRequestConfig		其他请求参数。

返回值中的 content 字段，和 options.responseType 相关。默认responseType为 arraybuffer。返回的content是 Buffer（for node.js）| ArrayBuffer（for 浏览器）。
如果确定文件内容是文本文件，options.responseType 应该设置为 text，这样返回的 content就是个字符串。

返回值

字段	类型	必选	说明
result	object	是	返回结果

result

字段	类型	必选	说明
headers	object	是	相应头信息。
content	Buffer \| string \| ...	是	内容信息，可能为空。根据 responseType 的设置返回不同格式。详细情况请参考axios的responseType说明。
size	number	是	文件大小，单位Byte。
type	string	是	文件ID。
updated_at	string	是	更新时间。
status	string	是	状态。

renameFile 方法

文件/文件夹重命名

const result = await client.renameFile(fileItem, newName,check_name_mode)

举例

await client.renameFile({
  drive_id: "1",
  file_id: 'xxxxxx',
}, '新的名称.txt')

参数说明

字段	类型	必选	说明
fileItem	IFileItem	是	要重命名的文件信息，查看 IFileItem 类型。
newName	string	是	新名称。
check_name_mode	string		同名策略配置，取值范围： auto_rename: 文件名后面增加随机数。 refuse: 抛出 `code` 为 `AlreadyExists` 的异常 ignore: 允许同名。默认 refuse。如果第一个参数含有 file_id 字段，则此字段失效。

返回值

字段	类型	必选	说明
result	object	是	返回结果，查看 IFileItem 类型。

updateFile 方法

修改文件/文件夹信息。

const result = await client.updateFile(params, options)

参数说明

字段	类型	必选	说明
params	object	是	要更新的文件信息，字段请查看 IUpdateFileReq。
options	IPDSRequestConfig		其它配置项。

IUpdateFileReq

字段	类型	必选	说明
drive_id	string		云盘ID。drive_id 和 share_id 必选其一。
share_id	string		分享ID。drive_id 和 share_id 必选其一。
file_id	string	是	文件ID。
check_name_mode	string		同名策略配置，取值范围： auto_rename: 文件名后面增加随机数。 refuse: 抛出 `code` 为 `AlreadyExists` 的异常 ignore: 允许同名。
parent_file_id	string		上级目录ID。
custom_index_key	string		自定义的key。
description	string		描述。
encrypt_mode	string		加密模式。
hidden	boolean		是否隐藏。
labels	array		标签。
meta	string
name	string		名称。
starred	boolean		是否收藏。
user_meta	string

返回值

字段	类型	必选	说明
result	object	是	返回更新之后的信息，具体项字段请参考 listFiles 方法中的 IFileItem 类型。

getFileByPath 方法

根据路径获取文件或文件夹信息。

比如：根据 /a/b/c ，获取对应的文件Item信息。

const result = await client.getFileByPath(params, options)

参数说明

字段	类型	必选	说明
params	IGetFileByPathReq	是	参数。
options	IPDSRequestConfig		其它配置项。

IGetFileByPathReq

字段	类型	必选	说明
drive_id	string	是	drive ID。
file_path	string	是	文件夹路径，样式如： ‘/a/b/c’ 。
fields	string		文件类型，全部为 *。
url_expire_sec	number		URL有效时间，单位：秒。
video_thumbnail_process	string		视频缩略图处理表达式。请参考图片处理。
image_thumbnail_process	string		图片缩略图处理表达式。请参考图片处理。
image_url_process	string		图片URL处理表达式。请参考图片处理。

返回值

字段	类型	必选	说明
result	object	是	返回结果，具体请查看 IFileItem 类型。

getBreadcrumbFolderList 方法

获取多级面包屑目录信息：从当前目录递归向上查找所有目录信息（调用getFile接口）。

返回的数组不包含root目录。

异常情况

* 1. 遇到没有权限（403）的目录，将截止。返回的数组包含一个 is_forbidden==true 的目录信息。

* 2. 其他异常直接抛出报错。

const result = await client.getBreadcrumbFolderList(params, options)

举例

// 假设有目录：/a/b/c/
// 目录 c 的 file_id 为 “620cb4363a20321aa66a495ca063ac2679a8f726”

const arr = await client.getBreadcrumbFoldderList({
  drive_id,
  file_id,
})
// 返回多级面包屑目录信息：[{file_id:'a的目录ID', name:'a'},{file_id:'b的目录ID', name:'b'}]

参数说明

字段	类型	必选	说明
params	IGetBreadcrumbReq	是	参数。
options	IPDSRequestConfig		其它配置项。

IGetBreadcrumbReq

字段	类型	必选	说明
drive_id	string		云盘 ID 。drive_id 和 share_id 必选其一。
share_id	string		分享ID。drive_id 和 share_id 必选其一。
file_id	string	是	当前目录 ID。
end_parent_id	string		截止查找的父目录ID。默认： root。

字段	类型	必选	说明
result	IParentFolderNameId[]	是	返回结果。

IParentFolderNameId

字段	类型	必选	说明
file_id	string	是	目录的文件ID。
name	string	是	目录名称。
is_forbidden	boolean		遇到没有权限查询的目录时为true。

getBreadcrumbFolders 方法

警告

（不推荐使用此方法）请使用 getBreadcrumbFolderList 方法替代

获取多级面包屑目录信息：从当前目录递归向上查找所有目录信息（调用getFile接口）。

返回的数组不包含root目录。

异常情况

* 1. 遇到没有权限（403）的目录，将截止。返回的数组包含一个 is_forbidden==true 的目录信息。

* 2. 其他异常直接抛出报错。

const result = await client.getBreadcrumbFolders(drive_id,file_id, end_parent_id)

参数说明

字段	类型	必选	说明
drive_id	string	是	当前云盘 ID。
file_id	string	是	当前目录 ID。
end_parent_id	string		截止查找的父目录ID。默认： root。

返回值

字段	类型	必选	说明
result	IParentFolderNameId[]	是	返回结果。

IParentFolderNameId

字段	类型	必选	说明
file_id	string	是	目录的文件ID。
name	string	是	目录名称。
is_forbidden	boolean		遇到没有权限查询的目录时为true。

createFolder 方法

创建目录（文件夹）

const result = await client.createFolder(params, options)

举例：

await client.createFolder({
  name: '新建文件夹',  
  drive_id: '1',
  parent_file_id: 'root',
  // check_name_mode:'auto_rename'
})

参数说明

字段	类型	必选	说明
params	ICreateFolderReq	是	查看 `ICreateFolderReq` 类型。
options	IPDSRequestConfig	否	其它配置项。

ICreateFolderReq

字段	类型	必选	说明
check_name_mode	string		同名策略配置，取值范围： auto_rename: 文件名后面增加随机数。 refuse: 抛出 `code` 为 `AlreadyExists` 的异常 ignore: 允许同名。默认 refuse。
drive_id	string		云盘ID。drive_id 和 share_id 必选其一。
share_id	string		分享ID（分享链接有效）。drive_id 和 share_id 必选其一。
name	string	是	目录名称。
parent_file_id	string	是	上级文件ID，根路径传 root。

返回值

字段	类型	必选	说明
result	ICreateFolderRes	是	返回结果

ICreateFolderRes

字段	类型	必选	说明
domain_id	string	是	domain ID。
drive_id	string		云盘ID。drive_id 和 share_id 必选其一。
share_id	string		分享ID。drive_id 和 share_id 必选其一。
encrypt_mode	string		加密模式
file_id	string	是	文件ID
file_name	string	是	文件名称
parent_file_id	string	是	上级文件ID，根路径传 'root'
type	string	是	文件类型，可选值 'file' \| 'folder'，

样例：

{
  "parent_file_id": "root",
  "type": "folder",
  "file_id": "61ba1892abbe9f56bb7342c4beee82156e68dd67",
  "domain_id": "daily123",
  "drive_id": "1",
  "file_name": "新建文件夹",
  "encrypt_mode": "none"
}

createFolders 方法

如果遇到同名的情况，根据 check_name_mode 策略执行。

const result = await client.createFolders(folderNames, parentKey, config)

参数说明

字段	类型	必选	说明
folderNames	string[]	是	目录名称，比如要创建的目录是 ‘a/b/c’, 传入格式 ['a', 'b', 'c' ]
parentKey	IParentFileKey	是	创建多级文件夹参数
config	ICreateFoldersConfig		可选配置参数

IParentFileKey

字段	类型	必选	说明
drive_id	string		云盘ID。drive_id 和 share_id 必选一个。
share_id	string		分享ID。drive_id 和 share_id 必选一个。
parent_file_id	string	是	上级目录ID，根目录为 'root'。

ICreateFoldersConfig

字段	类型	必选	说明
check_name_mode	string		同名策略配置，取值范围： auto_rename: 文件名后面增加随机数。 refuse: 回调 `onFolderRepeat`。 ignore: 允许同名。 overwrite: 同名覆盖。 skip: 同名跳过。默认 refuse。
create_folder_cache	Map<string, any>={}		缓存目录信息的map。
onFolderRepeat	()=>boolean		发现路径存在时的回调，返回 `true` 继续，返回 `false`，会抛出`code`为`AlreadyExists`的错误
onFolderCreated	(fileItem)=>void		创建成功的回调

返回值

字段	类型	必选	说明
result	string	是	创建成功的路径

deleteFile 方法

删除指定文件或者文件夹。

await client.deleteFile(params, permanently, options)

参数说明

字段	类型	必选	说明
params	IFileKey	是	要删除的文件信息。
permanently	boolean		是否永久删除，false 表示暂时删除，true 表示永久删除, 默认 false。
options	IPDSRequestConfig		其它配置项。

IFileKey

字段	类型	必选	说明
share_id	string		分享id，drive_id 和 share_id 必选其一。
drive_id	string		云盘id，drive_id 和 share_id 必选其一。
file_id	string		要删除的文件或文件夹ID。

如果是删除单个文件，可能直接返回 http status code 204，响应body为空。

如果是删除目录，可能会返回 http status code 202， body 以下字段组成的 JSON结构：

字段	类型	必选	说明
async_task_id	string		异步任务id。
domain_id	string		DomainID。
file_id	string		删除的文件或文件夹ID。

batchDeleteFiles 方法

批量删除指定文件或者文件夹。

const result = await client.batchDeleteFiles(params, permanently, options)

参数说明

字段	类型	必选	说明
params	IFileKey[]	是	要删除的文件信息列表，支持批量，其中每一项的字段请参考 IBatchFileReq 的说明。（注意：只需传入要删除的文件ID或目录ID，该方法会自动递归目录删除下面的文件。）
permanently	boolean	是	是否永久删除，false 表示暂时删除，true 表示永久删除, 默认 false 。
options	IPDSRequestConfig	否	其它配置项。

返回值

字段	类型	必选	说明
result	object	是	返回删除成功和失败的结果列表 { successArr: [], errorArr: [] }。

successArr 成功结果

如果删除的是文件，successArr 中的结果为 undefined，如果删除的是文件夹，返回的结果包含如下字段。

字段	类型	必选	说明
async_task_id	string	是	异步任务ID。
domain_id	string	是	domain ID。
drive_id	string	是	云盘ID。
share_id	string		分享ID。
file_id	string	是	删除失败成功的文件或文件夹ID。

errorArr 失败结果

如果失败了，则会将传入的文件信息对应的返回。

字段	类型	必选	说明
share_id	string		分享ID。
drive_id	string	是	云盘ID。
file_id	string	是	删除失败的文件或文件ID

copyFiles 方法

复制文件或文件夹。

const result = await client.copyFiles(params, config, options)

举例：

复制多个文件

const {items=[]} = await client.listFiles(req)
                                          
// 可以直接传入 fileItem 数组：              
await client.copyFiles(items, {to_parent_file_id, to_drive_id})

对于复制单个文件，可以重命名

await client.copyFiles(item, { new_name: '新文件名', ... })

复制过程中取消复制

let stopFlag=false

// 取消方法
function cancel(){
  stopFlag=true
}

await client.copyFiles(items, {
  getStopFlag()=>{
    return stopFlag
  } 
})

参数说明

字段	类型	必选	说明
params	IFileItemKey[]	是	要复制的文件列表，其中的项可查看 IFileKey 类型
config	ICopyFilesConfig	是	复制文件相关配置
options	IPDSRequestConfig		其它配置项

IFileItemKey

字段	类型	必选	说明
drive_id	string		云盘id。drive_id和share_id必选其一。
share_id	string		分享id。drive_id和share_id必选其一。
file_id	string	是	文件或文件夹ID。
parent_file_id	string	是	上级文件夹ID。

ICopyFilesConfig

字段	类型	必选	说明
to_parent_file_id	string	是	复制到该文件夹下，文件夹ID
to_drive_id	string		复制到目标云盘ID，支持跨云盘复制。to_drive_id和to_share_id必选其一
to_share_id	string		复制到目标分享目录ID。to_drive_id和to_share_id必选其一
new_name	string		对于单个文件，可以重命名。
onProgress	(count,totoal)=>{}		进度的回调，有两个参数 (count, total) 。
getStopFlag	()=>boolean		暂停方法。返回true则暂停。返回false则继续。

字段	类型	必选	说明
result	ICopyFileRes[]	是	操作结果列表

ICopyFileRes

字段	类型	必选	说明
async_task_id	string		异步任务ID。文件夹才有。
domain_id	string		Domain ID。
drive_id	string		云盘ID。drive_id 和 share_id 必选其一。
share_id	string		分享ID。drive_id 和 share_id 必选其一。
file_id	string	是	文件ID。

moveFiles 方法

移动文件或文件夹。

const result = await client.moveFiles(params, config, options)

举例：

移动多个文件。

const {items=[]} = await client.moveFiles(...)
                                          
// 可以直接传入 fileItem 数组：                                    
await client.moveFiles(items, {to_parent_file_id, to_drive_id })

对于移动单个文件，可以重命名。

await client.moveFiles(item, { new_name: '新文件名', ... })

移动过程中取消复制。

let stopFlag=false

// 取消方法
function cancel(){
  stopFlag=true
}

await client.moveFiles(items, {
  getStopFlag()=>{
    return stopFlag
  } 
})

参数说明

字段	类型	必选	说明
params	IFileItemKey[]	是	要移动的文件列表，其中的项可查看 IFileKey 类型
config	ICopyFilesConfig	是	移动文件相关配置，请参考 copyFiles 方法的描述
options	IPDSRequestConfig		其它配置项

返回值

字段	类型	必选	说明
result	ICopyFileRes[]	是	移动结果列表。请参考 copyFiles 方法的返回。

getAsyncTask 方法

获取任务进度。

const result = await client.getAsyncTask(async_task_id, options)

参数说明

字段	类型	必选	说明
async_task_id	string	是	任务ID。
options	IPDSRequestConfig		其它配置项。

返回值

字段	类型	必选	说明
result	object	是	返回结果，具体请查看 IAsyncTaskRes 的说明

IAsyncTaskRes

字段	类型	必选	说明
async_task_id	string	是	异步任务ID。
state	string	是	状态， Failed ｜ Success ｜PartialSucceed ｜ Running。
error_message	string		消息提示。
error_code	number		状态为 Failed 时返回的信息。
url	string		archiveFile 接口最终打包任务成功之后返回的下载地址。

pollingAsyncTask 方法

轮询获取任务进度，直到获取到最终结果。

const result = await client.getAsyncTask(async_task_id, ttl_ms options)

参数说明

字段	类型	必选	说明
async_task_id	string	是	任务ID。
ttl_ms	number		轮训间隔时间, 单位ms，默认： 5000。
options	IPDSRequestConfig		其它配置项。

返回值

字段	类型	必选	说明
result	IAsyncTaskRes	是	返回结果。