简介
本文档提供关于数据万象文件压缩的 API 概览以及 SDK 示例代码。
API | 操作描述 |
以提交任务的方式进行多文件打包压缩任务 | |
主动查询指定的多文件打包压缩任务结果 |
提交多文件打包压缩任务
功能说明
多文件打包压缩功能可以将您的多个文件,打包为 zip 等压缩包格式,以提交任务的方式进行多文件打包压缩,异步返回打包后的文件。
方法原型
func (s *CIService) CreateFileProcessJob(ctx context.Context, opt *FileProcessJobOptions) (*FileProcessJobResult, *Response, error)
请求示例
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket// 替换为用户的 region,存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。u, _ := url.Parse("https://test-1250000000.cos.ap-shanghai.myqcloud.com")cu, _ := url.Parse("https://test-1250000000.ci.ap-shanghai.myqcloud.com")b := &cos.BaseURL{BucketURL: u, CIURL: cu}c := cos.NewClient(b, &http.Client{Transport: &cos.AuthorizationTransport{// 通过环境变量获取密钥// 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretID: os.Getenv("SECRETID"),SecretKey: os.Getenv("SECRETKEY"),},})createJobOpt := &cos.FileProcessJobOptions{Tag: "FileCompress",Operation: &cos.FileProcessJobOperation{FileCompressConfig: &cos.FileCompressConfig{Format: "zip",Flatten: "0",Key: []string{"1.mp3", "2.jpg"},},Output: &cos.FileProcessOutput{Region: "ap-shanghai",Bucket: "test-1250000000",Object: "vvvvxxxzz.zip",},},}res, _, err := c.CI.CreateFileProcessJob(context.Background(), createJobOpt)if err != nil {fmt.Println(err)}fmt.Println(res)
参数说明
type FileProcessJobOptions struct {XMLName xml.NameTag stringOperation *FileProcessJobOperationQueueId stringCallBackFormat stringCallBackType stringCallBack stringCallBackMqConfig *NotifyConfigCallBackMqConfig}type FileProcessJobOperation struct {FileCompressConfig *FileCompressConfigFileCompressResult *FileCompressResultOutput *FileProcessOutputUserData string}type FileCompressConfig struct {Flatten stringFormat stringUrlList stringPrefix stringKey []stringType stringCompressKey stringIgnoreError stringKeyConfig []KeyConfig}type KeyConfig struct {Key stringRename stringImageParams string}type FileCompressResult struct {Region stringBucket stringObject stringCompressFileCount intErrorDetail *ErrorDetail}type ErrorDetail struct {ErrorCount stringErrorFile []string}type FileProcessOutput struct {Region stringBucket stringObject string}type NotifyConfigCallBackMqConfig struct {MqMode stringMqRegion stringMqName string}
参数名称 | 描述 | 类型 | 是否必选 |
Tag | 创建任务的 Tag,目前仅支持:FileCompress | String | 是 |
Operation | 操作规则 | Container | 是 |
Operation.FileCompressConfig | 指定文件打包压缩的处理规则 | Container | 是 |
Operation.FileCompressConfig.Flatten | 文件打包时,是否需要去除源文件已有的目录结构,有效值: 0:不需要去除目录结构,打包后压缩包中的文件会保留原有的目录结构; 1:需要,打包后压缩包内的文件会去除原有的目录结构,所有文件都在同一层级。 2:仅对以 Prefix 方式打包压缩时有效,表示不去除压缩包内的目录结构,在打包时会先创建一个目录,以参数Prefix 中的最后一层作为目录名称,目录内是当前打包的所有文件及文件夹。3:仅对以 Prefix 方式打包压缩时有效,表示不去除压缩包内的目录结构,在打包时直接将参数Prefix 下的所有文件及文件夹(不包含参数Prefix 本身)进行打包,放在压缩包的根目录。示例:
假设以 Prefix 进行打包,Prefix 的值为test/data/ ,则文件test/data/123/word.doc 在打包压缩,当Flatten=0 时:打包后,该文件在压缩包内为 test/data/123/word.doc Flatten=1 时:打包后,该文件在压缩包内为 word.doc Flatten=2 时:打包后,该文件在压缩包内为 data/123/word.doc Flatten=3 时:打包后,该文件在压缩包内为 123/word.doc | String | 是 |
Operation.FileCompressConfig.Format | 打包压缩的类型,有效值:zip、tar、tar.gz | String | 是 |
Operation.FileCompressConfig.UrlList | 支持将需要打包的文件整理成索引文件,后台将根据索引文件内提供的文件 url,打包为一个压缩包文件 索引文件需要保存在当前存储桶中,本字段需要提供索引文件的对象地址,例如:/test/index.csv 索引文件格式:仅支持 CSV 文件,一行一条 URL(仅支持本存储桶文件),如有多列字段,默认取第一列作为URL。最多不超过10000个文件,总大小不超过50G, 否则会导致任务失败 | String | 否 |
Operation.FileCompressConfig.Prefix | 支持对存储桶中的某个前缀进行打包,如果需要对某个目录进行打包,需要加/,例如test目录打包,则值为:test/。最多不超过10000个文件,总大小不超过50G,否则会导致任务失败 | String | 否 |
Operation.FileCompressConfig.Key | 支持对存储桶中的多个文件进行打包,个数不能超过 1000, 总大小不超过50G,否则会导致任务失败 | String 数组 | 否 |
Operation.FileCompressConfig.Type | 压缩类型,仅在 Format 为 tar.gz 或 zip 时有效。 faster:压缩速度较快 better:压缩质量较高,体积较小 default:适中的压缩方式 默认值为 default | String | 否 |
Operation.FileCompressConfig.CompressKey | 压缩包密钥,传入时需先经过 base64 编码, 编码后长度不能超过128。当 Format 为 zip 时生效 | String | 否 |
Operation.FileCompressConfig.IgnoreError | 打包时如果单个文件出错,是否忽略错误继续打包。有效值为:
true:忽略错误继续打包后续的文件;
false:遇到某个文件执行打包报错时,直接终止打包任务,不返回压缩包。
默认值为 false | String | 否 |
Operation.FileCompressConfig.KeyConfig | 支持对存储桶中的文件进行打包,可填写多个,个数不能超过 1000,如需打包更多文件,请使用 UrlList 或 Prefix 参数 | Container数组 | 否 |
Operation.FileCompressConfig.KeyConfig.Key | 存储桶中的包含路径的完整文件名称,请使用 UrlList 或 Prefix 参数 | String | 是 |
Operation.FileCompressConfig.KeyConfig.Rename | 文件重命名,打包后文件名将以该值为准,不填表示不更改文件名 | String | 否 |
Operation.FileCompressConfig.KeyConfig.ImageParams | String | 否 | |
Operation.FileCompressResult | 多文件打包压缩的结果,提交任务时不需要填写 | Container | 否 |
Operation.FileCompressResult.CompressFileCount | 打包文件的总数 | Int | 否 |
Operation.FileCompressResult.ErrorDetail | 当文件打包压缩任务失败时,可通过该字段查看具体的错误文件 | Container | 否 |
Operation.FileCompressResult.ErrorDetail.ErrorCount | 打包压缩失败时,出错的文件数 | String | 否 |
Operation.FileCompressResult.ErrorDetail.ErrorFile | 打包压缩失败时,出错的文件名称,该字段最多可列出1000个出错的文件名称,超过1000条的错误文件不再列出 | String 数组 | 否 |
Operation.Output | 指定文件处理后的文件保存的地址信息 | Container | 是 |
Operation.Output.Region | 存储桶的地域 | String | 是 |
Operation.Output.Bucket | 保存压缩后文件的存储桶 | String | 是 |
Operation.Output.Object | 压缩后文件的文件名 | String | 是 |
Operation.UserData | 透传用户信息,可打印的 ASCII 码,长度不超过1024 | String | 否 |
QueueId | String | 否 | |
CallBackFormat | 任务回调格式,JSON 或 XML,默认 XML,优先级高于队列的回调格式 | String | 否 |
CallBackType | 任务回调类型,Url 或 TDMQ,默认 Url,优先级高于队列的回调类型 | String | 否 |
CallBack | 任务回调的地址,优先级高于队列的回调地址 | String | 否 |
CallBackMqConfig | Container | 否 |
说明:
在 Operation.FileCompressConfig 中,UrlList、Prefix、Key 三者仅能选择一个,不能都为空,也不会同时生效。如果填了多个,会按优先级 UrlList > Prefix > Key 顺序执行。
返回结果说明
type FileProcessJobResult struct {JobsDetail FileProcessJobsDetail}type FileProcessJobsDetail struct {Code stringMessage stringJobId stringTag stringState stringCreationTime stringStartTime stringEndTime stringQueueId stringOperation *FileProcessJobOperation}
参数名称 | 描述 | 类型 |
JobsDetail | 任务的详细信息 | Container |
Code | 错误码,只有 State 为 Failed 时有意义 | String |
Message | 错误描述,只有 State 为 Failed 时有意义 | String |
JobId | 新创建任务的 ID | String |
Tag | 新创建任务的 Tag:FileCompress | String |
State | 任务的状态,为 Submitted、Running、Success、Failed、Pause、Cancel 其中一个 | String |
CreationTime | 任务的创建时间 | String |
StartTime | 任务的开始时间 | String |
EndTime | 任务的结束时间 | String |
QueueId | 任务所属的队列 ID | String |
Operation | 该任务的规则,详情请参见 FileProcessJobOptions.Operation | Container |
查询多文件打包压缩结果
功能说明
查询一个文件处理任务,根据任务 ID 查询任务详情。
方法原型
func (s *CIService) DescribeFileProcessJob(ctx context.Context, jobid string) (*FileProcessJobResult, *Response, error)
请求示例
jobid := "<jobid>"res, _, err := c.CI.DescribeFileProcessJob(context.Background(), jobid)
参数说明
参数名称 | 描述 | 类型 | 是否必选 |
jobid | 文件处理任务 ID | String | 是 |
返回结果说明
type FileProcessJobResult struct {JobsDetail *FileProcessJobsDetail}type FileProcessJobsDetail struct {Code string `xml:",omitempty"`Message string `xml:",omitempty"`JobId string `xml:",omitempty"`Tag string `xml:",omitempty"`State string `xml:",omitempty"`CreationTime string `xml:",omitempty"`StartTime string `xml:",omitempty"`EndTime string `xml:",omitempty"`QueueId string `xml:",omitempty"`Operation *FileProcessJobOperation `xml:",omitempty"`}
参数名称 | 描述 | 类型 |
JobsDetail | 任务的详细信息 | Container |
Code | 错误码,只有 State 为 Failed 时有意义 | String |
Message | 错误描述,只有 State 为 Failed 时有意义 | String |
JobId | 新创建任务的 ID | String |
Tag | 新创建任务的 Tag:FileCompress | String |
State | 任务的状态,为 Submitted、Running、Success、Failed、Pause、Cancel 其中一个 | String |
CreationTime | 任务的创建时间 | String |
StartTime | 任务的开始时间 | String |
EndTime | 任务的结束时间 | String |
QueueId | 任务所属的队列 ID | String |
Operation | 该任务的规则,详情请参见 FileProcessJobOptions.Operation | Container |