UPYUN JS SDK

upyun js sdk, 支持服务端和客户端使用，集成：

安全起见，浏览器端不能设置操作员账号名和密码
服务端需要设置操作员账号名和密码
浏览器端使用时，部分参数设置或方法调用会导致跨域失败问题
- listDir 设置 limit | order | iter
- putFile 设置 Content-Type 以外的其他选项
- makeDir | updateMetadata | blockUpload | copy 无法在浏览器端使用
- deleteFile 无法再浏览器端使用异步删除

安装

npm

$ npm install upyun --production --save

cdn

浏览器端手动安装时，需要手动引入 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

Client

初始化

const client = new upyun.Client(service[, options][, getHeaderSignCallback])

参数

service: 又拍云服务，Service 实例: new upyun.Service('your service name', 'your operator name', 'your operator password')
options: 配置项，可以配置以下参数
- domain: 又拍云 rest api 地址，默认 v0.api.upyun.com 其他可配置域名见又拍云文档
- protocol: 使用 http|https 协议，默认 https 协议
- proxy: 代理配置见使用说明. 默认为 undefined.
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);

usage(path = '/')

查看目录大小（单位: byte）

参数

示例

client.usage('/sub/dir').then(function(size) {
  console.log('/sub/dir total used size: ' + size)
})

listDir(remotePath, options)

获取目录下文件列表

参数

remotePath: 需要查看的目录路径
options:
- limit: 每次请求获取的目录最大列表，最大值 10000，默认 100
- order: 列表以文件最后修改时间排序，可选值 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
}

putFile(remotePath, localFile, options = {})

通过 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

initMultipartUpload(remotePath, fileOrPath, options = {})

初始化一个并行式断点续传任务

参数

remotePath: 文件保存路径 需包含文件名（路径不需要 encodeURI，sdk 会统一处理）
fileOrPath: 需要上传的文件。服务端支持 Buffer 和文件路径 String, 浏览器端支持 File
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

multipartUpload (remotePath, fileOrPath, multiUuid, partId)

参数

remotePath: 文件保存路径 需包含文件名（路径不需要 encodeURI，sdk 会统一处理）
fileOrPath: 需要上传的文件。服务端支持 Buffer 和文件路径 String, 浏览器端支持 File
multiUuid: 任务标识，初始化时生成。即 X-Upyun-Multi-Uuid
partId 分块序号，序号从 0 开始. 即 X-Upyun-Part-Id

响应

数据传输成功返回 true, 反之返回 false

completeMultipartUpload (remotePath, multiUuid)

参数

remotePath: 文件保存路径 需包含文件名（路径不需要 encodeURI，sdk 会统一处理）
multiUuid: 任务标识，初始化时生成。即 X-Upyun-Multi-Uuid

响应

数据传输成功返回 true, 反之返回 false

makeDir(remotePath)

创建目录

参数

remotePath: 新建目录的路径

响应

创建成功返回 true，否则 false

headFile(remotePath)

HEAD 请求，获取文件基本信息

参数

remotePath: 文件在又拍云云存储服务的路径

响应

文件不存在返回 false。否则返回一个对象，结构如下，详见又拍云 HEAD

{
  'type': 'file', // 文件类型
  'size': 289239, // 文件大小
  'date': 1486053098, // 文件创建时间
  'Content-Md5': '9a56c9d185758d2eda3751e03b891fce'  // 文件 md5 值
}

deleteFile(remotePath)

删除文件或目录

参数

remotePath: 文件或目录在又拍云服务的路径

响应

删除成功返回 true, 否则返回 false

getFile(remotePath, saveStream = null)

下载保存在又拍云服务的文件

参数

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

formPutFile(remotePath, localFile, params = {}, opts = {})

使用又拍云表单 api 上传文件。客户端使用该方法时，必须先设置获取又拍云 HTTP Body 签名的回调函数

参数

remotePath: 保存路径
localFile: 需要上传的文件，和 putFile 相同(**如果在浏览器端使用，只支持 String/Blob/File **)
params: 又拍云表单 api 支持的可选参数（service(同 bucket), save-key 两个必选参数不需要手动在这里设置）
opts
- filename 可选参数. 用于指定上传字符串/ Blob 的文件名. 支持路径取 basename. 文件名取值优先级 filename > localFile 是文件 > 默认值 "file"

响应

成功返回一个对象，详细说明见异步通知规则参数说明部分，失败返回 false

copy(targetPath, sourcePath, options = {})

将文件 sourcePath 拷贝至 targetPath，不适用于文件夹。

参数

sourcePath: 原文件地址
targetPath: 目标文件地址
options: 其他可选参数 x-upyun-metadata-directive | content-md5 | content-length（无视大小写）

响应

操作成功返回 true, 反之返回 false

move(targetPath, sourcePath, options = {})

将文件 sourcePath 移动并重命名至 targetPath，不适用于文件夹。

参数

sourcePath: 原文件地址
targetPath: 目标文件地址
options: 其他可选参数 x-upyun-metadata-directive | content-md5 | content-length（无视大小写）

响应

操作成功返回 true, 反之返回 false

Service

又拍云服务，包含以下属性

serviceName 服务名
operatorName 操作员名
password 操作员密码，读取该属性时，获取的值是 md5 加密后的结果

sign

签名模块

备注

upyun npm package 曾为 James Chen 所有。

经过与其的交流协商，James 已经将此 npm 包转由 UPYUN 开发团队管理和维护。

后续的代码和版本更新，将于原有的项目无任何直接关系。

在 npm 上, "upyun": "<=0.0.3" 是由 James Chen 曾开发的 node-upyun 项目.

非常感谢 James Chen 对 upyun 的支持和贡献

upyun/node-sdk