在 APICloud 使用 COS

本文将为您介绍如何使用 APICloud 快速集成 COS 功能模块并开发跨平台应用。

APICloud 相关资源

APICloud 官网

视频教程

准备

按照 APICloud 教程创建 App，并在模块库中搜索 cosClient 模块并点击添加。

cosClient 简单使用

1. 获取模块实例

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

2. 配置密钥

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});

3. 注册 COS 服务实例

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

cosClient 接口文档

1. 注册基础服务

实例代码

var demo = api.require('cosClient');demo.registerServiceForKey({"serviceKey":"test","useHttps":true})

参数说明

请求参数

返回参数 无

2. 注册传输服务

实例代码

var demo = api.require('cosClient');demo.registerTransferManger({"serviceKey":"test","useHttps":true})

参数说明

请求参数

返回参数 无

3. 获取桶列表

实例代码

/// 模块名称 cosClient，用过模块名拿到模块实例。var demo = api.require('cosClient');demo.getBucketList(    {"serviceKey":"test"}    ,function(ret,err){        /// err 为空时,返回""        if(err != ""){            alert(err.data);        }else{            alert(ret.data);        }});

参数说明

请求参数

返回参数

{

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


4. 删除存储桶

注意：

存储桶被删除后，其对应的数据将无法再被访问。

实例代码

/// 模块名称 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);    }});

参数说明

请求参数

返回参数

删除成功

{ "result":"success"}

删除失败并返回错误信息

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

5. 创建存储桶

实例代码

/// 模块名称 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);    }});

参数说明

请求参数

返回参数

创建成功

{ "result":"success"}

创建失败并返回错误信息

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

6. 获取存储桶内容

实例代码

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);    }});

参数说明

请求参数

返回参数

获取成功

{ "result":"success", "data":{     "Contents":[         {             "ETag":"\"c57b7cd3647561480b355a92dc2e971a\"", // 根据对象内容计算出的 MD5 算法校验值，例如"22ca88419e2ed4721c23807c678adbe4c08a7880"，注意前后携带双引号             "Owner":{                 "ID":"1250000000", // 对象持有者的完整 ID，格式为qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]，例如 qcs::cam::uin/100000000001:uin/100000000001，其中100000000001为 uin                 "DisplayName":"1250000000" // 对象持有者的名称             },             "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":"examplebucket-1250000000" // 存储桶的名称，格式为 BucketName-APPID，例如 examplebucket-1250000000}}

获取失败并返回错误信息

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

7. 上传文件

实例代码

var uploadTaskId;var demo = api.require('cosClient');demo.uploadObject({    "serviceKey":"test",    "region":"ap-chengdu",    "bucket":"0-appid",    "filePath":"file://test.gif",    "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);            }        }});

参数说明

请求参数

返回参数

上传初始化阶段

{ "result":"begin", "data":{    "taskId":taskId, // 当前任务 ID，可用于取消任务。    "uploadId":uploadId // 当前上传 ID，用于续传。 }}

上传阶段

{ "result":"processing", "data":{    "totalBytesSent":totalBytesSent, // 当前传输进度。    "totalBytesExpectedToSend":totalBytesExpectedToSend // 文件总大小。 }}

完成

上传成功

{ "result":"success", "data":{} // 文件信息}

上传失败并返回错误信息

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

8.  暂停上传

实例代码

var demo = api.require('cosClient');// uploadTaskId 为从上传接口中获取，由业务保存。demo.pauseUploadObject({"taskId":uploadTaskId});

请求参数

9. 下载文件

实例代码

var downloadTaskId;var demo = api.require('cosClient');demo.registerTransferManger({"serviceKey":"test","useHttps":true})demo.downloadObject({    "serviceKey":"test",    "region":"ap-chengdu",    "bucket":"0-appid",    "localPath":"file://test.gif",    "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);            }        }});

参数说明

请求参数

返回参数

下载初始化阶段

{ "result":"begin", "data":{    "taskId":taskId, // 当前任务 ID，可用于取消任务。 }}

下载阶段

{ "result":"processing", "data":{    "totalBytesDownload":totalBytesDownload, // 当前传输进度。    "totalBytesExpectedToDownload":totalBytesExpectedToDownload // 文件总大小。 }}

完成

下载成功

{"result":"success","data":{} // 文件信息}

下载失败并返回错误信息

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

10. 暂停下载

实例代码

var demo = api.require('cosClient');// downloadTaskId 为从下载接口中获取，由业务保存。demo.pauseDownloadObject({"taskId":downloadTaskId});

请求参数

11. 获取文件信息

实例代码

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);        }});

参数说明

请求参数

返回参数

获取成功

 "result":"success", "data":{} // 文件对象信息}

获取失败并返回错误信息

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

12. 删除文件

注意：

文件被删除后，其对应的数据将无法再被访问。

实例代码

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

demo.deleteObject({
    "serviceKey":"test",
    "region":"ap-chengdu",
    "bucket":"examplebucket-1250000000",
    "object":"test.jpg"},function(ret,err){
        if(err != ""){
            alert(err.data);
        }else{
            alert(ret.result);

        }
});

参数说明

请求参数

返回参数

删除成功

{ "result":"success",}

删除失败并返回错误信息

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

13. 取消所有请求任务

实例代码

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

demo.cancelAll({
    "serviceKey":"test"
    },function(ret,err){
        if(err != ""){
            alert(err.data);
        }else{
            alert(ret.result);

        }
});

参数说明

请求参数

返回参数

无