QCloudCOS

init beginUpload abortUpload getService copyObject putBucket getBucket getBucketACL putBucketACL getBucketCORS putBucketCORS deleteBucketCORS getBucketLocation headBucket putBucketLifecycle deleteBucketLifeCycle putObject getObject getObjectACL putObjectACL optionsObject deleteObject deleteMultipleObject headObject

论坛示例

为帮助用户更好更快的使用原生插件，论坛维护了一个示例，示例中包含示例代码、知识点讲解、注意事项等，供您参考。

概述

QCloudCOS 封装了腾讯对象储存，对象存储（Cloud Object Storage，简称：COS）是腾讯云提供的一种存储海量文件的分布式存储服务，用户可通过网络随时存储和查看数据。腾讯云 COS 使所有用户都能使用具备高扩展性、低成本、可靠和安全的数据存储服务。

COS 通过控制台、 API、SDK 等多样化方式简单、快速地接入，实现了海量数据存储和管理。通过 COS 可以进行多格式文件的上传、下载和管理。腾讯云提供了直观的 Web 管理界面，同时遍布全国范围的 CDN 节点可以对文件下载进行加速。

使用此原生插件之前建议先配置 config.xml 文件，配置完毕，需通过云端编译生效，配置方法如下：

  • 名称：QCloudCOS
  • 参数：appID、secretKey、secretKey、isCAM、regionName、startDate、experationDate、token、serviceName、backgroundEnable、backgroundIdentifier、backgroundIn4GEnable、useHTTPS、isCOSServer、isCustomeCOSServer、customerKey
  • 配置示例：
 <feature name="QCloudCOS">
   <param name="appID" value="" />
   <param name="secretId" value="" />
   <param name="secretKey" value="" />
   <param name="regionName" value="" />
   <param name="serviceName" value="" />
   <param name="isCAM" value=0 />
   <param name="startDate" value="" />
   <param name="experationDate" value="" />
   <param name="token" value="" />
   <param name="backgroundEnable" value=0 />
   <param name="backgroundIdentifier" value="" />
   <param name="backgroundIn4GEnable" value=0 />
   <param name="useHTTPS" value=0 />
   <param name="isCOSServer" value=0 />
   <param name="isCustomeCOSServer" value=0 />
   <param name="customerKey" value="" />
 </feature>
  • 字段描述：

appID：（必须配置）APPID 如何获取

secretId：（必须配置）开发者拥有的项目身份识别 ID，用以身份认证 如何获取

secretKey：（必须配置）开发者拥有的项目身份密钥。可以为永久密钥，也可以是临时密钥（参考CAM系统） 如何获取

regionName：（必须配置）服务地域名称,可用的服务地域名称请查看官网中提供的地域，这里填入官网里提供的地域简称，例如ap-beijing-1等

serviceName：（可选项）服务的基础名称, 默认值为: myqcloud.com

isCAM：（可选项）是否使用CAM系统实现临时签名；0：否 1：是；默认：0

startDate：（可选项）签名有效期的起始时间（时间戳）。默认是设备的本地时间，如果传入起始时间，那么将以起始时间去计算签名，当您使用了CAM系统获取临时密钥的时候，需要设置该值，永久密钥设置该值无效

experationDate：（可选项）签名有效期截止的时间（时间戳），没有设置的话，默认是起始时间加十分钟，当您使用了CAM系统获取临时密钥的时候，需要设置该值，永久密钥设置该值无效

token：（可选项）当您使用了CAM系统获取临时密钥的时候，此值为必填项，代表回话的ID，永久密钥设置该值无效

backgroundEnable：（可选项）是否开启了后台传输；0：否 1：是；默认：0；iOS端1.0.6版本后不再支持

backgroundIdentifier：（可选项）后台传输的标识；iOS端1.0.6版本后不再支持

backgroundIn4GEnable：（可选项）是否在4G的网络下开启后台传输；0：否 1：是；默认：0； iOS端1.0.6版本后不再支

useHTTPS：（可选项）SDK是否支持https请求；0：否 1：是；默认：0

isCOSServer：（可选项）是否使用cos托管加密密钥的服务端加密（SSE-COS）保护数据；0：否 1：是；默认：0

isCustomeCOSServer：（可选项）是否使用客户提供的加密密钥的服务器端加密 (SSE-C)保护数据；isCustomeCOSServer优先级高于isCOSServer；0：否 1：是；默认：0

customerKey：（可选项）用户提供的密钥，传入一个32字节的字符串，支持数字、字母、字符的组合，不支持中文；注意：useHTTPS和isCustomeCOSServer必须为1

接入 CAM 系统实现临时签名

虽然在本地提供了永久的 SecretId 和 SecretKey 来生成签名的接口，但请注意，将永久的 SecretId 和 SecretKey 存储在本地是非常危险的行为，容易造成泄露引起不必要的损失。因此基于安全性的考虑，建议您在服务器端实现签名的过程。

推荐您在自己的签名服务器内接入腾讯云的 CAM（Cloud Access Manager，访问管理）来实现整个签名流程。

至于如何搭建签名服务器接入 CAM 系统，您可以参考移动应用直传实践。

返回错误码说明

当 SDK 请求失败的时候，返回的 error 将不为空，并且包括了错误码、错误描述和其它一些调试必备的信息，以帮助开发者快速解决问题。返回错误码（封装在返回的error里）主要包括两类：设备本身因为网络原因等返回的错误码，以及 COS 返回的错误码。

对于设备本身因为网络原因产生的错误码，都是负数并且是四位数，例如-1001，这类错误码是苹果定义的，可以参考 NSURLError.h 头文件内的定义，或者是苹果官方文档说明。

对于COS返回的错误码，是基于 HTTP 的状态码而来的，也就是404, 503这类。对于这类错误码，可以参考 COS 官方文档中关于错误码的说明寻求解决方案。

注意：本原生插件 iOS 平台上最低适配系统版本为 iOS 11.0

所有参数不可填空('')

对接口有任何不明之处可参考腾讯对象储存官方文档

init

初始化原生插件,在调用其他接口之前Android必须先调用此接口,初始化接口只需要调用一次;

init()

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.init();

可用性

Android系统

可提供的1.0.0及更高版本

beginUpload

上传文件

beginUpload({params}, callback(ret, err))

params

path:

  • 类型：字符串类型
  • 描述：文件路径fs

bucket:

  • 类型：字符串类型
  • 描述：存储桶名称

object:

  • 类型：字符串类型
  • 描述：上传文件（对象）的文件名，也是对象的key，不可重复，请注意文件名中不可以含有问号即"?"字符，

storageClass:(IOS支持)

  • 类型：数字类型
  • 描述：（可选项）对象的存储级别；0：QCloudCOSStorageStandard 1:QCloudCOSStorageStandardIA
  • 默认：0

cacheControl:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）RFC 2616 中定义的缓存策略，将作为 Object 元数据保存

contentDisposition:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）RFC 2616 中定义的文件名称，将作为 Object 元数据保存

expect:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）当使用 Expect: 100-continue 时，在收到服务端确认后，才会发送请求内容

expires:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）RFC 2616 中定义的过期时间

accessControlList:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）定义 Object 的 ACL 属性。有效值：private，public-read-write，public-read
  • 默认值：'private'

grantRead:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）赋予被授权者读的权限。格式： id=" ",id=" "；当需要给子账户授权时，id="qcs::cam::uin/:uin/"，当需要给根账户授权时，id="qcs::cam::uin/:uin/" 其中 OwnerUin 指的是根账户的 ID，而 SubUin 指的是子账户的 ID

grantWrite:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）授予被授权者写的权限。格式同grantRead参数。1.0.6版本后不再支持

grantFullControl:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）授予被授权者读写权限。格式同grantRead参数。

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否上传成功（上传过程中出现失败会返回false）(IOS支持)
   finish:true,                //布尔类型；是否上传完成
   bytesSent:0,                //数字类型；发送了多少字节(IOS支持)
   totalBytesSent:0,           //数字类型；已经发送了多少字节
   totalBytesExpectedToSend:0, //数字类型；文件总大小（字节）
 
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.beginUpload({
   path:'',
   bucket:'',
   object:'',
   grantFullControl:'id=\"qcs::cam::uin/1234560608:uin/1234560608\"'
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

abortUpload

取消上传

abortUpload({params},callback(ret, err))

params

object:

  • 类型：字符串类型
  • 描述：上传文件（对象）的文件名，也是对象的key

callback(ret, err)

(IOS支持)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否取消成功
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.abortUpload({
  object:''
},function(ret,err) {
   api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

iOS系统

可提供的1.0.0及更高版本

getService

取请求者名下的所有存储空间列表

getService(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,               //布尔类型；是否取消成功
   displayName:'',            //字符类型；持有者的名称
   identifier:'',             //字符类型；持有者 ID
   buckets:[{
     name:'',                 //字符类型；存储桶名称
     location:'',             //字符类型；存储桶所在区域
     createDate:'',           //字符类型；存储桶创建时间
   }]
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.getService(function(ret,err) {
   api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

copyObject

复制文件

copyObject({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：目的存储桶名

object:

  • 类型：字符串类型
  • 描述：目的文件名

sourceBucket:

  • 类型：字符串类型
  • 描述：复制的源文件所在的存储桶名，需要是公有读或者在当前账号有权限

sourceObject:

  • 类型：数字类型
  • 描述：复制的源文件的文件名

sourceAPPID:

  • 类型：字符串类型
  • 描述：复制的源文件的APPID

sourceRegion:

  • 类型：字符串类型
  • 描述：复制的源文件所在的区域

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否上传成功（上传过程中出现失败会返回false）
   eTag:'',                    //字符类型；文件的 SHA-1 算法校验值。ETag 的值可以用于检查 Object 的内容是否发生变化
   lastModified:'',            //字符类型；文件的最后修改时间，GMT格式 (IOS支持)
   versionID:'',               //字符类型；对象对应的Version ID（在开启了多版本的情况才有） (IOS支持)
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.copyObject({
   bucket:'',
   object:'',
   sourceBucket:'',
   sourceObject:'',
   sourceAPPID:'',
   sourceRegion:'',
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

putBucket

创建存储桶

putBucket({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名

accessControlList:

  • 类型：字符串类型
  • 描述：（可选项）定义 Bucket 的 ACL 属性。有效值：private，public-read-write，public-read；
  • 默认值：private

grantRead:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）赋予被授权者读的权限。格式： id=" ",id=" "；当需要给子账户授权时，id="qcs::cam::uin/:uin/"，当需要给根账户授权时，id="qcs::cam::uin/:uin/" 其中 OwnerUin 指的是根账户的 ID，而 SubUin 指的是子账户的 ID

grantReadAndroid:(Android)

  • 类型：字符串数组

  • 描述：（可选项）赋予被授权者子账号读的权限。数组中第一个值是主账号ID 第二个值是子账号ID,数组不传主账号授权 grantWrite:(IOS支持)

  • 类型：数字类型

  • 描述：（可选项）授予被授权者写的权限。格式同grantRead

grantWriteAndroid:(Android)

  • 类型：字符串数组
  • 描述：（可选项）授予被授权者子账号写的权限。子账号读的权限。数组中第一个值是主账号ID 第二个值是子账号ID,数组不传主账号授权

grantFullControl:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）授予被授权者写的权限。格式同grantRead

grantFullControlAndroid:(Android)

  • 类型：字符串数组
  • 描述：（可选项）授予被授权者子账号完全控制。子账号读的权限。数组中第一个值是主账号ID 第二个值是子账号ID,数组不传主账号授权

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功
}

err：

  • 类型：JSON 对象
  • 内部字段：
{

   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.putBucket({
   bucket:'',
   grantFullControl:'id=\"qcs::cam::uin/1234560608:uin/1234560608\"'
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

getBucket

列举存储桶内的内容

getBucket({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名，格式为 - ,例如 testBucket-1253653367

prefix:

  • 类型：字符串类型
  • 描述：（可选项）前缀匹配，用来规定返回的文件前缀地址

delimiter:

  • 类型：字符串类型
  • 描述：（可选项）定界符为一个符号，如果有 Prefix，则将 Prefix 到 delimiter 之间的相同路径归为一类，定义为 Common Prefix，然后列出所有 Common Prefix。如果没有 Prefix，则从路径起点开始。可以将其理解为结束的符号，例如如果想要结尾是 A 的结果，那么将delimiter设置为 A 即可。

encodingType:

  • 类型：字符串类型
  • 描述：（可选项）规定返回值的编码方式，可选值：url

marker:

  • 类型：字符串类型
  • 描述：（可选项）默认以 UTF-8 二进制顺序列出条目，所有列出条目从 marker 开始

maxKeys:

  • 类型：数字类型
  • 描述：（可选项）单次返回的最大条目数量，
  • 默认： 1000

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：

bucket.put("name",listBucket.name);

{
   status:true,                //布尔类型；是否成功
   bucket:{                      //json对象；储桶内的内容
    "name": "rickenwang-guagnzhou-1258479375",
    "delimiter": "",
    "encodingType": "",
    "prefix": "",
    "marker": "",
    "nextMarker": "",
    "maxKeys": 1000,
    "isTruncated": false,
    "CommonPrefixes": [{"prefix":""}],
    "contentList": [{
        "size": 20480085,
        "key": "storage\/emulated\/0\/Download\/2b7912be0fa2b5c9ab9f286089194c5c-1.apk",
        "lastModified": "2019-01-16T11:03:28.000Z",
        "eTag": "\"9ce2069937f3c74d6d0b3106df079349-19\"",
        "storageClass": "STANDARD"
    }, {
        "size": 20480085,
        "key": "storage\/emulated\/0\/Download\/2b7912be0fa2b5c9ab9f286089194c5c-1.apk",
        "lastModified": "2019-01-16T11:03:28.000Z",
        "eTag": "\"9ce2069937f3c74d6d0b3106df079349-19\"",
        "storageClass": "STANDARD"
    }, {
        "size": 20480085,
        "key": "storage\/emulated\/0\/Download\/2b7912be0fa2b5c9ab9f286089194c5c-1.apk",
        "lastModified": "2019-01-16T11:03:28.000Z",
        "eTag": "\"9ce2069937f3c74d6d0b3106df079349-19\"",
        "storageClass": "STANDARD"
    }, {
        "size": 20480085,
        "key": "storage\/emulated\/0\/Download\/2b7912be0fa2b5c9ab9f286089194c5c-1.apk",
        "lastModified": "2019-01-16T11:03:28.000Z",
        "eTag": "\"9ce2069937f3c74d6d0b3106df079349-19\"",
        "storageClass": "STANDARD"
    }]
}                
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.getBucket({
   bucket:''
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

getBucketACL

获取存储桶的 ACL（Access Control List）

getBucket({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名，格式为 - ,例如 testBucket-1253653367

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功
   displayName:'',             //字符串类型；持有者的名称
   identifier:'',              //字符串类型；持有者 ID
   aCLGrants:[{
     subAccount:'',            //字符串类型；子账号(IOS支持)
     identifier:'',            //字符串类型；ID
     displayName:'',           //字符串类型；名称
     xmlns:'',                 //字符串类型；命名空间(IOS支持)
     type:0,                   //数字类型；账号类型；0：在 ID 中指定根帐号，1：在 ID 中指定子帐号(IOS支持)
     permission:0,             //数字类型；指明授予被授权者的权限信息；0：读，1：写，2：读写

   }]
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.getBucketACL({
   bucket:''
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

putBucketACL

设置存储桶的 ACL（Access Control List）

putBucketACL({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名，格式为 - ,例如 testBucket-1253653367

accessControlList:

  • 类型：字符串类型
  • 描述：（可选项）定义 Object 的 ACL 属性。有效值：private，public-read-write，public-read
  • 默认值：'private'

grantRead:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）赋予被授权者读的权限。格式： id=" ",id=" "；当需要给子账户授权时，id="qcs::cam::uin/:uin/"，当需要给根账户授权时，id="qcs::cam::uin/:uin/" 其中 OwnerUin 指的是根账户的 ID，而 SubUin 指的是子账户的 ID

grantReadAndroid:(Android)

  • 类型：字符串数组

  • 描述：（可选项）赋予被授权者子账号读的权限。数组中第一个值是主账号ID 第二个值是子账号ID,数组不传主账号授权 grantWrite:(IOS支持)

  • 类型：数字类型

  • 描述：（可选项）授予被授权者写的权限。格式同grantRead

grantWriteAndroid:(Android)

  • 类型：字符串数组
  • 描述：（可选项）授予被授权者子账号写的权限。子账号读的权限。数组中第一个值是主账号ID 第二个值是子账号ID,数组不传主账号授权

grantFullControl:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）授予被授权者写的权限。格式同grantRead

grantFullControlAndroid:(Android)

  • 类型：字符串数组
  • 描述：（可选项）授予被授权者子账号完全控制。子账号读的权限。数组中第一个值是主账号ID 第二个值是子账号ID,数组不传主账号授权

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.putBucketACL({
   bucket:'',
   grantFullControl:'id=\"qcs::cam::uin/1234560608:uin/1234560608\"'
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

getBucketCORS

获取存储桶的 CORS(跨域访问)设置

getBucketCORS({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名，格式为 - ,例如 testBucket-1253653367

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功
   rules:[{
     identifier:'',            //字符串类型；配置规则的 ID
     allowedMethod:[],         //数组类型；允许的 HTTP 操作，枚举值：GET，PUT，HEAD，POST，DELETE
     allowedOrigin:'',         //字符串类型；允许的访问来源，支持通配符 * , 格式为：协议://域名[:端口]如：http://www.qq.com
     allowedHeader:[],         //数组类型；在发送 OPTIONS 请求时告知服务端，接下来的请求可以使用哪些自定义的 HTTP 请求头部，支持通配符 *
     maxAgeSeconds:0,          //数字类型；设置 OPTIONS 请求得到结果的有效期
     exposeHeader:'',           //字符串类型；设置浏览器可以接收到的来自服务器端的自定义头部信息
   }]
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.getBucketCORS({
   bucket:''
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

putBucketCORS

设置存储桶的 CORS（跨域访问）

putBucketCORS({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名，格式为 - ,例如 testBucket-1253653367

rules:

  • 类型：JSON数组
  • 描述：放置 CORS 的数组
[{
     identifier:'',            //字符串类型；配置规则的 ID
     allowedMethod:[],         //数组类型；允许的 HTTP 操作，枚举值：GET，PUT，HEAD，POST，DELETE
     allowedOrigin:'',         //字符串类型；允许的访问来源，支持通配符 * , 格式为：协议://域名[:端口]如：http://www.qq.com
     allowedHeader:[],         //数组类型；在发送 OPTIONS 请求时告知服务端，接下来的请求可以使用哪些自定义的 HTTP 请求头部，支持通配符 *
     maxAgeSeconds:0,          //数字类型；设置 OPTIONS 请求得到结果的有效期
     exposeHeader:'',           //字符串类型；设置浏览器可以接收到的来自服务器端的自定义头部信息
   }]

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功
   
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.putBucketCORS({
   bucket:'',
   rules:[{identifier:'100008980821',            //字符串类型；配置规则的 ID
        allowedMethod:['PUT','GET'],         //数组类型；允许的 HTTP 操作，枚举值：GET，PUT，HEAD，POST，DELETE
        allowedOrigin:'http://cloud.tencent.com',         //字符串类型；允许的访问来源，支持通配符 * , 格式为：协议://域名[:端口]如：http://www.qq.com
       allowedHeader:['Host','Authorization'],         //数组类型；在发送 OPTIONS 请求时告知服务端，接下来的请求可以使用哪些自定义的 HTTP 请求头部，支持通配符 *
       maxAgeSeconds:5000,          //数字类型；设置 OPTIONS 请求得到结果的有效期
       exposeHeader:'x-cos-meta'} ]          //字符串类型；设置浏览器可以接收到的来自服务器端的自定义头部信息
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

deleteBucketCORS

删除存储桶 CORS 设置

deleteBucketCORS({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名，格式为 - ,例如 testBucket-1253653367

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功
   
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.deleteBucketCORS({
   bucket:'',
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

getBucketLocation

获取存储桶的地域信息

getBucketLocation({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名，格式为 - ,例如 testBucket-1253653367

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功
   locationConstraint:''       //字符类型；说明 Bucket 所在区域
   
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.getBucketLocation({
   bucket:'',
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

headBucket

查询 Bucket 是否存在

headBucket({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名，格式为 - ,例如 testBucket-1253653367

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否存在
   code:200                    //数字类型；当该 Bucket 存在时，返回200；当该 Bucket 无访问权限时，返回 403；当该 Bucket 不存在时，返回 404。(IOS支持)
   
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.headBucket({
   bucket:'',
},function(ret){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

putBucketLifecycle

Put Bucket Lifecycle

COS 支持用户以生命周期配置的方式来管理 Bucket 中 Object 的生命周期。生命周期配置包含一个或多个将应用于一组对象规则的规则集 (其中每个规则为 COS 定义一个操作)。 这些操作分为以下两种：

转换操作：定义对象转换为另一个存储类的时间。例如，您可以选择在对象创建 30 天后将其转换为 STANDARD_IA (IA，适用于不常访问) 存储类别。 过期操作：指定 Object 的过期时间。COS 将会自动为用户删除过期的 Object。

Put Bucket Lifecycle 用于为 Bucket 创建一个新的生命周期配置。如果该 Bucket 已配置生命周期，使用该接口创建新的配置的同时则会覆盖原有的配置。

putBucketLifecycle({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名，格式为 - ,例如 testBucket-1253653367

rules:

  • 类型：JSON数组
  • 描述：规则描述集合的数组
[{
     identifier:'',                   //字符串类型；用于唯一地标识规则，长度不能超过 255 个字符
     filter:{
       prefix:'',                     //字符类型；指定规则所适用的前缀。匹配前缀的对象受该规则影响                       
     },
     status:0,                        //数字类型；指明规则是否启用；0：启用 1；不启用；默认：1
     daysAfterInitiation:1,          //（可选项）数字类型；指明分片上传开始后多少天内必须完成上；默认：1
     transition:{                      //（可选项）json对象；规则转换属性，对象何时转换被转换为 Standard_IA 等(IOS)
       days:1,                         //（可选项）数字类型；指明规则对应的动作在对象最后的修改日期过后多少天操作，在Transition里，该字段有效值是非负整数；默认：1
       transitionDate:'',              //（可选项）字符类型；指明规则对应的动作在何时操作
       storageClass:0                  //（可选项）数字类型；对象的存储级别；0：QCloudCOSStorageStandard 1:QCloudCOSStorageStandardIA；默认：0
     },
     expiration:{                      //（可选项）json对象；规则过期属性
        days:1,                        //（可选项）数字类型；指明规则对应的动作在对象最后的修改日期过后多少天操作，在Expiration里，该字段有效值为正整数；默认：1
     },
     noncurrentVersionExpiration:{     (IOS支持)
         noncurrentDays:0,              //（可选项）数字类型；指明非当前版本对象何时转换被转换为 Standard_IA 等
         storageClass:0,                //（可选项）数字类型；对象的存储级别；0：QCloudCOSStorageStandard 1:QCloudCOSStorageStandardIA；默认：0
         
     }
 }]

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功
   
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.putBucketLifecycle({
   bucket:'',
   rules:[],
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

deleteBucketLifeCycle

Delete Bucket Lifecycle

deleteBucketLifeCycle({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名，格式为 - ,例如 testBucket-1253653367

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功
   
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.deleteBucketLifeCycle({
   bucket:'',
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

putObject

简单上传仅限于小文件（20MB以下）

putObject({params}, callback(ret, err))

params

path:

  • 类型：字符串类型
  • 描述：文件路径，支持、fs

bucket:

  • 类型：字符串类型
  • 描述：存储桶名,格式为- ,例如 testBucket-1253653367

object:

  • 类型：字符串类型
  • 描述：对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg 中，对象键为 doc1/pic1.jpg。更详细的描述可以参考对象描述

storageClass:(IOS支持)

  • 类型：数字类型
  • 描述：（可选项）对象的存储级别；0：QCloudCOSStorageStandard 1:QCloudCOSStorageStandardIA
  • 默认：0

cacheControl:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）RFC 2616 中定义的缓存策略

contentDisposition:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）RFC 2616 中定义的文件名称

expect:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）当使用expect=@"100-Continue"时，在收到服务端确认后才会发送请求内容

expires:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）RFC 2616 中定义的过期时间

accessControlList:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）定义 Object 的 ACL 属性。有效值：private，public-read-write，public-read
  • 默认值：'private'

grantRead:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）赋予被授权者读的权限。格式： id=" ",id=" "；当需要给子账户授权时，id="qcs::cam::uin/:uin/"，当需要给根账户授权时，id="qcs::cam::uin/:uin/" 其中 OwnerUin 指的是根账户的 ID，而 SubUin 指的是子账户的 ID

grantWrite:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）授予被授权者写的权限。格式同grantRead参数。

grantFullControl:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）授予被授权者读写权限。格式同grantRead参数。

grantReadAndroid:(Android)

  • 类型：字符串数组
  • 描述：（可选项）赋予被授权者子账号读的权限。数组中第一个值是主账号ID 第二个值是子账号ID,数组不传主账号授权

grantWriteAndroid:(Android)

  • 类型：字符串数组
  • 描述：（可选项）授予被授权者子账号写的权限。子账号读的权限。数组中第一个值是主账号ID 第二个值是子账号ID,数组不传主账号授权

grantFullControlAndroid:(Android)

  • 类型：字符串数组
  • 描述：（可选项）授予被授权者子账号完全控制。子账号读的权限。数组中第一个值是主账号ID 第二个值是子账号ID,数组不传主账号授权

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功 
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.putObject({
   path:'',
   bucket:'',
   object:'',
   grantFullControl:'id=\"qcs::cam::uin/1234560608:uin/1234560608\"'
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

getObjectACL

查询对象的 ACL（Access Control List）

getObjectACL({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名,格式为- ,例如 testBucket-1253653367

object:

  • 类型：字符串类型
  • 描述：对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg 中，对象键为 doc1/pic1.jpg。更详细的描述可以参考对象描述

versionID:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）指定多版本中的 Version ID

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功
     owner:{                     //json对象；持有者的信息
     displayName:'',           //字符类型；持有者的名称
     identifier:'',            //字符类型；Bucket 持有者 ID，格式：qcs::cam::uin/<OwnerUin>:uin/<SubUin>，如果是根帐号，<OwnerUin> 和 <SubUin> 是同一个值
   },
   aCLGrants:[          //数组对象；被授权者与权限的信息
      grantee:{         //json对象；说明被授权者的信息。type 类型可以为 RootAccount， Subaccount；当 type 类型为 RootAccount 时，ID 中指定的是根帐号;当 type 类型为 Subaccount 时，ID 中指定的是子帐号
        subAccount:'',  //字符类型；子账号子账号(IOS支持)
        identifier:'',  //字符类型；ID，格式：qcs::cam::uin/<OwnerUin>:uin/<SubUin> 如果是根帐号，<OwnerUin> 和 <SubUin> 是同一个值
        displayName:'',  //字符类型；名称
        type:0,         //数字类型；子账号；0：在 ID 中指定根帐号 1：在 ID 中指定子帐号
        xmlns:'',       //字符类型；命名空间(IOS支持)
      
      },
      permission:0      //数字类型；指明授予被授权者的权限信息；0：读 1：写 2：读写
   ]
 
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.getObjectACL({
   bucket:'',
   object:''
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

putObjectACL

设置对象的 ACL（Access Control List）

注意：当前访问策略条目限制为 1000 条，如果您不需要进行对象 ACL 控制，请在上传时不要设置，默认继承 Bucket 权限

putObjectACL({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名,格式为- ,例如 testBucket-1253653367

object:

  • 类型：字符串类型
  • 描述：对象名

accessControlList:

  • 类型：字符串类型
  • 描述：（可选项）定义 Object 的 ACL 属性。有效值：private，public-read-write，public-read
  • 默认值：'private'

grantRead:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）赋予被授权者读的权限。格式： id=" ",id=" "；当需要给子账户授权时，id="qcs::cam::uin/:uin/"，当需要给根账户授权时，id="qcs::cam::uin/:uin/" 其中 OwnerUin 指的是根账户的 ID，而 SubUin 指的是子账户的 ID

grantWrite:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）授予被授权者写的权限。格式同grantRead参数。

grantFullControl:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）授予被授权者读写权限。格式同grantRead参数。

grantReadAndroid:(Android)

  • 类型：字符串数组
  • 描述：（可选项）赋予被授权者子账号读的权限。数组中第一个值是主账号ID 第二个值是子账号ID,数组不传主账号授权

grantWriteAndroid:(Android)

  • 类型：字符串数组
  • 描述：（可选项）授予被授权者子账号写的权限。子账号读的权限。数组中第一个值是主账号ID 第二个值是子账号ID,数组不传主账号授权

grantFullControlAndroid:(Android)

  • 类型：字符串数组
  • 描述：（可选项）授予被授权者子账号完全控制。子账号读的权限。数组中第一个值是主账号ID 第二个值是子账号ID,数组不传主账号授权

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功
 
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.putObjectACL({
   bucket:'',
   object:'',
   grantFullControl:'id=\"qcs::cam::uin/1234560608:uin/1234560608\"'
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

getObject

下载Object文件

getObject({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名,格式为- ,例如 testBucket-1253653367

object:

  • 类型：字符串类型
  • 描述：对象名

savePath:

  • 类型：字符串类型
  • 描述：文件下载到本地文件夹的绝对路径(支持fs)

localFileName:

  • 类型：字符串类型
  • 描述：下载到本地的文件的名字带有后缀如(4432.jpg)

range:

  • 类型：字符串类型 (IOS支持)
  • 描述：（可选项）RFC 2616 中定义的指定文件下载范围，以字节（bytes）为单位

ifModifiedSince:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）如果文件修改时间晚于指定时间，才返回文件内容。否则返回 412 (not modified)

responseContentType:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）设置响应头部中的 Content-Type 参数

responseContentLanguage:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）设置响应头部中的 Content-Language 参数

responseContentExpires:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）设置响应头部中的 Content-Expires 参数

responseCacheControl:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）设置响应头部中的 Cache-Control 参数

responseContentDisposition:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）设置响应头部中的 Content-Disposition 参数

responseContentEncoding:(IOS支持)

  • 类型：字符串类型
  • 描述：（可选项）设置响应头部中的 Content-Encoding 参数

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,               //布尔类型；是否下载成功（上传过程中出现失败会返回false）(IOS支持)
   finish:true,                //布尔类型；是否下载完成
   bytesSent:0,                //数字类型；下载了多少字节(IOS支持)
   totalBytesSent:0,           //数字类型；已经下载了多少字节
   totalBytesExpectedToSend:0, //数字类型；文件总大小（字节）
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.getObject({
   bucket:'',
   object:''
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

optionsObject

Object 跨域访问配置的预请求 调用此接口之前需要先调用,putBucketCORS

optionsObject({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名,格式为- ,例如 testBucket-1253653367

object:

  • 类型：字符串类型
  • 描述：对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg 中，对象键为 doc1/pic1.jpg。更详细的描述可以参考对象描述

accessControlRequestMethod :

  • 类型：字符串类型
  • 描述：模拟跨域访问的请求HTTP方法

origin:

  • 类型：字符串类型
  • 描述：模拟跨域访问允许的访问来源，支持通配符 * , 格式为：协议://域名[:端口]如：http://www.qq.com

accessControlRequestHeaders:

  • 类型：数组
  • 描述：（可选项） 在发送 OPTIONS 请求时告知服务端，接下来的请求可以使用哪些自定义的 HTTP 请求头部，支持通配符 *

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,               //布尔类型；是否成功
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.optionsObject({
   bucket:'',
   object:'',
   origin:'',
   accessControlRequestMethod:[]
   
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

deleteObject

删除单个对象

deleteObject({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名,格式为- ,例如 testBucket-1253653367

object:

  • 类型：字符串类型
  • 描述：对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg 中，对象键为 doc1/pic1.jpg。更详细的描述可以参考对象描述

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,               //布尔类型；是否成功
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.deleteObject({
   bucket:'',
   object:'',   
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

deleteMultipleObject

删除多个对象

deleteMultipleObject({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名,格式为- ,例如 testBucket-1253653367

deleteObjects:

  • 类型：数组类型
  • 描述：存放需要删除对象信息的数组

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,               //布尔类型；是否成功
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.deleteMultipleObject({
   bucket:'',
   deleteObjects:[],   
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

headObject

获取对象meta信息

获取 COS 对象的元数据信息，需要与 Get 的权限一致.且请求是不返回消息体的.若请求中需要设置If-Modified-Since 头部，则统一采用 GMT(RFC822) 时间格式，例如：Tue, 22 Oct 2017 01:35:21 GMT.如果对象不存在，则 返回404.

headObject({params}, callback(ret, err))

params

bucket:

  • 类型：字符串类型
  • 描述：存储桶名,格式为- ,例如 testBucket-1253653367

object:

  • 类型：字符串类型
  • 描述：对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg 中，对象键为 doc1/pic1.jpg。更详细的描述可以参考对象描述

ifModifiedSince:(IOS)

  • 类型：字符串类型
  • 描述：如果文件修改时间晚于指定时间，才返回文件内容。否则返回 304 (not modified)

versionID:(IOS)

  • 类型：字符串类型
  • 描述：（可选项）如果HEAD指定版本的Object,请在该参数中指定versionID（在开启了多版本的情况才有）

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
   status:true,                //布尔类型；是否成功 
   result:{}                   //json对象；对象meta信息
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
   code:200,                    //数字类型，错误码
   msg:''                       //字符类型，错误信息
}

示例代码

var QCloudCOS= api.require('QCloudCOS');
QCloudCOS.headObject({
   bucket:'',
   object:'',
   ifModifiedSince:'22 Oct 2018 01:35:21 GMT'
},function(ret, err){
  api.alert({
            msg: JSON.stringify(ret)
        })
});

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

是否仍需要帮助？ 请保持联络！
最后更新于 2024/04/24