有奖捉虫:云通信与企业服务文档专题,速来> HOT

功能描述

多文件打包压缩功能可以将您的多个文件,打包为 zip 等压缩包格式,以提交任务的方式进行多文件打包压缩,异步返回打包后的文件,该接口属于 POST 请求。

授权说明

授权策略中 action 设置为 ci:CreateFileProcessJobs 。查看所有 action
子账号使用异步处理接口时,需要授予 cam:passrole 权限,异步处理接口会通过 CAM 的“角色”进行 COS 的资源读写操作,PassRole 权限用于传递角色。

服务开通

使用该功能需提前开通数据万象,并绑定存储桶。详情请参见 绑定存储桶

使用限制

使用该接口时,请先确认相关限制条件。详情请参见 使用限制
调用接口需携带签名,具体规则请参见 请求签名 文档。
本接口支持以下地域:北京、上海、广州、成都、南京、重庆、中国香港、新加坡、硅谷。

费用说明

如果文件为 COS 上的低频存储类型,调用会产生 COS 低频数据取回费用
不支持打包 COS 上的归档存储类型和深度归档存储类型的文件,如果打包需要此类型文件,请先 恢复归档文件


请求

请求示例

POST /jobs HTTP/1.1
Host: <BucketName-APPID>.ci.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
Content-Length: <length>
Content-Type: application/xml

<body>
说明
Authorization:Auth String(详情请参见 请求签名 文档)。
通过子账号使用时,需要授予相关的权限,详情请参见 授权粒度详情 文档。

请求头

此接口仅使用公共请求头部,详情请参见 公共请求头部 文档。

请求体

该请求操作的实现需要有如下请求体。
<Request>
<Tag>FileCompress</Tag>
<Operation>
<FileCompressConfig>
<Prefix>test/</Prefix>
<Format>zip</Format>
<Flatten>0</Flatten>
<Type>better</Type>
<CompressKey>MTIzNDU2Nzg5MA==</CompressKey>
</FileCompressConfig>
<Output>
<Region>ap-chongqing</Region>
<Bucket>test-1234567890</Bucket>
<Object>output/test.zip</Object>
</Output>
<UserData>This is my data.</UserData>
</Operation>
<CallBack>http://callback.demo.com</CallBack>
<CallBackFormat>JSON</CallBackFormat>
</Request>
具体的数据描述如下:
节点名称(关键字)
父节点
描述
类型
是否必选
Request
保存请求的容器。
Container
Container 类型 Request 的具体数据描述如下:
节点名称(关键字)
父节点
描述
类型
是否必选
Tag
Request
表示任务的类型,多文件打包压缩默认为:FileCompress。
String
Operation
Request
包含文件打包压缩的处理规则。
Container
CallBackFormat
Request
任务回调格式,JSON 或 XML,默认 XML,优先级高于队列的回调格式。
String
CallBackType
Request
任务回调类型,Url 或 TDMQ,默认 Url,优先级高于队列的回调类型。
String
CallBack
Request
任务回调的地址,优先级高于队列的回调地址。
String
CallBackMqConfig
Request
任务回调 TDMQ 配置,当 CallBackType 为 TDMQ 时必填。详情请参见 CallBackMqConfig
Container
Container 类型
Operation
的具体数据描述如下:
节点名称(关键字)
父节点
描述
类型
是否必选
FileCompressConfig
Request.Operation
指定文件打包压缩的处理规则。
Container
UserData
Request.Operation
透传用户信息,可打印的 ASCII 码,长度不超过1024。
String
Output
Request.Operation
指定打包压缩后的文件保存的地址信息。
Container
Container 类型 FileCompressConfig 的具体数据描述如下:
节点名称(关键字)
父节点
描述
类型
是否必选
Flatten
Request.Operation.FileCompressConfig
文件打包时,是否需要去除源文件已有的目录结构,有效值:
0:不需要去除目录结构,打包后压缩包中的文件会保留原有的目录结构;
1:需要,打包后压缩包内的文件会去除原有的目录结构,所有文件都在同一层级。
例如:源文件 URL 为 https://domain/source/test.mp4,则源文件路径为 source/test.mp4,如果为 1,则 ZIP 包中该文件路径为 test.mp4;如果为0, ZIP 包中该文件路径为 source/test.mp4。
String
Format
Request.Operation.FileCompressConfig
打包压缩的类型,有效值:zip、tar、tar.gz。
String
Type
Request.Operation.FileCompressConfig
压缩类型,仅在Format为tar.gz或zip时有效。
faster:压缩速度较快
better:压缩质量较高,体积较小
default:适中的压缩方式
默认值为default
String
CompressKey
Request.Operation.FileCompressConfig
压缩包密钥,传入时需先经过 base64 编码,编码后长度不能超过128。当 Format 为 zip 时生效。
String
UrlList
Request.Operation.FileCompressConfig
支持将需要打包的文件整理成索引文件,后台将根据索引文件内提供的文件 url,打包为一个压缩包文件。
索引文件需要保存在当前存储桶中,本字段需要提供索引文件的对象地址,不需要带域名,填写示例:/test/index.csv
索引文件格式:仅支持 CSV 文件,一行一条 URL(仅支持本存储桶文件),如有多列字段,默认取第一列作为URL。
String
Prefix
Request.Operation.FileCompressConfig
支持对存储桶中的某个前缀进行打包,如果需要对某个目录进行打包,需要加/,例如test目录打包,则值为:test/。
String
Key
Request.Operation.FileCompressConfig
支持对存储桶中的多个文件进行打包,个数不能超过 1000,如需打包更多文件,请使用UrlList或Prefix参数。
String 数组
IgnoreError
Request.Operation.FileCompressConfig
打包时如果单个文件出错,是否忽略错误继续打包。有效值为:
ture:忽略错误继续打包后续的文件;
false:遇到某个文件执行打包报错时,直接终止打包任务,不返回压缩包。
默认值为false。
String
注意
UrlList、Prefix、Key 三者仅能选择一个,不能都为空,也不会同时生效。如果填了多个,会按优先级 UrlList > Prefix > Key 取最高优先级执行。
Container 类型 Output 的具体数据描述如下:
节点名称(关键字)
父节点
描述
类型
是否必选
Region
Request.Operation.Output
存储桶的地域。
String
Bucket
Request.Operation.Output
保存压缩后文件的存储桶。
String
Object
Request.Operation.Output
压缩后文件的文件名
String

响应

响应头

此接口仅返回公共响应头部,详情请参见 公共响应头部 文档。

响应体

该响应体返回为 application/xml 数据,包含完整节点数据的内容展示如下:
<Response>
<JobsDetail>
<Code>Success</Code>
<Message/>
<JobId>f93984788066911ed89ed352d4d9d2084</JobId>
<State>Submitted</State>
<Progress>0</Progress>
<CreationTime>2022-07-18T15:16:43+0800</CreationTime>
<EndTime>-</EndTime>
<StartTime>-</StartTime>
<QueueId>p2911917386e148639319e13c285cc774</QueueId>
<Tag>FileCompress</Tag>
<Operation>
<FileCompressConfig>
<Prefix>test/</Prefix>
<Format>zip</Format>
<Flatten>0</Flatten>
<Type>better</Type>
<CompressKey>MTIzNDU2Nzg5MA==</CompressKey>
</FileCompressConfig>
<Output>
<Region>ap-chongqing</Region>
<Bucket>test-1234567890</Bucket>
<Object>output/test.zip</Object>
</Output>
<UserData>This is my data.</UserData>
</Operation>
</JobsDetail>
</Response>
具体的数据内容如下:
节点名称(关键字)
父节点
描述
类型
Response
保存结果的容器。
Container
Container 节点 Response 的内容:
节点名称(关键字)
父节点
描述
类型
JobsDetail
Response
任务的详细信息。
Container 数组
Container 节点
JobsDetail
的内容:
节点名称(关键字)
父节点
描述
类型
Code
Response.JobsDetail
错误码,只有 State 为 Failed 时有意义。
String
Message
Response.JobsDetail
错误描述,只有 State 为 Failed 时有意义。
String
JobId
Response.JobsDetail
新创建任务的 ID。
String
Tag
Response.JobsDetail
表示任务的类型,多文件打包压缩默认为:FileCompress。
String
State
Response.JobsDetail
任务状态
Submitted:已提交,待执行。
Running:执行中。
Success:执行成功。
Failed:执行失败。
Pause:任务暂停,当暂停队列时,待执行的任务会变为暂停状态。
Cancel:任务被取消执行。
String
Progress
Response.JobsDetail
任务进度百分比,范围为[0, 100]。
Int
CreationTime
Response.JobsDetail
任务的创建时间。
String
StartTime
Response.JobsDetail
任务的开始时间。
String
EndTime
Response.JobsDetail
任务的结束时间。
String
QueueId
Response.JobsDetail
任务所属的 队列 ID
String
Operation
Response.JobsDetail
多文件打包压缩的处理规则。
Container
Container 节点 Operation 的内容:
节点名称(关键字)
父节点
描述
类型
UserData
Response.JobsDetail.Operation
透传用户信息。
String
Output
Response.JobsDetail.Operation
同请求中的 Request.Operation.Output。
Container
FileCompressConfig
Response.JobsDetail.Operation
同请求中的 Request.Operation.FileCompressConfig。
Container
FileCompressResult
Response.JobsDetail.Operation
多文件打包压缩的结果,任务未完成时不返回。
Container
Container 节点 FileCompressResult 的内容:
节点名称(关键字)
父节点
描述
类型
Region
Response.JobsDetail.Operation.FileCompressResult
打包压缩后文件保存的存储桶的地域。
String
Bucket
Response.JobsDetail.Operation.FileCompressResult
打包压缩后文件保存的存储桶。
String
Object
Response.JobsDetail.Operation.FileCompressResult
打包压缩后文件的名称。
String
CompressFileCount
Response.JobsDetail.Operation.FileCompressResult
打包文件的总数
String
ErrorCount
Response.JobsDetail.Operation.FileCompressResult
打包时出错的文件数
String

错误码

该请求操作无特殊错误信息,常见的错误信息请参见 错误码 文档。

实际案例

请求

POST /jobs HTTP/1.1
Authorization:q-sign-algorithm=sha1&q-ak=AKIDZfbOAo7cllgPvF9cXFrJD0a1ICvR****&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=28e9a4986df11bed0255e97ff90500557e0ea057
Host:test-1234567890.ci.ap-chongqing.myqcloud.com
Content-Length: 166
Content-Type: application/xml

<Request>
<Tag>FileCompress</Tag>
<Operation>
<FileCompressConfig>
<Prefix>test/</Prefix>
<Format>zip</Format>
<Flatten>0</Flatten>
<Type>better</Type>
<CompressKey>MTIzNDU2Nzg5MA==</CompressKey>
</FileCompressConfig>
<Output>
<Region>ap-chongqing</Region>
<Bucket>test-1234567890</Bucket>
<Object>output/test.zip</Object>
</Output>
<UserData>This is my data.</UserData>
</Operation>
<CallBack>http://callback.demo.com</CallBack>
<CallBackFormat>JSON</CallBackFormat>
</Request>

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 230
Connection: keep-alive
Date: Mon, 18 Jul 2022 19:37:29 GMT
Server: tencent-ci
x-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc=

<Response>
<JobsDetail>
<Code>Success</Code>
<Message/>
<JobId>f93984788066911ed89ed352d4d9d2084</JobId>
<State>Submitted</State>
<Progress>0</Progress>
<CreationTime>2022-07-18T15:16:43+0800</CreationTime>
<EndTime>-</EndTime>
<StartTime>-</StartTime>
<QueueId>p2911917386e148639319e13c285cc774</QueueId>
<Tag>FileCompress</Tag>
<Operation>
<FileCompressConfig>
<Prefix>test/</Prefix>
<Format>zip</Format>
<Flatten>0</Flatten>
<Type>better</Type>
<CompressKey>MTIzNDU2Nzg5MA==</CompressKey>
</FileCompressConfig>
<Output>
<Region>ap-chongqing</Region>
<Bucket>test-1234567890</Bucket>
<Object>output/test.zip</Object>
</Output>
<UserData>This is my data.</UserData>
</Operation>
</JobsDetail>
</Response>