文档

文件操作

更新时间:
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

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

说明

请求参数中的 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

(drive_id和share_id互斥必选一个)

云盘ID。drive_id和share_id互斥必选一个。

share_id

string

(drive_id和share_id互斥必选一个)

分享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_urlurl 的区别: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

(drive_id和share_id互斥必选一个)

云盘ID。drive_id和share_id互斥必选其一。

share_id

string

(drive_id和share_id互斥必选一个)

分享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

(drive_id和share_id互斥必选一个)

云盘ID。drive_id和share_id互斥必选其一。

share_id

string

(drive_id和share_id互斥必选一个)

分享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: 抛出 codeAlreadyExists 的异常

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')

托管模式:

await client.renameFile({
  drive_id: "1",
  file_path: '/a.jpg',
}, '新名称.jpg')

参数说明

字段

类型

必选

说明

fileItem

IFileItem

要重命名的文件信息,查看 IFileItem 类型

newName

string

新名称

check_name_mode

string

(标准模式有效)同名策略配置,取值范围:

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

refuse: 抛出 codeAlreadyExists 的异常

ignore: 允许同名。

默认 refuse。

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

返回值

字段

类型

必选

说明

result

object

返回结果,查看 IFileItem 类型

  • 在托管模式下,遇到同名文件,会抛 codeAlreadyExists 的异常。

updateFile 方法

修改文件/文件夹信息。

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

参数说明

字段

类型

必选

说明

params

object

要更新的文件信息 ,字段请查看 IUpdateFileReq

options

IPDSRequestConfig

其它配置项

IUpdateFileReq

字段

类型

必选

说明

drive_id

string

云盘ID。drive_id 和 share_id 互斥必选一个

file_id

string

文件ID

check_name_mode

string

同名策略配置,取值范围:

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

refuse: 抛出 codeAlreadyExists 的异常

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

(drive_id 和 share_id 必选一个)

云盘 ID 。drive_id 和 share_id 互斥,必选一个。

share_id

string

(drive_id 和 share_id 必选一个)

分享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: 抛出 codeAlreadyExists 的异常

ignore: 允许同名。

默认 refuse。

drive_id

string

(标准模式必选)

云盘ID。drive_id 和 share_id 互斥必选一个。

share_id

string

(托管模式有效, drive_id 和 share_id 互斥必选一个)

共享ID(托管模式有效)。drive_id 和 share_id 互斥必选一个。

name

string

目录名称

parent_file_id

string

(标准模式必选)

上级文件ID,根路径传 root

parent_file_path

string

(托管模式必选)

上级文件路径

返回值

字段

类型

必选

说明

result

ICreateFolderRes

返回结果

ICreateFolderRes

字段

类型

必选

说明

domain_id

string

domain ID

drive_id

string

云盘ID

share_id

string

共享ID(托管模式有效)

encrypt_mode

string

加密模式(标准模式有效)

file_id

string

(标准模式必选)

文件ID

file_path

string

(托管模式必选)

文件路径

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"
}
{
  "type":"folder",
  "file_path":"/新建文件夹2/",
  "domain_id":"hz63",
  "drive_id":"4801"
}

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

share_id

string

共享ID (托管模式有效)

parent_file_id

string

(标准模式必选)

上级目录ID,根目录为 root

parent_file_path

string

(托管模式必选)

上级目录路径,根目录为 /

ICreateFoldersConfig

字段

类型

必选

说明

check_name_mode

string

同名策略配置,取值范围:

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

refuse: 回调 onFolderRepeat

ignore: 允许同名。

overwrite: 同名覆盖。

skip: 同名跳过。

默认 refuse。

create_folder_cache

Map<string, any>={}

缓存目录信息的map。

onFolderRepeat

()=>boolean

(标准模式有效)发现路径存在时的回调,返回 true 继续,返回 false,会抛出codeAlreadyExists的错误

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

(drive_id 和 share_id 互斥必须选一个)

分享id,drive_id 和 share_id 互斥必须选一个

drive_id

string

(drive_id 和 share_id 互斥必须选一个)

云盘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

(to_drive_id和to_share_id互斥必选一个)

复制到目标云盘ID, 支持跨云盘复制。

to_share_id

string

(to_drive_id和to_share_id互斥必选一个)

复制到目标分享目录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

(drive_id 和 share_id 互斥必选一个)

云盘ID。drive_id 和 share_id 互斥。

share_id

string

(drive_id 和 share_id 互斥必选一个)

分享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

返回结果

  • 本页导读 (0)
文档反馈