对象操作

最近更新时间:2019-07-19 16:06:40

简介

本文档重点提供关于对象的简单操作、其他操作相关的 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 操作名 操作描述
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 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
Region 存储桶所在地域,枚举值请参见 地域和访问域名 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 对象名称 String
    - - LastModified 说明 Object 最后被修改时间,例如2017-06-23T12:33:27.000Z String
    - - Owner Bucket 持有者信息 Object
    - ID Bucket 的 AppID String
    - StorageClass 对象的存储类型,枚举值:STANDARD、STANDARD_IA、ARCHIVE String

    简单上传对象

    功能说明

    PUT Object 接口请求可以上传一个对象至存储桶。该操作需要请求者对 Bucket 有 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',              /* 必须 */
        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 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region 存储桶所在地域枚举值请参见 地域和访问域名 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 设置对象的存储类型,枚举值:STANDARD、STANDARD_IA、ARCHIVE,默认值:STANDARD String
    x-cos-meta-* 允许用户自定义的头部信息,将作为 Object 元数据返回。大小限制2K String
    Body 创建的文件的文本内容,可以为字符串 String
    onProgress 进度回调函数,被调用时第一个参数是 processData 对象 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 在上传过程中是否有损坏,
    注意:这里的 ETag 值字符串前后带有双引号,例如"09cba091df696af91549de27b8e7d0f6"
    String

    表单上传对象

    POST Object 接口请求可以将用户 wx.chooseImage 选择的文件(Object)上传至指定 Bucket 中。该操作需要请求者对 Bucket 有 WRITE 权限。

    使用示例

    简单上传文件

    cos.postObject({
        Bucket: 'examplebucket-1250000000',
        Region: 'ap-beijing',
        Key: filename,
        FilePath: tmpFilePath, // wx.chooseImage 选择文件得到的 tmpFilePath
        onProgress: function (info) {
            console.log(JSON.stringify(info));
        }
    }, function (err, data) {
        console.log(err || data);
    });
    

    参数说明

    参数名 参数描述 类型 必填
    Bucket 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region 存储桶所在地域,枚举值请参见 地域和访问域名 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
    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 设置 对象的存储类型,枚举值:STANDARD、STANDARD_IA、ARCHIVE,默认值:STANDARD String
    x-cos-meta-* 允许用户自定义的头部信息,将作为 Object 元数据返回,大小限制2K String
    FilePath 上传文件的临时文件路径,可通过 wx.chooseImage 方法选择得到 String
    onProgress 进度回调函数,被调用时第一个参数是 processData 对象 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 在上传过程中是否有损坏,
    注意:这里的 ETag 值字符串前后带有双引号,例如"09cba091df696af91549de27b8e7d0f6"
    String

    查询对象元数据

    功能说明

    查询对象的元数据信息。

    使用示例

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

    参数说明

    参数名 参数描述 类型 必填
    Bucket 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region 存储桶所在地域,枚举值请参见 地域和访问域名 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 对象的存储类型,枚举值:STANDARD、STANDARD_IA、ARCHIVE String
    - x-cos-meta-* 用户自定义的 meta String
    - NotModified Object 是否在指定时间后未被修改 Boolean

    下载对象

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

    说明:

    该接口是读取文件内容到 JS 变量,如果需要发起浏览器下载文件,可以通过 cos.getObjectUrl 获取 url 再触发浏览器下载,详情请参见 预签名 URL 文档。

    使用示例

    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);
    });

    参数说明

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

    删除单个对象

    功能说明

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

    使用示例

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

    参数说明

    参数名 参数描述 类型 必填
    Bucket 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region 存储桶所在地域,枚举值请参见 地域和访问域名 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

    删除多个对象

    功能说明

    DELETE Multiple Objects 接口请求实现在存储桶中批量删除对象,单次请求最大支持批量删除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 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region 存储桶所在地域,枚举值请参见 地域和访问域名 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

    其他操作

    恢复归档对象

    功能说明

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

    使用示例

    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 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region 存储桶所在地域,枚举值请参见 地域和访问域名 String
    Key 对象键(对象的名称),对象在存储桶中的唯一标识,详情请参见 对象键说明 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 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region 存储桶所在地域,枚举值请参见 地域和访问域名 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

    功能说明

    查询对象的访问控制列表。只有 Bucket 的持有者才有权限操作。

    使用示例

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

    参数说明

    参数名 参数描述 类型 必填
    Bucket 存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式 String
    Region 存储桶所在地域,枚举值请参见 地域和访问域名 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

    高级接口

    上传队列

    小程序 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