Skip to content

Latest commit

 

History

History
354 lines (237 loc) · 11 KB

README.md

File metadata and controls

354 lines (237 loc) · 11 KB
Raw

UPYUN JS SDK

NPM version Build Status dependencies Status

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）

参数

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