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/8