Use Batch Operations to manage billions of objects - Object Storage Service

Availability

Batch Operations is available in China (Hangzhou), China (Shanghai), China (Shenzhen), China (Guangzhou), China (Qingdao), China (Beijing), China (Zhangjiakou), China (Hohhot), China (Ulanqab), China (Chengdu), China (Hong Kong), Singapore, Indonesia (Jakarta), and Germany (Frankfurt).

Workflow

Create a RAM role: Grant OSS permission to read manifests, perform batch operations, and generate reports.
Prepare a manifest: Specify the target objects using a bucket inventory file (manifest.json), a prefix, or a CSV manifest file (manifest.csv).
Create a job: Configure the operation (for example, tags, permissions, or restore) and submit the job.
Manage the job: Monitor the job status, confirm pending jobs, review execution reports, and adjust priority or cancel jobs.

Step 1: Create a RAM role

In the RAM console, create a RAM role. Set the trusted entity type to Alibaba Cloud Service and select Object Storage Service as the trusted service.
Create and attach a custom permission policy to the role. In the following policy, replace your-bucket with your actual bucket name.
```
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetBucketInfo",
        "oss:ListObjects",
        "oss:GetObject",
        "oss:GetObjectTagging",
        "oss:PutObjectTagging",
        "oss:DeleteObjectTagging",
        "oss:PutObjectAcl",
        "oss:RestoreObject",
        "oss:PutObject"
      ],
      "Resource": [
        "acs:oss:*:*:your-bucket",
        "acs:oss:*:*:your-bucket/*"
      ]
    }
  ]
}
```
Permissions
- Required permissions
  - oss:GetBucketInfo - Required to retrieve bucket metadata.
- Manifest-related permissions
  - oss:ListObjects - Required for prefix-based manifests.
  - oss:GetObject - Required for reading a bucket inventory file or a CSV manifest file.
- Permissions for batch operations
  - oss:GetObjectTagging - Required to batch replace tags (reads existing tags first).
  - oss:PutObjectTagging - Required to batch add or replace tags.
  - oss:DeleteObjectTagging - Required to batch delete tags.
  - oss:PutObjectAcl - Required to batch modify ACLs.
  - oss:RestoreObject - Required to batch restore archived objects.
- Permission for report output
  - oss:PutObject - Required to upload batch operation report files.
Record the role ARN, for example, acs:ram::<your-account-uid>:role/BatchRole. You will need it later.

Step 2: Prepare an input manifest

For a batch operation, you must specify which objects to process.

Bucket Inventory manifest file: Ideal for large-scale, recurring batch operations.
Prefix: Processes all objects with a specific prefix.
CSV manifest file: A CSV file listing the specific objects to process.

Bucket Inventory manifest file

Uses a manifest file automatically generated by Bucket Inventory.

<Manifest>
    <Location>
        <ETag>495B279A99C2BA72A66CA1E23B5FEA13</ETag>
        <Bucket>my-bucket</Bucket>
        <Object>inventory-reports/my-bucket/daily-inventory/2025-10-29T12-49Z/manifest.json</Object>
    </Location>
    <Spec>
        <Format>OSS_InventoryReport_CSV_20250611</Format>
    </Spec>
</Manifest>

Configuration

ETag: The ETag of the manifest.json file.
Format: OSS_InventoryReport_CSV_20250611

Prefix

Automatically generates an object list based on the specified prefix.

<KeyPrefixManifestGenerator>
    <SourceBucket>my-bucket</SourceBucket>
    <Prefix>documents/2024/</Prefix>
</KeyPrefixManifestGenerator>

CSV manifest file

Uses a CSV file to precisely list objects. The CSV manifest file must be uploaded to OSS and located in the same region as the batch job.

<Manifest>
    <Location>
        <Bucket>my-bucket</Bucket>
        <Object>manifest.csv</Object>
        <ETag>1466CA50719515AAE6F92101D83B6A20</ETag>
    </Location>
    <Spec>
        <Format>OSS_BatchOperations_CSV_20250611</Format>
        <Fields>Bucket,Key</Fields>
    </Spec>
</Manifest>

Configuration

ETag: The ETag of the manifest.csv file.
Fields: The column definitions in the CSV file.
- Versioning disabled: Bucket,Key
- Versioning enabled: Bucket,Key,VersionId
Format: OSS_BatchOperations_CSV_20250611

CSV file format

File encoding: UTF-8 encoded.
Field delimiter: Separated by a comma (,).
Object key encoding: URL-encoded (for example, documents%2Freport1.pdf).
Comments: Not supported.

CSV file examples

Versioning disabled

my-bucket,documents%2Freport1.pdf
my-bucket,documents%2Freport2.pdf
my-bucket,images%2Fphoto1.jpg

Versioning enabled

my-bucket,important%2Fdata.json,3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
my-bucket,config%2Fsettings.xml,null

Step 3: Create a job

Batch replace tags

The replace operation removes all existing tags from an object and applies a new set of tags. An object can have up to 10 tags. The total size of all tag keys and values cannot exceed 1 KB. Tag keys must be unique for each object and are case-sensitive.

Warning

If you have a lifecycle rule that depends on tags, you must check the results in the completion report after the batch job completes. A batch job is a non-atomic operation. This means that some object tagging operations may succeed while others fail, regardless of the final job status (Running, Complete, Failed, Paused, or Cancelled). Review the success and failure counts in the report to ensure that the outcome meets your expectations.

ossutil 2.0

ossutil api invoke-operation --op-name create-job --method POST --parameters batchJob --body file:///path/to/config.xml --endpoint oss-cn-hangzhou.aliyuncs.com

Bucket inventory file

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <PutObjectTagging>
            <TagSet>
                <Tag><Key>Environment</Key><Value>Production</Value></Tag>
                <Tag><Key>Team</Key><Value>DataOps</Value></Tag>
            </TagSet>
        </PutObjectTagging>
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>put-tag-inventory-job-001</ClientRequestToken>
    <Manifest>
        <Location>
            <ETag>495B279A99C2BA72A66CA1E23B5FEA13</ETag>
            <Bucket>my-bucket</Bucket>
            <Object>inventory-reports/my-bucket/daily-inventory/2025-10-29T12-49Z/manifest.json</Object>
        </Location>
        <Spec>
            <Format>OSS_InventoryReport_CSV_20250611</Format>
        </Spec>
    </Manifest>
    <Description>Batch replace tags using Inventory manifest</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

Prefix

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <PutObjectTagging>
            <TagSet>
                <Tag><Key>Environment</Key><Value>Production</Value></Tag>
                <Tag><Key>Team</Key><Value>DataOps</Value></Tag>
            </TagSet>
        </PutObjectTagging>
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>put-tag-job-001</ClientRequestToken>
    <KeyPrefixManifestGenerator>
        <SourceBucket>my-bucket</SourceBucket>
        <Prefix>documents/2024/</Prefix>
    </KeyPrefixManifestGenerator>
    <Description>Batch replace tags for documents</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

CSV manifest file

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <PutObjectTagging>
            <TagSet>
                <Tag><Key>Environment</Key><Value>Production</Value></Tag>
                <Tag><Key>Team</Key><Value>DataOps</Value></Tag>
            </TagSet>
        </PutObjectTagging>
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>put-tag-job-001</ClientRequestToken>
    <Manifest>
        <Location>
            <ETag>1466CA50719515AAE6F92101D83B6A20</ETag>
            <Bucket>my-bucket</Bucket>
            <Object>manifest.csv</Object>
        </Location>
        <Spec>
            <Fields>Bucket,Key</Fields>
            <Format>OSS_BatchOperations_CSV_20250611</Format>
        </Spec>
    </Manifest>
    <Description>Batch replace tags for specified objects</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

Response example

<?xml version="1.0" encoding="UTF-8"?>
<CreateJobResult>
  <JobId>ODRiZWQ5Njc5ZTE0NDE5NTlmNjJmZDlkMTk2ODI2NDU=</JobId>
</CreateJobResult>

After a job is created, it enters the Suspended state. Check the job status to verify the configuration, and then manually confirm it for execution.

API

Call the CreateJob operation to create a batch job. In the XML configuration, specify the <PutObjectTagging> operation type in the <Operation> node. Define the new tag set within the <TagSet> node to replace all existing tags on the objects.

Batch add tags

The add tags operation appends new tags to an object while preserving existing tags, which is useful for supplementing metadata. If a new tag uses the same key as an existing tag, its value overwrites the existing value. As this is a non-atomic operation, it may lead to data inconsistency in high-concurrency scenarios. To ensure data consistency, avoid running this operation concurrently with other tagging operations.

Warning

If you have a lifecycle rule that depends on tags, you must check the results in the completion report after the batch job completes. A batch job is a non-atomic operation. This means that some tagging operations may succeed while others fail, regardless of the final job status. Review the success and failure counts in the report to ensure that the outcome meets your expectations.

ossutil 2.0

ossutil api invoke-operation --op-name create-job --method POST --parameters batchJob --body file:///path/to/config.xml --endpoint oss-cn-hangzhou.aliyuncs.com

Bucket inventory file

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <AddObjectTagging>
            <TagSet>
                <Tag><Key>Department</Key><Value>Engineering</Value></Tag>
                <Tag><Key>Project</Key><Value>BatchOps</Value></Tag>
            </TagSet>
        </AddObjectTagging>
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>add-tag-inventory-job-001</ClientRequestToken>
    <Manifest>
        <Location>
            <ETag>495B279A99C2BA72A66CA1E23B5FEA13</ETag>
            <Bucket>my-bucket</Bucket>
            <Object>inventory-reports/my-bucket/daily-inventory/2025-10-29T12-49Z/manifest.json</Object>
        </Location>
        <Spec>
            <Format>OSS_InventoryReport_CSV_20250611</Format>
        </Spec>
    </Manifest>
    <Description>Batch add tags using Inventory manifest</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

Prefix

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <AddObjectTagging>
            <TagSet>
                <Tag><Key>Department</Key><Value>Engineering</Value></Tag>
                <Tag><Key>Project</Key><Value>BatchOps</Value></Tag>
            </TagSet>
        </AddObjectTagging>
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>add-tag-job-001</ClientRequestToken>
    <KeyPrefixManifestGenerator>
        <SourceBucket>my-bucket</SourceBucket>
        <Prefix>documents/2024/</Prefix>
    </KeyPrefixManifestGenerator>
    <Description>Batch add tags to documents</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

CSV manifest file

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <AddObjectTagging>
            <TagSet>
                <Tag><Key>Department</Key><Value>Engineering</Value></Tag>
                <Tag><Key>Project</Key><Value>BatchOps</Value></Tag>
            </TagSet>
        </AddObjectTagging>
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>add-tag-job-001</ClientRequestToken>
    <Manifest>
        <Location>
            <ETag>1466CA50719515AAE6F92101D83B6A20</ETag>
            <Bucket>my-bucket</Bucket>
            <Object>manifest.csv</Object>
        </Location>
        <Spec>
            <Fields>Bucket,Key</Fields>
            <Format>OSS_BatchOperations_CSV_20250611</Format>
        </Spec>
    </Manifest>
    <Description>Batch add tags to specified objects</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

Response example

<?xml version="1.0" encoding="UTF-8"?>
<CreateJobResult>
  <JobId>Nzg5ZjE3ZTU5OGMxNDZjZDk0YjJiODMzZDZiZjA0ZmU=</JobId>
</CreateJobResult>

After a job is created, it enters the Suspended state. Check the job status to verify the configuration, and then manually confirm it for execution.

API

Call the CreateJob operation to create a batch job. In the XML configuration, specify the <AddObjectTagging> operation type in the <Operation> node. Define the new tags to add within the <TagSet> node. The system adds the new tags while preserving existing ones.

Batch delete tags

This operation removes all tags from the specified objects, which is useful for bulk tag cleanup.

Warning

This operation is irreversible, and deleted tags cannot be recovered. To avoid affecting your business logic, test this operation in a test environment before running it in a production environment.
If you have a lifecycle rule that depends on tags, you must check the results in the completion report after the batch job completes. A batch job is a non-atomic operation. This means that some tag deletion operations may succeed while others fail, regardless of the final job status. Review the success and failure counts in the report to ensure that the outcome meets your expectations.

ossutil 2.0

ossutil api invoke-operation --op-name create-job --method POST --parameters batchJob --body file:///path/to/config.xml --endpoint oss-cn-hangzhou.aliyuncs.com

Bucket inventory file

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <DeleteObjectTagging />
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>delete-tag-inventory-job-001</ClientRequestToken>
    <Manifest>
        <Location>
            <ETag>495B279A99C2BA72A66CA1E23B5FEA13</ETag>
            <Bucket>my-bucket</Bucket>
            <Object>inventory-reports/my-bucket/daily-inventory/2025-10-29T12-49Z/manifest.json</Object>
        </Location>
        <Spec>
            <Format>OSS_InventoryReport_CSV_20250611</Format>
        </Spec>
    </Manifest>
    <Description>Batch delete tags using Inventory manifest</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

Prefix

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <DeleteObjectTagging />
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>delete-tag-job-001</ClientRequestToken>
    <KeyPrefixManifestGenerator>
        <SourceBucket>my-bucket</SourceBucket>
        <Prefix>documents/2024/</Prefix>
    </KeyPrefixManifestGenerator>
    <Description>Batch delete tags for documents</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

CSV manifest file

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <DeleteObjectTagging />
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>delete-tag-job-001</ClientRequestToken>
    <Manifest>
        <Location>
            <ETag>1466CA50719515AAE6F92101D83B6A20</ETag>
            <Bucket>my-bucket</Bucket>
            <Object>manifest.csv</Object>
        </Location>
        <Spec>
            <Fields>Bucket,Key</Fields>
            <Format>OSS_BatchOperations_CSV_20250611</Format>
        </Spec>
    </Manifest>
    <Description>Batch delete tags for specified objects</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

Response example

<?xml version="1.0" encoding="UTF-8"?>
<CreateJobResult>
  <JobId>NTVlYmQ4ZmQyOTM0NDJmY2E2NmNjYTUwNjU1ZGRkMGM=</JobId>
</CreateJobResult>

After a job is created, it enters the Suspended state. Check the job status to verify the configuration, and then manually confirm it for execution.

API

Call the CreateJob operation to create a batch job. In the XML configuration, specify the <DeleteObjectTagging/> operation type in the <Operation> node. No additional parameters are required. The system will delete all tags from the specified objects.

Batch modify ACLs

Batch Operations supports four predefined ACLs for objects: private (only the owner can read and write), public-read (all users can read; only the owner can write), public-read-write (all users can read and write), and default (inherits the ACL from the bucket). ACL changes take effect immediately and directly impact object access. Choose the appropriate ACL type carefully based on your business requirements.

ossutil 2.0

ossutil api invoke-operation --op-name create-job --method POST --parameters batchJob --body file:///path/to/config.xml --endpoint oss-cn-hangzhou.aliyuncs.com

Bucket inventory file

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <PutObjectAcl>
            <ObjectAcl>private</ObjectAcl>
        </PutObjectAcl>
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>acl-inventory-job-001</ClientRequestToken>
    <Manifest>
        <Location>
            <ETag>495B279A99C2BA72A66CA1E23B5FEA13</ETag>
            <Bucket>my-bucket</Bucket>
            <Object>inventory-reports/my-bucket/daily-inventory/2025-10-29T12-49Z/manifest.json</Object>
        </Location>
        <Spec>
            <Format>OSS_InventoryReport_CSV_20250611</Format>
        </Spec>
    </Manifest>
    <Description>Batch change ACL using Inventory manifest</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

Prefix

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <PutObjectAcl>
            <ObjectAcl>private</ObjectAcl>
        </PutObjectAcl>
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>acl-job-001</ClientRequestToken>
    <KeyPrefixManifestGenerator>
        <SourceBucket>my-bucket</SourceBucket>
        <Prefix>documents/2024/</Prefix>
    </KeyPrefixManifestGenerator>
    <Description>Batch change ACL to private for documents</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

CSV manifest file

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <PutObjectAcl>
            <ObjectAcl>private</ObjectAcl>
        </PutObjectAcl>
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>acl-job-001</ClientRequestToken>
    <Manifest>
        <Location>
            <ETag>1466CA50719515AAE6F92101D83B6A20</ETag>
            <Bucket>my-bucket</Bucket>
            <Object>manifest.csv</Object>
        </Location>
        <Spec>
            <Fields>Bucket,Key</Fields>
            <Format>OSS_BatchOperations_CSV_20250611</Format>
        </Spec>
    </Manifest>
    <Description>Batch change ACL to private for specified objects</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

Response example

<?xml version="1.0" encoding="UTF-8"?>
<CreateJobResult>
  <JobId>YWNsR29iMTIzNDU2Nzg5MA==</JobId>
</CreateJobResult>

After you create a job, it enters the Suspended state. Check the job status to verify the configuration, and then manually confirm the job for execution.

API

Call the CreateJob API to create a batch job. In the XML configuration, specify the <PutObjectAcl> operation type in the <Operation> node and use the <ObjectAcl> parameter to set the target permission (private/public-read/public-read-write/default).

Batch restore archived objects

Batch restore operations support objects in the Archive, Cold Archive, and Deep Cold Archive storage classes. For Archive objects, restoration typically completes within one hour, and they remain accessible for 1 to 7 days. The Cold Archive storage class offers two restore tiers: Standard (2–5 hours) and Bulk (5–12 hours). The Deep Cold Archive storage class supports only the Standard tier, which takes up to 48 hours to complete. You can set the accessibility period for a restored object to any value from 1 to 365 days.

Important

If the storage class of an object does not match the specified tier or the accessibility period is out of range, the operation for that object will fail.

ossutil 2.0

ossutil api invoke-operation --op-name create-job --method POST --parameters batchJob --body file:///path/to/config.xml --endpoint oss-cn-hangzhou.aliyuncs.com

Bucket inventory file

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <RestoreObject>
            <Days>7</Days>
            <Tier>Standard</Tier>
        </RestoreObject>
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>restore-inventory-job-001</ClientRequestToken>
    <Manifest>
        <Location>
            <ETag>495B279A99C2BA72A66CA1E23B5FEA13</ETag>
            <Bucket>my-bucket</Bucket>
            <Object>inventory-reports/my-bucket/daily-inventory/2025-10-29T12-49Z/manifest.json</Object>
        </Location>
        <Spec>
            <Format>OSS_InventoryReport_CSV_20250611</Format>
        </Spec>
    </Manifest>
    <Description>Batch restore using Inventory manifest for 7 days</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

Prefix

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <RestoreObject>
            <Days>7</Days>
            <Tier>Standard</Tier>
        </RestoreObject>
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>restore-job-001</ClientRequestToken>
    <KeyPrefixManifestGenerator>
        <SourceBucket>my-bucket</SourceBucket>
        <Prefix>archive/2024/</Prefix>
    </KeyPrefixManifestGenerator>
    <Description>Batch restore archive objects for 7 days</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

CSV manifest file

<CreateJobRequest>
    <ConfirmationRequired>true</ConfirmationRequired>
    <Operation>
        <RestoreObject>
            <Days>7</Days>
            <Tier>Standard</Tier>
        </RestoreObject>
    </Operation>
    <Report>
        <Bucket>my-bucket</Bucket>
        <Enabled>true</Enabled>
        <Prefix>batch-reports/</Prefix>
        <ReportScope>AllTasks</ReportScope>
    </Report>
    <ClientRequestToken>restore-job-001</ClientRequestToken>
    <Manifest>
        <Location>
            <ETag>1466CA50719515AAE6F92101D83B6A20</ETag>
            <Bucket>my-bucket</Bucket>
            <Object>manifest.csv</Object>
        </Location>
        <Spec>
            <Fields>Bucket,Key</Fields>
            <Format>OSS_BatchOperations_CSV_20250611</Format>
        </Spec>
    </Manifest>
    <Description>Batch restore specified archive objects for 7 days</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

Response example

<?xml version="1.0" encoding="UTF-8"?>
<CreateJobResult>
  <JobId>cmVzdG9yZUpvYjEyMzQ1Njc4OTA=</JobId>
</CreateJobResult>

After creation, the job enters the Suspended state. Check the job status to verify the configuration, and then manually confirm the job for execution.

API

Call the CreateJob operation to create a batch job. In your XML configuration, within the <Operation> node, specify <RestoreObject>. Use <Days> to set the accessibility period (1–365) and <Tier> to set the restore tier (Standard or Bulk).

Step 4: Manage and monitor jobs

View job status

After you create a job, query its details to monitor and confirm its status. The response contains complete information for the specified job, including its execution progress and configuration parameters.

Important

A job status of Complete does not mean all objects were processed successfully. You must review the detailed report to confirm the final results.

ossutil 2.0

ossutil api invoke-operation --op-name describe-job --method GET --parameters batchJob --parameters batchJobId=<JobId> --endpoint oss-cn-hangzhou.aliyuncs.com

Sample response

<?xml version="1.0" encoding="UTF-8"?>
<DescribeJobResult>
  <Job>
    <ConfirmationRequired>true</ConfirmationRequired>
    <CreationTime>1761723644</CreationTime>
    <FailureReasons>
      <JobFailure />
    </FailureReasons>
    <JobId>M2E0ODMyNmJjYmYzNGY0ZThiYjMyMmI1ZDE1YWE0OGE=</JobId>
    <Operation>
      <PutObjectTagging>
        <TagSet>
          <Tag>
            <Key>Environment</Key>
            <Value>Production</Value>
          </Tag>
          <Tag>
            <Key>Team</Key>
            <Value>DataOps</Value>
          </Tag>
        </TagSet>
      </PutObjectTagging>
    </Operation>
    <Report>
      <Enabled>true</Enabled>
      <Bucket>my-bucket</Bucket>
      <Prefix>batch-reports/</Prefix>
      <ReportScope>AllTasks</ReportScope>
    </Report>
    <Manifest>
      <Location>
        <ETag>1466CA50719515AAE6F92101D83B6A20</ETag>
        <Bucket>my-bucket</Bucket>
        <Object>manifest.csv</Object>
      </Location>
      <Spec>
        <Format>OSS_BatchOperations_CSV_20250611</Format>
        <Fields>Bucket,Key</Fields>
      </Spec>
    </Manifest>
    <Description>Test task for Suspended status</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
    <ProgressSummary>
      <NumberOfTasksFailed>0</NumberOfTasksFailed>
      <NumberOfTasksSucceeded>0</NumberOfTasksSucceeded>
      <TotalNumberOfTasks>3</TotalNumberOfTasks>
      <Timers>
        <ElapsedTimeInActiveSeconds>-1</ElapsedTimeInActiveSeconds>
      </Timers>
    </ProgressSummary>
    <Status>Suspended</Status>
    <TerminationDate>-1</TerminationDate>
  </Job>
</DescribeJobResult>

Status description:

ConfirmationRequired: true - The job requires manual confirmation.
Status: Suspended - The job is suspended and waiting for confirmation.
TotalNumberOfTasks: 3 - An estimated 3 objects will be processed.
NumberOfTasksSucceeded: 0 - The job has not started.
ElapsedTimeInActiveSeconds: -1 - Indicates the job has not yet started.

API

Use the DescribeJob operation to get details for a specific job, including its execution status, progress summary, configuration parameters, and error information.

Confirm a job

Change a job's status from Suspended to Ready to place it in the execution queue. If a job is not confirmed within 14 days, its status automatically changes to Failed.

ossutil 2.0

ossutil api invoke-operation --op-name update-job-status --method POST --parameters batchJobStatus --parameters batchJobId=<JobId> --parameters requestedJobStatus=Ready --endpoint oss-cn-hangzhou.aliyuncs.com

Sample response

<?xml version="1.0" encoding="UTF-8"?>
<UpdateJobStatusResult>
  <JobId>NGFhNmFmZDRlNTcxNDE2OGFhY2FjYWQyNDcxYjc3YzM=</JobId>
  <Status>Ready</Status>
</UpdateJobStatusResult>

API

Use the UpdateJobStatus operation to confirm a job for execution. This changes the job's status from Suspended to Ready and adds it to the execution queue.

List jobs

View all of your jobs. You can filter the job list by status and creation time range, limit the number of results, and use pagination to manage large numbers of jobs. By default, the results are sorted by creation time in descending order.

ossutil 2.0

ossutil api invoke-operation --op-name list-jobs --method GET --parameters batchJob --parameters maxKeys=100 --endpoint oss-cn-hangzhou.aliyuncs.com

Sample response

<?xml version="1.0" encoding="UTF-8"?>
<ListJobsResult>
  <Jobs>
    <Job>
      <JobId>OTE5ZGU1NWMxNjkyNGFkMjhkYTNmOGEzNTU2YmJiOWE=</JobId>
      <Status>Complete</Status>
      <CreationTime>1761666548</CreationTime>
    </Job>
  </Jobs>
</ListJobsResult>

API

Use the ListJobs operation to list the batch jobs in your account. You can filter by status and time range and use pagination for easier management and monitoring.

Update job priority

The priority is an integer from 0 to 2,147,483,647, where a higher value indicates a higher priority. Job priority does not guarantee a strict execution order. Instead, OSS allocates more resources to higher-priority jobs on a best-effort basis.

ossutil 2.0

ossutil api invoke-operation --op-name update-job-priority --method POST --parameters batchJobPriority --parameters batchJobId=<JobId> --parameters priority=1000 --endpoint oss-cn-hangzhou.aliyuncs.com

Sample response

<?xml version="1.0" encoding="UTF-8"?>
<UpdateJobPriorityResult>
  <JobId>OTE5ZGU1NWMxNjkyNGFkMjhkYTNmOGEzNTU2YmJiOWE=</JobId>
  <Priority>1000</Priority>
</UpdateJobPriorityResult>

API

Use the UpdateJobPriority operation to adjust a job's execution priority to influence resource scheduling and prioritize urgent jobs.

Cancel a job

Cancels a running or pending job. You cannot roll back operations on objects that have already been processed.

ossutil 2.0

ossutil api invoke-operation --op-name update-job-status --method POST --parameters batchJob --parameters batchJobId=<JobId> --parameters requestedJobStatus=Cancelled --endpoint oss-cn-hangzhou.aliyuncs.com

Sample response

<?xml version="1.0" encoding="UTF-8"?>
<UpdateJobStatusResult>
  <JobId>OTE5ZGU1NWMxNjkyNGFkMjhkYTNmOGEzNTU2YmJiOWE=</JobId>
  <Status>Cancelled</Status>
</UpdateJobStatusResult>

API

Use the UpdateJobStatus operation to set a job's status to Cancelled, which stops its execution and releases resources.

View job reports

After a job finishes, the system generates a detailed execution report in the location you specified. The report includes two key file types: a manifest.json file and a detailed report file in CSV format. Use these reports to understand the processing status for each object, view HTTP response codes, and identify reasons for failures, for troubleshooting failures and validating results.

Important

Regardless of a job's status, such as Running, Complete, Failed, Suspended, or Cancelled, some objects may be processed successfully while others fail. You must review the detailed report to confirm the actual results.

Report location

Report files are stored at the path specified in the <Report> node when you created the job. The path format is:

<Bucket>/<Prefix>/<JobId>/results/

For example, if you configured the following when creating the job:

<Report>
    <Bucket>my-bucket</Bucket>
    <Prefix>batch-reports/</Prefix>
    <ReportScope>AllTasks</ReportScope>
</Report>

The report files are stored at: my-bucket/batch-reports/<JobId>/results/

Report file structure

The report consists of two parts:

1. Report manifest (manifest.json)

A JSON file containing metadata about the report and the location of the CSV report file.

Example manifest for a successful job:

{
  "Format": "Report_CSV_20250901",
  "ReportCreationDate": "2025-10-31T07:18:56Z",
  "Results": [
    {
      "TaskExecutionStatus": "succeeded",
      "Bucket": "test-bucket",
      "MD5Checksum": "\"424356315f4a82c1b6a4c190dbed15d9\"",
      "Key": "reports/prefix-job-0/job-MTRiZGI1NDFiMTI2NDFiNDg0YWQyYTM2YmY1NzNjNDM=/results/report-0.csv"
    }
  ],
  "ReportSchema": "Bucket,Key,VersionId,HTTPStatus,Error"
}

Example manifest for a failed job:

{
  "Format": "Report_CSV_20250901",
  "ReportCreationDate": "2025-10-31T07:37:56Z",
  "Results": [
    {
      "TaskExecutionStatus": "failed",
      "Bucket": "test-bucket",
      "MD5Checksum": "\"85749f22b5b62b161daf00b4adcf6da7\"",
      "Key": "reports/prefix-job-0/job-M2E4MDkwNGJmNmQzNDgwYmE4ODI1YjdjNDgyNjk5NmM=/results/report-0.csv"
    }
  ],
  "ReportSchema": "Bucket,Key,VersionId,HTTPStatus,Error"
}

Field descriptions:

Format: The report format version, which is fixed at Report_CSV_20250901.
ReportCreationDate: The time the report was generated, in UTC.
TaskExecutionStatus: The overall execution status. succeeded indicates all tasks were successful, while failed indicates all tasks failed.
ReportSchema: The column definitions for the CSV report.

2. Detailed CSV report

This file lists task-level results for each object and includes the following columns:

Bucket: The bucket where the object is located.
Key: The object name (URL-encoded).
VersionId: The version ID. This field is empty if version control is not enabled on the bucket.
HTTPStatus: The HTTP status code. 200 indicates success.
Error: Detailed error information. This field is empty on success.

Example CSV report for successful tasks:

test-bucket,batchOperation%2F1761895099%2Fobject-1.txt,,200,
test-bucket,batchOperation%2F1761895099%2Fobject-9.txt,,200,
test-bucket,batchOperation%2F1761895099%2Fobject-4.txt,,200,
test-bucket,batchOperation%2F1761895099%2Fobject-8.txt,,200,
test-bucket,batchOperation%2F1761895099%2Fobject-3.txt,,200,

Example CSV report for failed tasks:

test-bucket,batchOperation%2F1761896253%2Fobject-0.txt,,403,"Error returned by Service. {""EC"":""0003-00000001"",""Error Code"":""AccessDenied"",""Http Status Code"":403,""Message"":""You have no right to access this object."",""Request Endpoint"":""PUT http://test-bucket.oss-cn-hangzhou-internal.aliyuncs.com/batchOperation/1761896253/object-0.txt?tagging"",""Request Id"":""690467520D9F2E3232004FFD"",""Timestamp"":""2025-10-31T07:37:54Z""}"
test-bucket,batchOperation%2F1761896253%2Fobject-7.txt,,403,"Error returned by Service. {""EC"":""0003-00000001"",""Error Code"":""AccessDenied"",""Http Status Code"":403,""Message"":""You have no right to access this object."",""Request Endpoint"":""PUT http://test-bucket.oss-cn-hangzhou-internal.aliyuncs.com/batchOperation/1761896253/object-7.txt?tagging"",""Request Id"":""69046752A016113937EB7029"",""Timestamp"":""2025-10-31T07:37:54Z""}"

Download and analyze reports

Locate the report files: Use the DescribeJob operation to get job details and find the report path in the <Report> node of the response.
Download manifest.json: Download the manifest file from the report path. Check the TaskExecutionStatus and Results nodes to understand the overall execution status.
Download the CSV report: Use the path specified in the Results[ ].Key field of the manifest.json file to download the detailed CSV report.
Analyze the execution results:
- Check the HTTPStatus column: 2xx indicates success, while 4xx/5xx indicates failure.
- For failed records, check the Error column for the error code and detailed message.
- Count the number of successful and failed objects and compare the counts with the ProgressSummary returned by the DescribeJob operation to validate the summary.

Example: Downloading reports with ossutil

# Download the report manifest file
ossutil cp oss://my-bucket/batch-reports/<JobId>/results/manifest.json ./

# Download the detailed CSV report
ossutil cp oss://my-bucket/batch-reports/<JobId>/results/report-0.csv ./

Common error codes

HTTP status code	Error code	Description	Solution
403	`AccessDenied`	Insufficient permissions to access the object.	Check the RAM role permission configuration.
404	`NoSuchKey`	The object does not exist.	Verify that the object path in the manifest file is correct.
400	`InvalidArgument`	Invalid argument.	Check the operation parameters, such as the tag format or ACL type.
409	`InvalidObjectState`	The object's state does not meet the operation's requirements.	Verify that the object's storage class is compatible with the operation.

Notes

Report files consume storage space and incur storage fees. We recommend periodically deleting historical reports.
For large-scale jobs, the CSV report file can be large. Consider your network bandwidth when downloading it.
If you set ReportScope to FailedTasksOnly, the report includes only failed objects.

Usage in a production environment

Best practices

Job planning

Scale control: To ensure execution stability, limit each job to 100 million objects. For larger datasets, split the data into multiple jobs to reduce the risk of a single point of failure.
Priority management: Set appropriate job priorities to prevent critical jobs from being blocked. Estimate the execution time to schedule maintenance windows accordingly.
Concurrent operations: The execution order is not guaranteed when multiple jobs operate on the same set of objects concurrently. Avoid running concurrent operations on the same object.

Performance optimization

Manifest file optimization: Organize your manifest files to avoid excessively large single files, which can slow down parsing.
QPS quota utilization: Batch operations use a dedicated QPS quota and do not consume your application's API QPS quota.
Concurrency control: Run a maximum of six jobs concurrently to avoid resource contention.
Hotspot avoidance: If the object range for an operation contains a hotspot (for example, a lexicographical prefix), batch operation execution can slow down. In severe cases, operations on some objects might fail.

Error handling

Detailed reports: Enable detailed reporting by setting ReportScope=AllTasks to get complete execution results for troubleshooting.
Retry mechanism: In rare cases, if a batch operation encounters an issue during execution, it may be retried several times. You are billed based on the final number of API calls made.
Failure threshold: If more than 20% of the items in a job fail, the entire job fails immediately and stops processing.
Status confirmation anomalies: In rare cases, some operations may succeed but are marked as failed in the completion report. Double-check any items reported as failed.

Verifying job results

Execution integrity validation: After a job finishes, some objects may have been processed successfully while others failed. This can happen regardless of the final job status (such as Complete, Failed, or Cancelled). Always check the success and failure counts in the completion report to ensure the outcome meets your expectations.
Failure handling recommendations:
- A job status of Complete only means the job has finished its lifecycle; it does not guarantee that all object operations succeeded. You must review the completion report for details.
- For failed tasks, analyze the cause of failure and retry. For jobs that have partially failed, you can create a new retry job based on the failure report.
- For jobs with a Cancelled, Paused, or Failed status, check the report to see if any objects were successfully processed before the job was halted.

Manifest file

Execution order and data consistency

Execution order: Batch operations are performed on the items listed in the manifest file, but the execution order is not guaranteed.
File updates: If an object is updated before the operation is performed, the job will act on the updated version. Do not modify objects while a batch job is in progress.
Limitations of using a prefix: If you use a prefix to specify the manifest, batch operations ignore any objects added to or deleted from that prefix after the job starts. Do not add or delete objects within the prefix while the job is running.

Manifest file format

URL encoding: Objects in a CSV manifest file must be URL-encoded. Otherwise, parsing may fail.
Duplicate key handling: If the manifest file contains duplicate keys, the operation will be executed once for each entry. The order of these executions is not guaranteed.

Resource scheduling

Priority scheduling

The priority range is 0 to 2,147,483,647.

Concurrency control

A single account can run a maximum of six concurrent jobs. Additional jobs are placed in a waiting queue.

Job status

Important

The Complete status only indicates that the job process is finished, not that all object operations were successful.
Jobs with a status of Cancelled, Paused, or Failed may have already processed some objects successfully.
Always review the success and failure counts in the completion report to verify the actual results.

Status	Description	Actions
New	The job has been created and the system is validating its parameters.	None
Preparing	The system is parsing the manifest, validating parameters, and counting the total number of objects.	Cancel job
Suspended	The job is suspended and awaiting user confirmation. If not confirmed within 14 days, the job automatically fails.	Confirm execution or cancel job
Ready	The job is in the queue, awaiting resource scheduling.	Cancel job
Active	The job is running. This includes: • Performing operations on objects • Generating the completion report	Cancel job
Pausing	The current job is being paused due to user resource constraints.	Cancel job
Paused	The job is paused and will resume when resources become available.	Cancel job
Complete	The job has finished running. (Note: This does not mean all objects were processed successfully.)	View report
Cancelling	The user has initiated cancellation, and the system is cleaning up active tasks.	None
Cancelled	The job has been cancelled.	View report
Failing	The system is terminating the job due to invalid parameters or an execution failure rate exceeding 20%.	None
Failed	The job has failed.	View report
Cleaning	Job data is being cleaned up (not visible to users).	None
Cleaned	Job data cleanup is complete (not visible to users).	None

Fault tolerance

Permission verification

Verify access permissions for the source path before creating a job to prevent execution interruptions.
Ensure that the RAM role has the complete permission chain required for the target operation.
Regularly rotate AccessKeys for your RAM role to enhance security.

Data protection

Create a data snapshot or backup before performing batch delete or overwrite operations.
Enable versioning for important data to retain multiple versions.
Verify your operation logic in a test environment before running it in a production environment.

Monitoring and alerting

Configure event notifications for job status changes to stay informed about execution progress.
Monitor job execution times to detect abnormally long-running jobs.
Set up failure rate threshold alerts to respond quickly to anomalies.

Cost control

Billing method

Billing is based on the number of objects processed, at a rate of CNY 1 per 1 million objects.
Job creation is free; you are billed only for the number of objects processed.
This can save over 90% in operational costs compared to calling the API for each object individually.

Optimization

Make full use of the six-concurrent-job limit to avoid idle resources.
Regularly delete historical job reports to save on storage costs.
Promptly clean up test jobs to avoid unnecessary expenses.

Quotas and limits

Item	Limit
Concurrent jobs per account	6
Queued jobs per account	Typically 1,000 per region
Objects per job	10 billion
Manifest file size	10 TB
Objects processed per account per day	Typically 1 billion per region
Job history retention	Typically 30 days or 10,000 entries

Billing

Batch Operations is billed pay-as-you-go at CNY 1 per 1 million processed objects. No fees are charged for job creation or management, and no additional data transfer charges apply.

Important

Standard OSS API charges also apply to the underlying operations on each object. For example, tagging operations incur fees for PUT requests.

Billing examples:

Tagging 5 million objects: 5 million / 1 million * CNY 1 = CNY 5
Processing 5 billion objects: 5 billion / 1 million * CNY 1 = CNY 5,000

Cost optimization tips: Combine related batch operations into a single job to reduce overhead. Use a precise prefix or a manifest file to avoid processing unnecessary objects. Schedule non-urgent batch operations during off-peak hours.

FAQ

Job stuck in the Preparing state

Common causes include:

A large manifest file that takes a long time to parse.
A prefix scan that covers a large number of objects.
High system load, which congests the processing queue.

To resolve this, split large jobs into smaller ones or use a pre-generated manifest file.

Handling failed object operations

Follow these steps:

Download the completion report to analyze failure causes.
Create a new job to retry the operations on the failed objects.
Verify the permission settings and ensure the RAM role has the required permissions.

Cancel a running job

Use the following request:

POST /?batchJobStatus&batchJobId=<JobId>&requestedJobStatus=Cancelled&statusUpdateReason=Cancelled by user HTTP/1.1
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: <SignatureInformation>

Getting an AccessDenied error

Verify the following permissions:

Ensure that the RAM user has the oss:CreateBatchJob permission.
Verify that the RAM role has the required permissions for the operation.
For cross-bucket operations, confirm that the destination bucket has the correct permissions.

RAM role permissions

The RAM role must include:

Read and write permissions for OSS resources.
Permission to call Batch Operations APIs.
Write permission for the completion report's destination bucket.

The trust policy must allow the OSS service to assume the role. The following is an example:

{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": ["oss.aliyuncs.com"]
      }
    }
  ]
}

Improve Batch Operations performance

Consider the following best practices:

Organize manifest files efficiently and avoid using a single, oversized file.
Avoid running large jobs during peak business hours.
Assign higher priorities to process critical jobs first.
Limit the number of objects in a single job to 100 million to prevent long execution times.
Avoid splitting a large job into an excessive number of small jobs, for example, splitting 1 million objects into 1,000 jobs. This increases scheduling overhead.

Slow job completion

Common causes include:

Uneven object distribution, which can cause some data shards to take longer to process.
Data hotspots in either the source or destination bucket, which can degrade processing speed.
Too many concurrent jobs, leading to resource contention.

To resolve this, adjust your job scheduling strategy or reduce the number of concurrent jobs.