对象操作

最近更新时间:2019-07-10 16:24:23

简介

本文档主要介绍关于对象的简单操作、分块操作以及其他操作相关的 API 概览以及 SDK 示例代码,并且举例如何使用。

简单操作

API 操作名 操作描述
GET Bucket(List Object) 查询对象列表 查询存储桶下的部分或者全部对象
PUT Object 简单上传对象 上传一个对象至存储桶
POST Object 表单上传对象 使用表单请求上传对象
HEAD Object 查询对象元数据 查询对象的元数据信息
GET Object 下载对象 下载一个对象至本地
OPTIONS Object 预请求跨域配置 用预请求来确认是否可以发送真正的跨域请求
PUT Object - Copy 复制对象 复制对象到目标路径(对象键)
DELETE Object 删除单个对象 在存储桶中删除指定对象
DELETE Multiple Objects 删除多个对象 在存储桶中批量删除对象

分块操作

API 操作名 操作描述
List Multipart Uploads 查询分块上传 查询正在进行中的分块上传信息
Initiate Multipart Upload 初始化分块上传 初始化分块上传任务
Upload Part 上传分块 分块上传对象
Upload Part - Copy 复制分块 将其他对象复制为一个分块
List Parts 查询已上传块 查询特定分块上传操作中的已上传的块
Complete Multipart Upload 完成分块上传 完成整个文件的分块上传
Abort Multipart Upload 终止分块上传 终止一个分块上传操作并删除已上传的块

其他操作

API 操作名 操作描述
POST Object restore 恢复归档对象 将归档类型的对象取回访问
PUT Object acl 设置对象 ACL 设置存储桶中某个对象的访问控制列表
GET Object acl 查询对象 ACL 查询对象的访问控制列表

简单操作

查询对象列表

功能说明

查询存储桶下的部分或者全部对象。

使用示例

示例一:列出目录 a 的所有文件。

cos.getBucket({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',     /* 必须 */
    Prefix: 'a/',           /* 非必须 */
}, function(err, data) {
    console.log(err || data.Contents);
});

返回值格式:

{
    "Name": "examplebucket-1250000000",
    "Prefix": "",
    "Marker": "a/",
    "MaxKeys": "1000",
    "Delimiter": "",
    "IsTruncated": "false",
    "Contents": [{
        "Key": "a/3mb.zip",
        "LastModified": "2018-10-18T07:08:03.000Z",
        "ETag": "\"05a9a30179f3db7b63136f30aa6aacae-3\"",
        "Size": "3145728",
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        },
        "StorageClass": "STANDARD"
    }],
    "statusCode": 200,
    "headers": {}
}

示例二:列出目录 a 的文件,不深度遍历。

cos.getBucket({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Prefix: 'a/',              /* 非必须 */
    Delimiter: '/',            /* 非必须 */
}, function(err, data) {
    console.log(err || data.CommonPrefix);
});

返回值格式:

{
    "Name": "examplebucket-1250000000",
    "Prefix": "a/",
    "Marker": "",
    "MaxKeys": "1000",
    "Delimiter": "/",
    "IsTruncated": "false",
    "CommonPrefixes": [{
        "Prefix": "a/1/"
    }],
    "Contents": [{
        "Key": "a/3mb.zip",
        "LastModified": "2018-10-18T07:08:03.000Z",
        "ETag": "\"05a9a30179f3db7b63136f30aa6aacae-3\"",
        "Size": "3145728",
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        },
        "StorageClass": "STANDARD"
    }],
    "statusCode": 200,
    "headers": {}
}

参数说明

参数名 参数描述 类型 必填
Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
Prefix 前缀匹配,用来规定返回的文件前缀地址 String
Delimiter 定界符为一个分隔符号,一般是传/,如果有 Prefix,则将 Prefix 到 delimiter 之间的相同路径归为一类,定义为 Common Prefix,并列出所有 Common Prefix。如果没有 Prefix,则从路径起点开始 String
Marker 默认以 UTF-8 二进制顺序列出条目,所有列出条目从 marker 开始 String
MaxKeys 单次返回最大的条目数量,默认值为1000 String
EncodingType 规定返回值的编码方式,可选值:url String

回调函数说明

function(err, data) { ... }
参数名 参数描述 类型
err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
- statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
- headers 请求返回的头部信息 Object
data 请求成功时返回的对象,如果请求发生错误,则为空 Object
- headers 请求返回的头部信息 Object
- statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
- CommonPrefixes 将 Prefix 到 delimiter 之间的相同路径归为一类,定义为 Common Prefix ObjectArray
- - Prefix 单条 Common 的前缀 String
- - Name 说明 Bucket 的信息 String
- Prefix 前缀匹配,用来规定返回的文件前缀地址 String
- Marker 默认以 UTF-8 二进制顺序列出条目,所有列出条目从 marker 开始 String
- MaxKeys 单次响应请求内返回结果的最大的条目数量 String
- IsTruncated 响应请求条目是否被截断,字符串,'true' 或者 'false' String
- NextMarker 假如返回条目被截断,则返回NextMarker就是下一个条目的起点 String
- Encoding-Type 返回值的编码方式,作用于Delimiter,Marker,Prefix,NextMarker,Key String
- Contents 元数据信息 ObjectArray
- - ETag 文件的 MD5 算法校验值
例如"22ca88419e2ed4721c23807c678adbe4c08a7880"注意前后携带双引号
String
- - Size 说明文件大小,单位为 Byte String
- - Key Object 名称 String
- - LastModified 说明 Object 最后被修改时间,例如2017-06-23T12:33:27.000Z String
- - Owner Bucket 持有者信息 Object
- ID Bucket 的 AppID String
- StorageClass Object 的存储级别,枚举值:STANDARD、STANDARD_IA、ARCHIVE String

简单上传对象

功能说明

上传一个对象至存储桶。该操作需要请求者对存储桶有 WRITE 权限。

注意:

  1. Key(文件名)不能以 / 结尾,否则会被识别为文件夹。
  2. 每个主账号(即同一个 APPID),存储桶的 ACL、Policy 和 CAM 关联的策略数量总和最多为1000条,对象 ACL 规则数量不限制。如果您不需要进行对象 ACL 控制,请在上传时不要设置,默认继承 Bucket 权限。
  3. 上传之后,您可以用同样的 Key 生成预签名链接(下载请指定 method 为 GET,具体接口说明见下文,分享到其他端来进行下载。但注意如果您的文件是私有读权限,那么预签名链接只有一定的有效期。

使用示例

简单上传文件,适用于小文件上传。

cos.putObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Key: 'picture.jpg',              /* 必须 */
    StorageClass: 'STANDARD',
    Body: fs.createReadStream('./picture.jpg'), // 上传文件对象
    onProgress: function(progressData) {
        console.log(JSON.stringify(progressData));
    }
}, function(err, data) {
    console.log(err || data);
});

上传 Buffer 作为文件内容:

cos.putObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Key: 'picture.jpg',              /* 必须 */
    Body: Buffer.from('hello!'), /* 必须 */
}, function(err, data) {
    console.log(err || data);
});

上传字符串作为文件内容:

cos.putObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Key: 'picture.jpg',              /* 必须 */
    Body: 'hello!',
}, function(err, data) {
    console.log(err || data);
});

创建目录:

cos.putObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Key: 'a/',              /* 必须 */
    Body: '',
}, function(err, data) {
    console.log(err || data);
});

参数说明

参数名 参数描述 类型 必填
Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
CacheControl RFC 2616中定义的缓存策略,将作为 Object 元数据保存 String
ContentDisposition RFC 2616中定义的文件名称,将作为 Object 元数据保存 String
ContentEncoding RFC 2616中定义的编码格式,将作为 Object 元数据保存 String
ContentLength RFC 2616中定义的 HTTP 请求内容长度(字节) String
ContentType RFC 2616中定义的内容类型(MIME),将作为 Object 元数据保存 String
Expect 当使用 Expect: 100-continue 时,在收到服务端确认后,才会发送请求内容 String
Expires RFC 2616中定义的过期时间,将作为 Object 元数据保存 String
ACL 定义 Object 的 ACL 属性,有效值:private、public-read;默认值:private String
GrantRead 赋予被授权者读的权限,格式:x-cos-grant-read: id="[OwnerUin]" String
GrantFullControl 赋予被授权者所有的权限,格式:x-cos-grant-full-control: id="[OwnerUin]" String
StorageClass 设置 Object 的存储级别,枚举值:STANDARD、STANDARD_IA、ARCHIVE,默认值:STANDARD String
x-cos-meta-* 允许用户自定义的头部信息,将作为 Object 元数据返回,大小限制2K String
Body 上传文件的内容,可以为 FileStream、字符串、Buffer Stream/Buffer/String
onProgress 进度的回调函数,进度回调响应对象(progressData)属性如下 Function
- progressData.loaded 已经下载的文件部分大小,以字节(Bytes)为单位 Number
- progressData.total 整个文件的大小,以字节(Bytes)为单位 Number
- progressData.speed 文件的下载速度,以字节/秒(Bytes/s)为单位 Number
- progressData.percent 文件下载的百分比,以小数形式呈现,例如:下载50%即为0.5 Number

回调函数说明

function(err, data) { ... }
参数名 参数描述 类型
err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
- statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
- headers 请求返回的头部信息 Object
data 请求成功时返回的对象,如果请求发生错误,则为空 Object
- statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
- headers 请求返回的头部信息 Object
- ETag 返回文件的 MD5 算法校验值。ETag 的值可以用于检查 Object 在上传过程中是否有损坏
例如"09cba091df696af91549de27b8e7d0f6"注意:这里的 ETag 值字符串前后带有双引号
String

表单上传对象

Node.js SDK 未提供 POST Object 接口对应的方法,如果需要使用该接口,请参见 Web 端直传实践 里的“方案 B:使用 Form 表单上传”。

查询对象元数据

功能说明

查询对象的元数据信息。

使用示例

cos.headObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Key: 'picture.jpg',               /* 必须 */
}, function(err, data) {
    console.log(err || data);
});

参数说明

参数名 参数描述 类型 必填
Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
IfModifiedSince 当 Object 在指定时间后被修改,则返回对应 Object 的 meta 信息,否则返回304 String

回调函数说明

function(err, data) { ... }
参数名 参数描述 类型
err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
- statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
- headers 请求返回的头部信息 Object
data 请求成功时返回的对象,如果请求发生错误,则为空 Object
- statusCode 请求返回的 HTTP 状态码,如200,304等,如果在指定时间后未被修改,则返回304 Number
- headers 请求返回的头部信息 Object
- x-cos-object-type 用来表示 Object 是否可以被追加上传,枚举值:normal、appendable String
- x-cos-storage-class Object 的存储级别,枚举值:STANDARD、STANDARD_IA、ARCHIVE String
- x-cos-meta-* 用户自定义的 meta String
- NotModified Object 是否在指定时间后未被修改 Boolean

下载对象

GET Object 接口请求可以获取存储桶里指定文件的内容,得到文件内容是字符串格式。

使用示例

cos.getObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Key: 'picture.jpg',              /* 必须 */
}, function(err, data) {
    console.log(err || data.Body);
});

指定 Range 获取文件内容:

cos.getObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Key: 'picture.jpg',              /* 必须 */
    Range: 'bytes=1-3',        /* 非必须 */
}, function(err, data) {
    console.log(err || data.Body);
});

下载文件到指定路径:

cos.getObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Key: 'picture.jpg',              /* 必须 */
    Output: './picture.jpg',
}, function(err, data) {
    console.log(err || data.Body);
});

下载文件到指定写文件流:

cos.getObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Key: 'picture.jpg',              /* 必须 */
    Output: fs.createWriteStream('./picture.jpg'),
}, function(err, data) {
    console.log(err || data.Body);
});

参数说明

参数名 参数描述 类型 必填
Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
Output 输出的文件路径或者一个写流,若不传入,则将完整内容写入回调函数data String/WriteStream
ResponseContentType 设置响应头部中的 Content-Type 参数 String
ResponseContentLanguage 设置返回头部中的 Content-Language 参数 String
ResponseExpires 设置返回头部中的 Content-Expires 参数 String
ResponseCacheControl 设置返回头部中的 Cache-Control 参数 String
ResponseContentDisposition 设置返回头部中的 Content-Disposition 参数 String
ResponseContentEncoding 设置返回头部中的 Content-Encoding 参数 String
Range 对象的字节范围,范围值必须使用 bytes=first-last 格式,first 和 last 都是基于0开始的偏移量。例如 bytes=0-9 表示您希望拷贝源对象的开头10个字节的数据 ,如果不指定,则表示读取整个对象 String
IfModifiedSince 当Object在指定时间后被修改,则返回对应 Object meta 信息,否则返回304 String
IfUnmodifiedSince 如果文件修改时间早于或等于指定时间,才返回文件内容,否则返回412(precondition failed) String
IfMatch 当 ETag 与指定的内容一致,才返回文件,否则返回412(precondition failed) String
IfNoneMatch 当 ETag 与指定的内容不一致,才返回文件,否则返回304(not modified) String

回调函数说明

function(err, data) { ... }
参数名 参数描述 类型
err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
- statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
- headers 请求返回的头部信息 Object
data 请求成功时返回的对象,如果请求发生错误,则为空 Object
- statusCode 请求返回的 HTTP 状态码,如200,304,403,404等 Number
- headers 请求返回的头部信息 Object
- x-cos-object-type 用来表示 Object 是否可以被追加上传,枚举值:normal、appendable String
- x-cos-storage-class Object 的存储级别,枚举值:STANDARD、STANDARD_IA,
注意:如果没有返回该头部,则说明文件存储级别为 STANDARD (标准存储)
String
- x-cos-meta-* 用户自定义的元数据 String
- NotModified 如果请求时带有 IfModifiedSince 则返回该属性,如果文件未被修改,则为 true,否则为 false Boolean
- Body 返回的文件内容,默认为 String 形式 String

预请求跨域配置

功能说明

OPTIONS Object 接口实现 Object 跨域访问配置的预请求。即在发送跨域请求之前会发送一个 OPTIONS 请求并带上特定的来源域,HTTP 方法和 HEADER 信息等给 COS,以决定是否可以发送真正的跨域请求。当 CORS 配置不存在时,请求返回403 Forbidden。用户可以通过 PUT Bucket cors 接口来开启 Bucket 的 CORS 支持。

使用示例

cos.optionsObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Key: 'picture.jpg',              /* 必须 */
    Origin: 'https://www.qq.com',      /* 必须 */
    AccessControlRequestMethod: 'PUT', /* 必须 */
    AccessControlRequestHeaders: 'origin,accept,content-type' /* 非必须 */
}, function(err, data) {
    console.log(err || data);
});

参数说明

参数名 参数描述 类型 必填
Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
Origin 模拟跨域访问的请求来源域名 String
AccessControlRequestMethod 模拟跨域访问的请求 HTTP 方法 String
AccessControlRequestHeaders 模拟跨域访问的请求头部 String

回调函数说明

function(err, data) { ... }
参数名 参数描述 类型
err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
- statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
- headers 请求返回的头部信息 Object
data 请求成功时返回的对象,如果请求发生错误,则为空 Object
- headers 请求返回的头部信息 Object
- statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
- AccessControlAllowOrigin 模拟跨域访问的请求来源域名,中间用逗号间隔,当来源不允许的时候,此 Header 不返回,例如* String
- AccessControlAllowMethods 模拟跨域访问的请求 HTTP 方法,中间用逗号间隔,当请求方法不允许的时候,此 Header 不返回,例如 PUT,GET,POST,DELETE,HEAD String
- AccessControlAllowHeaders 模拟跨域访问的请求头部,中间用逗号间隔,当模拟任何请求头部不允许的时候,此 Header 不返回该请求头部,例如 accept,content-type,origin,authorization String
- AccessControlExposeHeaders 跨域支持返回头部,中间用逗号间隔,例如 ETag String
- AccessControlMaxAge 设置 OPTIONS 请求得到结果的有效期,例如3600 String
- OptionsForbidden OPTIONS 请求是否被禁止,如果返回的 HTTP 状态码为403,则为 true Boolean

复制对象

功能说明

PUT Object - Copy 请求实现将一个文件从源路径复制到目标路径。建议文件大小1MB - 5GB,超过5GB的文件请使用分块上传 Upload - Copy。在拷贝的过程中,文件元属性和 ACL 可以被修改。用户可以通过该接口复制文件、修改文件属性(源文件和目标文件的属性相同)、移动或重命名文件(先复制,再单独调用删除接口)。

使用示例

cos.putObjectCopy({
    Bucket: 'examplebucket-1250000000',                               /* 必须 */
    Region: 'ap-beijing',                                  /* 必须 */
    Key: 'picture.jpg',                                            /* 必须 */
    CopySource: 'test-1250000000.cos.ap-guangzhou.myqcloud.com/2.jpg', /* 必须 */
}, function(err, data) {
    console.log(err || data);
});

参数说明

参数名 参数描述 类型 必填
Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
CopySource 源文件 URL 路径,可以通过 versionid 子资源指定历史版本 String
ACL 定义 Object 的 ACL 属性。有效值:private、public-read;默认值:private String
GrantRead 赋予被授权者读的权限。格式:id="[OwnerUin]" String
GrantFullControl 赋予被授权者所有的权限。格式:id="[OwnerUin]" String
MetadataDirective 是否拷贝元数据,枚举值:Copy,Replaced,默认值 Copy。假如标记为 Copy,忽略 Header 中的用户元数据信息直接复制;假如标记为 Replaced,按 Header 信息修改元数据。当目标路径和原路径一致,即用户试图修改元数据时,必须为 Replaced String
CopySourceIfModifiedSince 当 Object 在指定时间后被修改,则执行操作,否则返回412。可与 CopySourceIfNoneMatch 一起使用,与其他条件联合使用返回冲突 String
CopySourceIfUnmodifiedSince 当 Object 在指定时间后未被修改,则执行操作,否则返回412。可与 CopySourceIfMatch 一起使用,与其他条件联合使用返回冲突 String
CopySourceIfMatch 当 Object 的 Etag 和给定一致时,则执行操作,否则返回412。可与CopySourceIfUnmodifiedSince 一起使用,与其他条件联合使用返回冲突 String
CopySourceIfNoneMatch 当 Object 的 Etag 和给定不一致时,则执行操作,否则返回412。可与 CopySourceIfModifiedSince 一起使用,与其他条件联合使用返回冲突 String
StorageClass 存储级别,枚举值:存储级别,枚举值:Standard,Standard_IA;默认值:Standard String
x-cos-meta-* 其他自定义的文件头部 String
CacheControl 指定所有缓存机制在整个请求/响应链中必须服从的指令 String
ContentDisposition MIME 协议的扩展,MIME 协议指示 MIME 用户代理如何显示附加的文件 String
ContentEncoding HTTP 中用来对「采用何种编码格式传输正文」进行协定的一对头部字段 String
ContentType RFC 2616 中定义的 HTTP 请求内容类型(MIME),例如 text/plain String
Expect 请求的特定的服务器行为 String
Expires 响应过期的日期和时间 String

回调函数说明

function(err, data) { ... }
参数名 参数描述 类型
err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
- statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
- headers 请求返回的头部信息 Object
data 请求成功时返回的对象,如果请求发生错误,则为空 Object
- statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
- headers 请求返回的头部信息 Object
- ETag 文件的 MD5 算法校验值,例如"22ca88419e2ed4721c23807c678adbe4c08a7880"注意前后携带双引号 String
- LastModified 说明 Object 最后被修改时间,例如2017-06-23T12:33:27.000Z String

删除单个对象

功能说明

在存储桶中删除指定对象。该操作需要请求者对 Bucket 有 WRITE 权限。

使用示例

cos.deleteObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Key: 'picture.jpg'                            /* 必须 */
}, function(err, data) {
    console.log(err || data);
});

参数说明

参数名 参数描述 类型 必填
Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String

回调函数说明

function(err, data) { ... }
参数名 参数描述 类型
err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
- statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
- headers 请求返回的头部信息 Object
data 请求成功时返回的对象,如果请求发生错误,则为空 Object
- statusCode 请求返回的 HTTP 状态码,如200,204,403,404等,如果删除成功或者文件不存在则返回204或200,如果找不到指定的 Bucket,则返回404 Number
- headers 请求返回的头部信息 Object

删除多个对象

功能说明

在存储桶中批量删除对象,单次请求最大支持批量删除1000个 Object。对于响应结果,COS 提供 Verbose 和 Quiet 两种模式:Verbose 模式将返回每个 Object 的删除结果,Quiet 模式只返回报错的 Object 信息。

使用示例

删除多个文件:

cos.deleteMultipleObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Objects: [
        {Key: 'picture.jpg'},
        {Key: '2.zip'},
    ]
}, function(err, data) {
    console.log(err || data);
});

参数说明

参数名 参数描述 类型 必填
Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
Quiet 布尔值,这个值决定了是否启动 Quiet 模式,值为 true 启动 Quiet 模式,值为 false 则启动 Verbose 模式,默认值为 false Boolean
Objects 要删除的文件列表 ObjectArray
- Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
- VersionId 要删除的 Object 或 DeleteMarker 版本 ID String

回调函数说明

function(err, data) { ... }
参数名 参数描述 类型
err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
- statusCode 请求返回的 HTTP 状态码,如200,204,403,404等 Number
- headers 请求返回的头部信息 Object
data 请求成功时返回的对象,如果请求发生错误,则为空 Object
- statusCode 请求返回的 HTTP 状态码,如200,204,403,404等 Number
- headers 请求返回的头部信息 Object
- Deleted 说明本次删除的成功 Object 信息 ObjectArray
- - Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
- - VersionId 如果参数传入了 VersionId,返回也会带上 VersionId,表示刚操作的 Object 或 DeleteMarker 版本 String
- - DeleteMarker 如果开启了版本控制,并且参数没有 VersionId,本次删除不会真正抹去文件内容,只新增一个 DeleteMarker 代表可见的文件已删除,枚举值:true、false String
- - DeleteMarkerVersionId 当返回的 DeleteMarker 为 true 时,返回刚新增的 DeleteMarker 的 VersionId String
- Error 说明本次删除的失败 Object 信息 ObjectArray
- - Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
- - Code 删除失败的错误码 String
- - Message 删除错误信息 String

分块操作

查询分块上传

功能说明

List Multiparts Uploads 用来查询正在进行中的分块上传信息。单次最多列出1000个正在进行中的分块上传。

使用示例

获取前缀为1.zip的未完成的 UploadId 列表

cos.multipartList({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'ap-beijing',    /* 必须 */
    Prefix: '1.zip',                        /* 非必须 */
}, function(err, data) {
    console.log(err || data);
});

参数说明

参数名 参数描述 类型 必填
Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
Delimiter 定界符为一个符号,对 Object 名字包含指定前缀且第一次出现 delimiter 字符之间的 Object 作为一组元素:common prefix。如果没有 prefix,则从路径起点开始 String
EncodingType 规定返回值的编码格式,合法值:url String
Prefix 限定返回的 Object key 必须以 Prefix 作为前缀。注意使用 prefix 查询时,返回的 key 中仍会包含 Prefix String
MaxUploads 设置最大返回的 multipart 数量,合法取值范围为1 - 1000,默认为1000 String
KeyMarker 与 upload-id-marker 一起使用
  • 当 upload-id-marker 未被指定时:
    ObjectName 字母顺序大于 key-marker 的条目将被列出
  • 当 upload-id-marker 被指定时:
    ObjectName 字母顺序大于 key-marker 的条目被列出
    ObjectName 字母顺序等于 key-marker 且 UploadID 大于 upload-id-marker 的条目将被列出
  • String
    UploadIdMarker 与 key-marker 一起使用
  • 当 key-marker 未被指定时:upload-id-marker 将被忽略
  • 当 key-marker 被指定时:
    ObjectName 字母顺序大于 key-marker 的条目被列出
    ObjectName 字母顺序等于 key-marker 且 UploadID 大于 upload-id-marker 的条目将被列出
  • String

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    - Bucket 分块上传的目标 Bucket String
    - Encoding-Type 规定返回值的编码格式,合法值:url String
    - KeyMarker 列出条目从该 key 值开始 String
    - UploadIdMarker 列出条目从该 UploadId 值开始 String
    - NextKeyMarker 假如返回条目被截断,则返回 NextKeyMarker 就是下一个条目的起点 String
    - NextUploadIdMarker 假如返回条目被截断,则返回 UploadId 就是下一个条目的起点 String
    - MaxUploads 设置最大返回的 multipart 数量,合法取值范围为1 - 1000 String
    - IsTruncated 返回条目是否被截断,'true' 或者 'false' String
    - Delimiter 定界符为一个符号,对 object 名字包含指定前缀且第一次出现 delimiter 字符之间的 object 作为一组元素:common prefix。如果没有 prefix,则从路径起点开始 String
    - Prefix 限定返回的 Object key 必须以 Prefix 作为前缀。注意使用 prefix 查询时,返回的 key 中仍会包含 Prefix String
    - CommonPrefixs 将 prefix 到 delimiter 之间的相同路径归为一类,定义为 Common Prefix ObjectArray
    - - Prefix 显示具体的 CommonPrefixs String
    - Upload Upload 的信息集合 ObjectArray
    - - Key Object 的名称 String
    - - UploadId 标示本次分块上传的 ID String
    - StorageClass 用来表示分块的存储级别,枚举值:STANDARD、STANDARD_IA、ARCHIVE String
    - Initiator 用来表示本次上传发起者的信息 Object
    - - DisplayName 上传发起者的名称 String
    - - ID 上传发起者 ID,格式:qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    如果是主账号,<OwnerUin> 和 <SubUin> 是同一个值
    String
    - Owner 用来表示这些分块所有者的信息 Object
    - - DisplayName Bucket 持有者的名称 String
    - - ID Bucket 持有者 ID,格式:qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    如果是主账号,<OwnerUin> 和 <SubUin> 是同一个值
    String
    - Initiated 分块上传的起始时间 String

    初始化分块上传

    功能说明

    Initiate Multipart Upload 请求实现初始化分片上传,成功执行此请求后会返回 Upload ID ,用于后续的 Upload Part 请求。

    使用示例

    cos.multipartInit({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'ap-beijing',    /* 必须 */
        Key: 'picture.jpg',              /* 必须 */
    }, function(err, data) {
        console.log(err || data);
    });

    参数说明

    参数名 参数描述 类型 必填
    Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
    Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    CacheControl RFC 2616 中定义的缓存策略,将作为 Object 元数据保存 String
    ContentDisposition RFC 2616 中定义的文件名称,将作为 Object 元数据保存 String
    ContentEncoding RFC 2616 中定义的编码格式,将作为 Object 元数据保存 String
    ContentType RFC 2616 中定义的内容类型(MIME),将作为 Object 元数据保存 String
    Expires RFC 2616 中定义的过期时间,将作为 Object 元数据保存 String
    ACL 定义 Object 的 ACL 属性。有效值:private、public-read;默认值:private String
    GrantRead 赋予被授权者读的权限,格式:id="[OwnerUin]" String
    GrantFullControl 赋予被授权者所有的权限,格式:id="[OwnerUin]" String
    StorageClass 设置Object的存储级别,枚举值:STANDARD、STANDARD_IA、ARCHIVE,默认值:STANDARD String
    x-cos-meta-* 允许用户自定义的头部信息,将作为 Object 元数据返回。大小限制2K String

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    Bucket 分片上传的目标 Bucket String
    Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    UploadId 在后续上传中使用的 ID String

    上传分块

    功能说明

    Upload Part 接口请求实现在初始化以后的分块上传,支持的块的数量为1 - 10000,块的大小为1MB - 5GB。
    使用 Initiate Multipart Upload 接口初始化分片上传时会得到一个 uploadId,该 ID 不但唯一标识这一分块数据,也标识了这分块数据在整个文件内的相对位置。在每次请求 Upload Part 时候,需要携带 partNumber 和 uploadId,partNumber 为块的编号,支持乱序上传。
    当传入 uploadId 和 partNumber 都相同的时候,后传入的块将覆盖之前传入的块。当 uploadId 不存在时将返回404错误,NoSuchUpload。

    使用示例

    cos.multipartUpload({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'ap-beijing',    /* 必须 */
        Key: 'picture.jpg',       /* 必须 */
    }, function(err, data) {
        console.log(err || data);
    });

    参数说明

    参数名 参数描述 类型 必填
    Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
    Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    ContentLength RFC 2616 中定义的 HTTP 请求内容长度(字节) String
    PartNumber 分块的编号 String
    UploadId 上传任务编号 String
    Body 上传文件分块的内容,可以为字符串,File 对象或者 Blob 对象 String\File\Blob
    Expect 当使用Expect: 100-continue时,在收到服务端确认后,才会发送请求内容 String
    ContentMD5 RFC 1864中定义的经过 Base64 编码的128-bit内容 MD5 校验值,此头部用来校验文件内容是否发生变化 String

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object

    复制分块

    功能说明

    Upload Part 接口请求实现在初始化以后的分块上传,支持的块的数量为1 - 10000,块的大小为1MB - 5GB。
    使用 Initiate Multipart Upload 接口初始化分片上传时会得到一个 uploadId,该 ID 不但唯一标识这一分块数据,也标识了这分块数据在整个文件内的相对位置。在每次请求 Upload Part 时候,需要携带 partNumber 和 uploadId,partNumber 为块的编号,支持乱序上传。
    当传入 uploadId 和 partNumber 都相同的时候,后传入的块将覆盖之前传入的块。当 uploadId 不存在时会返回404错误,错误码为 NoSuchUpload。

    使用示例

    cos.multipartUpload({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'ap-beijing',    /* 必须 */
        Key: 'picture.jpg',       /* 必须 */
    }, function(err, data) {
        console.log(err || data);
    });

    参数说明

    参数名 参数描述 类型 必填
    Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
    Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    CopySource 源对象 URL 路径,可以通过 versionid 子资源指定历史版本 String
    CopySourceRange 源对象的字节范围,范围值必须使用 bytes=first-last 格式,first 和 last 都是基于0开始的偏移量。例如 bytes=0-9 表示您希望拷贝源对象的开头10个字节的数据 ,如果不指定,则表示拷贝整个对象 String
    CopySourceIfMatch 当 Object 的 Etag 和给定一致时,则执行操作,否则返回412,可与 x-cos-copy-source-If-Unmodified-Since 一起使用,与其他条件联合使用返回冲突 String
    CopySourceIfNoneMatch 当 Object 的 Etag 和给定不一致时,则执行操作,否则返回412,可与 x-cos-copy-source-If-Modified-Since 一起使用,与其他条件联合使用返回冲突 String
    CopySourceIfUnmodifiedSince 当 Object 在指定时间后未被修改,则执行操作,否则返回412,可与 x-cos-copy-source-If-Match 一起使用,与其他条件联合使用返回冲突 String
    CopySourceIfModifiedSince 当 Object 在指定时间后被修改,则执行操作,否则返回412,可与 x-cos-copy-source-If-None-Match 一起使用,与其他条件联合使用返回冲突 String

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    - ETag 文件的 MD5 算法校验值,例如"22ca88419e2ed4721c23807c678adbe4c08a7880"注意前后携带双引号 String

    查询已上传块

    功能说明

    List Parts 用来查询特定分块上传中的已上传的块,即列出指定 UploadId 所属的所有已上传成功的分块。

    使用示例

    cos.multipartListPart({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'ap-beijing',    /* 必须 */
        Key: 'picture.jpg',              /* 必须 */
        UploadId: '1521389146c60e7e198202e4e6670c5c78ea5d1c60ad62f1862f47294ec0fb8c6b7f3528a2',                      /* 必须 */
    }, function(err, data) {
        console.log(err || data);
    });

    参数说明

    参数名 参数描述 类型 必填
    Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
    Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    UploadId 标识本次分块上传的 ID。使用 Initiate Multipart Upload 接口初始化分片上传时会得到一个 uploadId,该 ID 不但唯一标识这一分块数据,也标识了这分块数据在整个文件内的相对位置 String
    EncodingType 规定返回值的编码方式 String
    MaxParts 单次返回最大的条目数量,默认为1000 String
    PartNumberMarker 默认以 UTF-8 二进制顺序列出条目,所有列出条目从 marker 开始 String

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    - Bucket 分块上传的目标 Bucket String
    - Encoding-type 规定返回值的编码方式 String
    - Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    - UploadId 标识本次分块上传的 ID String
    - Initiator 用来表示本次上传发起者的信息 Object
    - - DisplayName 上传发起者的名称 String
    - - ID 上传发起者 ID,格式:qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    如果是主账号,<OwnerUin> 和 <SubUin> 是同一个值
    String
    - Owner 用来表示这些分块所有者的信息 Object
    - - DisplayName Bucket 持有者的名称 String
    - - ID Bucket 持有者 ID,一般为用户的 UIN String
    - StorageClass 用来表示这些分块的存储级别,枚举值:Standard、Standard_IA、Archive String
    - PartNumberMarker 默认以 UTF-8 二进制顺序列出条目,所有列出条目从 marker 开始 String
    - NextPartNumberMarker 假如返回条目被截断,则返回 NextMarker 就是下一个条目的起点 String
    - MaxParts 单次返回最大的条目数量 String
    - IsTruncated 返回条目是否被截断,'true' 或者 'false' String
    - Part 分块信息列表 ObjectArray
    - - PartNumber 块的编号 String
    - - LastModified 块最后修改时间 String
    - - ETag 块的 MD5 算法校验值 String
    - - Size 块大小,单位为 Byte String

    完成分块上传

    功能说明

    Complete Multipart Upload 接口请求用来实现完成整个分块上传。当使用 Upload Parts 上传完所有块以后,必须调用该 API 来完成整个文件的分块上传。在使用该 API 时,您必须在请求 Body 中给出每一个块的 PartNumber 和 ETag,用来校验块的准确性。
    由于分块上传完后需要合并,而合并需要数分钟时间,因而当合并分块开始的时候,COS 就立即返回200的状态码,在合并的过程中,COS 会周期性的返回空格信息来保持连接活跃,直到合并完成,COS 会在 Body 中返回合并后块的内容。

    • 当上传块小于1MB ,在调用该 API 时,会返回400 EntityTooSmall。
    • 当上传块编号不连续,在调用该 API 时,会返回400 InvalidPart。
    • 当请求 Body 中的块信息未按序号从小到大排列,在调用该 API 时,会返回400 InvalidPartOrder。
    • 当 UploadId 不存在,在调用该 API 时,会返回404 NoSuchUpload。

    使用示例

    cos.multipartComplete({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'ap-beijing',    /* 必须 */
        Key: '1.zip',              /* 必须 */
        UploadId: '1521389146c60e7e198202e4e6670c5c78ea5d1c60ad62f1862f472941c0fb8c6b7f3528a2', /* 必须 */
        Parts: [
            {PartNumber: '1', ETag: '"0cce40bdbaf2fa0ff204c20fc965dd3f"'},
        ]
    }, function(err, data) {
        console.log(err || data);
    });

    参数说明

    参数名 参数描述 类型 必填
    Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
    Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    UploadId 上传任务编号 String
    Parts 用来说明本次分块上传中块的信息列表 ObjectArray
    - PartNumber 分块的编号 String
    - ETag 每个块文件的 MD5 算法校验值
    例如"22ca88419e2ed4721c23807c678adbe4c08a7880"注意前后携带双引号
    String

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    - Location 创建的 Object 的外网访问域名 String
    - Bucket 分块上传的目标 Bucket String
    - Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    - ETag 合并后文件的唯一 ID,格式:"uuid-<分块数>"
    例如"22ca88419e2ed4721c23807c678adbe4c08a7880-3"注意前后携带双引号
    String

    终止分块上传

    功能说明

    Abort Multipart Upload 用来实现终止一个分块上传操作并删除已上传的块。当您调用 Abort Multipart Upload 时,如果有正在使用这个 Upload Parts 上传块的请求,则 Upload Parts 会返回失败。当该 UploadId 不存在时,会返回404 NoSuchUpload。

    注意:

    建议您及时完成分块上传或者舍弃分块上传,因为已上传但是未终止的块会占用存储空间进而产生存储费用。

    使用示例

    cos.multipartAbort({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'ap-beijing',    /* 必须 */
        Key: '1.zip',                           /* 必须 */
        UploadId: '1521389146c60e7e198202e4e6670c5c78ea5d1c60ad62f1862f47294ec0fb8c6b7f3528a2'                       /* 必须 */
    }, function(err, data) {
        console.log(err || data);
    });

    参数说明

    参数名 参数描述 类型 必填
    Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
    Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    UploadId 标识本次分块上传的 ID。使用 Initiate Multipart Upload 接口初始化分片上传时会得到一个 uploadId,该 ID 不但唯一标识这一分块数据,也标识了这分块数据在整个文件内的相对位置 String

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object

    其他操作

    恢复归档对象

    功能说明

    将归档类型的对象取回访问。

    使用示例

    cos.restoreObject({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'ap-beijing',    /* 必须 */
        Key: 'picture.jpg',
        RestoreRequest: {
            Days: 1,
            CASJobParameters: {
                Tier: 'Expedited'
            }
        },
    }, function(err, data) {
        console.log(err || data);
    });

    参数说明

    参数名 参数描述 类型 必填
    Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
    Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    RestoreRequest 用于恢复数据的容器 Object
    - Days 设置临时副本的过期时间 Object
    - CASJobParameters 归档存储工作参数的容器 Object
    - - Tire 恢复数据时,Tier 可以指定为 CAS 支持的三种恢复模式,分别为 Standard(标准模式,恢复任务在3 - 5小时内完成)、Expedited(极速模式,恢复任务在15分钟内可完成)以及 Bulk(批量模式,恢复任务在5 - 12小时内完成) Integer

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object

    设置对象 ACL

    功能说明

    设置存储桶中某个对象的访问控制列表。

    注意:

    每个主账号(即同一个 APPID),存储桶的 ACL、Policy 和 CAM 关联的策略数量总和最多为1000条,对象 ACL 规则数量不限制。如果您不需要进行对象 ACL 控制,请不要设置,默认继承 Bucket 权限。

    使用示例

    cos.putObjectAcl({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'ap-beijing',    /* 必须 */
        Key: 'picture.jpg',              /* 必须 */
        ACL: 'public-read',        /* 非必须 */
    }, function(err, data) {
        console.log(err || data);
    });

    为某个用户赋予文件读写权限:

    cos.putObjectAcl({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'ap-beijing',    /* 必须 */
        Key: 'picture.jpg',              /* 必须 */
        GrantFullControl: 'id="100000000001"' // 100000000001是主账号 uin
    }, function(err, data) {
        console.log(err || data);
    });

    通过 AccessControlPolicy 修改 Bucket 权限:

    cos.putObjectAcl({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'ap-beijing',    /* 必须 */
        Key: 'picture.jpg',              /* 必须 */
        AccessControlPolicy: {
            "Owner": { // AccessControlPolicy 里必须有 owner
                "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 是 Bucket 所属用户的 QQ 号
            },
            "Grants": [{
                "Grantee": {
                    "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 是 QQ 号
                },
                "Permission": "WRITE"
            }]
        }
    }, function(err, data) {
        console.log(err || data);
    });

    参数说明

    参数名 参数描述 类型 必填
    Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
    Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    ACL 定义 Object 的 ACL 属性。有效值:private、public-read、default。默认值:private。传 default 时清除文件权限,权限恢复为继承权限 String
    GrantRead 赋予被授权者读的权限。格式:id="[OwnerUin]" String
    GrantFullControl 赋予被授权者所有的权限。格式:id="[OwnerUin]" String
    AccessControlPolicy Object 的 ACL JSON 定义格式 Object
    - Owner 标识资源的所有者 Object
    - - ID Object 持有者 ID,格式:qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    如果是主账号,<OwnerUin> 和<SubUin> 是同一个值
    String
    - - DisplayName Object 持有者的名称 String
    - Grants 被授权者信息与权限信息列表 ObjectArray
    - - Permission 指明授予被授权者的权限信息,枚举值:READ、WRITE、READ_ACP、WRITE_ACP、FULL_CONTROL String
    - - Grantee 说明被授权者的信息,type 类型可以为 RootAccount、Subaccount。当 type 类型为 RootAccount 时,ID 中指定的是主账号,当 type 类型为 Subaccount 时,ID 中指定的是子账号 Object
    - - - DisplayName 用户的名称 String
    - - - ID 用户的 ID,格式:qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    如果是主账号,<OwnerUin>和<SubUin> 是同一个值
    String

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    - statusCode 请求返回的 HTTP 状态码,如200,204,403,404等 Number
    - headers 请求返回的头部信息 Object

    查询对象 ACL

    功能说明

    查询对象的访问控制列表。

    使用示例

    cos.getObjectAcl({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'ap-beijing',    /* 必须 */
        Key: 'picture.jpg',              /* 必须 */
    }, function(err, data) {
        console.log(err || data);
    });

    参数说明

    参数名 参数描述 类型 必填
    Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
    Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    - ACL Object 的 ACL 属性。枚举值:private、public-read、default Object
    - Owner 标识资源的所有者 Object
    - - ID Object 持有者 ID,格式为:qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    如果是主账号 ID,<OwnerUin>和<SubUin>是同一个值
    String
    - - DisplayName Object 持有者的名称 String
    - Grants 被授权者信息与权限信息列表 ObjectArray
    - - Permission 指明授予被授权者的权限信息,枚举值:READ、READ_ACP、WRITE_ACP、FULL_CONTROL String
    - - Grantee 说明被授权者的信息。type 类型可以为 RootAccount、Subaccount;当 type 类型为 RootAccount 时,ID 中指定的是主账号,当 type 类型为 Subaccount 时,ID 中指定的是子账号 Object
    - - - DisplayName 用户的名称 String
    - - - ID 用户的 ID,格式为:qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    如果是主账号 ID,<OwnerUin>和<SubUin>是同一个值
    String

    高级接口(推荐)

    该类方法是对上面原生方法的封装,实现了分块上传/复制的全过程,支持并发分块上传/复制,支持断点续传,支持上传任务的取消,暂停和重新开始等。

    分片上传对象

    功能说明

    Slice Upload File 可用于实现文件的分块上传,适用于大文件上传。

    使用示例

    cos.sliceUploadFile({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'ap-beijing',    /* 必须 */
        Key: '1.zip',              /* 必须 */
        FilePath: filePath,                /* 必须 */
        TaskReady: function(taskId) {                   /* 非必须 */
            console.log(taskId);
        },
        onHashProgress: function (progressData) {       /* 非必须 */
            console.log(JSON.stringify(progressData));
        },
        onProgress: function (progressData) {           /* 非必须 */
            console.log(JSON.stringify(progressData));
        }
    }, function(err, data) {
        console.log(err || data);
    });

    参数说明

    参数名 参数描述 类型 必填
    Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
    Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    FilePath 上传文件路径 String
    SliceSize 分块大小 String
    AsyncLimit 分块的并发量 String
    StorageClass Object 的存储级别,枚举值:STANDARD、STANDARD_IA String
    TaskReady 上传任务创建时的回调函数,返回一个 taskId,唯一标识上传任务,可用于上传任务的取消(cancelTask),停止(pauseTask)和重新开始(restartTask) Function
    - taskId 上传任务的编号 String
    onHashProgress 计算文件 MD5 值的进度回调函数,回调参数为进度对象 progressData Function
    - progressData.loaded 已经校验的文件部分大小,以字节(Bytes)为单位 Number
    - progressData.total 整个文件的大小,以字节(Bytes)为单位 Number
    - progressData.speed 文件的校验速度,以字节/秒(Bytes/s)为单位 Number
    - progressData.percent 文件的校验百分比,以小数形式呈现,例如:下载50%即为0.5 Number
    onProgress 上传文件的进度回调函数,回调参数为进度对象 progressData Function
    - progressData.loaded 已经上传的文件部分大小,以字节(Bytes)为单位 Number
    - progressData.total 整个文件的大小,以字节(Bytes)为单位 Number
    - progressData.speed 文件的上传速度,以字节/秒(Bytes/s)为单位 Number
    - progressData.percent 文件的上传百分比,以小数形式呈现,例如:下载50%即为0.5 Number

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    - Location 创建的 Object 的外网访问域名 String
    - Bucket 分块上传的目标 Bucket String
    - Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    - ETag 合并后文件的唯一 ID,格式:"uuid-<分块数>"
    例如"22ca88419e2ed4721c23807c678adbe4c08a7880-3"注意前后携带双引号
    String

    复制对象

    功能说明

    Slice Copy File 可用于实现通过分块复制将一个文件从源路径复制到目标路径。在拷贝的过程中,对象元属性和 ACL 可以被修改。用户可以通过该接口实现文件移动,文件重命名,修改文件属性和创建副本。

    方法原型

    调用 Slice Copy File 操作:

    cos.sliceCopyFile({
        Bucket: 'examplebucket-1250000000',                               /* 必须 */
        Region: 'ap-beijing',                                  /* 必须 */
        Key: '1.zip',                                            /* 必须 */
        CopySource: 'test.cos.ap-guangzhou.myqcloud.com/2.zip', /* 必须 */
        onProgress:function (progressData) {                     /* 非必须 */
            console.log(JSON.stringify(progressData));
        }
    },function (err,data) {
        console.log(err || data);
    });

    参数说明

    参数名 参数描述 类型 必填
    Bucket Bucket 的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region Bucket 所在地域,枚举值请参见 地域和访问域名 String
    Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    CopySource 源文件 URL 路径,可以通过 versionid 子资源指定历史版本 String
    ChunkSize 分片复制时,每片的大小字节数,默认值 1048576(1MB) Number
    SliceSize 使用分片复制的文件大小,默认值为5G Number
    onProgress 上传文件的进度回调函数,回调参数为进度对象 progressData Function
    - progressData.loaded 已经上传的文件部分大小,以字节(Bytes)为单位 Number
    - progressData.total 整个文件的大小,以字节(Bytes)为单位 Number
    - progressData.speed 文件的上传速度,以字节/秒(Bytes/s)为单位 Number
    - progressData.percent 文件的上传百分比,以小数形式呈现,例如:下载50%即为0.5 Number

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    - Location 创建的 Object 的外网访问域名 String
    - Bucket 分块上传的目标 Bucket String
    - Key 对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述 String
    - ETag 合并后文件的 MD5 算法校验值
    例如"22ca88419e2ed4721c23807c678adbe4c08a7880"注意前后携带双引号
    String

    批量上传

    功能说明

    方法一:
    批量上传可以直接多次调用 putObject 和 sliceUploadFile,达到批量上传效果。通过实例化参数 FileParallelLimit 控制文件并发数,默认3个并发。

    方法二:
    可以调用 cos.uploadFiles 实现批量上传,方法参数 SliceSize 可以控制文件。以下是 uploadFiles 方法说明。

    方法原型

    调用 uploadFiles 操作:

    cos.uploadFiles({
        files: [{
            Bucket: 'examplebucket-1250000000',
            Region: 'ap-beijing',
            Key: 'picture.jpg',
            FilePath: filePath1,
        }, {
            Bucket: 'examplebucket-1250000000',
            Region: 'ap-beijing',
            Key: '2.jpg',
            FilePath: filePath2,
        }],
        SliceSize: 1024 * 1024,
        onProgress: function (info) {
            var percent = parseInt(info.percent * 10000) / 100;
            var speed = parseInt(info.speed / 1024 / 1024 * 100) / 100;
            console.log('进度:' + percent + '%; 速度:' + speed + 'Mb/s;');
        },
        onFileFinish: function (err, data, options) {
            console.log(options.Key + '上传' + (err ? '失败' : '完成'));
        },
    }, function (err, data) {
        console.log(err || data);
    });

    参数说明

    参数名 参数描述 类型 必填
    files 文件列表,每一项是传给 putObject 和 sliceUploadFile 的参数对象 Object
    SliceSize 文件大小多大以上使用分片上传,单位 B,小于等于改数值会使用 putObject 上传,大于该数值会使用 sliceUploadFile 上传 Nunber
    onProgress 所有任务 进度汇总计算出来的上传进度 String
    - progressData.loaded 已经上传的文件部分大小,以字节(Bytes)为单位 Number
    - progressData.total 整个文件的大小,以字节(Bytes)为单位 Number
    - progressData.speed 文件的上传速度,以字节/秒(Bytes/s)为单位 Number
    - progressData.percent 文件的上传百分比,以小数形式呈现,例如:下载50%即为0.5 Number
    onFileFinish 每个文件完成或错误回调 String
    - err 上传的错误信息 Object
    - data 文件完成的信息 Object
    - options 当前完成文件的参数信息 Object

    回调函数说明

    function(err, data) { ... }
    参数名 参数描述 类型
    err 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 Object
    - statusCode 请求返回的 HTTP 状态码,如200、403、404等 Number
    - headers 请求返回的头部信息 Object
    data 请求成功时返回的对象,如果请求发生错误,则为空 Object
    - files 每个文件的 error 或 data ObjectArray
    - - err 上传的错误信息 Object
    - - data 文件完成的信息 Object
    - - options 当前完成文件的参数信息 Object

    上传队列

    JavaScript SDK 针对 putObject 和 sliceUploadFile 发起的上传任务都有记录队列里,队列相关方法如下。

    1. cos.getTaskList 可以获取任务列表。
    2. cos.pauseTask、cos.restartTask、cos.cancelTask 操作任务。
    3. cos.on('list-update', callback); 可以监听列表和进度变化。

    完整的队列使用示例请参见 demo-queue

    取消上传任务

    根据 taskId 取消上传任务。

    使用示例

    var taskId = 'xxxxx';                   /* 必须 */
    cos.cancelTask(taskId);

    参数说明

    参数名 参数描述 类型 必填
    taskId 文件上传任务的编号,在调用 sliceUploadFile 方法时,其 TaskReady 回调会返回该上传任务的 taskId String

    暂停上传任务

    根据 taskId 暂停上传任务。

    使用示例

    var taskId = 'xxxxx';                   /* 必须 */
    cos.pauseTask(taskId);

    参数说明

    参数名 参数描述 类型 必填
    taskId 文件上传任务的编号,在调用 sliceUploadFile 方法时,其 TaskReady 回调会返回该上传任务的 taskId String

    重启上传任务

    根据 taskId 重新开始上传任务,可以用于开启用户手动停止的(调用 pauseTask 停止)或者因为上传错误而停止的上传任务。

    使用示例

    var taskId = 'xxxxx';                   /* 必须 */
    cos.restartTask(taskId);

    参数说明

    参数名 参数描述 类型 必填
    taskId 文件上传任务的编号,在调用 sliceUploadFile 方法时,其 TaskReady 回调会返回该上传任务的 taskId String