全部文档
当前文档

热搜词推荐

云服务器 虚拟私有网络 边缘节点计算 对等连接

共搜索到 0 条结果

暂无内容

如果没有找到您期望的内容，请尝试其他搜索词

文档中心

对象存储(KS3)

查看更多结果
未找到含当前关键字的文档标题
页面目录
全部展开全部收起
未找到含该关键词的产品
文档中心 对象存储(KS3) API文档 批量处理 CreateJob

CreateJob

最近更新时间：2025-07-25 18:58:01

CreateJob接口用于在存储桶中创建批量处理任务。

1. 创建批量处理任务会产生额外收费，KS3会按创建的任务数和对象处理量进行收费。价格详情参见文档：价格详情。

2. 有关批量处理功能更多详细描述请参见文档：批量处理。

权限描述

  • 使用此接口的用户，必须是主账号或具有ks3:CreateJob权限。

  • 使用此接口的用户，必须已经在控制台开通批量处理角色授权（KsyunKS3BucketLoggingProcessingRole）。

1. 如果需要为子账号授予ks3:CreateJob权限，需登录IAM控制台为子账号授予相应的策略权限。

2. 控制台开通批量处理角色授权有使用以下任意一种方式即可：

（1）KS3控制台批量处理页面点击授权按钮，根据操作指引完成授权。

（2）IAM控制台新增KsyunKS3BucketLoggingProcessingRole角色。

请求

请求语法

PUT /?jobs HTTP/1.1
Host: ks3-cn-beijing.ksyuncs.com
Date: {date}
Authorization: {SignatureValue}

Job written in XML

1. Endpoint与Region对应关系

2. SignatureValue签名算法

请求头

该接口仅使用公共请求头。

请求体

请求体为一段描述批量处理规则的XML：

<CreateJobRequest>
    <ClientRequestToken>184ce261-18af-5e3d-3e30-253723cfd937</ClientRequestToken>
    <Description>example-job</Description>
    <Manifest>
        <Location>
            <Filter>
                <Bucket>krn:ksc:ks3:::bucket1</Bucket>
                <Prefix>Prefix1</Prefix>
                <Prefix>Prefix2</Prefix>
            </Filter>
            <Filter>
                <Bucket>krn:ksc:ks3:::bucket2</Bucket>
                <Prefix>Prefix1</Prefix>
                <Prefix>Prefix2</Prefix>
            </Filter>
        </Location>
        <Spec>
            <Format>KS3BatchOperations_Bucket_V1</Format>
        </Spec>
    </Manifest>
    <Operation>
        <KS3RestoreObject>
            <StorageClass>ARCHIVE</StorageClass> 
            <Days>2</Days>
        </KS3RestoreObject>
    </Operation>
    <Priority>1</Priority>
    <Report>
        <Enabled>true</Enabled>
        <Bucket>krn:ksc:ks3:::bucket</Bucket>
        <Prefix>job-result</Prefix>
        <ReportScope>FailedTasksOnly</ReportScope>
    </Report>
</CreateJobRequest>

请求体内相关元素的具体描述如下：

名称

描述

是否必选

CreateJobRequest

批量处理配置规则的容器。

  • 类型：容器

  • 父节点：无

是

ClientRequestToken

每个请求唯一的 token，用于避免前端重复发起同一批处理任务。长度为1 - 64字节，建议使用uuid。

  • 类型：String

  • 父节点：CreateJobRequest

1. 仅支持数字、字母、横线（-）。

2. 同一个UID下的ClientRequestToken必须唯一。

3. 创建任务时设置的ClientRequestToken不能与近48小时内已删除的规则ClientRequestToken重复。

是

Description

任务描述。描述长度范围为0 - 256字节。

  • 类型：String

  • 父节点：CreateJobRequest

仅支持字母、数字、中文、下划线（_）和横线（-）的组合。

否

Manifest

待处理的文件信息。

  • 类型：容器

  • 父节点：CreateJobRequest

是

Location

待处理的文件位置信息。

  • 类型：容器

  • 父节点：Manifest

是

Filter

指定需要进行批量操作的桶或前缀。

  • 类型：容器

  • 父节点：Location

单个规则可以同时设置多个Filter来实现对不同桶内的不同前缀进行批量处理。单个规则最多支持设置100个Filter。

是

Bucket

指定需要进行批量操作桶的资源标识符。

  • 类型：String

  • 父节点：Filter

  • 取值范围：1-1024字节

  • 格式：krn:ksc:ks3:::bucketname

  • 示例值：krn:ksc:ks3:::examplebucket

单个Filter内仅支持填写一个桶名称，如果需要同时对多个桶设置批量处理规则，可通过设置多个Filter实现。

是

Prefix

指定需要进行批量操作的前缀。

  • 类型：String

  • 父节点：Filter

  • 取值范围：0-1024字节

1. 单个Filter内填写的Prefix不支持重叠。

2. 单个Filter内支持填写多个前缀，表示对桶内多个指定前缀的文件进行批量处理。

3. Prefix参数值设置为空，表示对桶内的全部文件进行批量操作。

4. 单个Filter内最多支持填写1000个Prefix。

是

Spec

描述待处理文件列表的格式信息。

  • 类型：容器

  • 父节点：Manifest

是

Format

指定待处理文件列表的格式信息。固定取值：KS3BatchOperations_Bucket_V1。

  • 类型：String

  • 父节点：Spec

是

Operation

选择要执行的具体操作。支持批量解冻、批量修改ACL、批量删除操作。

  • 类型：容器

  • 父节点：CreateJobRequest

单个任务中Operation只能设置一种操作类型（批量解冻/批量修改ACL/批量删除）。

是

KS3RestoreObject

对归档类型文件批量执行解冻操作的具体参数。

  • 类型：容器

  • 父节点：Operation

否

StorageClass

表示需要解冻的存储类型。

  • 可选值：ARCHIVE

  • 类型：String

  • 父节点：KS3RestoreObject

当Operation选择KS3RestoreObject时，必选该参数。

Days

设置解冻持续时间。

  • 可选值：1-7的整数

  • 类型：Int

  • 父节点：KS3RestoreObject

当Operation选择KS3RestoreObject时，必选该参数。

KS3PutObjectAcl

批量设置ACL的具体参数。

  • 类型：容器

  • 父节点：Operation

否

CannedAccessControlList

预定义ACL，针对所有用户生效。

  • 取值：private、public-read

  • 类型：String

  • 父节点：KS3PutObjectAcl

1. 设置为private表示只有文件的拥有者可以对该文件进行读写操作，其他人无法访问该文件。

2. 设置为public-read表示任何人（包括匿名访问者）都可以对该文件进行读操作。

否

AccessControlList

针对指定用户设置ACL权限。

  • 类型：容器

  • 父节点：KS3PutObjectAcl

否

Grant

包含被授权者和其ACL信息。

  • 类型：容器

  • 父节点：AccessControlList

单条规则最多支持设置100条Grant。

否

Grantee

被授权者的账号（UID）信息。

  • 类型：String

  • 父节点：Grant

1. 单个Grantee参数仅支持传入一个账号信息。

2. 仅支持针对UID授予ACL权限。

否

Permission

指明授予被授权者的权限信息。

  • 取值：FULL_CONTROL、READ

  • 类型：String

  • 父节点：Grant

1. FULL_CONTROL表示被授权者具有对文件的读写权限。

2. READ表示被授权者具有对文件的只读权限。

否

KS3DeleteObject

对文件批量执行删除操作的具体参数。

  • 父节点：Operation

对文件批量执行删除操作时，该参数取值设置为空即可。

否

Priority

任务优先级。取值越大表示任务执行的优先级越高。

  • 取值范围：0-2147483647

  • 类型：Int

  • 父节点：CreateJobRequest

是

Report

任务完成报告。仅支持导出操作失败列表报告。

  • 类型：容器

  • 父节点：CreateJobRequest

有关任务完成报告的详细内容，请参见文档：批量处理。

是

Enabled

是否输出任务完成报告。

  • 取值：true、false

  • 类型：Boolean

  • 父节点：Report

取值为true表示输出任务完成报告，取值为false表示不输出任务完成报告。

是

Bucket

任务完成报告的投递存储桶。

  • 类型：String

  • 父节点：Report

当Enabled取值为true时，必选该参数。

Prefix

任务完成报告投递的前缀信息。

  • 取值范围：0-512字节

  • 类型：String

  • 父节点：Report

否

ReportScope

任务完成报告内容类型。

  • 取值：固定取值FailedTasksOnly

  • 类型：String

  • 父节点：Report

当Enabled取值为true时，必选该参数。

响应

响应头

该接口仅返回公共响应头部。

响应体

<CreateJobResult>
   <JobId>string</JobId>
</CreateJobResult>

响应体具体参数描述如下：

节点名

描述

CreateJobResult

包含任务ID的容器。

  • 类型：容器

JobId

任务ID。规则创建成功后，KS3会自动返回该参数，每个规则对应唯一的任务ID。

  • 类型：String

  • 父节点：CreateJobResult

JobId的值与请求参数ClientRequestToken值一致。

示例

批量解冻请求示例

PUT /?jobs HTTP/1.1
Host: ks3-cn-beijing.ksyuncs.com
Date: Wed, 14 May 2025 02:11:21 GMT
Authorization: authorization string

<CreateJobRequest>
    <ClientRequestToken>184ce261-18af-5e3d-3e30-253723cfd937</ClientRequestToken>
    <Description>example-job</Description>
    <Manifest>
        <Location>
            <Filter>
                <Bucket>krn:ksc:ks3:::bucket1</Bucket>
                <Prefix>Prefix1</Prefix>
                <Prefix>Prefix2</Prefix>
            </Filter>
            <Filter>
                <Bucket>krn:ksc:ks3:::bucket2</Bucket>
                <Prefix>Prefix1</Prefix>
                <Prefix>Prefix2</Prefix>
            </Filter>
        </Location>
        <Spec>
            <Format>KS3BatchOperations_Bucket_V1</Format>
        </Spec>
    </Manifest>
    <Operation>
        <KS3RestoreObject> 
            <StorageClass>ARCHIVE</StorageClass>
            <Days>2</Days>
        </KS3RestoreObject>
    </Operation>
    <Priority>1</Priority>
    <Report>
        <Enabled>true</Enabled>
        <Bucket>krn:ksc:ks3:::bucket1</Bucket>
        <Prefix>job-result</Prefix>
        <ReportScope>FailedTasksOnly</ReportScope>
    </Report>
</CreateJobRequest>

批量解冻响应示例

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Wed, 14 May 2025 02:11:21 GMT
Server: ks3
x-kss-request-id: 5CAC0AD16D0232E2051B****

<CreateJobResult>
   <JobId>184ce261-18af-5e3d-3e30-253723cfd937</JobId>
</CreateJobResult>

批量修改ACL请求示例

  • 针对全部用户设置ACL权限请求示例：

    PUT /?jobs HTTP/1.1
Host:ks3-cn-beijing.ksyuncs.com
Date: Wed, 14 May 2025 02:11:21 GMT
Authorization: authorization string

<CreateJobRequest>
    <ClientRequestToken>184ce261-18af-5e3d-3e30-253723cfd937</ClientRequestToken>
    <Description>example-job</Description>
    <Manifest>
        <Location>
            <Filter>
                <Bucket>krn:ksc:ks3:::bucket1</Bucket>
                <Prefix>Prefix1</Prefix>
                <Prefix>Prefix2</Prefix>
            </Filter>
            <Filter>
                <Bucket>krn:ksc:ks3:::bucket2</Bucket>
                <Prefix>Prefix1</Prefix>
                <Prefix>Prefix2</Prefix>
            </Filter>
        </Location>
        <Spec>
            <Format>KS3BatchOperations_Bucket_V1</Format>
        </Spec>
    </Manifest>
    <Operation>
        <KS3PutObjectAcl>
            <CannedAccessControlList>private</CannedAccessControlList>
        </KS3PutObjectAcl>
    </Operation>
    <Priority>1</Priority>
    <Report>
        <Enabled>true</Enabled>
        <Bucket>krn:ksc:ks3:::bucket</Bucket>
        <Prefix>job-result</Prefix>
        <ReportScope>FailedTasksOnly</ReportScope>
    </Report>
</CreateJobRequest>

  • 指定用户设置ACL权限请求示例：

    PUT /?jobs HTTP/1.1
Host:ks3-cn-beijing.ksyuncs.com
Date: Wed, 14 May 2025 02:11:21 GMT
Authorization: authorization string

<CreateJobRequest>
    <ClientRequestToken>184ce261-18af-5e3d-3e30-253723cfd937</ClientRequestToken>
    <Description>example-job</Description>
    <Manifest>
        <Location>
            <Filter>
                <Bucket>krn:ksc:ks3:::bucket1</Bucket>
                <Prefix>Prefix1</Prefix>
                <Prefix>Prefix2</Prefix>
            </Filter>
            <Filter>
                <Bucket>krn:ksc:ks3:::bucket2</Bucket>
                <Prefix>Prefix1</Prefix>
                <Prefix>Prefix2</Prefix>
            </Filter>
        </Location>
        <Spec>
            <Format>KS3BatchOperations_Bucket_V1</Format>
        </Spec>
    </Manifest>
    <Operation>
        <KS3PutObjectAcl>
            <AccessControlList>
                <Grant>
                    <Grantee>12345678</Grantee>
                    <Permission>FULL_CONTROL</Permission>
                </Grant>
                <Grant>
                    <Grantee>87654321</Grantee>
                    <Permission>READ</Permission>
                </Grant>
            </AccessControlList>
        </KS3PutObjectAcl>
    </Operation>
    <Priority>1</Priority>
    <Report>
        <Enabled>true</Enabled>
        <Bucket>krn:ksc:ks3:::bucket</Bucket>
        <Prefix>job-result</Prefix>
        <ReportScope>FailedTasksOnly</ReportScope>
    </Report>
</CreateJobRequest>

批量修改ACL响应示例

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Wed, 14 May 2025 02:11:21 GMT
Server: ks3
x-kss-request-id: 5CAC0AD16D0232E2051B****

<CreateJobResult>
   <JobId>184ce261-18af-5e3d-3e30-253723cfd937</JobId>
</CreateJobResult>

批量删除请求示例

PUT /?jobs HTTP/1.1
Host:ks3-cn-beijing.ksyuncs.com
Date: Wed, 14 May 2025 02:11:21 GMT
Authorization: authorization string

<CreateJobRequest>
    <ClientRequestToken>184ce261-18af-5e3d-3e30-253723cfd937</ClientRequestToken>
    <Description>example-job</Description>
    <Manifest>
        <Location>
            <Filter>
                <Bucket>krn:ksc:ks3:::bucket1</Bucket>
                <Prefix>Prefix1</Prefix>
                <Prefix>Prefix2</Prefix>
            </Filter>
            <Filter>
                <Bucket>krn:ksc:ks3:::bucket2</Bucket>
                <Prefix>Prefix1</Prefix>
                <Prefix>Prefix2</Prefix>
            </Filter>
        </Location>
        <Spec>
            <Format>KS3BatchOperations_Bucket_V1</Format>
        </Spec>
    </Manifest>
    <Operation>
        <KS3DeleteObject></KS3DeleteObject>
    </Operation>
    <Priority>1</Priority>
    <Report>
        <Enabled>true</Enabled>
        <Bucket>krn:ksc:ks3:::bucket</Bucket>
        <Prefix>job-result</Prefix>
        <ReportScope>FailedTasksOnly</ReportScope>
    </Report>
</CreateJobRequest>

批量删除响应示例

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Wed, 14 May 2025 02:11:21 GMT
Server: ks3
x-kss-request-id: 5CAC0AD16D0232E2051B****

<CreateJobResult>
   <JobId>184ce261-18af-5e3d-3e30-253723cfd937</JobId>
</CreateJobResult>

错误码

状态码（Status）

错误码（Code）

描述

400 Bad Request

InvalidRequest

存在以下情况：

  • 重复的请求

  • 请求体为空

  • 参数重复填写

  • 填写的桶不存在

400 Bad Request

InvalidArgument

存在以下情况：

  • 必填的参数为空

  • 参数值不合法

  • 单个Filter内前缀重叠

400 Bad Request

MalformedXML

请求体不符合XML语法

403 Forbidden

AccessDenied

缺少权限

文档导读
上一篇：批量处理
下一篇：DescribeJob
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈