All Products
Search

This Product

    Object Storage Service:CreateJob

    Document Center

    Object Storage Service:CreateJob

    Last Updated:Jun 22, 2026

    Creates a batch job that performs a specified operation on multiple objects.

    Usage notes

    • A job status of `Complete` does not guarantee that all tasks in the job were successful. You must check the final report to determine the execution status of each task. For example, if a lifecycle rule relies on a batch job to add tags for object deletion, the final report is the definitive source for the outcome.

    • `PutObjectTagging` overwrites existing tags.

    • `AddObjectTagging` is not an atomic operation. It first retrieves existing tags and then updates them. Overwrites can occur if there are concurrent operations.

    • If multiple jobs concurrently operate on the same set of objects, the execution order may differ from the submission order. Avoid running concurrent operations on the same set of objects.

    • A `Complete` status only indicates that the job has finished. It does not mean all objects were processed successfully. Similarly, for jobs with `Cancelled`, `Paused`, `Suspended`, or `Failed` statuses, some objects may have been processed successfully.

    • If a job remains in the `Suspended` state for more than 14 days without user confirmation, its status changes to `Failed`.

    • When a job is canceled, it does not stop immediately. The job first enters the `Cancelling` state for a period of time.

    Permissions

    An Alibaba Cloud account has full permissions by default. RAM users and RAM roles require explicit permissions granted through a RAM Policy or a Bucket Policy.

    API

    Action

    Description

    CreateJob

    oss:CreateJob

    Creates a batch operation job.

    Request syntax

    POST /?batchJob HTTP/1.1
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<CreateJobRequest>
  <ConfirmationRequired>boolean</ConfirmationRequired>
  <Operation>
    <PutObjectTagging>
      <TagSet>
        <Tag>
          <Key>string</Key>
          <Value>string</Value>
        </Tag>
      </TagSet>
    </PutObjectTagging>
    <DeleteObjectTagging>
    </DeleteObjectTagging>
    <PutObjectAcl>
      <ObjectAcl>string</ObjectAcl>
    </PutObjectAcl>
    <RestoreObject>
      <Days>integer</Days>
      <Tier>string</Tier>
    </RestoreObject>
  </Operation>
  <Report>
    <Bucket>string</Bucket>
    <Enabled>boolean</Enabled>
    <Prefix>string</Prefix>
    <ReportScope>string</ReportScope>
  </Report>
  <ClientRequestToken>string</ClientRequestToken>
  <Manifest>
    <Location>
      <ETag>string</ETag>
      <Bucket>string</Bucket>
      <Object>string</Object>
      <VersionId>string</VersionId>
    </Location>
    <Spec>
      <Fields>string</Fields>
      <Format>string</Format>
    </Spec>
  </Manifest>
  <Description>string</Description>
  <Priority>integer</Priority>
  <RoleArn>string</RoleArn>
</CreateJobRequest>

    Request headers

    This operation uses only common request headers. For more information, see Common Request Headers.

    Request elements

    Name

    Type

    Required

    Example

    Description

    CreateJobRequest

    Container

    Yes

    None

    The root node of the batch operation job.

    Child nodes: ConfirmationRequired, Operation, Report, ClientRequestToken, Manifest, KeyPrefixManifestGenerator, Description, Priority, and RoleArn

    Parent node: None

    ConfirmationRequired

    Boolean

    No

    false

    Confirmation before the job is executed.

    Child node: None

    Parent node: CreateJobRequest

    Description

    String

    No

    Description of the batch operation job

    The description of the job.

    Child node: None

    Parent node: CreateJobRequest

    Priority

    Integer

    Yes

    10

    The priority of the job.

    Child node: None

    Parent node: CreateJobRequest

    RoleArn

    String

    Yes

    arn:acs:ram::uid:role/BatchOperationRole

    The RAM role that OSS assumes to execute the batch operation job.

    Child node: None

    Parent node: CreateJobRequest

    Operation

    Container

    Yes

    None

    The type of operation to perform in the batch job. Only one operation type is allowed. Supported operations include PutObjectTagging, AddObjectTagging, DeleteObjectTagging, PutObjectAcl, and RestoreObject.

    Child nodes: PutObjectTagging, AddObjectTagging, DeleteObjectTagging, PutObjectAcl, and RestoreObject

    Parent node: CreateJobRequest

    PutObjectTagging

    Container

    No

    None

    The operation to set object tags.

    Child node: TagSet

    Parent node: Operation

    TagSet

    Container

    Yes (when PutObjectTagging is used)

    None

    A collection of tag keys and values.

    Child node: Tag

    Parent node: PutObjectTagging

    Tag

    Container

    Yes

    None

    A tag item.

    Child nodes: Key and Value

    Parent node: TagSet

    Key

    String

    Yes

    Environment

    The tag key.

    Child node: None

    Parent node: Tag

    Value

    String

    Yes

    Production

    The tag value.

    Child node: None

    Parent node: Tag

    DeleteObjectTagging

    Container

    No

    None

    The operation to delete object tags. This is an empty node.

    Child node: None

    Parent node: Operation

    PutObjectAcl

    Container

    No

    None

    The operation to set an object's ACL.

    Child node: ObjectAcl

    Parent node: Operation

    ObjectAcl

    String

    Yes (when PutObjectAcl is used)

    private

    The ACL of the object. Valid values: default, private, public-read, and public-read-write.

    Child node: None

    Parent node: PutObjectAcl

    RestoreObject

    Container

    No

    None

    The operation to restore an archived object.

    Child nodes: Days and Tier

    Parent node: Operation

    Days

    Integer

    No

    7

    The number of days to keep the restored Archive, Cold Archive, or Deep Cold Archive object available. For Archive objects, the value range is 1 to 7. For Cold Archive and Deep Cold Archive objects, the value range is 1 to 365.

    Child node: None

    Parent node: RestoreObject

    Tier

    String

    No

    Standard

    The restoration priority for Cold Archive or Deep Cold Archive objects. For Cold Archive objects, valid values are Standard (2 to 5 hours) and Bulk (5 to 12 hours). For Deep Cold Archive objects, the valid value is Standard (within 48 hours).

    Child node: None

    Parent node: RestoreObject

    Report

    Container

    Yes

    None

    The configuration node for the output report.

    Child nodes: Bucket, Enabled, Prefix, and ReportScope

    Parent node: CreateJobRequest

    Bucket

    String

    Yes

    report-bucket

    The bucket where the output report is stored. The destination bucket must be in the same region as the batch operation job.

    Child node: None

    Parent node: Report

    Enabled

    Boolean

    Yes

    true

    Specifies whether to generate a report.

    Child node: None

    Parent node: Report

    Prefix

    String

    No

    reports/

    The prefix for the output report. This lets you store the report in a subdirectory.

    Child node: None

    Parent node: Report

    ReportScope

    String

    No

    AllTasks

    The scope of the report. Valid values: AllTasks and FailedTasksOnly. Default value: AllTasks (reports on all tasks).

    Child node: None

    Parent node: Report

    ClientRequestToken

    String

    Yes

    unique-token-123

    A unique identifier to ensure the idempotence of the request. The length must be 1 to 64 characters.

    Child node: None

    Parent node: CreateJobRequest

    Manifest

    Container

    Conditionally required

    None

    The manifest file node. You must specify either this node or KeyPrefixManifestGenerator.

    Child nodes: Location and Spec

    Parent node: CreateJobRequest

    Location

    Container

    Yes (when Manifest is used)

    None

    The location of the manifest file. The bucket that contains the manifest file must be in the same region as the batch operation job.

    Child nodes: ETag, Bucket, Object, and VersionId

    Parent node: Manifest

    ETag

    String

    No

    d41d8cd98f00b204e9800998ecf8427e

    The ETag of the manifest file.

    Child node: None

    Parent node: Location

    Object

    String

    Yes

    manifest.csv

    The object that corresponds to the manifest file.

    Child node: None

    Parent node: Location

    VersionId

    String

    No

    3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo

    The version ID of the object that corresponds to the manifest file.

    Child node: None

    Parent node: Location

    Spec

    Container

    Yes (when Manifest is used)

    None

    The format of the manifest file.

    Child nodes: Fields and Format

    Parent node: Manifest

    Format

    String

    Yes

    OSS_BatchOperations_CSV_20250611

    The type of manifest file. Valid values:

    • OSS_BatchOperations_CSV_20250611: The CSV format for OSS Batch Operations. Use this for manifest files created for batch operation jobs.

    • OSS_InventoryReport_CSV_20250611: The CSV format for OSS inventory reports. Use this for manifest reports generated by the inventory feature.

    Child node: None

    Parent node: Spec

    Fields

    String

    No

    Bucket,Key,VersionId

    If you upload a custom CSV file, define the CSV format.

    Child node: None

    Parent node: Spec

    KeyPrefixManifestGenerator

    Container

    Conditionally required

    None

    Generates a manifest file based on a prefix. You must specify either this node or Manifest.

    Child nodes: SourceBucket and Prefix

    Parent node: CreateJobRequest

    SourceBucket

    String

    Yes (when KeyPrefixManifestGenerator is used)

    source-bucket

    The source bucket for the manifest file.

    Child node: None

    Parent node: KeyPrefixManifestGenerator

    Prefix

    String

    No

    prefix/

    The object prefix used to filter objects for processing.

    Child node: None

    Parent node: KeyPrefixManifestGenerator

    Response elements

    Name

    Type

    Example

    Description

    JobId

    String

    MzRjZGU2NGQ3YTY5NGRhMTkxZmZhYzY5OTM5YTcxYWU=

    The job ID generated by OSS. The value is 44 characters long and contains only letters (a-z, A-Z) and digits (0-9), without hyphens (-) or underscores (_).

    Response headers

    This operation uses only common response headers. For more information, see Common Response Headers.

    Examples

    • Sample request

      POST /?batchJob HTTP/1.1
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<CreateJobRequest>
  <ConfirmationRequired>false</ConfirmationRequired>
  <Operation>
    <PutObjectTagging>
      <TagSet>
        <Tag>
          <Key>Environment</Key>
          <Value>Production</Value>
        </Tag>
      </TagSet>
    </PutObjectTagging>
  </Operation>
  <Report>
    <Bucket>report-bucket</Bucket>
    <Enabled>true</Enabled>
    <Prefix>batch-reports/</Prefix>
    <ReportScope>AllTasks</ReportScope>
  </Report>
  <ClientRequestToken>unique-token-123</ClientRequestToken>
  <Manifest>
    <Location>
      <ETag>d41d8cd98f00b204e9800998ecf8427e</ETag>
      <Bucket>manifest-bucket</Bucket>
      <Object>manifest.csv</Object>
    </Location>
    <Spec>
      <Fields>Bucket,Key</Fields>
      <Format>OSS_BatchOperations_CSV_20250611</Format>
    </Spec>
  </Manifest>
  <Description>Batch job to set object tags</Description>
  <Priority>10</Priority>
  <RoleArn>arn:acs:ram::uid:role/BatchOperationRole</RoleArn>
</CreateJobRequest>

    • Sample response

      HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<CreateJobResult>
   <JobId>MzRjZGU2NGQ3YTY5NGRhMTkxZmZhYzY5OTM5YTcxYWU=</JobId>
</CreateJobResult>