cosClient

概述

关于腾讯云对象存储

腾讯云对象存储（COS）是由腾讯云推出的无目录层次结构、无数据格式限制，可容纳海量数据且支持 HTTP/HTTPS 协议访问的分布式存储服务。腾讯云COS的存储桶空间无容量上限，无需分区管理，适用于CDN数据分发、数据万象处理或大数据计算与分析的数据湖等多种场景。

了解更多腾讯云COS相关内容请到腾讯云对象存储COS产品页。

注册及购买

注册

您可以在这里注册腾讯云账号，详情参见注册腾讯云教程。

如您有任何问题，欢迎联系腾讯云官方。

免费体验

前往腾讯云免费体验馆搜索【对象存储 COS】即可免费体验。

最新活动

腾讯云COS产品最新活动，首单低至1元起，立即选购

了解更多购买信息

了解腾讯云对象存储COS产品定价请参考腾讯云对象存储COS产品定价

快速入门

获取插件实例

var demo = api.require('cosClient');

配置密钥

COS SDK 插件提供两种密钥配置方法：

  • 临时密钥（推荐使用） 在 script 标签中实现如下方法：
function refreshCredentail() {
    // 通过请求接口获取临时秘钥 secretID 、secretKey、token、startDate、expirationDate；
    // 拼接成如下格式 返回即可；
    return  "secretID=***&secretKey=***&token=***&startDate=***&expirationDate=***";
}
  • 永久密钥 在注册服务之前设置永久密钥
var demo = api.require('cosClient');
demo.setupPermanentCredentail({"secretID":secretID,"secretKey":secretKey});

注册COS服务实例

demo.registerTransferManger({"serviceKey":"test","useHttps":true})

接口文档

注册基础服务

  • 实例代码
var demo = api.require('cosClient');
demo.registerServiceForKey({"serviceKey":"test","useHttps":true})
  • 参数说明

请求参数

参数名 类型 说明 是否必传
serviceKey 字符串 cos服务实例唯一标识，不传则注册默认服务 否
appId 字符串 您的AppID 否
region 字符串 服务地域名称,可用的服务地域名称请查看官网https://www.qcloud.com/document/product/436/6224 中提供的地域，这里填入官网里提供的地域简称，例如ap-beijing等。 否
isPrefixURL 布尔值 否
timeOut 整型 超时时间 否
serviceName 字符串 服务的基础名称, 默认值为: myqcloud.com 否
suffix 字符串 自定义域名：http://bucketname.suffix 未指定该参数，该存储桶host为 http://bucketname.**** 。 指定该参数为testsuffix，该存储桶host为 http://bucketname.testsuffix.**** 。 在ios 端生效。 否
useHttps 布尔值 是否使用https 否
userAgent 字符串 设置自定义ua 否
host 字符串 自定义域名，不包含“http://”， 在安卓端生效 否
port 整型 自定义端口， 在安卓端生效 否

返回参数

无

注册传输服务

  • 实例代码
var demo = api.require('cosClient');
demo.registerTransferManger({"serviceKey":"test","useHttps":true})
  • 参数说明

请求参数

参数名 类型 说明 是否必传
serviceKey 字符串 cos服务实例唯一标识，不传则注册默认服务 否
appId 字符串 您的AppID 否
region 字符串 服务地域名称,可用的服务地域名称请查看官网https://www.qcloud.com/document/product/436/6224 中提供的地域，这里填入官网里提供的地域简称，例如ap-beijing等。 否
isPrefixURL 布尔值 否
timeOut 整型 超时时间 否
serviceName 字符串 服务的基础名称, 默认值为: myqcloud.com 否
suffix 字符串 自定义域名：http://bucketname.suffix 未指定该参数，该存储桶host为 http://bucketname.**** 。 指定该参数为testsuffix，该存储桶host为 http://bucketname.testsuffix.**** 。在ios 端生效。 否
useHttps 布尔值 是否使用https 否
userAgent 字符串 设置自定义ua 否
host 字符串 自定义域名，不包含“http://”， 在安卓端生效 否
port 整型 自定义端口， 在安卓端生效 否

返回参数

无

获取桶列表

  • 实例代码
/// 插件名称 cosClient，用过插件名拿到插件实例。
var demo = api.require('cosClient');
demo.getBucketList(
    {"serviceKey":"test"}
    ,function(ret,err){
        /// err 为空时,返回""
        if(err != ""){
            alert(err.data);
        }else{
            alert(ret.data);
        }
});
  • 参数说明

请求参数

参数名 类型 说明 是否必传
serviceKey 字符串 cos服务实例唯一标识，不传则使用默认服务实例进行网络请求 否

返回参数

{
    "result":"success",
    "data":{
    buckets =     [ /// 桶列表
                {
            createDate = "2021-06-02T07:33:33Z"; /// 创建时间
            location = "ap-chengdu"; /// 地域
            name = "0-1253960454";  /// 桶名称
            type = ""; 存储桶类型
        }];
    owner =     {
        displayName = 2832742109; /// 持有者的名称
        id = "qcs::cam::uin/2832742109:uin/2832742109"; /// 持有者 ID，
    };
}
}

删除存储桶

  • 实例代码
/// 插件名称 cosClient，用过插件名拿到插件实例。
var demo = api.require('cosClient');
demo.deleteBucket({
    "serviceKey":"test",
    "region":"ap-chengdu",
    "bucket":"0-appid",},
    function(ret,err){
    /// err 为空时,返回""
    if(err != ""){
        alert(err.data);
    }else{
        alert(ret.data);
    }
});
  • 参数说明

请求参数

参数名 类型 说明 是否必传
serviceKey 字符串 cos服务实例唯一标识，不传则使用默认服务实例进行网络请求 否
region 字符串 桶地域 是
bucket 字符串 存储桶名称，格式为 BucketName-APPID 是

返回参数 删除成功

{
    "result":"success"
}

or

删除失败并返回错误信息

{
    "result":"error",
    "error":{} /// 错误信息
}

创建存储桶

  • 实例代码
/// 插件名称 cosClient，用过插件名拿到插件实例。
var demo = api.require('cosClient');
demo.createBucket({
"serviceKey":"test",
"name":"apicloudtest",
"appId":"appId",
"region":"ap-chengdu"},function(ret,err){
    /// err 为空时,返回""
    if(err != ""){
        alert(err.data);
    }else{
        alert(ret.data);
    }
});
  • 参数说明

请求参数

参数名 类型 说明 是否必传
serviceKey 字符串 cos服务实例唯一标识，不传则使用默认服务实例进行网络请求 否
name 字符串 桶名称不包含appid 是
appId 字符串 用户appid 是
region 字符串 桶地域 是
accessControlList 字符串 定义 bucket 的acl属性。有效值：private，public-read-write，public-read；默认值：private 否
readAccount 字符串 赋予被授权者读的权限,id="OwnerUin"； 否
writeAccount 字符串 赋予被授权者写的权限。格式: id="OwnerUin"； 否
readWriteAccount 字符串 赋予被授权者读写权限。格式: id="OwnerUin"； 否
enableMAZ 布尔值 是否使用多AZ，默认否 否

返回参数 删除成功

{
    "result":"success"
}

or

创建失败并返回错误信息

{
    "result":"error",
    "error":{} /// 错误信息
}

获取存储桶内容

  • 实例代码
var demo = api.require('cosClient');
demo.listBucketContent({"serviceKey":"test","bucket":"0-appid","region":"ap-chengdu"},function(ret,err){
    /// err 为空时,返回""
    if(err != ""){
        alert(err.data);
    }else{
        alert(ret.data);
    }
});
  • 参数说明

请求参数

参数名 类型 说明 是否必传
serviceKey 字符串 cos服务实例唯一标识，不传则使用默认服务实例进行网络请求 否
region 字符串 桶地域 是
bucket 字符串 存储桶名称，格式为 BucketName-APPID 是
prefix 字符串 前缀匹配，用来规定返回的文件前缀地址 否
delimiter 字符串 定界符为一个符号，如果有 Prefix，则将 Prefix 到 delimiter 之间的相同路径归为一类，定义为Common Prefix，然后列出所有 Common Prefix。如果没有 Prefix，则从路径起点开始 否
marker 字符串 默认以UTF-8二进制顺序列出条目，所有列出条目从marker开始 否
maxKeys 字符串 单次返回的最大条目数量，默认1000 否

返回参数

  • 成功
{
    "result":"success",
    "data":{
        "Contents":[
            {
                "ETag":"\"c57b7cd3647561480b355a92dc2e971a\"", // 根据对象内容计算出的 MD5 算法校验值，
例如"22ca88419e2ed4721c23807c678adbe4c08a7880"，注意前后携带双引号
                "Owner":{
                    "ID":"1253960454", // 对象持有者的完整 ID，格式为qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]，
例如 qcs::cam::uin/100000000001:uin/100000000001，其中100000000001为 uin
                    "DisplayName":"1253960454" // 对象持有者的名称
                },
                "StorageClass":"STANDARD", // 类型标准
                "Key":"02_常用语法.pdf", // 文件名
                "LastModified":"2023-01-09T11:15:25.000Z", // 最后修改时间
                "Size":816838 // 文件大小
            }
        ],
        "MaxKeys":1000, 
        "IsTruncated":"False",// 响应请求条目是否被截断，值为 'true' 或者 'false'
        "CommonPrefixes":[  // 将 Prefix 到 delimiter 之间的相同路径归为一类，定义为 Common Prefix
            {
                "Prefix":"1\/" // 单条 Common Prefix 的前缀
            }
        ],
        "Delimiter":"\/", // 定界符
        "Name":"0-1253960454" // 存储桶的名称，格式为 BucketName-APPID，例如 examplebucket-1250000000
}
}

or

  • 获取失败并返回错误信息
{
    "result":"error",
    "error":{} /// 错误信息
}

上传文件

  • 实例代码
var uploadTaskId;
var demo = api.require('cosClient');
demo.uploadObject({
    "serviceKey":"test",
    "region":"ap-chengdu",
    "bucket":"0-appid",
    "filePath":"file://test.jpg",
    "object":"test.gif"},function(ret,err){
        if(err != ""){
            alert(err.data);
        }else{
            if(ret.result == "begin"){
                // 在begin时，拿到taskId，用于取消任务。
                uploadTaskId = JSON.parse(ret.data).taskId;
                alert(uploadTaskId);
            }
        }
});
  • 参数说明

请求参数

参数名 类型 说明 是否必传
serviceKey 字符串 cos服务实例唯一标识，不传则使用默认服务实例进行网络请求 否
region 字符串 桶地域 是
bucket 字符串 存储桶名称，格式为 BucketName-APPID 是
object 字符串 上传到服务端的文件名 是
filePath 字符串 本地文件路径 是
uploadId 字符串 在第一次上传文件时无需设置，再次续传时需要设置 否
stroageClass 字符串 对象的存储级别 否
trafficLimit 字符串 针对本次下载行流量控制的限速值，必须为数字，单位默认为 bit/s。限速值设置范围为819200 - 838860800,即100KB/s - 100MB/s，如果超出该范围将返回400错误 否
enableVerification 字符串 是否在上传完成以后，将 COS 返回的文件MD5与本地文件算出来的md5进行校验。默认开启，如果校验出错，文件仍然会被上传到 COS, 不过我们会在本地抛出校验失败的error。 否

返回参数

  • 上传初始化阶段
{
    "result":"begin",
    "data":{
       "taskId":taskId, // 当前任务id，用户取消任务。
       "uploadId":uploadId // 当前上传id，用于续传。
    }
}
  • 上传阶段
{
    "result":"processing",
    "data":{
       "totalBytesSent":totalBytesSent, // 当前传输进度。
       "totalBytesExpectedToSend":totalBytesExpectedToSend // 文件总大小。
    }
}
  • 完成
  1. 成功
{
    "result":"success",
    "data":{} // 文件信息
}
  1. 错误
{
    "result":"error",
    "error":{} /// 错误信息
}

暂停上传

  • 实例代码
var demo = api.require('cosClient');
// uploadTaskId 为从上传接口中获取 由业务保存。
demo.pauseUploadObject({"taskId":uploadTaskId});
  • 请求参数
参数名 类型 说明 是否必传
taskId 字符串 上传接口中获取 由业务保存，用于取消当前任务 否

下载文件

  • 实例代码
var downloadTaskId;
var demo = api.require('cosClient');
demo.registerTransferManger({"serviceKey":"test","useHttps":true})
demo.uploadObject({
    "serviceKey":"test",
    "region":"ap-chengdu",
    "bucket":"0-appid",
    "filePath":"0-1253960454",
    "object":"test.gif"},function(ret,err){
        if(err != ""){
            alert(err.data);
        }else{
            if(ret.result == "begin"){
                // 在begin时，拿到taskId，用于取消任务。
                downloadTaskId = JSON.parse(ret.data).taskId;
                alert(downloadTaskId);
            }
        }
});
  • 参数说明

请求参数

参数名 类型 说明 是否必传
serviceKey 字符串 cos服务实例唯一标识，不传则使用默认服务实例进行网络请求 否
region 字符串 桶地域 是
bucket 字符串 存储桶名称，格式为 BucketName-APPID 是
object 字符串 服务端的文件名 是
versionId 字符串 文件版本号 否
localPath 字符串 本地文件路径 是
trafficLimit 字符串 针对本次下载行流量控制的限速值，必须为数字，单位默认为 bit/s。限速值设置范围为819200 - 838860800,即100KB/s - 100MB/s，如果超出该范围将返回400错误 否
enableVerification 字符串 是否在上传完成以后，将 COS 返回的文件MD5与本地文件算出来的md5进行校验。默认开启，如果校验出错，文件仍然会被上传到 COS, 不过我们会在本地抛出校验失败的error。默认校验。 否

返回参数

  • 下载初始化阶段
{
    "result":"begin",
    "data":{
       "taskId":taskId, // 当前任务id，用户取消任务。
    }
}
  • 下载阶段
{
    "result":"processing",
    "data":{
       "totalBytesDownload":totalBytesDownload, // 当前传输进度。
       "totalBytesExpectedToDownload":totalBytesExpectedToDownload // 文件总大小。
    }
}
  • 完成
  1. 成功
{
    "result":"success",
    "data":{} // 文件信息
}
  1. 错误
{
    "result":"error",
    "error":{} /// 错误信息
}

暂停下载

  • 实例代码
var demo = api.require('cosClient');
// uploadTaskId 为从下载接口中获取 由业务保存。
demo.pauseDownloadObject({"taskId":downloadTaskId});
  • 请求参数
参数名 类型 说明 是否必传
taskId 字符串 下载接口中获取 由业务保存，用于取消当前任务 否

获取文件信息

  • 实例代码
var demo = api.require('cosClient');
demo.headObject({
    "serviceKey":"test",
    "region":"ap-chengdu",
    "bucket":"0-appid",
    "object":"test.jpg"},function(ret,err){
        if(err != ""){
            alert(err.data);
        }else{
            alert(ret.data);
        }
});
  • 参数说明

请求参数

参数名 类型 说明 是否必传
serviceKey 字符串 cos服务实例唯一标识，不传则使用默认服务实例进行网络请求 否
region 字符串 桶地域 是
bucket 字符串 存储桶名称，格式为 BucketName-APPID 是
object 字符串 服务端的文件名 是
versionId 字符串 文件版本号 否

返回参数

  • 成功
{
    "result":"success",
    "data":{} // 文件对象信息
}
  • 失败
{
    "result":"error",
    "error":{} /// 错误信息
}

删除文件

  • 实例代码
var demo = api.require('cosClient');
demo.deleteObject({
    "serviceKey":"test",
    "region":"ap-chengdu",
    "bucket":"0-1253960454",
    "object":"test.jpg"},function(ret,err){
        if(err != ""){
            alert(err.data);
        }else{
            alert(ret.result);
            
        }
});
  • 参数说明

请求参数

参数名 类型 说明 是否必传
serviceKey 字符串 cos服务实例唯一标识，不传则使用默认服务实例进行网络请求 否
region 字符串 桶地域 是
bucket 字符串 桶名称-AppId 是
object 字符串 服务端的文件名 是
versionId 字符串 文件版本号 否

返回参数

  • 成功
{
    "result":"success",
}
  • 失败
{
    "result":"error",
    "error":{} /// 错误信息
}

取消所有请求任务

  • 实例代码
var demo = api.require('cosClient');
demo.cancelAll({
    "serviceKey":"test"
    },function(ret,err){
        if(err != ""){
            alert(err.data);
        }else{
            alert(ret.result);
            
        }
});
  • 参数说明

请求参数

|  参数名   | 类型  | 说明 | 是否必传 |
|  ----  | ----  | --- | --- |
| serviceKey  | 字符串 | cos服务实例唯一标识，取消对应服务实例发起的网络请求 | 否 |

返回参数

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