接口文档

本文针对 JavaScript SDK 的接口做详细的介绍说明。

下文中在代码里出现的 COS 代表 SDK 的 类名，cos 代表 SDK 的实例。

下文中出现的 SecretId、SecretKey、Bucket、Region 等名称的含义和获取方式请参考：COS 术语信息

下文中参数名称前的-代表"子参数"。

构造函数

new COS({})

直接 script 标签引用 SDK 时，SDK 占用了全局变量名 COS，通过它的构造函数可以创建 SDK 实例。

使用示例

创建一个 COS SDK 实例：

var cos = new COS({
    // 必选参数
    getAuthorization: function (options, callback) {
        $.get('http://example.com/server/auth.php', {
            method: options.Method,
            pathname: '/' + options.Key,
        }, function (authorization) {
            callback(authorization);
        });
    },
    // 可选参数
    FileParallelLimit: 3,    // 控制文件上传并发数
    ChunkParallelLimit: 3,   // 控制单个文件下分片上传并发数
    ProgressInterval: 1000,  // 控制上传的 onProgress 回调的间隔
});

• 使用临时密钥格式一：

   var cos = new COS({
     // 必选参数
     getAuthorization: function (options, callback) {
         $.get('http://example.com/server/sts-auth.php', {
             method: options.Method,
             pathname: '/' + options.Key,
         }, function (data) {
             callback({
                 Authorization: data.Authorization,
                 XCosSecurityToken: data.XCosSecurityToken
             });
         });
     }
   });

• 使用临时密钥格式二：

   var cos = new COS({
     // 必选参数
     getAuthorization: function (options, callback) {
         $.get('http://example.com/server/sts.php', {
             bucket: options.Bucket,
             region: options.Region,
         }, function (data) {
             callback({
                 SecretId: data.SecretId,
                 SecretKey: data.SecretKey,
                 XCosSecurityToken: data.XCosSecurityToken,
                 ExpiredTime: data.ExpiredTime,
             });
         });
     }
   });

• 使用固定密钥，前端计算签名（建议只在调试使用，避免泄露密钥）：

   var cos = new COS({
     SecretId: 'AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
     SecretKey: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
   });

构造函数参数说明

getAuthorization 的函数说明

function(options, callback) { ... }

getAuthorization 的函数说明回调参数说明：

• getAuthorization 计算完成后，callback 回传一个签名字符串或一个对象： 回传签名字符串时，回传字符串类型，是请求要用的鉴权凭证 Authorization。
• 回传对象时，回传对象属性列表如下：

  属性名	参数描述	类型	必填
  Authorization	获取回来的临时密钥的	String	是
  XCosSecurityToken	获取回来的临时密钥的 sessionToken，对应 header 的 x-cos-security-token 字段	String	否

getSTS 回调函数说明

function(options, callback) { ... }

getSTS 的回调参数说明：

getSTS 计算完成后，callback 回传一个对象，回传对象的属性列表如下：

获取鉴权凭证

实例本身鉴权凭证可以通过实例化时传入的参数控制如何或获取，有三种获取方式：

1. 实例化时传入 SecretId、SecretKey，每次需要签名都由实例内部计算。
2. 实例化时，传入 getAuthorization 回调，每次需要签名通过这个回调计算完返回签名给实例。
3. 实例化时，传入 getSTS 回调，每次需要临时密钥通过这个回调回去完返回给实例，在每次请求时实例内部使用临时密钥计算得到签名。

静态方法

COS.getAuthorization

COS XML API 的请求里，私有资源操作都需要鉴权凭证 Authorization，用于判断当前请求是否合法。

鉴权凭证使用方式有两种：

1. 放在 header 参数里使用，自断名: authorization
2. 放在 url 参数里使用，字段名：sign

COS.getAuthorization 方法用于计算鉴权凭证（Authorization），用以验证请求合法性的签名信息。

注意：

该方法推荐只在前端调试时使用，项目上线不推荐使用前端计算签名的方法，有暴露秘钥的风险。

使用示例

获取文件下载的鉴权凭证：

var Authorization = COS.getAuthorization({
    SecretId: 'AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    SecretKey: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    Method: 'get',
    Key: 'a.jpg',
    Expires: 60,
    Query: {},
    Headers: {}
});

参数说明

返回值说明

返回值是计算得到的鉴权凭证字符串 authorization。

工具方法

Get Auth

cos.getAuth 方法是 COS.getAuthorization 挂在实例上的版本，区别是 cos.getAuth 不需要传入 SecretId 和 SecretKey，会使用对象本身获取鉴权凭证的方法。

使用示例

var authorization = cos.getAuth({
    Method: 'get',
    Key: '1.jpg'
});

参数说明

返回值说明

返回值是计算得到的鉴权凭证字符串 authorization

Get Object Url

使用示例

// 获取不带签名 Object Url

var url = cos.getObjectUrl({
    Key: '1.jpg',
    Sign: false
});

// 获取带签名的 Object Url

cos.getObjectUrl({
    Key: '1.jpg',
    Sign: true
}, function (err, data) {
    console.log(err || data.Url);
});

参数说明

返回值说明

返回值是一个字符串，两种情况：

1. 如果签名计算可以同步计算（如：实例化传入了 SecretId 和 SecretKey），则默认返回带签名的 url
2. 否则返回不带签名的 url

回调函数说明

function(err, data) { ... }

Bucket 操作

Head Bucket

功能说明

Head Bucket 请求可以确认该 Bucket 是否存在，是否有权限访问。Head 的权限与 Read 一致。当该 Bucket 存在时，返回 HTTP 状态码 200；当该 Bucket 无访问权限时，返回 HTTP 状态码 403；当该 Bucket 不存在时，返回 HTTP 状态码 404。

使用示例

cos.headBucket({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou',     /* 必须 */
}, function(err, data) {
    console.log(err || data);
});

参数说明

回调函数说明

function(err, data) { ... }

Get Bucket

功能说明

Get Bucket 请求等同于 List Object 请求，可以列出该 Bucket 下的部分或者全部 Object。此 API 调用者需要对 Bucket 有 Read 权限。

使用示例

列出目录 a 的所有文件

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

列出目录 a 的文件，不深度遍历

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Delete Bucket

功能说明

Delete Bucket 接口请求可以在指定账号下删除 Bucket，删除之前要求 Bucket 内的内容为空，只有删除了 Bucket 内的信息，才能删除 Bucket 本身。注意，如果删除成功，则返回的 HTTP 状态码为 200 或 204 。

使用示例

调用 Delete Bucket 操作：

cos.deleteBucket({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou'     /* 必须 */
}, function(err, data) {
    console.log(err || data);
});

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Get Bucket ACL

功能说明

Get Bucket ACL 接口用来获取 Bucket 的 ACL(access control list)， 即存储桶（Bucket）的访问权限控制列表。 此 API 接口只有 Bucket 的持有者有权限操作。

使用示例

cos.getBucketAcl({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou'     /* 必须 */
}, function(err, data) {
    console.log(err || data);
});

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Put Bucket ACL

功能说明

Put Bucket ACL 接口用来写入 Bucket 的 ACL 表，您可以通过 Header："x-cos-acl"，"x-cos-grant-read"，"x-cos-grant-write"，"x-cos-grant-full-control" 传入 ACL 信息，或者通过 Body 以 XML 格式传入 ACL 信息。

使用示例

设置 Bucket 公有读

cos.putBucketAcl({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou',    /* 必须 */
    ACL: 'public-read'
}, function(err, data) {
    console.log(err || data);
});

为某个用户赋予 Bucket 读写权限

cos.putBucketAcl({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou',    /* 必须 */
    GrantFullControl: 'id="qcs::cam::uin/1001:uin/1001",id="qcs::cam::uin/1002:uin/1002"' // 1001 是 uin
}, function(err, data) {
    console.log(err || data);
});

为某个用户赋予 Bucket 读写权限

cos.putBucketAcl({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou',    /* 必须 */
    GrantFullControl: 'id="qcs::cam::uin/1001:uin/1001",id="qcs::cam::uin/1002:uin/1002"' // 1001 是 uin
}, function(err, data) {
    console.log(err || data);
});

通过 AccessControlPolicy 修改 Bucket 权限

cos.putBucketAcl({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou',    /* 必须 */
    AccessControlPolicy: {
        "Owner": { // AccessControlPolicy 里必须有 owner
            "ID": 'qcs::cam::uin/459000000:uin/459000000' // 459000000 是 Bucket 所属用户的 QQ 号
        },
        "Grants": [{
            "Grantee": {
                "ID": "qcs::cam::uin/10002:uin/10002", // 10002 是 QQ 号
            },
            "Permission": "WRITE"
        }]
    }
}, function(err, data) {
    console.log(err || data);
});

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Get Bucket CORS

功能说明

Get Bucket CORS 接口实现 Bucket 持有者在 Bucket 上进行跨域资源共享的信息配置。（CORS 是一个 W3C 标准，全称是"跨域资源共享"（Cross-origin Resource Sharing））。默认情况下，Bucket 的持有者直接有权限使用该 API 接口，Bucket 持有者也可以将权限授予其他用户。

使用示例

调用 Get Bucket CORS 操作：

cos.getBucketCors({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou',    /* 必须 */
}, function(err, data) {
    console.log(err || data);
});

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Put Bucket CORS

注意：

1. 如果要在前端修改跨域访问配置，需要该 Bucket 本身支持跨域，可以在控制台进行跨域访问配置。
2. 在修改跨域访问配置时，请注意不要影响到当前的 Origin 下的跨域请求。

功能说明

Put Bucket CORS 接口用来请求设置 Bucket 的跨域资源共享权限，您可以通过传入 XML 格式的配置文件来实现配置，文件大小限制为64 KB。默认情况下，Bucket 的持有者直接有权限使用该 API 接口，Bucket 持有者也可以将权限授予其他用户。

使用示例

调用 Put Bucket CORS 操作：

cos.putBucketCors({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou',    /* 必须 */
    CORSRules: [{
        "AllowedOrigin": ["*"],
        "AllowedMethod": ["GET", "POST", "PUT", "DELETE", "HEAD"],
        "AllowedHeader": ["*"],
        "ExposeHeader": ["ETag", "x-cos-acl", "x-cos-version-id", "x-cos-delete-marker", "x-cos-server-side-encryption"],
        "MaxAgeSeconds": "5"
    }]
}, function(err, data) {
    console.log(err || data);
});

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Delete Bucket CORS

注意：

1. 删除当前 Bucket 的跨域访问配置信息，会导致所有请求跨域失败，请谨慎操作。
2. 不推荐在浏览器端使用该方法。

功能说明

Delete Bucket CORS 接口请求实现删除跨域访问配置信息。

使用示例

调用 Delete Bucket CORS 操作：

cos.deleteBucketCors({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou',    /* 必须 */
}, function(err, data) {
    console.log(err || data);
});

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Get Bucket Location

功能说明

Get Bucket Location 接口用于获取 Bucket 所在的地域信息，该 GET 操作使用 location 子资源返回 Bucket 所在的区域，只有 Bucket 持有者才有该 API 接口的操作权限。

使用示例

调用 Get Bucket Location 操作：

cos.getBucketLocation({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou',    /* 必须 */
}, function(err, data) {
    console.log(err || data);
});

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Object 操作

Head Object

功能说明

Head Object 接口请求可以获取对应 Object 的 meta 信息数据，Head 的权限与 Get 的权限一致。

使用示例

调用 Head Object 操作：

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Get Object

功能说明

Get Object 接口请求可以在 COS 的 Bucket 中将一个文件（Object）下载至本地。该操作需要请求者对目标 Object 具有读权限或目标 Object 对所有人都开放了读权限（公有读）。

使用示例

调用 Get Object 操作：

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

指定 Range 获取文件内容

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Put Object

功能说明

Put Object 接口请求可以将本地的文件（Object）上传至指定 Bucket 中。该操作需要请求者对 Bucket 有 WRITE 权限。

注意：

1. Key（文件名）不能以 / 结尾，否则会被识别为文件夹。
2. 单个 Bucket 下 ACL 策略限制 1000 条，因此在单个 Bucket 下，最多允许对 999 个文件设置 ACL 权限。

使用示例

调用 Put Object 上传文件：

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

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

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

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

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

创建目录：

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Delete Object

功能说明

Delete Object 接口请求可以在 COS 的 Bucket 中将一个文件（Object）删除。该操作需要请求者对 Bucket 有 WRITE 权限。

使用示例

调用 Delete Object 操作：

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Options Object

功能说明

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

使用示例

调用 Options Object 操作：

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Get Object ACL

功能说明

Get Object ACL 接口用来获取某个 Bucket 下的某个 Object 的访问权限。只有 Bucket 的持有者才有权限操作。

使用示例

调用 Get Object ACL 操作：

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Put Object ACL

功能说明

Put Object ACL 接口用来对某个 Bucket 中的某个的 Object 进行 ACL 表的配置 单个 Bucket 下 ACL 策略限制 1000 条，因此在单个 Bucket 下，最多允许对 999 个文件设置 ACL 权限

使用示例

调用 Put Object ACL 修改文件权限：

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

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

cos.putObjectAcl({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou',    /* 必须 */
    Key: '1.jpg',              /* 必须 */
    GrantFullControl: 'id="qcs::cam::uin/1001:uin/1001",id="qcs::cam::uin/1002:uin/1002"' // 1001 是 uin
}, function(err, data) {
    console.log(err || data);
});

通过 AccessControlPolicy 修改 Bucket 权限

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Delete Multiple Object

功能说明

Delete Multiple Object 接口请求实现在指定 Bucket 中批量删除 Object，单次请求最大支持批量删除 1000 个 Object。对于响应结果，COS 提供 Verbose 和 Quiet 两种模式：Verbose 模式将返回每个 Object 的删除结果；Quiet 模式只返回报错的 Object 信息。

使用示例

删除多个文件：

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Put Object Copy

功能说明

Put Object Copy 请求实现将一个文件从源路径复制到目标路径。建议文件大小 1MB 到 5GB，超过 5GB 的文件请使用分块上传 Upload - Copy。在拷贝的过程中，文件元属性和 ACL 可以被修改。用户可以通过该接口实现文件移动，文件重命名，修改文件属性和创建副本。

使用示例

调用 Put Object Copy 操作：

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

分块上传操作

Initiate Multipart Upload

功能说明

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

使用示例

调用 Initiate Multipart Upload 操作：

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Upload Part

功能说明

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

使用示例

调用 Upload Part 操作：

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Complete Multipart Upload

功能说明

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

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

使用示例

调用 Complete Multipart Upload 操作：

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

List Parts

功能说明

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

使用示例

调用 List Parts 操作：

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Abort Multipart Upload

功能说明

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

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

使用示例

调用 Abort Multipart Upload 操作：

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

List Multipart Uploads

功能说明

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

使用示例

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

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

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

分块上传任务操作

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

Slice Upload File

功能说明

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

使用示例

调用 Slice Upload File 操作：

cos.sliceUploadFile({
    Bucket: 'test-1250000000', /* 必须 */
    Region: 'ap-guangzhou',    /* 必须 */
    Key: '1.zip',              /* 必须 */
    Body: file,                /* 必须 */
    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);
});

参数说明

回调函数说明

function(err, data) { ... }

回调参数说明

Cancel Task

功能说明

根据 taskId 取消分块上传任务。

使用示例

调用 Cancel Task 操作。

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

参数说明

Pause Task

功能说明

根据 taskId 暂停分块上传任务。

使用示例

调用 Pause Task 操作。

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

参数说明

Restart Task

功能说明

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

使用示例

调用 Restart Task 操作：

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

参数说明