Tencent Cloud

Recent Pages

上传对象

最后更新时间：2024-01-22 11:32:01
简介
本文档重点提供关于对象的简单操作、其他操作相关的 API 概览以及 SDK 示例代码，并且举例如何使用。
说明
 常见上传错误排查，请参考 常见问题。
简单操作
API
操作名
操作描述
PUT Object
简单上传对象
上传一个对象至存储桶
Append Object
追加上传对象
将对象以分块追加的方式上传至存储桶
POST Object
表单上传对象
使用表单请求上传对象
分块操作
API
操作名
操作描述
List Multipart Uploads
查询分块上传
查询正在进行中的分块上传信息
Initiate Multipart Upload
初始化分块上传
初始化分块上传任务
Upload Part
上传分块
分块上传对象
List Parts
查询已上传块
查询特定分块上传操作中已上传的块
Complete Multipart Upload
完成分块上传
完成整个对象的分块上传
Abort Multipart Upload
终止分块上传
终止一个分块上传操作并删除已上传的块
简单操作
简单上传对象
功能说明
PUT Object 接口可以上传一个对象至指定存储桶中。该操作需要请求者对存储桶有 WRITE 权限。
注意
1. Key（文件名）不能以/结尾，否则会被识别为文件夹。
2. Key（文件名）同名上传默认为覆盖操作。若您未开启版本控制且不想覆盖云上文件时，请确保上传时的Key不重复。
3. 每个主账号（即同一个 APPID），存储桶的 ACL 规则数量最多为1000条，对象 ACL 规则数量不限制。如果您不需要进行对象 ACL 控制，请在上传时不要设置，默认继承存储桶权限。
4. 上传之后，您可以用同样的 Key 生成预签名链接（下载请指定 method 为 GET，具体接口说明见下文，分享到其他端来进行下载。但注意如果您的文件是私有读权限，那么预签名链接只有一定的有效期。
使用示例
选择文件并上传(使用Body参数):
// 此处以选择图片api(wx.chooseImage)为参考，其他api请参考小程序官方文档
wx.chooseImage({
    count: 1,
    success: function(res) {
        var file = res.tempFiles[0];
        // 微信小程序里获取文件管理器
        var wxfs = wx.getFileSystemManager();
        wxfs.readFile({
            filePath: file.path,
            success: function (res) {
                cos.putObject({
                    Bucket: config.Bucket,
                    Region: config.Region,
                    Key: file.name,
                    Body: res.data, // Body里传入的是文件内容
                }, function(err, data) {
                    console.log(err || data);
                });
            },
            fail: function(err) {
              console.error(err)
            },
        });
    },
    fail: function(err) {
      console.error(err)
    },
});
选择文件并上传(使用FilePath参数 需要sdk版本至少达到v1.3.0):
// 此处以选择图片api(wx.chooseImage)为参考，其他api请参考小程序官方文档
wx.chooseImage({
    count: 1,
    success: function(res) {
        var file = res.tempFiles[0];
        cos.putObject({
            Bucket: config.Bucket,
            Region: config.Region,
            Key: file.name,
            FilePath: file.path,  // FilePath传入的是文件路径
        }, function(err, data) {
            console.log(err || data);
        });
    },
    fail: function(err) {
      console.error(err)
    },
});
传字符串作为文件内容：
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);
});
上传对象（单链接限速）：
说明
关于上传对象的限速说明，请参见 单链接限速。
cos.putObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'COS_REGION',     /* 存储桶所在地域，必须字段 */
    Key: 'exampleobject',              /* 必须 */
    StorageClass: 'STANDARD',
    Body: 'hello!', // 上传文件对象,字符串或选择的文件
    Headers: {
      'x-cos-traffic-limit': 819200, // 限速值设置范围为819200 - 838860800，即100KB/s - 100MB/s，如果超出该范围将返回400错误。
    },
    onProgress: function(progressData) {
        console.log(JSON.stringify(progressData));
    }
}, function(err, data) {
    console.log(err || data);
});
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域枚举值请参见 地域和访问域名
String
是
Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
是
Body
创建的文件的文本内容，可以为字符串、ArrayBuffer
String\\ArrayBuffer
是
CacheControl
RFC 2616中定义的缓存策略，将作为对象的元数据保存
String
否
ContentDisposition
RFC 2616中定义的文件名称，将作为对象的元数据保存
String
否
ContentEncoding
RFC 2616中定义的编码格式，将作为对象的元数据保存
String
否
ContentLength
RFC 2616中定义的 HTTP 请求内容长度（字节）
String
否
ContentType
RFC 2616中定义的内容类型（MIME），将作为对象的元数据保存
String
否
Expires
RFC 2616中定义的过期时间，将作为对象的元数据保存
String
否
Expect
当使用 Expect: 100-continue 时，在收到服务端确认后，才会发送请求内容
String
否
ACL
定义对象的访问控制列表（ACL）属性，枚举值请参见 ACL 概述 文档中对象的预设 ACL 部分，例如 default，private，public-read 等 
注意：如果您不需要进行对象 ACL 控制，请设置为 default 或者此项不进行设置，默认继承存储桶权限
String
否
GrantRead
赋予被授权者读取对象的权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账户授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantReadAcp
赋予被授权者读取对象的访问控制列表（ACL）的权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账户授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantWriteAcp
赋予被授权者写入对象的访问控制列表（ACL）的权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账户授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantFullControl
赋予被授权者操作对象的所有权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账户授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
StorageClass
设置对象的存储类型，枚举值：STANDARD、STANDARD_IA、ARCHIVE，默认值：STANDARD。更多存储类型，请参见 存储类型概述
String
否
x-cos-meta-*
允许用户自定义的头部信息，将作为对象的元数据保存。大小限制2KB
String
否
onTaskReady
上传任务创建时的回调函数，返回一个 taskId，唯一标识上传任务，可用于上传任务的取消（cancelTask），停止（pauseTask）和重新开始（restartTask）
Function
否
- taskId
上传任务的编号
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 的值可以用于检查对象在上传过程中是否有损坏
例如"09cba091df696af91549de27b8e7d0f6"，注意：这里的 ETag 值字符串前后带有双引号
String
- Location
创建对象的外网访问域名
String
- VersionId
在开启过版本控制的存储桶中上传对象返回对象的版本 ID，存储桶从未开启则不返回该参数
String
追加上传对象
功能说明
将对象以分块追加的方式上传至存储桶（APPEND Object）。
注意
COS 小程序 SDK 版本需要大于等于 v1.1.1。
对象属性为 appendable 时才能使用本接口追加上传。
对象首次使用 APPEND Object 接口上传时，该对象的属性自动为 appendable。
可以使用 GET Object 或 HEAD Object 接口获取 x-cos-object-type 响应头来判断对象属性。
使用示例
初次追加上传对象:
cos.appendObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'COS_REGION',     /* 存储桶所在地域，必须字段 */
    Key: 'test.txt',              /* 必须 */
    Body: fileObject, // 上传文件对象
    Position: 0, // 初次上传为0
}, function(err, data) {
    console.log(err || data);
});
判断存储桶内的对象是否可追加对象:
cos.headObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'COS_REGION',     /* 存储桶所在地域，必须字段 */
    Key: 'test.txt',              /* 必须 */
}, function(err, data) {
    if (err) return console.log(err);
    // data.headers没有x-cos-object-type字段需要配置expose-headers，参考文档：https://www.tencentcloud.com/document/product/436/13318?from_cn_redirect=1
    var objectType = data.headers['x-cos-object-type'];
    console.log(objectType === 'appendable');
});
查询可追加对象的Position并追加上传:
cos.headObject({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'COS_REGION',     /* 存储桶所在地域，必须字段 */
    Key: 'test.txt',              /* 必须 */
}, function(err, data) {
    if (err) return console.log(err);
    // 首先取到要追加的文件当前长度，即需要上送的Position
    var position = data.headers['content-length'];
    cos.appendObject({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'COS_REGION',     /* 存储桶所在地域，必须字段 */
        Key: 'test.txt',              /* 必须 */
        Body: '66666',
        Position: position,
    },
    function(err, data) {
        if (err) return console.log(err);
        // 也可以取到下一次上传的position继续追加上传
        // data.headers没有x-cos-next-append-position字段需要配置expose-headers，参考文档：https://www.tencentcloud.com/document/product/436/13318?from_cn_redirect=1
        var nextPosition = data.headers['x-cos-next-append-position'];
        console.log(nextPosition);
    })
});
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
是
Body
创建的文件的文本内容，可以为字符串
String\\ArrayBuffer
是
Position
追加操作的起始点，单位为字节。首次追加则设置 Position=0，后续追加则设置 Position 为当前 Object 的 content-length
Number
是
CacheControl
RFC 2616中定义的缓存策略，将作为对象的元数据保存
String
否
ContentDisposition
RFC 2616中定义的文件名称，将作为对象的元数据保存
String
否
ContentEncoding
RFC 2616中定义的编码格式，将作为对象的元数据保存
String
否
ContentLength
RFC 2616中定义的 HTTP 请求内容长度（字节）
String
否
ContentType
RFC 2616中定义的内容类型（MIME），将作为对象的元数据保存
String
否
Expires
RFC 2616中定义的过期时间，将作为对象的元数据保存
String
否
Expect
当使用 Expect: 100-continue 时，在收到服务端确认后，才会发送请求内容
String
否
ACL
定义对象的访问控制列表（ACL）属性，枚举值请参见 ACL 概述 文档中对象的预设 ACL 部分，例如 default，private，public-read 等
注意：如果您不需要进行对象 ACL 控制，请设置为 default 或者此项不进行设置，默认继承存储桶权限
String
否
GrantRead
赋予被授权者读取对象的权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账户授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantReadAcp
赋予被授权者读取对象的访问控制列表（ACL）的权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账户授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantWriteAcp
赋予被授权者写入对象的访问控制列表（ACL）的权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账户授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantFullControl
赋予被授权者操作对象的所有权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账户授权时，id="qcs::cam::uin/OwnerUin:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
StorageClass
设置对象的存储类型，枚举值：STANDARD、STANDARD_IA、ARCHIVE、DEEP_ARCHIVE 等，默认值：STANDARD。更多存储类型请参见 存储类型概述
String
否
x-cos-meta-*
允许用户自定义的头部信息，将作为对象的元数据保存。大小限制2KB
String
否
回调函数说明
function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象，包括网络错误和业务错误。如果请求成功则为空，更多详情请参见 错误码
Object
- statusCode
请求返回的 HTTP 状态码，例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象，如果请求发生错误，则为空
Object
- statusCode
请求返回的 HTTP 状态码，例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- RequestId
请求的唯一 ID
String
表单上传对象
POST Object 接口请求可以将用户 wx.chooseImage 选择的文件对象（Object）上传至指定存储桶中。该操作需要请求者对存储桶有 WRITE 权限。
注意
 onProgress 进度反馈依赖小程序 UploadTask.onProgressUpdate，在部分安卓机型上会有进度不准确的问题。
使用示例
简单上传文件
cos.postObject({
    Bucket: 'examplebucket-1250000000',
    Region: 'ap-beijing',
    Key: filename,
    FilePath: tmpFilePath, // wx.chooseImage 选择文件得到的 tmpFilePath
    onProgress: function(progressData) {
        console.log(JSON.stringify(progressData));
    }
}, function (err, data) {
    console.log(err || data);
});
上传文件到指定目录：
var folder = 'examplefolder/';
cos.postObject({
    Bucket: 'examplebucket-1250000000',
    Region: 'ap-beijing',
    Key: folder + filename,              /* 必须 */
    FilePath: tmpFilePath, // wx.chooseImage 选择文件得到的 tmpFilePath
    onProgress: function(progressData) {
        console.log(JSON.stringify(progressData));
    }
}, function(err, data) {
    console.log(err || data);
});
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
是
ContentLength
RFC 2616中定义的 HTTP 请求内容长度（字节）
String
是
CacheControl
RFC 2616中定义的缓存策略，将作为对象的元数据保存
String
否
ContentDisposition
RFC 2616中定义的文件名称，将作为对象的元数据保存
String
否
ContentEncoding
RFC 2616中定义的编码格式，将作为对象的元数据保存
String
否
ContentType
RFC 2616中定义的内容类型（MIME），将作为对象的元数据保存
String
否
Expires
RFC 2616中定义的过期时间，将作为对象的元数据保存
String
否
Expect
当使用 Expect: 100-continue 时，在收到服务端确认后，才会发送请求内容
String
否
ACL
定义对象的访问控制列表（ACL）属性，枚举值请参见 ACL 概述 文档中对象的预设 ACL 部分，如 default，private，public-read 等
注意：如果您不需要进行对象 ACL 控制，请设置为 default 或者此项不进行设置，默认继承存储桶权限
String
否
StorageClass
设置对象的存储类型，枚举值：STANDARD、STANDARD_IA、ARCHIVE，默认值：STANDARD。更多存储类型，请参见 存储类型概述
String
否
x-cos-meta-*
允许用户自定义的头部信息，将作为对象的元数据保存，大小限制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
- Location
返回创建对象的外网访问域名
String
- VersionId
在启用版本控制的存储桶中，返回对象的版本 ID
String
分块操作
查询分块上传
功能说明
List Multiparts Uploads 用来查询正在进行中的分块上传信息。单次最多列出1000个正在进行中的分块上传。
使用示例
获取前缀为 exampleobject 的未完成的 UploadId 列表，示例如下：
cos.multipartList({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'COS_REGION',    /* 必须 */
    Prefix: 'exampleobject',                        /* 非必须 */
}, function(err, data) {
    console.log(err || data);
});
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
Prefix
对象键前缀匹配，限定返回中只包含指定前缀的对象键。注意使用 prefix 查询时，返回的对象键 中仍会包含 Prefix
String
否
Delimiter
定界符为一个分隔符号，用于对对象键进行分组。一般是传/。所有对象键从 Prefix 或从头（如未指定 Prefix）到首个 delimiter 之间相同部分的路径归为一类，定义为 Common Prefix，然后列出所有 Common Prefix
String
否
EncodingType
规定返回值的编码格式，合法值：url
String
否
MaxUploads
设置最大返回的条目数量，合法取值为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
分块上传的目标存储桶
String
- Encoding-Type
规定返回值的编码格式，合法值：url
String
- KeyMarker
列出条目从该 key 值开始
String
- UploadIdMarker
列出条目从该 UploadId 值开始
String
- NextKeyMarker
假如返回条目被截断，则返回 NextKeyMarker 就是下一个条目的起点
String
- NextUploadIdMarker
假如返回条目被截断，则返回 UploadId 就是下一个条目的起点
String
- MaxUploads
设置最大返回的条目数量，合法取值范围为1 - 1000
String
- IsTruncated
返回条目是否被截断，'true' 或者 'false'
String
- Prefix
对象键前缀匹配，限定返回中只包含指定前缀的对象键。
String
- Delimiter
定界符为一个分隔符号，用于对对象键进行分组。一般是传/。所有对象键从 Prefix 或从头（如未指定 Prefix）到首个 delimiter 之间相同部分的路径归为一类，定义为 Common Prefix，然后列出所有 Common Prefix
String
- CommonPrefixs
将 prefix 到 delimiter 之间的相同路径归为一类，定义为 Common Prefix
ObjectArray
- - Prefix
显示具体的 Common Prefixs
String
- Upload
分块上传的信息集合
ObjectArray
- - Key
对象的名称，即对象键
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
分块持有者的名称
String
- - - ID
分块持有者 ID，格式：qcs::cam::uin/<OwnerUin>:uin/<SubUin>
如果是主账号，<OwnerUin> 和 <SubUin> 是同一个值
String
- - Initiated
分块上传的起始时间
String
初始化分块上传
功能说明
Initiate Multipart Uploads 请求实现初始化分块上传，成功执行此请求后会返回 Upload ID ，用于后续的 Upload Part 请求。
使用示例
cos.multipartInit({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'COS_REGION',    /* 必须 */
    Key: 'exampleobject',              /* 必须 */
}, function(err, data) {
    console.log(err || data);
    if (data) {
      uploadId = data.UploadId;
    }
});
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
是
CacheControl
RFC 2616 中定义的缓存策略，将作为对象的元数据保存
String
否
ContentDisposition
RFC 2616 中定义的文件名称，将作为对象的元数据保存
String
否
ContentEncoding
RFC 2616 中定义的编码格式，将作为对象的元数据保存
String
否
ContentType
RFC 2616 中定义的内容类型（MIME），将作为对象的元数据保存
String
否
Expires
RFC 2616 中定义的过期时间，将作为对象的元数据保存
String
否
ACL
定义对象的访问控制列表（ACL）属性，枚举值请参见 ACL 概述 文档中对象的预设 ACL 部分，如 default，private，public-read 等 
注意：如果您不需要进行对象 ACL 控制，请设置为 default 或者此项不进行设置，默认继承存储桶权限
String
否
GrantRead
赋予被授权者读取对象的权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantFullControl
赋予被授权者操作对象的所有权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
StorageClass
设置对象的存储类型，枚举值：STANDARD、STANDARD_IA、ARCHIVE 等，更多存储类型请参见 存储类型概述 文档。默认值：STANDARD
String
否
x-cos-meta-*
允许用户自定义的头部信息，将作为对象的元数据返回。大小限制2KB
String
否
回调函数说明
function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象，包括网络错误和业务错误，如果请求成功则为空，更多详情请参见 错误码 文档
Object
data
请求成功时返回的对象，如果请求发生错误，则为空
Object
Bucket
分块上传的目标存储桶，格式为 BucketName-APPID，例如 examplebucket-1250000000
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: 'COS_REGION',     /* 存储桶所在地域，必须字段 */
   Key: 'exampleobject',       /* 必须 */
   UploadId: 'exampleUploadId',
   PartNumber: 1,
   Body: fileObject
}, function(err, data) {
   console.log(err || data);
   if (data) {
     eTag = data.ETag;
   }
});
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
是
ContentLength
RFC 2616中定义的 HTTP 请求内容长度（字节）
String
是
PartNumber
分块的编号
Number
是
UploadId
本次分块上传任务的编号
String
是
Body
上传文件分块的内容，可以为字符串或者 ArrayBuffer 对象
String/ArrayBuffer
是
Expect
RFC 2616 中定义的 HTTP 请求内容长度（字节）。当使用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
查询已上传块
功能说明
List Parts 用来查询特定分块上传中的已上传的块，即列出指定 UploadId 所属的所有已上传成功的分块。
使用示例
cos.multipartListPart({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'COS_REGION',    /* 必须 */
    Key: 'exampleobject',              /* 必须 */
    UploadId: 'exampleUploadId',                      /* 必须 */
}, function(err, data) {
    console.log(err || data);
});
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
是
UploadId
标识本次分块上传的 ID，使用 Initiate Multipart Upload 接口初始化分块上传时得到的 UploadId
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
分块上传的目标存储桶
String
- Encoding-type
规定返回值的编码方式
String
- Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
- UploadId
标识本次分块上传的 ID，使用 Initiate Multipart Upload 接口初始化分块上传时得到的 UploadId
String
- Initiator
用来表示本次上传发起者的信息
Object
- - DisplayName
上传发起者的名称
String
- - ID
上传发起者 ID，格式：qcs::cam::uin/<OwnerUin>:uin/<SubUin>
如果是主账号，<OwnerUin> 和 <SubUin> 是同一个值
String
- Owner
用来表示这些分块所有者的信息
Object
- - DisplayName
存储桶持有者的名称
String
- - ID
存储桶持有者 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: 'COS_REGION',    /* 必须 */
    Key: 'exampleobject',              /* 必须 */
    UploadId: 'exampleUploadId', /* 必须 */
    Parts: [
        {PartNumber: 1, ETag: 'exampleETag'},
    ]
}, function(err, data) {
    console.log(err || data);
});
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
是
UploadId
上传任务编号
String
是
Parts
用来说明本次分块上传中块的信息列表
ObjectArray
是
- PartNumber
分块的编号
Number
是
- 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
创建对象的外网访问域名
String
- Bucket
分块上传的目标存储桶
String
- Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
- ETag
合并后文件的唯一 ID，格式："uuid-<分块数>"
例如"22ca88419e2ed4721c23807c678adbe4c08a7880-3"，注意前后携带双引号
String
终止分块上传
功能说明
Abort Multipart Upload 用来实现终止一个分块上传操作并删除已上传的块。当您调用 Abort Multipart Upload 时，如果有正在使用这个 UploadId 上传块的请求，则 Upload Parts 会返回失败。当该 UploadId 不存在时，会返回404 NoSuchUpload。
注意
建议您及时完成分块上传或者舍弃分块上传，因为已上传但是未终止的块会占用存储空间进而产生存储费用。
使用示例
cos.multipartAbort({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'COS_REGION',    /* 必须 */
    Key: 'exampleobject',                           /* 必须 */
    UploadId: 'exampleUploadId'                       /* 必须 */
}, function(err, data) {
    console.log(err || data);
});
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
是
UploadId
标识本次分块上传的 ID，使用 Initiate Multipart Upload 接口初始化分块上传时得到的 UploadId
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 File 实现高级上传，传入参数 SliceSize 可以控制文件大小超出一个数值（默认1MB）时自动使用分块上传，否则使用简单上传。
使用示例
var uploadFile = function(file) {
    cos.uploadFile({
        Bucket: 'examplebucket-1250000000', /* 必须 */
        Region: 'COS_REGION',     /* 存储桶所在地域，必须字段 */
        Key: file.name,              /* 必须 */
        FilePath: file.path,                /* 必须 */
        FileSize: file.size,                 /* v1.4.3之前的版本必须，v1.4.3及以后的版本非必须 */
        SliceSize: 1024 * 1024 * 5,     /* 触发分块上传的阈值，超过5MB使用分块上传，非必须，按需调整，最小支持1MB */
        onTaskReady: function(taskId) {                   /* 非必须 */
            console.log(taskId);
        },
        onProgress: function (progressData) {           /* 非必须 */
            console.log(JSON.stringify(progressData));
        },
        onFileFinish: function (err, data, options) {   /* 非必须 */
          console.log(options.Key + '上传' + (err ? '失败' : '完成'));
        },
    }, function(err, data) {
        console.log(err || data);
    });
}
﻿
wx.chooseMessageFile({
   count: 10,
   type: 'all',
   success: function(res) {
       uploadFile(res.tempFiles[0]);
   }
});
参数说明
参数名                                
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
是
FilePath
上传文件路径
String
是
FileSize
上传文件大小(v1.4.3之前的版本必须，v1.4.3及以后的版本非必须)
Number
是
SliceSize
表示文件大小超出一个数值时使用分块上传，单位 Byte，默认值1048576（1MB），小于等于该数值会使用 putObject 上传，大于该数值会使用 sliceUploadFile 上传
Number
否
AsyncLimit
分块的并发量，仅在触发分块上传时有效
Number
否
StorageClass
对象的存储类型，枚举值：STANDARD、STANDARD_IA、ARCHIVE、DEEP_ARCHIVE 等，更多存储类型请参见 存储类型概述
String
否
UploadAddMetaMd5
当上传时，给对象的元数据信息增加 x-cos-meta-md5 赋值为对象内容的 MD5 值，格式为 32 位小写字符串。例如：4d00d79b6733c9cc066584a02ed03410
String
否
CacheControl
RFC 2616中定义的缓存策略，将作为对象的元数据保存
String
否
ContentDisposition
RFC 2616中定义的文件名称，将作为对象的元数据保存
String
否
ContentEncoding
RFC 2616中定义的编码格式，将作为对象的元数据保存
String
否
ContentLength
RFC 2616中定义的 HTTP 请求内容长度（字节）
String
否
ContentType
RFC 2616中定义的内容类型（MIME），将作为对象的元数据保存
String
否
Expires
RFC 2616中定义的过期时间，将作为对象的元数据保存
String
否
Expect
当使用 Expect: 100-continue 时，在收到服务端确认后，才会发送请求内容
String
否
onTaskReady
上传任务创建时的回调函数，返回一个 taskId，唯一标识上传任务，可用于上传任务的取消（cancelTask），停止（pauseTask）和重新开始（restartTask）
Function
否
- taskId
上传任务的编号
String
否
onProgress
上传文件的进度回调函数，回调参数为进度对象 progressData
Function
否
- progressData.loaded
已经上传的文件部分大小，以字节（Bytes）为单位
Number
否
- progressData.total
整个文件的大小，以字节（Bytes）为单位
Number
否
- progressData.speed
文件的上传速度，以字节/秒（Bytes/s）为单位
Number
否
- progressData.percent
文件的上传百分比，以小数形式呈现，例如，上传50%即为0.5
Number
否
onFileFinish
每个文件完成或错误回调
Function
否
- err
上传的错误信息
Object
否
- data
文件完成的信息
Object
否
- options
当前完成文件的参数信息
Object
否
回调函数说明
function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象，包括网络错误和业务错误。如果请求成功则为空，更多详情请参见 错误码
Object
- statusCode
请求返回的 HTTP 状态码，例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象，如果请求发生错误，则为空
Object
- statusCode
请求返回的 HTTP 状态码，例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- Location
上传完的文件访问地址
String
- Bucket
分块上传的目标存储桶,仅在触发分块上传时返回
String
- Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述，仅在触发分块上传时返回
String
- ETag
合并后文件的唯一 ID，格式："uuid-<分块数>"
例如"22ca88419e2ed4721c23807c678adbe4c08a7880-3"，注意前后携带双引号
String
- VersionId
在开启过版本控制的存储桶中上传对象返回对象的版本 ID，存储桶从未开启则不返回该参数
String
分块上传对象（断点续传）
功能说明
Slice Upload File 可用于实现文件的分块上传，适用于大文件上传。
使用示例
var sliceUploadFile = function (file) {
    var key = file.name;
    cos.sliceUploadFile({
        Bucket: 'examplebucket-1250000000',         /* 必须 */
        Region: 'COS_REGION',                       /* 必须 */
        Key: 'exampleobject',                       /* 必须 */
        FilePath: file.path,                        /* 必须 */
        FileSize: file.size,                        /* 非必须 */
        CacheControl: 'max-age=7200',               /* 非必须 */
        Headers: {                                  /* 非必须 */
            aa: 123,
        },
        Query: {                                     /* 非必须 */
            bb: 123,
        },
        onTaskReady: function(taskId) {              /* 非必须 */
            console.log(taskId);
        },
        onHashProgress: function(info) {             /* 非必须 */
            console.log('check hash', JSON.stringify(info));
        },
        onProgress: function(info) {                 /* 非必须 */
            console.log(JSON.stringify(info));
        }
    }, requestCallback);
};
wx.chooseMessageFile({
    count: 10,
    type: 'all',
    success: function(res) {
        sliceUploadFile(res.tempFiles[0]);
    }
});
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
是
FilePath
上传文件路径
String
是
SliceSize
分块大小
Number
否
AsyncLimit
分块的并发量，仅在触发分块上传时有效
Number
否
StorageClass
对象的存储类型，枚举值：STANDARD、STANDARD_IA、ARCHIVE 等，更多存储类型请参见 存储类型概述 文档
String
否
CacheControl
RFC 2616中定义的缓存策略，将作为对象的元数据保存
String
否
ContentDisposition
RFC 2616中定义的文件名称，将作为对象的元数据保存
String
否
ContentEncoding
RFC 2616中定义的编码格式，将作为对象的元数据保存
String
否
ContentLength
RFC 2616中定义的 HTTP 请求内容长度（字节）
String
否
ContentType
RFC 2616中定义的内容类型（MIME），将作为对象的元数据保存
String
否
Expires
RFC 2616中定义的过期时间，将作为对象的元数据保存
String
否
Expect
当使用 Expect: 100-continue 时，在收到服务端确认后，才会发送请求内容
String
否
onTaskReady
上传任务创建时的回调函数，返回一个 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
创建对象的外网访问域名
String
- Bucket
分块上传的目标存储桶
String
- Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
- ETag
合并后文件的唯一 ID，格式："uuid-<分块数>"
例如"22ca88419e2ed4721c23807c678adbe4c08a7880-3"，注意前后携带双引号
String
- VersionId
在开启过版本控制的存储桶中上传对象返回对象的版本 ID，存储桶从未开启则不返回该参数
String
批量上传
功能说明
方法一：
批量上传可以直接多次调用 putObject 和 sliceUploadFile，达到批量上传效果。通过实例化参数 FileParallelLimit 控制文件并发数，默认3个并发。
方法二：
可以调用 cos.uploadFiles 实现批量上传，传入参数 SliceSize 可以控制文件大小超出一个数值时使用分块上传。以下是 uploadFiles 方法说明。
方法原型
调用 uploadFiles 操作：
var uploadFiles = function(files) {
    var fileList = files.map(function(file) {
        return Object.assign(file, {  
            FilePath: file.path, /* 必须 */
            FileSize: file.size, /* v1.4.3之前的版本必须，v1.4.3及以后的版本非必须 */
            Bucket: 'examplebucket-1250000000', /* 必须 */
            Region: 'COS_REGION',/* 存储桶所在地域，必须字段 */
            Key: file.name, /* 必须 */
            onTaskReady: function(taskId) {
              /* taskId可通过队列操作来取消上传cos.cancelTask(taskId)、停止上传cos.pauseTask(taskId)、重新开始上传cos.restartTask(taskId) */
              console.log(taskId);
            }
        });
    });
    cos.uploadFiles({
        files: fileList,
        SliceSize: 1024 * 1024 * 10,    /* 设置大于10MB采用分块上传，按需调整，最小支持1MB */
        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);
    });
}
wx.chooseMessageFile({
    count: 10,
    type: 'all',
    success: function(res) {
        uploadFiles(res.tempFiles);
    }
});
参数说明
参数名
参数描述
类型
是否必填
files
文件列表，每一项是传给 putObject 和 sliceUploadFile 的参数对象
Object
是
- Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
- Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
- Key
对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见 对象概述
String
是
- FilePath
上传文件路径
String
是
- FileSize
上传文件大小(v1.4.3之前的版本必须，v1.4.3及以后的版本非必须)
Number
是
- CacheControl
RFC 2616中定义的缓存策略，将作为对象的元数据保存
String
否
- ContentDisposition
RFC 2616中定义的文件名称，将作为对象的元数据保存
String
否
- ContentEncoding
RFC 2616中定义的编码格式，将作为对象的元数据保存
String
否
- ContentLength
RFC 2616中定义的 HTTP 请求内容长度（字节）
String
否
- ContentType
RFC 2616中定义的内容类型（MIME），将作为对象的元数据保存
String
否
- Expires
RFC 2616中定义的过期时间，将作为对象的元数据保存
String
否
- Expect
当使用 Expect: 100-continue 时，在收到服务端确认后，才会发送请求内容
String
否
- onTaskReady
上传任务创建时的回调函数，返回一个 taskId，唯一标识上传任务，可用于上传任务的取消（cancelTask），停止（pauseTask）和重新开始（restartTask）
Function
否
-- taskId
上传任务的编号
String
否
SliceSize
表示文件大小超出一个数值时使用分块上传，单位 Byte，默认值1048576（1MB），小于等于该数值会使用 putObject 上传，大于该数值会使用 sliceUploadFile 上传
Number
是
onProgress
所有任务 进度汇总计算出来的上传进度
String
是
- progressData.loaded
已经上传的文件部分大小，以字节（Bytes）为单位
Number
否
- progressData.total
整个文件的大小，以字节（Bytes）为单位
Number
否
- progressData.speed
文件的上传速度，以字节/秒（Bytes/s）为单位
Number
否
- progressData.percent
文件的上传百分比，以小数形式呈现，例如：上传50%即为0.5
Number
否
onFileFinish
每个文件完成或错误回调
Function
否
- 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
- - error
上传的错误信息
Object
- - data
文件完成的信息
Object
- - options
当前完成文件的参数信息
Object
上传队列
小程序 SDK 针对 putObject 发起的上传任务都有记录在队列中，队列相关方法如下。
1. var taskList = 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
文件上传任务的编号，在调用 putObject 方法时，其 TaskReady 回调会返回该上传任务的 taskId
String
是
暂停上传任务
根据 taskId 暂停上传任务。
使用示例
var taskId = 'xxxxx';                   /* 必须 */
cos.pauseTask(taskId);
参数说明
参数名
参数描述
类型
是否必填
taskId
文件上传任务的编号，在调用 putObject 方法时，其 TaskReady 回调会返回该上传任务的 taskId
String
是
重启上传任务
根据 taskId 重新开始上传任务，可以用于开启用户手动停止的（调用 pauseTask 停止）或者因为上传错误而停止的上传任务。
使用示例
var taskId = 'xxxxx';                   /* 必须 */
cos.restartTask(taskId);
参数说明
参数名
参数描述
类型
是否必填
taskId
文件上传任务的编号，在调用 putObject 方法时，其 TaskReady 回调将返回该上传任务的 taskId
String
是
联系我们
联系我们，为您的业务提供专属服务。
技术支持
如果你想寻求进一步的帮助，通过工单与我们进行联络。我们提供7x24的工单服务。
7x24 电话支持
API	操作名	操作描述
PUT Object	简单上传对象	上传一个对象至存储桶
Append Object	追加上传对象	将对象以分块追加的方式上传至存储桶
POST Object	表单上传对象	使用表单请求上传对象
API	操作名	操作描述
List Multipart Uploads	查询分块上传	查询正在进行中的分块上传信息
Initiate Multipart Upload	初始化分块上传	初始化分块上传任务
Upload Part	上传分块	分块上传对象
List Parts	查询已上传块	查询特定分块上传操作中已上传的块
Complete Multipart Upload	完成分块上传	完成整个对象的分块上传
Abort Multipart Upload	终止分块上传	终止一个分块上传操作并删除已上传的块
参数名	参数描述	类型	是否必填
Bucket	存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式	String	是
Region	存储桶所在地域枚举值请参见地域和访问域名	String	是
Key	对象键（Object 的名称），对象在存储桶中的唯一标识，详情请参见对象概述	String	是
Body	创建的文件的文本内容，可以为字符串、ArrayBuffer	String\\ArrayBuffer	是
CacheControl	RFC 2616中定义的缓存策略，将作为对象的元数据保存	String	否
ContentDisposition	RFC 2616中定义的文件名称，将作为对象的元数据保存	String	否
ContentEncoding	RFC 2616中定义的编码格式，将作为对象的元数据保存	String	否
ContentLength	RFC 2616中定义的 HTTP 请求内容长度（字节）	String	否
ContentType	RFC 2616中定义的内容类型（MIME），将作为对象的元数据保存	String	否
Expires	RFC 2616中定义的过期时间，将作为对象的元数据保存	String	否
Expect	当使用 Expect: 100-continue 时，在收到服务端确认后，才会发送请求内容	String	否
ACL	定义对象的访问控制列表（ACL）属性，枚举值请参见 ACL 概述文档中对象的预设 ACL 部分，例如 default，private，public-read 等注意：如果您不需要进行对象 ACL 控制，请设置为 default 或者此项不进行设置，默认继承存储桶权限	String	否
GrantRead	赋予被授权者读取对象的权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：当需要给子账户授权时，`id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"` 当需要给主账号授权时，`id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"` 例如`'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	否
GrantReadAcp	赋予被授权者读取对象的访问控制列表（ACL）的权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：当需要给子账户授权时，`id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"` 当需要给主账号授权时，`id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"` 例如`'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	否
GrantWriteAcp	赋予被授权者写入对象的访问控制列表（ACL）的权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：当需要给子账户授权时，`id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"` 当需要给主账号授权时，`id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"` 例如`'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	否
GrantFullControl	赋予被授权者操作对象的所有权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：当需要给子账户授权时，`id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"` 当需要给主账号授权时，`id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"` 例如`'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	否
StorageClass	设置对象的存储类型，枚举值：STANDARD、STANDARD_IA、ARCHIVE，默认值：STANDARD。更多存储类型，请参见存储类型概述	String	否
x-cos-meta-*	允许用户自定义的头部信息，将作为对象的元数据保存。大小限制2KB	String	否
onTaskReady	上传任务创建时的回调函数，返回一个 taskId，唯一标识上传任务，可用于上传任务的取消（cancelTask），停止（pauseTask）和重新开始（restartTask）	Function	否
- taskId	上传任务的编号	String	否
onProgress	进度的回调函数，进度回调响应对象（progressData）属性如下	Function	否
- progressData.loaded	已经上传的文件部分大小，以字节（Bytes）为单位	Number	否
- progressData.total	整个文件的大小，以字节（Bytes）为单位	Number	否
- progressData.speed	文件的上传速度，以字节/秒（Bytes/s）为单位	Number	否
- progressData.percent	文件上传的百分比，以小数形式呈现，例如：上传50%即为0.5	Number	否
tencent cloud

注册

登录

Recent Pages

上传对象

简介

简单操作

简单上传对象

功能说明

使用示例

参数说明

回调函数说明

追加上传对象

功能说明

使用示例

参数说明

回调函数说明

表单上传对象

使用示例

参数说明

回调函数说明

分块操作

查询分块上传

功能说明

使用示例

参数说明

回调函数说明

初始化分块上传

功能说明

使用示例

参数说明

回调函数说明

上传分块

功能说明

使用示例

参数说明

回调函数说明

查询已上传块

功能说明

使用示例

参数说明

回调函数说明

完成分块上传

功能说明

使用示例

参数说明

回调函数说明

终止分块上传

功能说明

使用示例

参数说明

回调函数说明

高级接口（推荐）

高级上传

功能说明

使用示例

参数说明

回调函数说明

分块上传对象（断点续传）

功能说明

使用示例

参数说明

回调函数说明

批量上传

功能说明

方法原型

参数说明

回调函数说明

上传队列

取消上传任务

暂停上传任务

重启上传任务

本页内容是否解决了您的问题？

本页内容是否解决了您的问题？
