/node-sdk

UPYUN SDK for JS(support browser and node.js)

Primary LanguageJavaScript

UPYUN JS SDK

NPM version Build Status dependencies Status

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

  • 安全起见,浏览器端不能设置操作员账号名和密码
  • 服务端需要设置操作员账号名和密码
  • 浏览器端使用时,部分参数设置或方法调用会导致跨域失败问题
    • listDir 设置 limit | order | iter
    • putFile 设置 Content-Type 以外的其他选项
    • makeDir | updateMetadata | blockUpload 无法在浏览器端使用
    • 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)

参数

  • path: 目录路径

示例

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, localFile, options = {})

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

参数

  • 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

multipartUpload (remotePath, fileOrPath, multiUuid, partId)

参数

  • remotePath: 文件保存路径 需包含文件名路径不需要 encodeURI,sdk 会统一处理
  • localFile: 需要上传的文件。服务端支持 String | Stream | Buffer, 浏览器端支持 File | String 注意 String 表示文件内容,不是本地文件路径
  • 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

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 的支持和贡献