upyun js sdk, 支持服务端和客户端使用,集成:
- 安全起见,浏览器端不能设置操作员账号名和密码
- 服务端需要设置操作员账号名和密码
- 浏览器端使用时,部分参数设置或方法调用会导致跨域失败问题
listDir
设置limit | order | iter
putFile
设置Content-Type
以外的其他选项makeDir | updateMetadata | blockUpload
无法在浏览器端使用deleteFile
无法再浏览器端使用异步删除
$ npm install upyun --production --save
浏览器端手动安装时,需要手动引入 sdk 的依赖 axios
(考虑到方便 axios 被复用,浏览器版本构建时,没有引入此依赖)
<script src="https://unpkg.com/axios/dist/axios.min.js"></script>
再引入编译后的 sdk 文件
<script src="https://unpkg.com/upyun/dist/upyun.min.js"></script>
$ npm run test
所有的接口返回均是 Promise
const client = new upyun.Client(service[, options][, getHeaderSignCallback])
参数
service
: 又拍云服务,Service 实例:new upyun.Service('your service name', 'your operator name', 'your operator password')
options
: 配置项,可以配置以下参数getHeaderSignCallback
: 获取又拍云 HTTP Header 签名回调函数,服务端使用时不需要设置该参数。客户端使用必须设置该回调函数,它接受四个参数:service, method, path, contentMD5
, 用于计算当前请求签名,其中contentMD5
可选填。如果回调函数是异步,则必须返回一个Promise
示例
- 服务端使用,一般只需要配置完整又拍云服务信息(服务名、操作员名、操作员密码)即可:
const service = new upyun.Service('your service name', 'your operator name', 'your operator password')
const client = new upyun.Client(service);
- 客户端使用,必须设置签名回调函数,又拍云服务信息只需服务名即可(注意:如果回调函数是异步,则必须返回一个 Promise)
/**
* @param {!Service} service: Service 实例
* @param {!string} method: 当前请求的 API 使用的方法
* @param {!string} path: 当前请求的资源路径
* @param {?string} contentMD5 内容的 md5 值
*/
function getSignHeader(service, method, path, contentMD5 = null) {
// 请求自己的服务器,计算当前 api 请求签名信息
// 可以参考该项目 sample 目录中的示例代码
...
}
const service = new upyun.Service('your service name')
const client = new upyun.Client(service, getSignHeader);
查看目录大小(单位: byte)
参数
path
: 目录路径
示例
client.usage('/sub/dir').then(function(size) {
console.log('/sub/dir total used size: ' + size)
})
获取目录下文件列表
参数
remotePath
: 需要查看的目录路径options
:limit
: 每次请求获取的目录最大列表,最大值 10000,默认 100order
: 列表以文件最后修改时间排序,可选值asc|desc
,默认asc
iter
: 遍历起点,每次响应参数中,将会包含遍历下一页需要的iter
值
响应
目录不存在,返回 false
,否则返回一个对象,结构如下:
{
files: [
{
name: 'example.txt', // file or dir name
type: 'N', // file type, N: file; F: dir
size: 28392812, // file size
time: 1486053098 // last modify time
}
],
next: 'dlam9pd2Vmd2Z3Zg==' // next page iter
}
通过 rest api 上传文件
参数
remotePath
: 文件保存路径 需包含文件名(路径不需要 encodeURI,sdk 会统一处理)localFile
: 需要上传的文件。服务端支持String | Stream | Buffer
, 浏览器端支持File | String
注意String
表示文件内容,不是本地文件路径options
: 其他可选参数Content-MD5 | Content-Length | Content-Type | Content-Secret | x-gmkerl-thumb | x-upyun-meta-x | x-upyun-meta-ttl
(大小写无关,详见上传参数),其中Content-Type
未设置时,将会根据文件路径设置默认值
响应
如果是非图片类文件,上传成功返回 true
, 否则返回一个对象,包含图片的基本信息:
{
width: 80,
height: 80,
'file-type': 'image/jpg',
frames: 1
}
如果上传失败,返回 false
初始化一个并行式断点续传任务
参数
remotePath
: 文件保存路径 需包含文件名(路径不需要 encodeURI,sdk 会统一处理)localFile
: 需要上传的文件。服务端支持String | Stream | Buffer
, 浏览器端支持File | String
注意String
表示文件内容,不是本地文件路径options
: 其他可选参数Content-MD5 | X-Upyun-Multi-Type | X-Upyun-Meta-X | X-Upyun-Meta-Ttl
(大小写无关,详见上传参数),其中Content-Type
未设置时,将会根据文件路径设置默认值。
响应
初始化成功,返回一个对象:
{
fileSize: 55997,
partCount: 1,
uuid: 'b2326f91-c5c4-4c6e-bce9-a41dae78ca2a'
}
如果初始化失败,返回 false
参数
remotePath
: 文件保存路径 需包含文件名(路径不需要 encodeURI,sdk 会统一处理)localFile
: 需要上传的文件。服务端支持String | Stream | Buffer
, 浏览器端支持File | String
注意String
表示文件内容,不是本地文件路径multiUuid
: 任务标识,初始化时生成。即X-Upyun-Multi-Uuid
partId
分块序号,序号从 0 开始. 即X-Upyun-Part-Id
响应
数据传输成功返回 true
, 反之返回 false
参数
remotePath
: 文件保存路径 需包含文件名(路径不需要 encodeURI,sdk 会统一处理)multiUuid
: 任务标识,初始化时生成。即X-Upyun-Multi-Uuid
响应
数据传输成功返回 true
, 反之返回 false
创建目录
参数
remotePath
: 新建目录的路径
响应
创建成功返回 true
,否则 false
HEAD
请求,获取文件基本信息
参数
remotePath
: 文件在又拍云云存储服务的路径
响应
文件不存在返回 false
。否则返回一个对象,结构如下,详见又拍云 HEAD
{
'type': 'file', // 文件类型
'size': 289239, // 文件大小
'date': 1486053098, // 文件创建时间
'Content-Md5': '9a56c9d185758d2eda3751e03b891fce' // 文件 md5 值
}
删除文件或目录
参数
remotePath
: 文件或目录在又拍云服务的路径
响应
删除成功返回 true
, 否则返回 false
下载保存在又拍云服务的文件
参数
remotePath
: 需要下载的文件路径saveStream
: 可选值,一个可以写入的流。若传递该参数,下载的文件将直接写入该流。该参数不支持浏览器端使用
响应
如果文件不存在,将会返回 false
。文件存在时,若没有设置 saveStream
,该方法
将直接返回文件内容。若设置了 saveStream
,文件将直接写入该流,并返回流信息
示例
获取文件内容
client.getFile('/sample.txt').then(function (content) {
console.log(content) // will out put file content directly
})
写入其他流
const saveTo = fs.createWriteStream('./localSample.txt')
client.getFile('/sample.txt', saveTo).then(function (stream) {
// file has been saved to localSample.txt
// you can pipe the stream to anywhere you want
})
使用又拍云表单 api 上传文件。客户端使用该方法时, 必须先设置获取又拍云 HTTP Body 签名的回调函数
参数
remotePath
: 保存路径localFile
: 需要上传的文件,和putFile
相同(**如果在浏览器端使用,只支持 String/Blob/File **)params
: 又拍云表单 api 支持的可选参数(service(同 bucket)
,save-key
两个必选参数不需要手动在这里设置)opts
filename
可选参数. 用于指定上传字符串/ Blob 的文件名. 支持路径取 basename. 文件名取值优先级filename
>localFile
是文件 > 默认值"file"
响应
成功返回一个对象,详细说明见异步通知规则参数说明部分,失败返回 false
将文件 sourcePath
拷贝至 targetPath
,不适用于文件夹。
参数
sourcePath
: 原文件地址targetPath
: 目标文件地址options
: 其他可选参数x-upyun-metadata-directive | content-md5 | content-length
(无视大小写)
响应
操作成功返回 true
, 反之返回 false
将文件 sourcePath
移动并重命名至 targetPath
,不适用于文件夹。
参数
sourcePath
: 原文件地址targetPath
: 目标文件地址options
: 其他可选参数x-upyun-metadata-directive | content-md5 | content-length
(无视大小写)
响应
操作成功返回 true
, 反之返回 false
又拍云服务,包含以下属性
serviceName
服务名operatorName
操作员名password
操作员密码,读取该属性时,获取的值是 md5 加密后的结果
签名模块
upyun npm package 曾为 James Chen 所有。
经过与其的交流协商,James 已经将此 npm 包转由 UPYUN 开发团队管理和维护。
后续的代码和版本更新,将于原有的项目无任何直接关系。
在 npm 上, "upyun": "<=0.0.3"
是由 James Chen 曾开发的 node-upyun 项目.
非常感谢 James Chen 对 upyun 的支持和贡献