comss-js-sdk v1.0.1

COMSS-JavaScript-SDK

捷信消费金融COMSS服务Javascript SDK

功能简介

• 上传
  • 支持ASE256加密
  • 支持二进制数据上传
  • 支持任意格式文件上传
• 下载
  • 支持ASE256解密
  • 支持直接下载对象
  • 支持获取对象URL
  • 支持获取对象二进制数据

准备

• 在使用 JS-SDK 之前，您的后端服务必须先注册一个COMSS账号，并获得 AK 和 SK

• JS-SDK 依赖服务端，可以通过以下二种方式：

  • 调用自己的后端服务：利用JAVA-SDK构建后端服务，并按照JAVA-SDK文档提供必要Restful API
  • 调用云端agent服务：利用JAVA-SDK构建后端服务，并由服务端颁发token

引入

支持以下几种安装方式

• 直接通过sctipt标签引入：

  /node_modules/comss-js-sdk/umd/index.min.js

  通过sctipt标签引入该文件，会在全局生成名为 COMSS 的对象

• 使用 NPM 安装

  目前npm package发布在homecredit registry，需提前设置下registry

  npm config set registry http://registry.npmjs.org
  npm install comss-js-sdk
  // or
  npm install comss-js-sdk --registry=https://registry.npm.taobao.org

  import COMSSClient from 'comss-js-sdk'
  // or
  const COMSSClient = require('comss-js-sdk')

使用

实例化一个COMSSClient对象，并传入必要参数即可

Example

以下示例使用了ES6的async、await语法，您也可以使用Promise来操作。下方仅为部分方法示例，全部api请下看文档API部分

文件上传：

async uploadHandler() {

    // 创建一个客户端实例
    const client = new COMSSClient({
        host: "http url"
    });
    
    try {
        const response = await client.upload({
            // 待上传对象，支持File、Blob、ArrayBuffer
            source: this.file,
            // 如果需要加密对象，添加该字段
            passwordKey: this.data.password,
            // 上传进度监听
            onProgress: (progressEvent, loaded, total) => {
                console.log("Progress：" + (loaded * 100 / total).toFixed(2) + "%")
            },
            // 你可以调用canceler()取消对象上传
            cancel: (canceler) => {
                // canceler()
            }
        })
        console.log("Upload Success:" + response)
    } catch (ev) {
        if (ev instanceof UploadException) {
            console.log('Upload Error:'+ ev.message)
        } else if (ev instanceof EncryptException) {
            console.log('Encrypt Error:'+ ev.message)
        } else if (ev instanceof UserCancelException) {
            console.log('User Cancel:'+ ev.message)
        }
    }
    
}

文件下载：

async downloadHandler() {
    // 创建一个客户端实例
    const client = new COMSSClient({
        host: "http url"
    });
    
    try {
        const arrayBuffer = await client.download({
            // 对象fullId
            fullId: 'xxxxxxx',
            // 如果对象已被加密，需传递密钥进行解密，否则下载的文件是加密的
            passwordKey: this.data.password,
            // 下载进度监听
            onProgress: (progressEvent, loaded, total) => {
                console.log("Progress：" + (loaded * 100 / total).toFixed(2) + "%")
            },
            // 你可以调用canceler()取消对象下载
            cancel: (canceler) => {
                // canceler()
            }
        })
        console.log("Download Success:" + arrayBuffer)
    } catch (ev) {
        if (ev instanceof DownloadException) {
            console.log('Download Error:'+ ev.message)
        } else if (ev instanceof DecryptException) {
            console.log('Decrypt Error:'+ ev.message)
        } else if (ev instanceof UserCancelException) {
            console.log('User Cancel:'+ ev.message)
        }
    }
}

API

【类】COMSSClient

class COMSSClient {
    constructor(option: ClientOption);
    
    /**
    * 上传文件或二进制,并返回ObjectCloudData
    * @param  option: UploadOption
    * @param  type: string = 'multipart/form-data'
    * @return Promise<ObjectCloudData>;
    * */
    upload(option: UploadOption, type?: string): Promise<ObjectCloudData>;
    
    /**
    * 下载文件并返回二进制数据
    * @param  option: DownloadOption
    * @return Promise<ArrayBuffer>;
    * */
    download(option: DownloadOption): Promise<ArrayBuffer>;
    
    /**
    * 下载并保存为文件
    * @param  option: DownloadOption;
    * @param  filename: string;
    * @return Promise<void>;
    * */
    downloadAsFile(option: DownloadOption, filename?: string): Promise<void>;
    
    /**
    * 下载并保存为文件
    * @param  option: DownloadOption;
    * @return Promise<string>;
    * */
    downloadAsUrl(option: DownloadOption): Promise<string>;
}

【接口】ClientOption

interface ClientOption {
    // host\token至少需要传递一项，host优先级大于token，即优先访问后端服务
    // 后端服务DNS地址
    host?: string;
    // 后端签发的token，以便调用云端agent服务
    token?: string;
    // 自定义请求header，方便实现前后端身份校验，例如：【'Authorization': 'Bearer ' + token】
    headers?: {
        [key: string]: string;
    };
    // 可方便实现HTTP Basic auth认证
    auth?: {
      username: string;
      password: string;
    };
};

【接口】UploadOption

interface UploadOption {
    // 待上传对象
    source: File|Blob|ArrayBuffer;
    // 上传对象名称，如果为File则默认为File.name
    filename?: string;
    // ObjectKey
    objectKey?: string;
    // 上传进度
    onProgress?: (progressEvent: ProgressEvent, loaded: number, total: number) => void;
    // 取消回调
    cancel?: (canceler: Canceler) => void;
    // 加密密钥
    passwordKey?: string;
};

【接口】DownloadOption

interface DownloadOption {
    // 对象FullId
    fullId: string;
    // 下载进度监听
    onProgress?: (progressEvent: ProgressEvent, loaded: number, total: number) => void;
    // 取消回调
    cancel?: (canceler: Canceler) => void;
    // 解密密钥
    passwordKey?: string;
};

【接口】ObjectCloudData

interface ObjectCloudData {
    // 对象FullId
    fullId: string;
    // ObjectKey
    objectKey: string;
};