快速入门

安装

npm install 'wenxing-oss'

初始化

import {Client， ClientType } from 'wenxing-oss';
const client = Client(ClientType.MINIO,options);
options 具体参考原sdk配置 并且需要加上bucket

例如:

//minio
import {Client，ClientType } from 'lanyuan-wenxing';
const client = Client(ClientType.MINIO, {
  endPoint: '192.168.0.37',
  port: 9090,
  useSSL: false,
  accessKey: 'your accessKey',
  secretKey: 'your secretKey',
  bucket: 'lanyuan',    
});

ClientType

| 枚举 | 含义 | | :-----: | :-------------------------------: | | MINIO | 使用Minio的面向对象服务 | | ALI_OSS | 使用阿里云的OSS服务（采用V4签名） | | AWS_S3 | 使用 AWS S3 云存储服务 |

对象操作

文件列表

listObjects(prefix,recursive,options)

参数

• prefix{string} 可选参数 前缀，可以用来查询文件夹里面的内容
• recursive{boolean} 可选参数 默认为false 是否递归查询所有子目录文件
• options {object} 可选参数
  • nextContinuationToken{string}可选参数 使用这个token来请求下一页的数据
  • timeout {number | undefined} 可选参数 (AliOSS中有效)
  • maxKeys {String|Number} 可选参数 最大数量，默认为100，限制为1000 (AliOSS中有效)
  • startAfter{string} 可选参数 从哪个文件开始检索

返回值

Promise<
    objects: Array<{
    name?: string | undefined;
    lastModified?: Date | undefined;
    etag?: string | undefined;
    size?: number;
    prefix?: string;
  }>;
  isTruncated: boolean; //是否还有数据
  nextContinuationToken?: string;>//获取下一页数据token

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      const res = await client.ObjectList('', true);
    } catch (error) {}

上传本地文件

fPutObject(key,filePath,options)

参数

• key{string} 对象名称
• filePath {string} 文件路径
• options {object} 可选参数
  • metaData {object} 可选参数 元数据
  • timeout {number | undefined} (AliOSS中有效)
  • minme {number | undefined} 自定义 mime，将与Content-Type实体标头一起发送 (AliOSS中有效)
  • headers { object | undefined;} (AliOSS中有效)
  • callback{object} 回调参数 详情见 (AliOSS中有效)

返回值

Promise<void>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

try {
      await client.fPutObject(
        'test',
        'D://lanyuan/1.jpg'
      );
    } catch (error) {}
}

上传文件流

putObject(key,stream,size,options)

参数

• key {string} 对象名称

• body{Body} 详情见

• size {number} 文件内容 可选参数 文件大小

  [!NOTE]

  若body是可读流 则必须要传size 否则会上传失败

• options {object} 可选参数

  • metaData {object} 可选参数 元数据
  • timeout {number | undefined} (AliOSS中有效)
  • minme {number | undefined} 自定义 mime，将与Content-Type实体标头一起发送 (AliOSS中有效)
  • headers { object | undefined;}(AliOSS中有效)
  • callback{object} (AliOSS中有效) 回调参数 详情见

返回值

Promise<void>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

  try {
   let path = 'D://lanyuan/lanyuan-oss-js/test/node/src/assets/2.png';
   const stream = fs.createReadStream(path);
   await client.putStream('test',stream);
  } catch (error) {
  }
 }

下载文件到本地

fGetObject(key,filePath,options)

参数

• key{string} 对象名称
• filePath{object} 保存的路径
• options {object} 可选参数
  • versionId {string} 版本id
  • timeout {number | undefined} 可选参数 (AliOSS中有效)
  • process: {string| undefined} 图像处理参数 (AliOSS中有效)
  • responseCacheControl {String} (AliOSS中有效) 默认no-cache，（仅支持浏览器）。response-cache-control 将使用 HTTP Header 进行响应Cache-Control
  • headers { object | undefined;} (AliOSS中有效)

返回值

Promise<void>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      await client.fGetObject(
        'test',
        'D://lanyuan/lanyuan-oss-js/test/node/src/assets/test.png'
      );
    } catch (error) {
    }

下载文件流

getObject(key,options)

参数

• key{string} 对象名称
• options {object} 可选参数
  • versionId {string} 可选参数 版本id (Minio中有效)
  • timeout {number | undefined} 可选参数 (AliOSS中有效)
  • process: {string| undefined} 可选参数 (AliOSS中有效)
  • headers { object | undefined;} 可选参数 (AliOSS中有效)

返回值

Promise<stream.Readable>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      const res = await client.getObject('test');
    } catch (error) {
    }

下载指定范围文件流

getPartialObject(key,offset,length,options)

参数

• key{string} 对象名称
• offset {number} 对象名称
• length{number} 保存的路径
• options {object} 可选参数
  • versionId {string} 可选参数 版本id
  • timeout {number | undefined} 可选参数 (AliOSS中有效)
  • process: {string| undefined} 可选参数 (AliOSS中有效)
  • headers { object | undefined;} 可选参数 (AliOSS中有效)

返回值

Promise<stream.Readable>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

  try {
      const res = await client.getPartialObject('test',100,200);
    } catch (error) {
    }

复制对象

copyObject(key,sourceObject,conditions)

参数

• key{string} 对象名称 格式:/桶名称/对象名称
• sourceObject{string} 源对象的路径
• options{ object} 可选项
  • versionId: {string} 可选参数 版本id (AliOSS中有效)
  • timeout: {number } 可选参数 超时时间 (AliOSS中有效)
  • meta: {Record<string, string>} 可选参数 要设置的元数据 设置覆盖源对象元数据
  • headers: {object } 可选参数 (AliOSS中有效)

返回值

Promise<void>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

   try {
      const res = await client.copyObject('test','fan/test');
    } catch (error) {
    }

获取对象的元数据

statObject(key,statOpts)

参数

• key{string} 对象名称
• options{object} 可选参数
  • versionId {string} 可选参数 版本id (Minio中有效)
  • timeout: {number } 可选参数 超时时间 (AliOSS中有效)
  • headers: {object } 可选参数 (AliOSS中有效)

返回值

Promise<{
  size: number; //文件大小
  etag: string; //文件etag
  lastModified: Date; //文件上一次修改时间
  metaData: Record<string, string | number>;//元数据
  versionId?: string | null; //版本id  
 >}

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      const res = await client.statObject('test');
      return res
    } catch (error) {
    }

删除对象

removeObject(key,options)

参数

• key{string} 对象名称
• options{object} 可选参数
  • versionId {string} 可选参数 版本id
  • governanceBypass {boolean} 可选参数 规避存储桶的生命周期治理策略 (Minio中有效)
  • forceDelete {boolean} 可选参数 是否强制删除对象 (Minio中有效)
  • timeout {number | undefined} 可选参数 超时时间 (AliOSS中有效)

返回值

Promise<void>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      const res = await client.removeObject('test');
    } catch (error) {
    }

删除多个对象

removeObjects(key,options)

参数

• objectsList {Array | Array<{ key: string; versionId?: string }>} 对象名称集合
• options{object} 可选参数
  • timeout {number | undefined} 可选参数 超时时间 (Minio中有效)
  • quiet{boolean | undefined} 可选参数 超时时间 (Minio中有效)

返回值

Promise<void>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

   try {
      const res = await client.removeObjects(['test']);
    } catch (error) {
    }

删除上传的对象

removeIncompleteUpload(key)

参数

• key{string} 对象名称

返回值

Promise<void>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | × | × |

示例

    try {
      const res = await client.removeIncompleteUpload('test');
    } catch (error) {
    }

设置对象标签

setObjectTagging(key,tags,options)

参数

• key{string} 对象名称
• options{object} 可选参数
  • versionId {string} 可选参数 版本id

返回值

Promise<void>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

获取对象标签

setObjectTagging(key,tags,options)

参数

• key{string} 对象名称
• options{object} 可选参数
  • versionId {string} 可选参数 版本id

返回值

Promise<Array<{Key：string,Value:string}>>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      const res = await client.getObjectTagging('test');
    } catch (error) {
    }

删除对象标签

removeObjectTagging(key,tags,options)

参数

• key{string} 对象名称
• options{object} 可选参数
  • versionId {string} 可选参数 版本id

返回值

Promise<void>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      await client.removeObjectTagging('test');
    } catch (error) {
    }

创建分片上传

initMultipartUpload(key,options)

参数

• key{string} 对象名称
• options{object} 可选参数
  • headers{Record<string, string | boolean | number | undefined>} 可选参数 版本id (Minio alioss中有效)
  • timeout {number} 可选参数 (alioss中有效)
  • mime {string} 可选参数 (alioss中有效)
  • metaData {Record<string, string>} 可选参数 (alioss awss3中有效)

返回值

Promise<string>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      const uploadId = await client.initMultipartUpload('test');
    } catch (error) {
    }

查询已上传分片的列表

listParts(key,uploadId)

参数

• key{string} 对象名称

• uploadId{string} 上传id

• options {object} 可选参数

  • versionId: {string} 可选参数(alioss有效)

  • timeout: {number} (alioss 中有效)

  • maxParts: {number } 可选参数 最大分块数量 (alioss,awss3中有效)

  • partNumberMarker: {number} 可选参数 分块时的起始位置 (alioss,awss3中有效)

  • encodingType: {string} 可选参数 (alioss中有效)

返回值

Promise<Array<{
  number?: number;
  lastModified?: Date;
  etag?: string;
  size?: number;
}>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      const res = await client.listParts(
        'test',
        'D1427E49EA8F1EAE37A22C73843064F9'
      );
    } catch (error) {
    }

终止分片上传

abortMultipartUpload(key,uploadId)

终止分片上传 同时会删除已上传的分片 此uploadId不可再用

参数

• key{string} 对象名称

• uploadId{string} 上传id

• options {object} 可选参数

  • versionId: {string} 可选参数 (alioss中有效）
  • timeout: {number }可选参数 (alioss中有效）

返回值

Promise<void>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      const res = await client.abortMultipartUpload(
        'test',
        'D1427E49EA8F1EAE37A22C73843064F9'
      );
      return res;
    } catch (error) {
      console.log(error);
    }

分片模式上传

multipartUpload(key,file,partSize,options)

参数

• key{string} 对象名称

• body{Body} 文件内容 详情见 当file为string时是文件路径

• partSize{number} 块大小

• options {object} 可选参数

  • parallel: {number} 可选参数 并行上传的数量 (alioss中有效)
  • partSize: {number} 可选参数 分片建议大小(minio默认为5MB 最小为5MB alioss默认为1MB 最小为100KB)
  • fileSize: {number} 可选参数 alioss最好传下 minio最好传否则进度失效
  • progress: ((...args: any[]) => any) 可选参数 获取进度回调
  • checkpoint: {Checkpoint} 可选参数 恢复上传的检查点，如果提供了该检查点，它将从中断的地方继续上传，否则将创建新的分段上传
  • headers: {Record<string, string | boolean | number | undefined>} 可选参数
  • mime: {string}; 可选参数 (alioss中有效)
  • metaData: {Record<string, string>}; 可选参数 (alioss中有效)

Checkpoint

interface Checkpoint {
  uploadId: string;
  doneParts: Array<{ number: number; etag: string }>;
}

返回值

Promise<void>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | × |

示例

    try {
       const body= fs.createReadStream('D//test.png')
      const res = await client.multipartUpload(
        'test',
         body,
         1024*1024*5,
          {
       		progress: e => {
            	console.log(`进度: ${e}`);
          	},
          }
      );
    } catch (error) {
    }

查找分片上传ID

findUploadId(key)

参数

• key{string} 对象名称

返回值

Promise<string | undefined>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      const res = await client.findUploadId(
        'test',
      );
    } catch (error) {
    }

单个分片上传

uploadPart(key,uploadId,number,file,start,end)

参数

• key{string} 对象名称
• uploadId {string}
• number {number} 块排序号
• body {Body } 文件内容 详情见
• start {number} 起始位置 当file为Buffer时生效
• end {number} 结束位置 当file为Buffer时生效

返回值

Promise<void>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
        const res = await client.uploadPart(
         'test',
         'D1427E49EA8F1EAE37A22C73843064F9',
          1
          buffer,
          1024*1024*5,
          0,
          5242880 
          }
      );
    } catch (error) {
    }

合并分片

completeMultipartUpload(key,uploadId,etags)

参数

• key {string} 对象名称
• uploadId {string}
• etags {Array<{ number: number; etag: string }>}

返回值

Promise<{ etag: string; versionId: string | null }>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
        const res = await client.uploadPart(
         'test',
         'D1427E49EA8F1EAE37A22C73843064F9',
          etags:[{number:1,etag:"D1427E49EA8F1EAE37A22C73843064F9"}] 

      );
    } catch (error) {
    }

设置Acl

putObjectAcl(key,acl)

参数

• key {string} 对象名称

• acl{Acl} 具体参数见Acl

返回值

Promise<{ key: string; acl:Acl  }> 

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | × | √ | √ |

示例

    try {
        const res = await client.putObjectAcl(
         'test',
         'public-read'
      );
    } catch (error) {
    }

获取Acl

getObjectAcl(key,acl)

参数

• key {string} 对象名称

返回值

具体参数见ReturnAcl

Promise<{ key: string; acl:ReturnAcl}> 

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | × | √ | √ |

示例

    try {
        const res = await client.getObjectAcl(
         'test',
       );
    } catch (error) {
    }

签名直传

获取文件下载链接

getDownloadUrl(key,expires)

参数

• key {string} 对象名称
• expires{number} 有效时间

返回值

Promise<string>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      const res = await Client.getUploadUrl("test","60*60*24");
    } catch (error) {
    }

获取文件上传链接

getUploadUrl(key,expires,contentType)

[!IMPORTANT]

1. 当alioss上传时 需要headers中的content-type和getUploadUrl获取链接时传递的一致包括没有 若getUploadUrl没 传headers中存在则报错 当getUploadUrl传递了acl 则headers中需要携带x- oss-object-acl headers中不允许存在其它x-oss- 的key
2. 当aws上传时 不会校验content-type 既getUploadUrl传入的content-type和文件的type和headers中的content-type都不会影响上传 元数据中存的是getUploadUrl中传递content-type
3. content-disposition取headers中的content-disposition

参数

• key{string} 对象名称

• options: 可选参数

  • expires{number} 可选参数 有效时间 默认为3 * 60 * 60 * 24
  • contentType {string} 可选参数 (alioss中有效)
  • acl {Acl} 可选参数 （alioss aws中有效） 具体参数见Acl
  • metaData {Record<string, string>} 元数据

返回值

Promise<string>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      const options={
          expires:"60*60*24", 
          contentType:"image/png",
          metaData:{name:"lanyuan"},
          acl:"public-read"
      }
      const res = await Client.getUploadUrl("test",options);
    } catch (error) {
    }

获取文件上传链接POST

getUploadUrlPost(key,options)

[!IMPORTANT]

1. getUploadUrlPost所返回的formData的数据必须要在上传时的formData
2. minio签名直传 上传时不会校验content-type 当key为前缀时 上传时对象只有前缀 如test/ 上传时对象名也为test/ 能上传成功 但minio客户端不显示 sdk能获取到
3. alioss签名直传 上传会校验content-type 当key为前缀时 上传时对象只有前缀 如test/ 上传时对象名也为test/ 能上传成功 但alioss客户端不显示 sdk也获取不到
4. aws签名直传 上传会校验content-type 当key为前缀时 上传时对象只有前缀 如test/ 上传时对象名也为test/ 能上传成功 aws客户端能显示 sdk能获到

参数

• options: {

  • key{string} 对象名称
  • keyPrefix{string} key前缀 keyPrefix和key同时存在 优先使用keyPrefix
  • expires {number } 可选参数 有效时间 默认为3 * 60 * 60 * 24
  • contentType {string} 可选参数
  • contentTypePrefix{string} 可选参数 contentType前缀 如 image/ 则匹配image/png、image/gif 等 contentType和contentTypePrefix同时存在 优先 contentTypePrefix
  • contentDisposition {string} 可选参数
  • contentLengthRange {{ min: number; max: number }} 可选参数
  • metaData {Record<string, string>} 可选参数 元数据
  • acl{Acl} （alioss aws中有效） 具体参数见Acl

  };

返回值

Promise< {
  postURL: string;
  formData: {
    [key: string]: any;
  };
}>

兼容性

| Minio | AliOSS | AWSS3 | | :-------: | :--------: | :---: | | √ | √ | √ |

示例

    try {
      const options={
          key:"test",
          expires:"60*60*24", 
          contentType:"image/png",
          contentDisposition:"attachment;filename=test.png",
          metaData:{name:"lanyuan"},
          acl:"public-read"
      }
      const res = await Client.getUploadUrlPost(body);
    } catch (error) {
    }

参数说明

Callback

• 仅AliOSS模式下 PutObject、PostObject和CompleteMultipartUpload接口支持设置Callback。 详情见

Acl

• miniio: 无 minio中不能设置对象acl
• alioss: private | public-read| public-read-write
• aws: private | public-read| public-read-write| authenticated-read| aws-exec-read| bucket-owner-read| bucket-owner-full-control | string;

ReturnAcl

• miniio: 无 minio中不能设置对象acl
• alioss: private | public-read| public-read-write
• aws: 具体见aws3getObjectAcl方法返回参数 S3.Types.GetObjectAclOutput

Body

Body类型为 Readable | Buffer | string

• string： multipartUpload中为文件路径 若方法中无特定声明 则为文本字符串
• Readable: 可读流 因Readable不好计算文件大小 所以若Body为Readable 请按方法文档传递文件大小
• Buffer: 二进制数据