帮你快速理解、总结文档立即下载
文档中心>云点播>开发指南>媒体上传>客户端上传>鸿蒙上传示例

鸿蒙上传示例

最近更新时间：2026-01-14 14:48:32
我的收藏

本页目录：

本文档描述了如何在鸿蒙应用中集成腾讯云点播 UGC 视频上传功能。
运行实例可参考 示例 Demo。

整体流程



依赖配置

在 oh-package.json5 中添加 COS 鸿蒙 SDK，可以参考 COS 鸿蒙 的集成方式：
{
  "dependencies": {
    "@tencentcloud/cos": "^x.x.x"
  }
}

权限配置

在 entry/src/main/module.json5 中声明必要权限：
{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:internet_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "always"
        }
      }
    ]
  }
}
权限
说明
ohos.permission.INTERNET
网络访问权限，用于上传文件和请求接口（必须）。

注意事项

签名安全：signature 应由业务后台生成，不要在客户端硬编码。
文件路径：COS SDK 需要应用沙箱内的绝对路径，需先将相册文件复制到沙箱。
断点续传：保存 vodSessionKey，重新上传时传入可实现断点续传。
超时配置：大文件上传建议适当增加 readTimeout 和 connectTimeout。
COS 服务初始化：initDefaultService 只需调用一次，后续上传无需重复初始化。

步骤详解

步骤 1：准备视频文件

视频文件可来源于相册选择、相机录制、本地文件等，由业务自行实现。
上传前需准备以下信息：
字段
类型
说明
absolutePath
string
视频文件的沙箱绝对路径。
fileName
string
文件名。
fileType
string
文件类型（如 mp4）。
fileSize
number
文件大小（字节）。
说明：
COS SDK 需要应用沙箱内的绝对路径，如果视频来源于相册等外部路径，需先复制到应用沙箱目录。

步骤 2：ApplyUploadUGC - 申请上传

请求点播后台获取上传凭证和 COS 配置信息。
接口地址：POST https://vod2.qcloud.com/v3/index.php?Action=ApplyUploadUGC
请求参数：
参数
类型
必填
说明
signature
string
是
上传签名（由业务后台生成）。
videoName
string
是
视频文件名。
videoType
string
是
视频类型（如 mp4）。
videoSize
number
是
视频大小（字节）。
clientReportId
string
是
客户端标识。
clientVersion
string
是
客户端版本。
vodSessionKey
string
否
断点续传时使用。
请求示例：
const reqUrl = "https://vod2.qcloud.com/v3/index.php?Action=ApplyUploadUGC";

const params = {
  signature: "您的签名",
  videoName: videoInfo.fileName,
  videoType: videoInfo.fileType,
  videoSize: videoInfo.fileSize,
  clientReportId: "custom_key",
  clientVersion: "1.3.1.0"
};

// 发起 POST 请求
const response = await httpPost(reqUrl, JSON.stringify(params));
响应示例：
{
  "code": 0,
  "message": "success",
  "data": {
    "storageRegionV5": "ap-guangzhou",
    "storageAppId": "125xxxxxxx",
    "storageBucket": "bucket-name",
    "vodSessionKey": "VodSessionKey_xxx",
    "timestamp": 1704067200,
    "tempCertificate": {
      "secretId": "AKIDxxxxxxxx",
      "secretKey": "xxxxxxxx",
      "token": "xxxxxxxx",
      "expiredTime": 1704070800
    },
    "video": {
      "storagePath": "/path/to/video.mp4"
    }
  }
}

步骤 3：使用 COS SDK 上传视频

从 ApplyUploadUGC 响应中提取配置，初始化 COS SDK 并上传。

3.1 初始化 COS 服务（只需调用一次）

建议在页面 aboutToAppear 生命周期或应用启动时初始化：
import {
  QCloudCredential,
  CosXmlBaseService,
  CosXmlServiceConfig,
  PutObjectRequest,
  TransferConfig,
  UploadTask,
  HttpProgress,
  CosXmlUploadTaskResult,
  CosError
} from '@tencentcloud/cos';

// 在页面初始化时调用
aboutToAppear(): void {
  this.initCosService();
}

private initCosService(): void {
  const cosXmlServiceConfig = new CosXmlServiceConfig("");
  cosXmlServiceConfig.readTimeout = 120 * 1000;
  cosXmlServiceConfig.connectTimeout = 120 * 1000;
  CosXmlBaseService.initDefaultService(context, cosXmlServiceConfig);
}

3.2 执行上传

// 解析响应数据
const dataJson = response["data"];
const certJson = dataJson["tempCertificate"];
const videoJson = dataJson["video"];

// 构建临时凭证
const credential = new QCloudCredential();
credential.secretID = certJson["secretId"];
credential.secretKey = certJson["secretKey"];
credential.token = certJson["token"];
credential.startDate = new Date(dataJson["timestamp"] * 1000);
credential.expirationDate = new Date(certJson["expiredTime"] * 1000);

// 获取上传参数
const cosAppId = dataJson["storageAppId"];
const cosHost = dataJson["storageBucket"] + "-" + cosAppId;
const cosVideoPath = videoJson["storagePath"].replace(/^\\//, ''); // 去除开头斜杠
const vodSessionKey = dataJson["vodSessionKey"]; // 保存用于 CommitUploadUGC

// 创建上传任务并设置凭证
const putRequest = new PutObjectRequest(cosHost, cosVideoPath, localVideoPath);
putRequest.credential = credential;
const task: UploadTask = CosXmlBaseService.default().upload(putRequest, undefined, new TransferConfig());

// 监听上传进度
task.onProgress = (progress: HttpProgress) => {
  const percent = (progress.complete / progress.target) * 100;
  console.info(`上传进度: ${percent.toFixed(1)}%`);
};

// 监听上传结果
task.onResult = {
  onSuccess: (request, result: CosXmlUploadTaskResult) => {
    console.info('上传成功');
    // 调用 CommitUploadUGC
    commitUploadUGC(vodSessionKey);
  },
  onFail: (request, error: CosError) => {
    console.error(`上传失败: ${error.message}`);
  }
};

// 开始上传
task.start();
说明：
更多 COS 鸿蒙 SDK 接口可参考 COS 鸿蒙 SDK 文档。
上传失败时可参考 错误码文档。

步骤 4：CommitUploadUGC - 确认上传

上传完成后，调用此接口确认上传并获取媒资信息。
接口地址：POST https://vod2.qcloud.com/v3/index.php?Action=CommitUploadUGC
请求参数：
参数
类型
必填
说明
signature
string
是
上传签名。
vodSessionKey
string
是
ApplyUploadUGC 返回的会话标识。
clientReportId
string
是
客户端标识。
clientVersion
string
是
客户端版本。
请求示例：
const reqUrl = "https://vod2.qcloud.com/v3/index.php?Action=CommitUploadUGC";

const params = {
  signature: "您的签名",
  vodSessionKey: vodSessionKey,
  clientReportId: "custom_key",
  clientVersion: "1.3.1.0"
};

const response = await httpPost(reqUrl, JSON.stringify(params));
响应示例：
{
  "code": 0,
  "message": "success",
  "data": {
    "fileId": "52858907xxxxxx",
    "video": {
      "url": "https://xxx.vod2.myqcloud.com/xxx/xxx.mp4"
    }
  }
}
解析响应获取媒资信息：
if (response["code"] === 0) {
  const dataJson = response["data"];
  const videoJson = dataJson["video"];
  
  const videoFileId = dataJson["fileId"];  // 视频文件 ID
  const videoPlayUrl = videoJson["url"];   // 视频播放地址
  
  console.info(`上传成功！FileId: ${videoFileId}, URL: ${videoPlayUrl}`);
}

关键配置项

配置项
说明
signature
上传签名，需由业务后台生成，参考 签名生成文档。
clientReportId
自定义客户端标识，用于日志追踪。
clientVersion
客户端版本号。

相关文档

个人信息保护规则
合规使用指南
COS 鸿蒙 SDK
签名生成文档
中国站