对象存储 快速入门（鸿蒙(Harmony) SDK）

一、相关资源

·SDK 源码下载请参见 鸿蒙 SDK。

·示例 Demo 请参见 鸿蒙 SDK Demo。

·SDK 更新日志请参见 CHANGELOG。

·SDK 常见问题请参见 鸿蒙 SDK 常见问题。

·鸿蒙仓库地址请参见 @tencentcloud/cos。

二、环境配置与准备

·你需要一个鸿蒙 NEXT 应用，这个应用可以是现有的工程，也可以是新建的一个空的工程，详情请参见 鸿蒙 NEXT 应用开发指引。

·请确保你的鸿蒙 NEXT 应用目标为 API 级别12或更高版本。

三、安装 SDK

1. 运行此命令进行 SDK 依赖安装：

"dependencies": { … "@tencentcloud/cos":"1.2.5"}

2. SDK 需要网络权限，用于与 COS 服务器进行通信，请在应用模块下的 module.json5中添加如下权限声明：

…"requestPermissions":[ { "name" : "ohos.permission.INTERNET", … }
]…

四、设置 API 访问密钥

单次临时密钥临时密钥回调服务端签名回调单次请求签名固定密钥（仅测试）将单个密钥设置给具体的 CosXmlRequest（例如上传的 PutObjectRequest 等），该密钥仅用于本次 COS 操作（例如上传等）。import { QCloudCredential } from '@tencentcloud/cos';// 获取临时密钥（业务层控制获取的方式）let credential : QCloudCredential= new QCloudCredential();credential.secretID = "secretID";credential.secretKey = "secretKey";credential.token = "token";// startDate 和 expirationDate 均为 Date 类型，此处通过毫秒时间戳构造 Datecredential.startDate = new Date();credential.expirationDate = new Date();采用回调的方式给 COS SDK 提供获取临时密钥的方法，SDK 会在首次和缓存的临时密钥快过期时使用该回调重新获取临时密钥。import { CredentialCallBack, QCloudCredential } from '@tencentcloud/cos';export class Credential { /** * 获取 STS 临时密钥 */ public static sessionCredential: CredentialCallBack = (request)=>{ return new Promise((resolve, reject) => { // 首先从你的临时密钥服务器获取包含了密钥信息的响应 let httpRequest = http.createHttp(); httpRequest.request( // 请替换为具体的 sts 临时密钥获取服务 url "http://127.0.0.1/sts", { method: http.RequestMethod.GET }, (err: BusinessError, data: http.HttpResponse) => { if (!err) { const stsSessionQCloudCredentials: StsSessionQCloudCredentials = JSON.parse(data.result.toString()); let credential : QCloudCredential= new QCloudCredential(); credential.secretID = stsSessionQCloudCredentials.credentials.tmpSecretId; credential.secretKey = stsSessionQCloudCredentials.credentials.tmpSecretKey; credential.token = stsSessionQCloudCredentials.credentials.sessionToken; // 建议返回服务器时间作为签名的开始时间，避免由于用户手机本地时间偏差过大导致请求过期 // startDate 和 expirationDate 均为 Date 类型，此处通过毫秒时间戳构造 Date， // sts 响应的时间戳一般单位为秒，因此需要乘以1000，如果你的临时密钥服务响应的时间单位为毫秒，则无需乘以1000 credential.startDate = new Date(stsSessionQCloudCredentials.startTime * 1000); credential.expirationDate = new Date(stsSessionQCloudCredentials.expiredTime * 1000); httpRequest.destroy(); // 最后返回临时密钥信息对象 resolve(credential); } else { httpRequest.destroy(); reject(err); } }); }) }}/** * 临时密钥实体定义 */export class StsSessionQCloudCredentials{ credentials: StsCredentials; startTime: number; expiredTime: number; constructor(credentials: StsCredentials, startTime: number, expiredTime: number) { this.credentials = credentials; this.startTime = startTime; this.expiredTime = expiredTime; }}export class StsCredentials{ tmpSecretId: string; tmpSecretKey: string; sessionToken: string; constructor(tmpSecretId: string, tmpSecretKey: string, sessionToken: string) { this.tmpSecretId = tmpSecretId; this.tmpSecretKey = tmpSecretKey; this.sessionToken = sessionToken; }}采用回调的方式给 COS SDK 提供获取签名的方法，SDK 会在发起网络请求时调用该方法，该方法内可以做签名相关逻辑。// 定义服务端签名回调let selfSignCallBack = async (request)=>{ // 首先从你的服务器获取包含了签名信息的响应 let httpRequest = http.createHttp(); httpRequest.request( // 请替换为具体的签名获取服务 url "http://127.0.0.1/sign", { method: http.RequestMethod.GET }, (err: BusinessError, data: http.HttpResponse) => { if (!err) { // 拿到签名信息 let signData: object = JSON.parse(data.result.toString()); // 对 request 进行签名 header 的设置 request.addHeader(HttpHeader.AUTHORIZATION, signData['authorization']) if(signData['securityToken']){ request.addHeader("x-cos-security-token", signData['securityToken']) } httpRequest.destroy(); } else { httpRequest.destroy(); } });}将单个请求签名设置给具体的 CosXmlRequest（例如上传的 PutObjectRequest 等），该签名仅用于本次 COS 操作（例如上传等）。// 获取签名数据（业务层控制获取的方式）
let authorization: string = "authorization";
let token: string = "token";
let tokenName: string = "x-cos-security-token";你可以使用腾讯云的永久密钥来进行开发阶段的本地调试。由于该方式存在泄露密钥的风险，请务必在上线前替换为临时密钥的方式。import { CredentialCallBack, QCloudCredential } from '@tencentcloud/cos';
export class Credential { /** * 获取固定密钥 仅在测试时使用 */ public static constCredential: CredentialCallBack = (request)=>{ return new Promise((resolve, reject) => { let credential : QCloudCredential= new QCloudCredential(); // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140 credential.secretID = "SECRETID"; // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140 credential.secretKey = "SECRETKEY"; resolve(credential); }) }
}

五、初始化 COS 服务

调用 CosXmlBaseService.initDefaultService 进行 COS 服务初始化之后就可以调用 CosXmlBaseService.default() 获取到默认的 COS 服务进行 COS 操作了。

COS 服务也支持自行实例化 CosXmlBaseService 进行 COS 操作（不建议每次 COS 操作都实例化一个 CosXmlBaseService）。

单次临时密钥临时密钥回调服务端签名回调单次请求签名固定密钥（仅测试）1. 初始化默认的 Service，可以不设置临时密钥回调。import { CosXmlBaseService, CosXmlServiceConfig } from '@tencentcloud/cos';
// 服务配置let cosXmlServiceConfig = new CosXmlServiceConfig("ap-guangzhou");// 初始化默认的 ServiceCosXmlBaseService.initDefaultService( this.context.getApplicationContext(), cosXmlServiceConfig // 可以不设置临时密钥回调)2. 给 CosXmlRequest 设置 credential 并使用。单次临时密钥的优先级高于 CosXmlBaseService 中初始化配置的临时密钥回调，因此 CosXmlBaseService 中配置的临时密钥回调不会影响单次临时密钥的设置，直接给 CosXmlRequest 设置 credential 即可。import { CosXmlBaseService, PutObjectRequest, UploadTask } from '@tencentcloud/cos';
// 任何 CosXmlRequest 都支持这种方式，例如上传 PutObjectRequest、下载 GetObjectRequest、删除 DeleteObjectRequest 等// 以下用上传进行示例let putRequest = new PutObjectRequest("examplebucket-1250000000", "exampleobject.txt", "本地文件路径");// credential 为第一步“初始化密钥”中获取到的单次临时密钥putRequest.credential = credential;let task: UploadTask = CosXmlBaseService.default().upload(putRequest);task.start();初始化默认的 Service。import { CosXmlBaseService, CosXmlServiceConfig } from '@tencentcloud/cos';
// 服务配置let cosXmlServiceConfig = new CosXmlServiceConfig("ap-guangzhou");// 初始化默认的 ServiceCosXmlBaseService.initDefaultService( this.context.getApplicationContext(), cosXmlServiceConfig, // 第一步“初始化密钥”中获取到的临时密钥回调 Credential.sessionCredential)初始化默认的 Service。import { CosXmlBaseService, CosXmlServiceConfig } from '@tencentcloud/cos';// 服务配置let cosXmlServiceConfig = new CosXmlServiceConfig("ap-guangzhou");// 初始化默认的 ServiceCosXmlBaseService.initDefaultService( this.context.getApplicationContext(), cosXmlServiceConfig)// 第一步“初始化密钥”中获取到的服务端签名回调CosXmlBaseService.default().setSelfSignCallBack(selfSignCallBack);单次请求签名的优先级高于密钥进行的签名，因此设置的密钥不会影响单次请求签名的设置，直接给 CosXmlRequest 通过 setSign 设置签名即可。import { CosXmlBaseService, PutObjectRequest, UploadTask } from '@tencentcloud/cos';// 任何 CosXmlRequest 都支持这种方式，例如上传 PutObjectRequest、下载 GetObjectRequest、删除 DeleteObjectRequest 等// 以下用上传进行示例let putRequest = new PutObjectRequest("examplebucket-1250000000", "exampleobject.txt", "本地文件路径");// authorization、token、tokenName 为第一步“初始化密钥”中获取到的单次签名信息putRequest.setSign(authorization, stoken, tokenName);let task: UploadTask = CosXmlBaseService.default().upload(putRequest);task.start();初始化默认的 Service。由于该方式存在泄露密钥的风险，请务必在上线前替换为临时密钥的方式。// 服务配置let cosXmlServiceConfig = new CosXmlServiceConfig("ap-guangzhou");// 初始化默认的 ServiceCosXmlBaseService.initDefaultService( this.context.getApplicationContext(), cosXmlServiceConfig, // 第一步“初始化密钥”中获取到的固定密钥回调 Credential.constCredential
)

六、参数说明

CosXmlServiceConfig 用于配置 COS 服务，其主要成员说明如下：

七、访问 COS 服务

上传对象下载对象

注意：说明：

注意：更多完整示例，请前往 GitHub 查看。

八、授权说明

在你进行 授权策略 时，action 请参考如下示例。

{ "version": "2.0", "statement": [ { "action": [ //head 操作 "name/cos:HeadObject", //简单上传操作 "name/cos:PutObject", //分块上传：初始化分块操作 "name/cos:InitiateMultipartUpload", //分块上传：List 已上传分块操作 "name/cos:ListParts", //分块上传：上传分块操作 "name/cos:UploadPart", //分块上传：完成所有分块上传操作 "name/cos:CompleteMultipartUpload", //取消分块上传操作 "name/cos:AbortMultipartUpload" ], "effect": "allow", "resource": [ "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*" ] } ]}

对象存储的更多 action，请参见 支持 CAM 的业务接口。

九、上传示例

import { CosXmlBaseService, HttpProgress, PutObjectRequest, UploadTask, TransferConfig, CosError } from '@tencentcloud/cos';import { CosXmlUploadTaskResult } from '@tencentcloud/cos/src/main/ets/transfer/UploadTask'// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketlet bucket = "examplebucket-1250000000";//对象在存储桶中的位置标识符，即称对象键let cosPath = "exampleobject.txt"; //本地文件路径let srcPath = "本地文件路径"; //若存在初始化分块上传的 UploadId，则赋值对应的 _uploadId 值用于续传；否则，赋值 undefinedlet _uploadId: string | undefined = undefined;// 上传配置let transferConfig = new TransferConfig();let putRequest = new PutObjectRequest(bucket, cosPath, srcPath);let task: UploadTask = CosXmlBaseService.default().upload(putRequest, _uploadId, transferConfig);// 上传进度回调task.onProgress = (progress: HttpProgress) => { // progress.complete 为当前已上传大小 // progress.target 为总大小};// http 请求耗时回调task.onTimeInfo = (request: CosXmlRequest, timeInfo: rcp.TimeInfo) => { // request 当前请求信息 // timeInfo 耗时信息}task.onResult = { // 上传成功回调 onSuccess: (request, result: CosXmlUploadTaskResult) => { // todo 上传成功后的逻辑 }, //上传失败回调 onFail: (request, error: CosError) => { // todo 上传失败后的逻辑 }}//初始化完成回调task.initCallBack = (uploadId) =>{ //用于下次续传上传的 uploadId _uploadId = uploadId;}//开始上传task.start();//暂停任务// task.pause();//恢复任务// task.resume();//取消任务// task.cancel();

TransferConfig 用于配置 COS 上传服务，其主要参数说明如下：

注意：说明：

十、授权说明

在你进行 授权策略 时，action 请参考如下示例。

{ "version": "2.0", "statement": [ { "action": [ //head 操作 "name/cos:HeadObject", //下载操作 "name/cos:GetObject", ], "effect": "allow", "resource": [ "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*" ] } ]}

对象存储的更多 action，请参见 支持 CAM 的业务接口。

十一、下载示例

高级接口支持暂停、恢复以及取消下载请求，同时支持断点下载功能。

你只需要保证 bucket、cosPath、savePath 参数一致，SDK 便会从上次已经下载的位置继续下载。

import { CosXmlBaseService, HttpProgress, GetObjectRequest, DownloadTask, CosError } from '@tencentcloud/cos';import { CosXmlDownloadTaskResult } from '@tencentcloud/cos/src/main/ets/transfer/DownloadTask'// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucketlet bucket = "examplebucket-1250000000";//对象在存储桶中的位置标识符，即称对象键let cosPath = "exampleobject.txt"; //本地文件下载路径，如果文件不存在 sdk 会自动创建let downLoadPath = "本地文件路径"; let getRequest = new GetObjectRequest(bucket, cosPath, downLoadPath);let task: DownloadTask = CosXmlBaseService.default().download(getRequest);// 下载进度回调task.onProgress = (progress: HttpProgress) => { // progress.complete 为当前已下载大小 // progress.target 为总大小};task.onResult = { // 下载成功回调 onSuccess: (request, result: CosXmlDownloadTaskResult) => { // todo 下载成功后的逻辑 }, //下载失败回调 onFail: (request, error: CosError) => { // todo 下载失败后的逻辑 }}//开始下载task.start();//暂停任务// task.pause();//恢复任务// task.resume();//取消任务// task.cancel();

十二、常见问题

你在使用过程中可能会碰到的一些常见问题，相关的解决办法可参见 鸿蒙(Harmony) SDK 常见问题。