# KS3-SDK-Nodejs



本代码库为 `金山云存储KS3`服务.主要提供 `KS3 nodejs SDK`和 `命令行工具`.

[![Build Status](https://travis-ci.org/ks3sdk/ks3-nodejs-sdk.svg?branch=master)](https://travis-ci.org/ks3sdk/ks3-nodejs-sdk)

## Nodejs-sdk

### 安装

下载后安装
```
npm install
```

通过npm直接安装
```
npm install ks3
```

### 测试

请先安装 `mocha`

```
npm install -g mocha
```

然后进行测试

```
// 全部测试
npm run test

// 建议测试时使用主账户的ak、sk

// 指定自己ak,sk和bucket做测试
AK=$ak SK=$sk BUCKET=$bucket mocha

// 大文件(大于5M)上传测试
BIGFILE=$path mocha test/upload.js

// 文件夹上传测试
UPDIR=$path mocha test/upload.js
```

### 使用


```
var KS3 = require('ks3');
// 使用默认的region：BEIJING
var client = new KS3(AK,SK);
// 如果bucket所在的region不是BEIJING，需要使用下面的形式创建
// var client = new KS3(<ak>, <sk>, <bucketName>, <region>)

```

### api

以下调用详细信息,可以访问[官方文档](https://docs.ksyun.com/documents/39060)

`ks3.service.get` : 可以通过该操作来列出客户所有的 Bucket 信息
<br>
#### **bucket相关**

<details>
<pre>
<code>

`ks3.bucket.put` : 创建一个新的Bucket

`ks3.bucket.del` : 删除指定Bucket

`ks3.bucket.get` : 枚举Bucket内的Object

`ks3.bucket.head` : 获取Bucket元数据

`ks3.bucket.getLocation` : 获取bucket的位置

`ks3.bucket.getACL` : 获取Bucket的ACL

`ks3.bucket.putACL` : 设置Bucket的ACL

`ks3.bucket.listMultipartUploads` : 获取Bucket碎片

`ks3.bucket.getLogging` : 获得Bucket的日志信息

`ks3.bucket.putLogging` : 设置Bucket的日志信息

`ks3.bucket.getBucketCors` : 获取bucket的Cors信息

`ks3.bucket.putBucketCors` : 设置bucket的Cors信息

`ks3.bucket.deleteBucketCors` : 删除bucket的Cors信息

`ks3.bucket.getBucketReplicationConfiguration` : 获取bucket的复制规则

`ks3.bucket.putBucketReplicationConfiguration` : 设置bucket的复制规则

`ks3.bucket.deleteBucketReplicationConfiguration` : 删除bucket的复制规则

`ks3.bucket.getBucketMirror` : 获取bucket的镜像回源规则

`ks3.bucket.putBucketMirror` : 设置bucket的镜像回源规则

`ks3.bucket.deleteBucketMirror` : 删除bucket的镜像回源规则

`ks3.bucket.getBucketPolicy` : 获取bucket的策略

`ks3.bucket.putBucketPolicy` : 设置bucket的策略

`ks3.bucket.deleteBucketPolicy` : 删除bucket的策略

`ks3.bucket.getBucketLifecycle` : 获取bucket的生命周期

`ks3.bucket.putBucketLifecycle` : 设置bucket的生命周期

`ks3.bucket.deleteBucketLifecycle` : 删除bucket的生命周期


</code>
</pre>
</details>

<br>

#### **Object相关**

<details>
<pre>
<code>

`ks3.object.del` : 删除指定Object

`ks3.object.get` : 下载该Object数据

`ks3.object.put` : 上传Object数据

`ks3.object.getAcl` : 获得Object的acl

`ks3.object.putAcl` : 上传Object的acl

`ks3.object.head` : 获取指定Object元数据

`ks3.object.copy` : 复制Object

`ks3.object.restore` : 解冻Object

`ks3.object.rename` : Object重命名

`ks3.object.modifyStorageClass` : 更新Object的存储类型

`ks3.object.generatePresignedUrl` : 生成分享外链

`ks3.object.multitpart_upload_init` : 调用这个接口会初始化一个分块上传并且返回一个upload id, upload id 用来标识属于当前object的具体的块，并且用来标识完成分块上传或者取消分块上传

`ks3.object.upload_part` : 初始化分块上传后，上传分块接口

`ks3.object.upload_complete` : 组装之前上传的块，然后完成分块上传。通过你提供的xml文件，进行分块组装。在xml文件中，块号必须使用升序排列。必须提供每个块的ETag值

`ks3.object.upload_abort` : 取消分块上传

`ks3.object.upload_list_part` : 罗列出已经上传的块

`ks3.object.putObjectTagging` : 设置标签

`ks3.object.getObjectTagging` : 获取标签

`ks3.object.deleteObjectTagging` : 删除标签
</code>
</pre>
</details>

<br>

### STS功能
> 详细介绍请参考[文档](https://docs.ksyun.com/documents/1517?type=6)
<details>
<pre>
<code>
const { STS } = require('ks3')
const sts = new STS({
   ak: '',
   sk: ''
})

sts.assumeRole({
    roleKrn: krn, // 要扮演的IAM角色的KRN
    roleSessionName: 'temp' // 角色会话名称
}).then(response => {
    console.log('-----> response', response)
}).catch(err => {
    console.error(err.error)
})
</code>
</pre>
</details>

<br>

### 其他功能

<details>
<pre>
<code>

`ks3.upload.start` : 文件(文件夹)上传

`ks3.download.start`: 文件下载（分块下载）

`ks3.auth.getQueryStringSignature` : 计算通过URL QueryString发送的签名

`ks3.auth.getFormSignature` : 计算通过POST请求的表单实体发送的签名

`ks3.auth.generateAuth` : 计算通过请求头发送的签名/Token（Authorization请求头的值）
</code>
</pre>
</details>

SDK方法详细介绍参见，[SDK详细介绍](https://docs.ksyun.com/documents/41836)



### 命令行

关于命令行工具,文档请查看 `./bin/readme.md`,或者[查看这里](https://gitee.com/ks3sdk/ks3-nodejs-sdk/tree/dev/bin)

功能包括上传文件和文件夹.上传过程中会根据文件大小进行简单上传和分块上传

如果大文件在上传过程中发生意外,限次上传文件的时候会从上次断开的地方续传.