nos-node-sdk
Version:
NOS Node.js SDK实现了NOS对象操作接口，基于此SDK能方便快速地实现JavaScript应用程序来使用NOS的对象存储服务。
634 lines (494 loc) • 19 kB
Markdown
# 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信息
}
```