README

NOS Node.js SDK

NOS Node.js SDK实现了NOS对象操作接口，基于此SDK能方便快速地实现JavaScript应用程序来使用NOS的对象存储服务。

支持的功能

对象操作接口

Delete Object —— 删除一个对象
Delete Multiple Objects —— 用一个HTTP请求删除同一个Bucket中的多个对象
Get Object —— 读取对象内容
Head Object —— 获取对象相关元数据信息
List Objects —— 获取一个桶的对象列表
Put Object —— 上传一个对象
Put Object - Copy —— 拷贝一个对象
Put Object - Move —— 桶内部move一个对象

大对象分块操作接口

Initiate Multipart Upload —— 初始化分块上传
Upload Part —— 上传一个分块
Complete Multipart Upload —— 完成分块上传
Abort Multipart Upload —— 取消分块上传并删除已上传的分块
List Parts —— 列出已上传的分块
List Multipart Uploads —— 列出所有执行中的分块上传事件

使用说明

在调用对象操作接口前需要如下步骤：

1.安装nos-node-sdk-test模块 npm install nos-node-sdk-test

2.引入模块 nos-node-sdk-test 模块 var NOSClient = require('nos-node-sdk-test')

3.新建 NOSClient对象并初始化参数

nosclient.setAccessId('您的accessKeyId');
nosclient.setSecretKey('您的accessKeySecret');
nosclient.setEndpoint('建桶时选择的的区域域名');
nosclient.setPort('80');

若使用https协议:
var nosclient = new NosClient();
nosclient.setAccessId('您的accessKeyId');
nosclient.setSecretKey('您的accessKeySecret');
nosclient.setEndpoint('建桶时选择的的区域域名');
nosclient.setProtocol('https');
nosclient.setPort('443');

4.调用nosclient对象的各个方法发送不同的请求，第一个参数是map，第二个参数是一个回调函数

 nosclient.delete_object({bucket:'bucket',key:'b.txt'}，func)

关于第二个参数，即回调函数，是一个异步函数，会在接收到响应的时候回调，由用户自己定义,该函数有如下声明：

var func = function(result){
   //用户自己的逻辑，result为响应的结构体，用户可以使用这个结构体读取statusCode，requestId等信息
   //例如map['statusCode'] 可以获取statusCode
}

5.如果调用返回[200,400)，用户可以参考result中包含的信息构造回调函数，实现自己的逻辑。状态码在这个区间外，一律抛出异常，异常信息包括状态码，requestid,错误说明，resource
如果桶名非法，异常信息为invalid bucket name，如果对象名非法，异常信息为invalid object name

接口实现

对象操作接口

Delete Object

使用举例

var func = function(result){
       //打印statusCode
       console.log(result['statusCode']);
       //打印requestId
       console.log(result['headers']['x-nos-version-id'])
    }

nosclient.delete_object({bucket:'bucket',key:'b.txt'}，func)

参数说明

bucket(string) -- 桶名。
key(string) -- 对象名。

异步调用的result参数中包含的信息

statusCode: 200
headers: {
'x-nos-request-id': 'e2f97ce70af100000155fb63f9fc15fb',
  'x-nos-version-id': '0',
  'content-length': '0',
  connection: 'close',
  server: 'Jetty(6.1.11)' }

Delete Multiple Objects

使用举例

    var func = function(result){
       //打印statusCode
       console.log(result['statusCode']);
       //打印requestId
       console.log(result['headers']['x-nos-version-id'])
       //打印所有删除成功的对象名
       var deleteSuccess = result['deleteSuccess']
       for(var i=0;i<deleteSuccess.length;i++){
            console.log(deleteSuccess[i])
       }
       //打印所有删除失败的对象名
       var deleteFail = result['deleteFail']
       for(var i=0;i<deleteFail;i++){
            console.log(deleteFail[i]['Key']);
            console.log(deleteFail[i]['Message']);
       }
    }

nosclient.delete_objects(
    {bucket:'bucket',
    keys:[{Key:'b.txt'},{Key:'c.txt'}],func)

参数说明

bucket(string) -- 桶名。
keys(array) -- 待删除的对象名称列表，是一个数组，每个元素是一个键值对

异步调用的map参数中包含的信息

statusCode: 200
headers: {
'x-nos-request-id': 'ab6f6cce0af100000155fb68571115fb',
  'content-type': 'application/xml; charset=UTF-8',
  'content-length': '55',
  connection: 'close',
  server: 'Jetty(6.1.11)' }
delete-success:['1.jpg','2.jpg']
delete-fail:[{Key:'3.jpg',Message:'NoSuchBucket'},{Key:'4.jpg',Message:'AccessDenied'}]

Get Object

可以返回一个流或者下载整个文件

使用举例

返回一个流

    var func = function(result){
       //打印statusCode
       console.log(result['statusCode']);
       //打印requestId
       console.log(result['headers']['x-nos-version-id'])
       //获取流
       var stream = result['stream']
       //处理流
       ..........
    }

nosclient.get_object_stream({bucket:'bucket',key:'b.txt'},func)

下载整个文件到指定路径

nosclient.get_object_file({bucket:'bucket',key:'b.txt',path:'destpath'},func)
这里的destpath包括了文件名

参数说明

bucket(string) -- 桶名。
key(string) -- 对象名。
其他可选参数，如下。
- range(string) -- 下载指定的数据块，Range Header参考RFC2616。
- if_modified_since(datetime) -- 指定时间，只有当指定时间之后做过修改操作才返回这个对象。

异步调用的result参数中包含的信息

statusCode: 200
headers: {
'x-nos-request-id': 'aa2402d20af100000155fb6d6cd915fb',
  'content-type': 'application/octet-stream; charset=UTF-8',
  etag: '926d74ef88054b6586a5530c5c6606b3',
  'content-disposition': 'inline; filename="c.txt"',
  'last-modified': 'Mon, 18 Jul 2016 08:33:12 Asia/Shanghai',
  'cache-control': 'no-cache',
  'content-length': '18',
  connection: 'close',
  server: 'Jetty(6.1.11)' }
stream:readablestream(如果是下载文件不包含这个)  


如果返回的状态码是304，result中包含的信息如下
statusCode:304 
headers{
server: ngx_openresty/1.4.3.6
date: Wed, 31 Aug 2016 02:38:52 GMT
content-Type: text/plain
connection: keep-alive
x-nos-request-id: 6b57bc8f0aa000000156de76a52b849b
}

Head Object

使用举例

var func = function(result){
       //打印statusCode
       console.log(result['statusCode']);
       //打印requestId
       console.log(result['headers']['x-nos-version-id'])
    }

nosclient.head_object({bucket:'bucket',key:'b.txt'},func)

参数说明

bucket(string) -- 桶名。
key(string) -- 对象名。
其他可选参数，如下。
- if_modified_since(datetime) -- 指定时间，只有当指定时间之后做过修改操作才返回这个对象。

异步调用的result参数中包含的信息

statusCode: 200
headers: { 'x-nos-request-id': '346251790af100000155fb76baac15fb',
  etag: '926d74ef88054b6586a5530c5c6606b3',
  'content-length': '18',
  'last-modified': 'Mon, 18 Jul 2016 08:33:12 Asia/Shanghai',
  'content-type': 'application/octet-stream',
  'cache-control': 'no-cache',
  connection: 'close',
  server: 'Jetty(6.1.11)' }

List Objects

使用举例

var func = function(result){
       //获取对象列表
       var objectlist = result['bucketInfo']['objectlist'];
       //遍历对象列表
       for(var i = 0 ; i < objectlist.length ; i++){
            //打印对象信息
            console.log(objectlist[i]['key']);
            console.log(objectlist[i]['lastmodified']);
            console.log(objectlist[i]['etag']);
            console.log(objectlist[i]['size']);
            console.log(objectlist[i]['storageclass'])
       }
    }

nosclient.list_objects({bucket:'bucket'},func)

参数说明

bucket(string) -- 桶名。
kwargs -- 其他可选参数。
- delimiter(string) -- 分界符，用于做groupby操作。
- marker(string) -- 字典序的起始标记，只列出该标记之后的部分。
- limit(integer) -- 限定返回的数量，返回的结果小于或等于该值。取值范围：0-1000，默认：100
- prefix(string) -- 只返回Key以特定前缀开头的那些对象。可以使用前缀把一个桶里面的对象分成不同的组，类似文件系统的目录一样。

异步调用的result参数中包含的信息

statusCode: 200
headers: { 'x-nos-request-id': 'db9524a10af100000155fb7ab73d15fb',
  'content-type': 'application/xml; charset=UTF-8',
  'content-length': '1343',
  connection: 'close',
  server: 'Jetty(6.1.11)' }
bucketInfo:{
  name:'bucket',
  prefix:'',
  marker:'',
  maxkeys:100,
  is_truncated:false,
  objectList:[{key:'a.txt',lastmodified:'2016-07-18T08:49:03 +0800',
  etag:'926d74ef88054b6586a5530c5c6606b3',size:18,storageclass:archive-standard},......]
  //object-list是一个数组，每个数据元素都是一个map，包含key,lastmodify,etag,size,storageclass 5项信息，代表桶里面的对象
}

Put Object

这个接口提供流式上传和提供文件路径的上传

使用举例

流式上传，需要指定流的长度，如果不指定则抛出异常

nosclient.put_object_stream({
           bucket:'bucket',
           key:'d.txt',
           body:readableStream,length:1135},func)

文件路径上传,不需要指定length

nosclient.put_file({
           bucket:'bucket',
           key:'d.txt',
           filepath:'path'},func)
           
文件路径上传大对象(对象最大为1T)，此接口内部调用了分块上传接口

nosclient.put_big_file({
           bucket:'bucket',
           key:'d.txt',
           filepath:'path'},func)
此接口回调函数中result参数的返回内容请参见 complete multipart upload 接口

参数说明

bucket(string) -- 桶名。
key(string) -- 对象名。
body -- 对象内容，请传入一个readableStream对象
filepath -- 对象的文件路径，绝对路径
length -- 对象大小，对于上传一个流来说是必须的，其他两个接口不需要
kwargs -- 其他可选参数。
- meta_data(dict) -- 用户自定义的元数据，通过键值对的形式上报，键名和值均为字符串，且键名需以x-nos-meta-开头。
- expires 缓存时间
- disposition 浏览器打开时是否需要提示用户保存
- contentType 对象类型
- encoding 对象的编码
- cacheControl 缓存控制
- language 对象的语言
- contentMD5 对象的MD5
- object_md5 仅对上传大对象文件时有效，与complete_multipart_upload接口中的object_md5含义相同

异步调用的result参数中包含的信息

18 Jul 08:58:35 - STATUS: 200
18 Jul 08:58:35 - HEADERS: { 'x-nos-request-id': '2aa8555c0af100000155fb83034c15fb',
  etag: 'b1335fbca4c89d12719cf99fdcab707e',
  'x-nos-object-name': 'd.txt',
  'content-length': '0',
  connection: 'close',
  server: 'Jetty(6.1.11)' }

Put Object - Copy

使用举例

nosclient.copy_object({src_bucket:'bucket',
    src_key:'nimawangjiao',
    dest_bucket:'bucket2',
    dest_key:'q.txt'},func)

参数说明

src_bucket(string) -- 来源对象的桶名。
src_key(string) -- 来源对象的对象名。
dest_bucket(string) -- 目标对象的桶名。
dest_key(string) -- 目标对象的对象名。

异步调用的result参数中包含的信息

18 Jul 09:09:52 - STATUS: 200
18 Jul 09:09:52 - HEADERS: { 'x-nos-request-id': 'aa1c14690af100000155fb8d577415fb',
  'content-length': '0',
  connection: 'close',
  server: 'Jetty(6.1.11)' }

Move Object

使用举例

nosclient.move_object({
      src_bucket:'bucket2',
      src_key:'q.txt',
      dest_bucket:'bucket2',
      dest_key:'m.txt'},func)

参数说明

src_bucket(string) -- 来源对象的桶名。
src_key(string) -- 来源对象的对象名。
dest_bucket(string) -- 目标对象的桶名。
dest_key(string) -- 目标对象的对象名。

异步调用的result参数中包含的信息

18 Jul 09:13:34 - STATUS: 200
18 Jul 09:13:34 - HEADERS: {
'x-nos-request-id': '94c462780af100000155fb90a20515fb',
  'content-length': '0',
  connection: 'close',
  server: 'Jetty(6.1.11)' }

Initiate Multipart Upload

使用举例

nosclient.create_multipart_upload({
      bucket:'bucket',
      key:'d.txt',
      meta_data:{'x-nos-meta-hell':'hello'}},func)

参数说明

bucket(string) -- 桶名。
key(string) -- 对象名。
其他可选参数。
- meta_data(dict) -- 用户自定义的元数据，通过键值对的形式上报，键名和值均为字符串，且键名需以x-nos-meta-开头。

异步调用的result参数中包含的信息

statusCode: 200
headers: { 'x-nos-request-id': 'a39843610af100000155fb949f8115fb',
  'content-type': 'application/xml; charset=UTF-8',
  'content-length': '193',
  connection: 'close',
  server: 'Jetty(6.1.11)' }
multipart_upload_info:{
   bucket:'bucket',
   key:'d.txt',
   upload_id:4688949732940019989
}

Upload Part

使用举例

nosclient.upload_part({
        bucket:'bucket',
        key:'d.txt',
        part_num:1,
        upload_id:'4688949732940019989', (此处不能省略引号)
        body:readableStream,length:1235},func)

参数说明

bucket(string) -- 桶名。
key(string) -- 对象名。
part_num(integer) -- 数据分块编码号（1-10000）。
upload_id(string) -- 数据上传标识号。
body -- 对象内容，传入一个readableStream
length -- 分块大小

异步调用的result参数中包含的信息

statusCode: 200
headers: { 'x-nos-request-id': 'af253f210af100000155fb97d3ad15fb',
  etag: 'ff9360dc18c5e09a80db8f0aa115d52c',
  'content-length': '0',
  connection: 'close',
  server: 'Jetty(6.1.11)' }
partNumber:1

Complete Multipart Upload

在将所有数据Part都上传完成后，必须调用Complete Multipart Upload API来完成整个文件的Multipart Upload。在执行该操作时，用户必须提供所有有效的数据Part的列表（包括part号码和ETAG）；NOS收到用户提交的Part列表后，会逐一验证每个数据Part的有效性。当所有的数据Part验证通过后，NOS将把这些数据part组合成一个完整的Object。使用x-nos-Object-md5扩展头发送对象的MD5值，用作去重库的建立（Put Object使用Content-MD5建立对象去重库）。

使用举例

nosclient.complete_multipart_upload({
         bucket:'bucket',
         key:'d.txt',
         upload_id:'4688949732940019989',
         info:[{PartNumber:'1',ETag : 'dc28229fb48cc93025ce862e79c4623f'}]},func)

参数说明

bucket(string) -- 桶名。
key(string) -- 对象名。
upload_id(string) -- 数据上传标识号。
info(list) -- 所有有效的数据Part的列表，传入的是一个数组，数组元素是一个map，map中的key-value规则如上例所示
kwargs -- 其他可选参数，如下。
- object_md5(string) -- 发送对象的md5值，用于后续去重。

异步调用的result参数中包含的信息

statusCode: 200
{ server: 'openresty/1.9.15.1',
     date: 'Mon, 05 Sep 2016 06:47:28 GMT',
     'content-type': 'application/xml;charset=UTF-8',
     'content-length': '334',
     connection: 'close',
     'x-nos-request-id': 'c980b4d80ab000000156f91a09e43f0c' },
multipart_upload_result:{
  location:filestation.nos.netease.com/movie.avi,
  bucket:filestation,
  key:movie.avi,
  etag:"3858f62230ac3c915f300c664312c11f-9"
}

Abort Multipart Upload

使用举例

nosclient.abort_multipart_upload({
        bucket:'bucket',
        key:'d.txt',
        upload_id:'4688949732940019989'},func)

参数说明

bucket(string) -- 桶名。
key(string) -- 对象名。
upload_id(string) -- 数据上传标识号。

异步调用的result参数中包含的信息

statusCode: 200
headers: { 'x-nos-request-id': 'f381b02c0af100000155fba0d89e15fb',
  'content-length': '0',
  connection: 'close',
  server: 'Jetty(6.1.11)' }

List Parts

使用举例

nosclient.list_parts({
       bucket:'bucket',
       key:'d.txt',
       upload_id:'4688949732940019989'},func)

参数说明

bucket(string) -- 桶名。
key(string) -- 对象名。
upload_id(string) -- 数据上传标识号。
kwargs -- 其他可选参数，如下。
- limit(integer) -- 限制响应中返回的记录个数。取值范围：0-1000，默认1000。
- part_number_marker(string) -- 分块号的界限，只有更大的分块号会被列出来。

异步调用的result参数中包含的信息

statusCode: 200
headers: { 'x-nos-request-id': '5292fe910af100000155fba5740515fb',
  'content-type': 'application/xml; charset=UTF-8',
  'content-length': '1123',
  connection: 'close',
  server: 'Jetty(6.1.11)' }
list_parts_info:{
  bucket:'bucket',
  key:'d.txt',
  upload_id:'4685815523730016248',
  owner:{productid:'productid'},
  storageclass:'archive-standard',
  part_number_marker:'0',
  next_part_number_marker:'4',
  max_parts:'1000',
  is_truncated:'false',
  part_list:[{part_number:1,last_modified:2016-07-15T19:20:27 +0800,etag:b33df4c9833e4dcba58e72ea0a9fcd7f,size:12}......]
  //part_list是parts的数组，数据每个元素是一个map，包含part_number,last_modified,etag,size信息
}

List Multipart Uploads

使用举例：

nosclient.list_multipart_upload({bucket:'bucket'},func)

参数说明

bucket(string) -- 桶名。
kwargs -- 其他可选参数，如下。
- limit(integer) -- 限制响应中返回的记录个数。取值范围：0-1000，默认1000。
- key_marker(string) -- 指定某一uploads key，只有大于该key-marker的才会被列出。

返回值举例

statusCode: 200
headers: { 'x-nos-request-id': '6213b3d00af100000155fbabcf8115fb',
  'content-type': 'application/xml; charset=UTF-8',
  'content-length': '455',
  connection: 'close',
  server: 'Jetty(6.1.11)' }
multipart_upload_result:{
  bucket:'bucket',
  next_key_marker:'4685815523730016248',
  is_truncated:'false',
  uploads:[{key:'d.txt',upload_id:'4685815523730016248',storage_class:'archive-standard',owner:{name:'name',productid:'productid'},initiated:'2016-07-15T19:19:12 +0800'}......]
  //展示每个上传信息的数组，数组的每个元素都是一个map，包含key,upload_id,storage_class,owner,initiated信息
}

Usage no npm install needed!

README

NOS Node.js SDK

支持的功能

对象操作接口

大对象分块操作接口

使用说明

接口实现

对象操作接口

Delete Object

Delete Multiple Objects

Get Object

Head Object

List Objects

Put Object

Put Object - Copy

Move Object

Initiate Multipart Upload

Upload Part

Complete Multipart Upload

Abort Multipart Upload

List Parts

List Multipart Uploads