异步处理任务接口

最近更新时间:2024-07-26 11:33:42

我的收藏

简介

本文档提供关于文档预览任务接口的 API 概览以及 SDK 示例代码。
API
说明
用于提交一个文档预览任务
用于查询指定的文档预览任务
用于拉取符合条件的文档预览任务

提交文档预览任务

功能说明

用于提交一个文档预览任务。

示例代码

function createDocProcessJobs() {
var config = {
// 需要替换成您自己的存储桶信息
Bucket: 'examplebucket-1250000000', /* 存储桶,必须 */
Region: 'COS_REGION', /* 存储桶所在地域,必须字段 */
};
var host = config.Bucket + '.ci.' + config.Region + '.myqcloud.com/doc_jobs';
var url = 'https://' + host;
var body = COS.util.json2xml({
Request: {
Tag: 'DocProcess',
Input: {
Object: '文档.docx', // 存在 cos 里的路径
},
Operation: {
DocProcess: {
TgtType: 'jpg',
},
Output: {
Bucket: config.Bucket,
Region: config.Region,
Object: '文档转码_${Number}.jpg', // 转码后存到 cos 的路径
},
},
}
});
cos.request({
Method: 'POST',
Key: 'doc_jobs',
Url: url,
Body: body,
ContentType: 'application/xml',
},
function(err, data){
console.log(err || data);
});
}
createDocProcessJobs();

参数说明

Request 中的具体数据描述如下:
参数名称
类型
描述
是否必填
Bucket
String
存储桶名称,格式:BucketName-APPID
Operation
Array
操作规则
Tag
String
创建任务的 Tag,目前仅支持:DocProcess
Input
Array
待操作的文件对象
QueueId
String
任务所在的队列 ID,开通预览服务后自动生成,请使用查询队列获取或前往万象控制台在存储桶中查询
Input 中的具体数据描述如下:
参数名称
类型
描述
是否必填
Object
String
文件在 COS 上的文件路径,Bucket 由 Host 指定
Operation 中的具体数据描述如下:
参数名称
类型
描述
是否必填
DocProcess
Array
当 Tag 为 DocProcess 时有效,指定该任务的参数
Output
Array
结果输出地址
DocProcess 中的具体数据描述如下:

通用请求参数

节点名称(关键字)
父节点
描述
类型
是否必选
SrcType
Request.Operation.DocProcess
源数据的后缀类型,当前文档转换根据 cos 对象的后缀名来确定源数据类型,当 cos 对象没有后缀名时,可以设置该值
String
TgtType
Request.Operation.DocProcess
转换输出目标文件类型:<br><li>jpg,转成 jpg 格式的图片文件;如果传入的格式未能识别,默认使用 jpg 格式<li>png,转成 png 格式的图片文件<br><li>pdf,转成 pdf 格式文件(暂不支持指定页数)<br>
String
StartPage
Request.Operation.DocProcess
从第 X 页开始转换;在表格文件中,一张表可能分割为多页转换,生成多张图片。StartPage 表示从指定 SheetId 的第 X 页开始转换。默认为1
Int
EndPage
Request.Operation.DocProcess
转换至第 X 页;在表格文件中,一张表可能分割为多页转换,生成多张图片。EndPage 表示转换至指定 SheetId 的第 X 页。默认为-1,即转换全部页
Int

适用于表格文件(Excel)的参数

节点名称(关键字)
父节点
描述
类型
是否必选
SheetId
Request.Operation.DocProcess
表格文件参数,转换第 X 个表,默认为0;设置 SheetId 为0,即转换文档中全部表
Int
PaperDirection
Request.Operation.DocProcess
表格文件转换纸张方向,0代表垂直方向,非0代表水平方向,默认为0
Int
PaperSize
Request.Operation.DocProcess
设置纸张(画布)大小,对应信息为: 0 → A41 → A22 → A0 ,默认 A4 纸张
Int

适用于转码成 png/jpg 图片的参数

节点名称(关键字)
父节点
描述
类型
是否必选
ImageParams
Request.Operation.DocProcess
转换后的图片处理参数,支持 基础图片处理 所有处理参数,多个处理参数可通过 管道操作符 分隔,从而实现在一次访问中按顺序对图片进行不同处理
String
Quality
Request.Operation.DocProces
生成预览图的图片质量,取值范围 [1-100],默认值100。 例:值为100,代表生成图片质量为100%
Int
Zoom
Request.Operation.DocProces
预览图片的缩放参数,取值范围[10-200], 默认值100。 例:值为200,代表图片缩放比例为200% 即放大两倍
Int
ImageDpi
Request.Operation.DocProcess
按指定 dpi 渲染图片,该参数与 Zoom 共同作用,取值范围 96-600 ,默认值为 96 。转码后的图片单边宽度需小于65500像素
Int
PicPagination
Request.Operation.DocProcess
是否转换成单张长图,设置为 1 时,最多仅支持将 20 标准页面合成单张长图,超过可能会报错,分页范围可以通过 StartPage、EndPage 控制。默认值为 0 ,按页导出图片,TgtType="png"/"jpg" 时生效
Int

Output 中的具体数据描述如下:
参数名称
类型
描述
是否必填
Region
String
存储桶的地域
Bucket
String
存储结果的存储桶
Object
String
输出文件路径

返回结果说明

详情请参见 提交文档转码任务
参数名称
描述
类型
err
请求发生错误时返回的对象,包括网络错误和业务错误。如果请求成功则为空,更多详情请参见 错误码
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象,如果请求发生错误,则为空
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- Response
-
Object
- - - JobsDetail
任务的详细信息
Container
- - - - Code
错误码,只有 State 为 Failed 时有意义
String
- - - - Message
错误描述,只有 State 为 Failed 时有意义
String
- - - - JobId
新创建任务的 ID
String
- - - - Tag
新创建任务的 Tag:DocProcess
String
- - - - State
任务的状态,为 Submitted、Running、Success、Failed、Pause、Cancel 其中一个
String
- - - - CreationTime
任务的创建时间
String
- - - - QueueId
任务所属的队列 ID
String
- - - - Input
该任务的输入文件路径,详情请参见 CreateDocProcessJobsOptions.Input
Container
- - - - Operation
该任务的规则,详情请参见 CreateDocProcessJobsOptions.Operation
Container

查询指定文档预览任务

功能说明

用于查询指定的文档预览任务。

示例代码

function describeDocProcessJob() {
var config = {
// 需要替换成您自己的存储桶信息
Bucket: 'examplebucket-1250000000', /* 存储桶,必须 */
Region: 'COS_REGION', /* 存储桶所在地域,必须字段 */
};
var jobId = 'd87fbabd07b8611ed974b3f4b4064872e'; // 替换为自己的 jobId
var host = config.Bucket + '.ci.' + config.Region + '.myqcloud.com/doc_jobs/' + jobId;
var url = 'https://' + host;
cos.request({
Method: 'GET',
Key: 'doc_jobs/' + jobId,
Url: url,
},
function(err, data){
console.log(err || data);
});
}
describeDocProcessJob();

参数说明

参数名称
描述
类型
jobId
文档预览任务 ID
String

返回结果说明

参数名称
描述
类型
err
请求发生错误时返回的对象,包括网络错误和业务错误。如果请求成功则为空,更多详情请参见 错误码
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象,如果请求发生错误,则为空
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- Response
-
Object
- - JobsDetail
任务的详细信息, 同 CreateDocProcessJobs 接口的 Response.JobsDetail 节点
Container
- - NonExistJobIds
查询的 ID 中不存在的任务,所有任务都存在时不返回
String

拉取符合条件的文档预览任务

功能说明

用于拉取符合条件的文档预览任务。

示例代码

function describeDocProcessJobs() {
var config = {
// 需要替换成您自己的存储桶信息
Bucket: 'examplebucket-1250000000', /* 存储桶,必须 */
Region: 'COS_REGION', /* 存储桶所在地域,必须字段 */
};
var host = config.Bucket + '.ci.' + config.Region + '.myqcloud.com/doc_jobs';
var url = 'https://' + host;
cos.request({
Method: 'GET',
Key: 'doc_jobs',
Url: url,
Query: {
tag: 'DocProcess',
},
},
function(err, data){
console.log(err || data);
});
}
describeDocProcessJobs();

参数说明

参数名称
描述
类型
queueId
拉取该队列 ID 下的任务,开通预览服务后自动生成,请使用查询队列获取或前往万象控制台在存储桶中查询
String
tag
任务的 Tag:DocProcess
String
orderByTime
Desc 或者 Asc。默认为 Desc
String
nextToken
请求的上下文,用于翻页。上次返回的值
String
size
拉取的最大任务数。默认为10,最大值为100
Int
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

返回结果说明

参数名称
描述
类型
err
请求发生错误时返回的对象,包括网络错误和业务错误。如果请求成功则为空,更多详情请参见 错误码
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象,如果请求发生错误,则为空
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- Response
-
Object
- - JobsDetail
任务的详细信息,同 CreateDocProcessJobs 接口中的 Response.JobsDetail 节点
Container
- - NextToken
翻页的上下文 Token
String