API 文档

SDK 文档

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

功能描述

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

费用说明

限制说明

  • 文件数量支持:最多支持打包 1 万个文件;
  • 文件大小支持:打包压缩后总大小小于 50GB;
  • 调用接口需携带签名,具体规则请参见 请求签名 文档。
  • 本接口当前支持以下地域:北京、上海、广州、成都、中国香港、新加坡、硅谷。

请求

请求示例

POST /file_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>
        </FileCompressConfig>
        <Output>
            <Region>ap-chongqing</Region>
            <Bucket>test-1234567890</Bucket>
            <Object>output/test.zip</Object>
        </Output>
        <UserData>This is my data.</UserData>
    </Operation>
    <QueueId>p2911917386e148639319e13c285cc774</QueueId>
    <CallBack>http://callback.demo.com</CallBack>
    <CallBackFormat>JSON<CallBackFormat>
</Request>

具体的数据描述如下:

节点名称(关键字) 父节点 描述 类型 是否必选
Request 保存请求的容器。 Container

Container 类型 Request 的具体数据描述如下:

节点名称(关键字) 父节点 描述 类型 是否必选
Tag Request 表示任务的类型,多文件打包压缩默认为:FileCompress。 String
Operation Request 包含文件打包压缩的处理规则。 Container
QueueId Request 任务所在的队列 ID。 String
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
UrlList Request.Operation.FileCompressConfig 支持将需要打包的文件整理成索引文件,后台将根据索引文件内提供的文件url,打包为一个压缩包文件。索引文件需要保存在当前存储桶中,本字段需要提供索引文件的对象地址,例如:/test/index.csv。
索引文件格式:仅支持 CVS文件,一行一条URL(仅支持本存储桶文件),如有多列字段,默认取第一列作为URL。最多不超过10000个文件, 总大小不超过50G, 否则会导致任务失败。
String
Prefix Request.Operation.FileCompressConfig 支持对存储桶中的某个前缀进行打包,如果需要对某个目录进行打包,需要加/,例如test目录打包,则值为:test/。最多不超过10000个文件,总大小不超过50G,否则会导致任务失败。 String
Key Request.Operation.FileCompressConfig 支持对存储桶中的多个文件进行打包,个数不能超过 1000, 总大小不超过50G,否则会导致任务失败。 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>
        <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>
            </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
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

错误码

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

实际案例

请求

POST /file_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>
        </FileCompressConfig>
        <Output>
            <Region>ap-chongqing</Region>
            <Bucket>test-1234567890</Bucket>
            <Object>output/test.zip</Object>
        </Output>
        <UserData>This is my data.</UserData>
    </Operation>
    <QueueId>p2911917386e148639319e13c285cc774</QueueId>
    <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>
        <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>
            </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>

目录