Create a batch job by using the CreateJob API - Object Storage Service

Call the CreateJob operation to create 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

By default, an Alibaba Cloud account has all permissions. In contrast, a Resource Access Management (RAM) user or a RAM role has no permissions by default. The Alibaba Cloud account owner or an administrator must grant permissions using 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	Describes 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 JobId generated by OSS for the task. It is 44 characters long and contains letters (a-z, A-Z) and digits (0-9). It does not contain 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>