tencent cloud

文档反馈

提交多文件打包压缩任务

最后更新时间:2023-12-30 10:41:13

    功能描述

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

    费用说明

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

    限制说明

    文件数量支持:最多支持打包 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
    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>