帮你快速理解、总结文档立即下载

任务操作

最近更新时间:2026-10-20 16:24:02
本文档已由 AI 辅助审校
我的收藏

简介

本文档提供关于数据万象媒体处理任务的相关 API 概览以及 SDK 示例代码,此处以转码任务举例。
注意:
该功能需要 COS Java SDK v5.6.269及以上版本。旧版本 SDK 该接口可能未覆盖或缺少更新参数,使用时建议升级到 最新版本。
API
操作名
操作描述
创建任务
创建一个媒体处理任务。
删除任务
删除一个媒体处理任务,正在处理中的任务不可删除。
查询任务
查询一个任务。
查询任务列表
查询队列中的任务列表。

基本操作

创建任务

功能说明

创建一个媒体处理任务。

方法原型

public MediaJobResponseV2 createMediaJobsV2(MediaJobsRequestV2 req);

参数说明

Request 中的具体数据描述如下:
节点名称(关键字)
父节点
描述
类型
必选
Tag
Request
创建任务的 Tag:Animation 动图任务,Snapshot 截图任务,Transcode 转码任务,SmartCover 智能封面任务。
String
是
Input
Request
待操作的媒体信息。
Container
是
Operation
Request
操作规则。
Container
是
QueueId
Request
任务所在的队列 ID 开通预览服务后自动生成,请在 数据万象控制台 中查询。
String
否
QueueType
Request
任务所在的队列类型,设置为 SpeedTranscoding 表示为开启倍速转码。
String
否
CallBackType
Request
任务回调类型,Url、Kafka 或 TDMQ,默认 Url,优先级高于队列的回调类型。
String
否
CallBack
Request
任务回调地址,优先级高于队列的回调地址。设置为 no 时,表示队列的回调地址不产生回调。
String
否
CallBackMqConfig
Request
任务回调 TDMQ 配置,当 CallBackType 为 TDMQ 时必填。详情见 CallBackMqConfig。
Container
否
CallBackKafkaConfig
Request
任务回调 Kafka 配置,当 CallBackType 为 Kafka 时必填。详情见 KafkaConfig。
Container
否
Container 类型 Input 的具体数据描述如下:
节点名称(关键字)
父节点
描述
类型
必选
Object
Request.Input
媒体文件的名字。
String
是
Container 类型 Operation 的具体数据描述如下:
节点名称(关键字)
父节点
描述
类型
必选
Animation
Request.Operation
指定该任务的参数,同创建动图模板 CreateMediaTemplate 接口中的 Request.Animation。
Container
否
Snapshot
Request.Operation
指定该任务的参数,同创建截图模板 CreateMediaTemplate 接口中的 Request.Snapshot。
Container
否
Transcode
Request.Operation
指定该任务的参数,同创建转码模板 CreateMediaTemplate 接口中的 Request.Transcode。
Container
否
Watermark
Request.Operation
指定该任务的参数,同创建水印模板 CreateMediaTemplate 接口中的 Request.Watermark。
Container
否
SmartCover
Request.Operation
当 Tag 为 SmartCover 时有效,目前为空。
Container
否
TemplateId
Request.Operation
指定的模板 ID。
String
否
Output
Request.Operation
结果输出地址。
Container
是
注意:
优先使用 TemplateId,无 TemplateId 时使用对应任务类型的参数。
Container 类型 Animation 的具体数据描述如下:
节点名称(关键字)
父节点
描述
类型
必选
Container
Request.Operation.Animation
同动图模板 CreateMediaTemplate 接口中的 Request.Container。
Container
否
Video
Request.Operation.Animation
同动图模板 CreateMediaTemplate 接口中的 Request.Video。
Container
否
TimeInterval
Request.Operation.Animation
同动图模板 CreateMediaTemplate 接口中的 Request.TimeInterval。
Container
否
Container 类型 Output 的具体数据描述如下:
节点名称(关键字)
父节点
描述
类型
必选
Region
Request.Operation.Output
存储桶的地域。
String
是
Bucket
Request.Operation.Output
存储结果的存储桶。
String
是
Object
Request.Operation.Output
结果文件的名字。
String
是

返回结果说明

成功:返回 job 对象响应信息。
失败:发生错误(如 Bucket 不存在),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

请求示例

public void createMediaJobs(COSClient client) throws UnsupportedEncodingException {
//1.创建任务请求对象
MediaJobsRequestV2 request = new MediaJobsRequestV2();
//2.添加请求参数 参数详情请见api接口文档
request.setBucketName("demo-1234567890");
request.setTag("Transcode");
request.getInput().setObject("1.mp4");
ArrayList<String> watermarkTemplateList = new ArrayList<>();
watermarkTemplateList.add("templateId");
request.getOperation().setWatermarkTemplateId(watermarkTemplateList);
request.getOperation().setTemplateId("t0e09a9456d4124542b1f0e44d501*****");
request.getOperation().getOutput().setBucket("demo-1234567890");
request.getOperation().getOutput().setRegion("ap-chongqing");
request.getOperation().getOutput().setObject("2.mp4");
request.setCallBack("https://cloud.tencent.com/xxx");
// request.setCallBackFormat("json");
//3.调用接口,获取任务响应对象
MediaJobResponseV2 response = client.createMediaJobsV2(request);
//4.解析response
}

取消任务

功能说明

取消一个未在处理中的任务。

方法原型

public Boolean cancelMediaJob(MediaJobsRequest req);

参数说明

参数名称
描述
类型
必选
bucketName
Bucket 的命名规则为 BucketName-APPID,详情请参见 存储桶概述。
String
是
jobId
要取消的任务 ID。
String
是

返回结果说明

成功: 返回一个布尔类型,成功则返回 true。
失败: 发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

请求示例

public void cancelMediaJob(COSClient client) {
//1.创建任务请求对象
MediaJobsRequest request = new MediaJobsRequest();
//2.添加请求参数 参数详情请见api接口文档
request.setBucketName("demo-1234567890");
request.setJobId("jbfb0d02a092111ebb3167781d*****");
//3.调用接口,获取任务响应对象
Boolean response = client.cancelMediaJob(request);
//4.解析response
}

查询任务

功能说明

根据任务 ID 查询任务详情。

方法原型

public MediaJobResponse describeMediaJob(MediaJobsRequest req);

参数说明

参数名称
描述
类型
必选
bucketName
Bucket 的命名规则为 BucketName-APPID,详情请参见 存储桶概述。
String
是
jobId
要查询的任务 ID。
String
是

返回结果说明

成功: 返回任务详情响应包装类,类中包含一个 MediaJobObject 任务详情对象。
失败: 发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

请求示例

public void describeMediaJob(COSClient client) {
//1.创建任务请求对象
MediaJobsRequest request = new MediaJobsRequest();
//2.添加请求参数 参数详情请见api接口文档
request.setBucketName("demo-1234567890");
request.setJobId("j12007314677b11f09e4931a92d9*****");
//3.调用接口,获取任务响应对象
MediaJobResponseV2 response = client.describeMediaJobV2(request);
//4.解析response
}

查询任务列表

功能说明

查询队列中的任务列表。

方法原型

public MediaListJobResponse describeMediaJobs(MediaJobsRequest cIMediaJobsRequest);

参数说明

节点名称(关键字)
描述
类型
必选
bucketName
Bucket 的命名规则为 BucketName-APPID,详情请参见 存储桶概述。
String
是
queueId
拉取该队列 ID 下的任务,开通预览服务后自动生成,请在 数据万象控制台 中查询。
String
否
tag
任务的 Tag:Animation。
String
是
orderByTime
Desc 或者 Asc,默认为 Desc。
String
否
nextToken
请求的上下文,用于翻页。上次返回的值
String
否
size
拉取的最大任务数。默认为10,最大为100。
Integer
否
states
拉取该状态的任务,以,分割支持多状态 All、Submitted、Running、Success
Failed、Pause、Cancel。默认为 All。
String
否
startCreationTime
拉取创建时间大于该时间的任务。格式为:%Y-%m-%dT%H:%m:%S%z。
String
否
endCreationTime
拉取创建时间小于该时间的任务。格式为:%Y-%m-%dT%H:%m:%S%z。
String
否

返回结果说明

成功: 返回一个任务集合响应实体。
失败: 发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

请求示例

public void describeMediaJobs(COSClient client) {
//1.创建任务请求对象
MediaJobsRequest request = new MediaJobsRequest();
//2.添加请求参数 参数详情请见api接口文档
request.setBucketName("demo-1251704708");
request.setTag("Transcode");
//3.调用接口,获取任务响应对象
MediaListJobResponse response = client.describeMediaJobsV2(request);
List<MediaJobObject> jobsDetail = response.getJobsDetailList();
if (jobsDetail != null) {
for (MediaJobObject mediaJobObject : jobsDetail) {
//4.解析每个任务结果
System.out.println(mediaJobObject.getJobId());
System.out.println(mediaJobObject.getState());
}
}
}