ACTencentCOS

Method

putBucket getService deleteBucket inspectBucket setBucketLabel queryBucketLabel setManagement beginUpload abortUpload putBucket getBucket getObjec GenerateLinks deleteObject deleteMultipleObject copyObject queryObjectMetadata

概述

ACTencentCOS插件封装了腾讯对象储存

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

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

使用此插件之前必须先配置 config 文件，配置方法如下：

名称：ACTencentCOS
参数：appID、secretKey、secretKey、isCAM、regionName、startDate、experationDate、token、serviceName、backgroundEnable、backgroundIdentifier、useHTTPS、isCOSServer、isCustomeCOSServer、customerKey
配置示例：

 <feature name="ACTencentCOS">
   <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="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（仅iOS支持）

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

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

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

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

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

backgroundIdentifier：（可选项）后台传输的标识（仅iOS支持，1.0.4版本以后不再支持）

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

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

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

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

返回错误码说明

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

对于设备本身因为网络原因产生的错误码，都是负数并且是四位数，例如-1001，这类错误码是苹果定义的，可以参考 NSURLError.h 头文件内的定义，或者是苹果官方文档说明。
对于COS返回的错误码，是基于 HTTP 的状态码而来的，也就是404, 503这类。对于这类错误码，可以参考 COS 官方文档中关于错误码的说明寻求解决方案。
对于腾讯云 SDK 网络层本地客户端自定义错误：主要是指网络异常、证书无效、参数校验失败等可以参考错误码列表

putBucket

创建存储桶

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

params

bucket:

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

accessControlList:

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

grantRead:

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

grantWrite:

类型：数字类型
描述：（可选项）授予被授权者写的权限。格式同grantRead（仅iOS支持）

grantFullControl

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

grantReadAccount:

类型：JSON数组类型
描述：（可选项）设置可读权限账号（仅android支持）
例：

['','']

grantWriteAccount:

类型：JSON数组类型
描述：（可选项）设置可写权限账号（仅android支持）
例：

['','']

grantFullAccount:

类型：JSON数组类型
描述：（可选项）设置可读可写可写权限账号（仅android支持）
例：

['','']

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
   status:true,                //布尔类型；是否成功
}

err：

类型：JSON 对象
内部字段：

{

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

示例代码

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

可用性

iOS、Android系统

可提供的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 ACTencentCOS= api.require('ACTencentCOS');
ACTencentCOS.getService(function(ret,err) {
   alert(JSON.stringify(ret));
});

可用性

iOS、Android系统

可提供的1.0.0及更高版本

deleteBucket

删除存储桶

注意：删除存储桶前，请确保存储桶内的数据和未完成上传的分块数据已全部清空，否则会无法删除存储桶

deleteBucket({param},callback(ret))

params

bucket：

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

callback(ret)

ret：

类型：JSON类型
内部字段：

{
    status:true
    msg:"删除成功"
}

示例代码

var ACTencentCOS = api.require('ACTencentCOS');
var param = {
    "bucket":"examplebucket-1250000000"
}
ACTencentCOS.deleteBucket(param,function(ret){
    alert(JSON.stringify(ret))
});

可用性

iOS、Android系统

可提供的1.0.0及更高版本

inspectBucket

确认该存储桶是否存在，是否有权限访问

inspectBucket({param},callback(ret))

param

bucket：

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

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:true
    code:""			//数字类型；取值范围：
                    //200（存储桶存在且有读取权限）
                    //403（无存储桶读取权限）
                    //404（存储桶不存在）
}

示例代码

var ACTencentCOS = api.require('ACTencentCOS');
var param = {
    "bucket":"examplebucket-1250000000"
}
ACTencentCOS.inspectBucket(param,function(ret){
    alert(JSON.stringify(ret))
})

可用性

iOS、Android系统

可提供的1.0.0及更高版本

setBucketLabel

为已存在的存储桶设置标签

setBucketLabel({param},callback(ret))

param

bucket：

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

key：

类型：字符串类型
描述：标签名

value：

类型：字符串类型
描述：标签值

示例代码

var ACTencentCOS = api.require('ACTencentCOS');
var param = {
    "bucket":"examplebucket-1250000000",
    "key":"myKey",
    "value":"myValue"
}
ACTencentCOS.setBucketLabel(param);

可用性

iOS、Android系统

可提供的1.0.0及更高版本

queryBucketLabel

查询指定存储桶下已有的存储桶标签

queryBucketLabel({param},callback(ret))

param

bucket：

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

callback(ret)

类型：JSON对象
内部字段：

{
    "status":true
    "tag":""		//字符串类型；存储桶标签地址
}

示例代码

var ACTencentCOS = api.require('ACTencentCOS');
var param = {
    "bucket":"examplebucket-1250000000"
}
ACTencentCOS.queryBucketLabel(param,function(ret){
    alert(JSON.stringify(ret));
});

可用性

iOS、Android系统

可提供的1.0.0及更高版本

setManagement

为源存储桶开启日志记录，将源存储桶的访问日志保存到指定的目标存储桶中。

注意：使用日志记录功能前，需要在控制台中开启目标存储桶的【日志管理】-【日志存储】功能，启用日志管理后，COS的所有访问请求信息都将以日志的形式，以5分钟为单位保存至目标存储桶中。

设置开启日志记录后，可以通过getBucket方法获取。

setManagement({param},callback(ret))

param

srcBucket：

类型：字符串类型
描述：源存储桶

targetBucket：

类型：字符串类型
描述：目标存储桶

storagePath：

类型：字符串类型
描述：日志存储的指定位置
注意：该存储位置可以在控制台中查看，可以使用默认位置，也可以自定义位置

callback(ret)

ret：

类型：JSON对象
内部对象：

{
    "status":true	
    "code":""		//数字类型
                //200（日志设置成功）
}

示例代码

var ACTencentCOS = api.require('ACTencentCOS');
var param = {
    "srcBucket":"srcbucket-1250000000",
    "targetBucket":"targetbucket-1250000000",
    "storagePath":"cos-access-log/"
}
ACTencentCOS.setManagement(param,function(ret){
    alert(JSON.stringify(ret));
});

可用性

iOS、Android系统

可提供的1.0.0及更高版本

beginUpload

上传文件

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

params

path:

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

bucket:

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

object:

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

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
   eventType: '',    	                   //字符串类型；回调事件状态，取值范围如下：
                                       //finish：上传完成事件回调
                                       //progress：上传进度事件回调
   status:true,                	   //布尔类型；是否上传成功
   totalBytesSent:0,           	   //数字类型；已经发送了多少字节
   totalBytesExpectedToSend:0, //数字类型；文件总大小（字节）
 
}

err：

类型：JSON 对象
内部字段：

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

示例代码

var ACTencentCOS= api.require('ACTencentCOS');
ACTencentCOS.beginUpload({
   path:'',
   bucket:'',
   object:''
},function(ret, err){
  alert(JSON.stringify(ret));
});

可用性

iOS、Android系统

可提供的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 ACTencentCOS= api.require('ACTencentCOS');
ACTencentCOS.abortUpload({
  object:''
},function(ret,err) {
   alert(JSON.stringify(ret));
});

可用性

iOS、Android系统

可提供的1.0.0及更高版本

getBucket

列举存储桶内的内容

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

params

bucket:

类型：字符串类型
描述：存储桶名，存储桶名称规范

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 对象
内部字段：

{
   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 ACTencentCOS= api.require('ACTencentCOS');
ACTencentCOS.getBucket({
   bucket:''
},function(ret, err){
  alert(JSON.stringify(ret));
});

可用性

iOS、Android系统

可提供的1.0.0及更高版本

getObject

下载对象文件

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

params

bucket:

类型：字符串类型
描述：存储桶名,存储桶名称规范

object:

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

savePath:

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

localFileName:

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

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
   eventType: '',    //字符串类型；回调事件状态，取值范围如下：
                     //finish：下载完成事件回调
                     //progress：下载进度事件回调
   status:true,                //布尔类型；是否下载成功
   totalBytesDownload:0,           //数字类型；已经下载了多少字节
   totalBytesExpectedToDownload:0, //数字类型；文件总大小（字节）
}

err：

类型：JSON 对象
内部字段：

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

示例代码

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

可用性

iOS、Android系统

可提供的1.0.0及更高版本

GenerateLinks

生成预签名下载链接

GenerateLinks({param},callback(ret))

param

bucket：

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

cosPath

类型：存储桶类型
描述：对象键（文件名）

callback(ret)

{
    "status":true		//布尔类型
    "downloadUrl":""	//字符串类型。下载链接
}

示例代码

var ACTencentCOS = api.require('ACTencentCOS');
var param = {
    "bucket":"examplebucket-1250000000",
    "cosPath":"1"
}
ACTencentCOS.GenerateLinks(param,function(ret){
    alert(JSON.stringify(ret));
});

可用性

iOS、Android系统

可提供的1.0.0及更高版本

deleteObject

删除单个对象

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

params

bucket:

类型：字符串类型
描述：存储桶名,存储桶名称规范

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 ACTencentCOS= api.require('ACTencentCOS');
ACTencentCOS.deleteObject({
   bucket:'',
   object:'',   
},function(ret, err){
  alert(JSON.stringify(ret));
});

可用性

iOS、Android系统

可提供的1.0.0及更高版本

deleteMultipleObject

删除多个对象

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

params

bucket:

类型：字符串类型
描述：存储桶名,存储桶名称规范

deleteObjects:

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

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
   status:true,               //布尔类型；是否成功
}

err：

类型：JSON 对象
内部字段：

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

示例代码

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

可用性

iOS、Android系统

可提供的1.0.0及更高版本

copyObject

复制文件到目标存储桶

copyObject({param},callback(ret))

param

sourceAppid：

类型：字符串类型
描述：账号APPID

sourceBucket：

类型：字符串类型
描述：源对象所在的存储桶，不需要加【-APPID】

sourceRegion：

类型：字符串类型
描述：源对象的存储桶所在的地域

sourceCosPath：

类型：字符串类型
描述：源对象的对象键（文件名）

targetBucket：

类型：字符串类型
描述：目标存储桶，需要加【-APPID】

targetCosPath：

类型：字符串类型
描述：存入的目标存储桶的对象键（文件名）

callback(ret)

{
    status:true		//布尔类型
    code:""			//数字类型；
                //200（复制成功）
}

示例代码

var ACTencentCOS= api.require('ACTencentCOS');
var param = {
    "sourceAppid":"您申请的APPID",
    "sourceBucket":"example",
    "sourceRegion":"ap-beijing",
    "sourceCosPath":"源存储桶内的对象键",
    "targetBucket":"target-1250000000",
    "targetCosPath":"目标存储桶内的对象键"
}
ACTencentCOS.copyObject(param,function(ret){
    alert(JSON.stringify(ret));
});

可用性

iOS、Android系统

可提供的1.0.0及更高版本

queryObjectMetadata

查询对象元数据

queryObjectMetadata({param},callback(ret))

param

bucket：

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

cosPath

类型：存储桶类型
描述：对象键（文件名）

callback(ret)

{
    status:true
    code:""			
    {
        accept-ranges=[bytes]
        connection=[keep-alive]
        content-length=[73928]
        content-type=[image/png]
        date=[Thu, 14 Jul 2022 09:38:46 GMT]
        etag=["cbb372bec271e34270da0da932a10182"]
        last-modified=[Wed, 13 Jul 2022 05:42:12 GMT]
        server=[tencent-cos]
        x-cos-hash-crc64ecma=[3941368982471181329]
        x-cos-request-id=[NjJjZmU0MjZfOTI0ZTQ0MGJfMWNkMmNfY2RiZGVkMw==]
    }
}

示例代码

var ACTencentCOS = api.require('ACTencentCOS');
var param = {
    "bucket":"examplebucket-1250000000",
    "cosPath":"examplebucket"
}
ACTencentCOS.queryObjectMetadata(param,function(ret){
    alert(JSON.stringify(ret));
});

可用性

iOS、Android系统

可提供的1.0.0及更高版本

是否仍需要帮助？请保持联络！

最后更新于 2024/04/24