Object Storage Service:バッチ操作を使用して数十億個のオブジェクトを管理する

可用性

バッチ操作は、中国 (杭州)、中国 (上海)、中国 (深セン)、中国 (広州)、中国 (青島)、中国 (北京)、中国 (張家口)、中国 (フフホト)、中国 (ウランチャブ)、中国 (成都)、中国 (香港)、シンガポール、インドネシア (ジャカルタ)、ドイツ (フランクフルト) でご利用いただけます。

ワークフロー

1. RAM ロールの作成：マニフェストの読み取り、バッチ操作の実行、レポートの生成に対する OSS の権限を付与します。

1. 入力マニフェストの準備：バケットインベントリファイル（manifest.json）、プレフィックス、または CSV 形式のマニフェストファイル（manifest.csv）を用いて対象オブジェクトを指定します。

2. ジョブの作成：操作内容（例：タグ設定、権限変更、復元）を構成し、ジョブを送信します。

3. ジョブの管理：ジョブのステータスを監視し、保留中のジョブを確認し、実行レポートを確認し、優先度を調整またはジョブをキャンセルします。

手順 1：RAM ロールの作成

1. RAM コンソールで RAM ロールを作成します。信頼されるエンティティの種類を Alibaba Cloud サービス に設定し、信頼されるサービスとして Object Storage Service を選択します。

2. カスタム権限ポリシーを作成し、ロールにアタッチします。以下のポリシーでは、your-bucket を実際のバケット名に置き換えてください。

   {
     "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/*"
         ]
       }
     ]
   }

   必要な権限

   • 必須権限

     • oss:GetBucketInfo — バケットのメタデータを取得するために必要です。

   • マニフェスト関連の権限

     • oss:ListObjects — プレフィックスベースのマニフェストに必要です。

     • oss:GetObject — バケットインベントリファイルまたは CSV 形式のマニフェストファイルを読み取るために必要です。

   • バッチ操作の権限

     • oss:GetObjectTagging — タグの一括置き換えに必要です（既存のタグを事前に読み取ります）。

     • oss:PutObjectTagging — タグの一括追加または置き換えに必要です。

     • oss:DeleteObjectTagging — タグの一括削除に必要です。

     • oss:PutObjectAcl — ACL の一括変更に必要です。

     • oss:RestoreObject — アーカイブ済みオブジェクトの一括復元に必要です。

   • レポート出力の権限

     • oss:PutObject — バッチ操作レポートファイルのアップロードに必要です。

3. ロール ARN（例：acs:ram::<your-account-uid>:role/BatchRole）を記録します。後ほど使用します。

手順 2：入力マニフェストの準備

バッチ操作を実行するには、処理対象のオブジェクトを指定する必要があります。

• バケットインベントリマニフェストファイル：大規模かつ定期的に実行されるバッチ操作に最適です。

• プレフィックス：特定のプレフィックスを持つすべてのオブジェクトを処理します。

• CSV マニフェストファイル：処理対象のオブジェクトを明示的に一覧表示する CSV ファイルです。

バケットインベントリマニフェストファイル

バケットインベントリによって自動生成されたマニフェストファイルを使用します。

<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>

構成

• ETag：manifest.json ファイルの ETag です。

• Format：OSS_InventoryReport_CSV_20250611

プレフィックス

指定されたプレフィックスに基づいてオブジェクトリストを自動生成します。

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

CSV マニフェストファイル

CSV ファイルを用いてオブジェクトを正確に一覧表示します。CSV マニフェストファイルは OSS にアップロードし、バッチジョブと同じリージョンに配置する必要があります。

<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>

構成

• ETag：manifest.csv ファイルの ETag です。

• Fields：CSV ファイル内の列定義です。

  • バージョン管理が無効の場合：Bucket,Key

  • バージョン管理が有効の場合：Bucket,Key,VersionId

• Format：OSS_BatchOperations_CSV_20250611

CSV ファイル形式

• ファイルエンコーディング：UTF-8 エンコーディングです。

• フィールド区切り文字：カンマ（,）で区切られます。

• オブジェクトキーのエンコーディング：URL エンコーディングされています（例：documents%2Freport1.pdf）。

• コメント：サポートされていません。

CSV ファイルの例

• バージョン管理が無効の場合

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

• バージョン管理が有効の場合

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

手順 3：ジョブの作成

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

<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>インベントリマニフェストを用いたタグの一括置き換え</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

<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>ドキュメントへのタグの一括置き換え</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

<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>指定オブジェクトへのタグの一括置き換え</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

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

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

<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>インベントリマニフェストを用いたタグの一括追加</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

<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>ドキュメントへのタグの一括追加</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

<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>指定オブジェクトへのタグの一括追加</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

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

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

<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>インベントリマニフェストを用いたタグの一括削除</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

<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>ドキュメントへのタグの一括削除</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

<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>指定オブジェクトへのタグの一括削除</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

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

ACL の一括変更

バッチ操作では、オブジェクトに対して事前定義された 4 種類の ACL（アクセス制御リスト）がサポートされています。private（所有者のみ読み取りおよび書き込み可能）、public-read（すべてのユーザーが読み取り可能、所有者のみ書き込み可能）、public-read-write（すべてのユーザーが読み取りおよび書き込み可能）、および default（バケットから ACL を継承）です。ACL の変更は即時に有効となり、オブジェクトへのアクセスに直接影響します。ビジネス要件に基づき、適切な ACL タイプを慎重に選択してください。

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

<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>

<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>

<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>

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

アーカイブ済みオブジェクトのバッチ復元

バッチ復元操作は、Archive、Cold Archive、および Deep Cold Archive ストレージクラスに格納されたオブジェクトをサポートします。Archive オブジェクトの場合、復元は通常 1 時間以内に完了し、その後 1～7 日間アクセス可能になります。Cold Archive ストレージクラスでは、Standard（2～5 時間）および Bulk（5～12 時間）の 2 つの復元ティアが提供されます。Deep Cold Archive ストレージクラスでは Standard ティアのみがサポートされており、最大 48 時間かかる場合があります。復元されたオブジェクトのアクセス可能期間は、1～365 日の任意の値に設定できます。

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

<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>7 日間のアクセス可能期間でインベントリマニフェストを用いたバッチ復元</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

<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>7 日間のアクセス可能期間でアーカイブオブジェクトをバッチ復元</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

<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>7 日間のアクセス可能期間で指定されたアーカイブオブジェクトをバッチ復元</Description>
    <Priority>10</Priority>
    <RoleArn>acs:ram::<your-account-uid>:role/BatchRole</RoleArn>
</CreateJobRequest>

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

手順 4：ジョブの管理とモニタリング

ジョブステータスの表示

ジョブを作成した後、その詳細をクエリしてステータスをモニタリングおよび確認します。応答には、実行の進捗状況や設定パラメーターなど、指定されたジョブの完全な情報が含まれます。

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

<?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>

ジョブの確認

ジョブのステータスを `Suspended` から `Ready` に変更して、実行キューに入れます。ジョブが 14 日以内に確認されない場合、そのステータスは自動的に `Failed` に変わります。

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

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

ジョブのリスト表示

すべてのジョブを表示します。ステータスや作成時間範囲でジョブリストをフィルターしたり、結果の数を制限したり、ページネーションを使用して多数のジョブを管理したりできます。デフォルトでは、結果は作成時間の降順でソートされます。

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

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

ジョブの優先度の更新

優先度は 0 から 2,147,483,647 までの整数で、値が大きいほど優先度が高くなります。ジョブの優先度は、厳密な実行順序を保証するものではありません。代わりに、OSS はベストエフォートベースで、優先度の高いジョブにより多くのリソースを割り当てます。

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

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

ジョブのキャンセル

実行中または保留中のジョブをキャンセルします。すでに処理されたオブジェクトに対する操作はロールバックできません。

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

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

ジョブレポートの表示

ジョブが完了すると、指定した場所に詳細な実行レポートが生成されます。レポートには、manifest.json ファイルと CSV 形式の詳細レポートファイルの 2 種類の主要なファイルが含まれます。これらのレポートを使用して、各オブジェクトの処理ステータスを把握し、HTTP 応答コードを表示し、障害の原因を特定することで、トラブルシューティングや結果の検証に役立てます。

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

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

{
  "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"
}

{
  "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"
}

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,

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""}"

# レポートマニフェストファイルをダウンロードする
ossutil cp oss://my-bucket/batch-reports/<JobId>/results/manifest.json ./

# 詳細な CSV レポートをダウンロードする
ossutil cp oss://my-bucket/batch-reports/<JobId>/results/report-0.csv ./

本番環境での利用

ベストプラクティス

ジョブ計画

• スケールコントロール：実行の安定性を確保するため、各ジョブのオブジェクト数を 1 億個に制限してください。より大きなデータセットの場合は、データを複数のジョブに分割して、単一障害点のリスクを低減します。

• 優先度管理：重要なジョブがブロックされるのを防ぐため、適切なジョブ優先度を設定してください。実行時間を見積もり、それに応じてメンテナンスウィンドウをスケジュールします。

• 同時操作：複数のジョブが同じオブジェクトセットに対して同時に操作する場合、実行順序は保証されません。同じオブジェクトに対して同時操作を実行しないでください。

パフォーマンスの最適化

• マニフェストファイルの最適化：マニフェストファイルを整理し、解析が遅くなる原因となる過度に大きな単一ファイルを避けてください。

• QPS クォータの利用：バッチ操作は専用の QPS クォータを使用し、ご利用のアプリケーションの API QPS クォータを消費しません。

• 同時実行制御：リソース競合を避けるため、同時に実行するジョブは最大 6 つにしてください。

• ホットスポットの回避：操作対象のオブジェクト範囲にホットスポット (例えば、辞書順プレフィックス) が含まれている場合、バッチ操作の実行が遅くなる可能性があります。深刻な場合には、一部のオブジェクトに対する操作が失敗することがあります。

エラー処理

• 詳細レポート：ReportScope=AllTasks を設定して詳細レポートを有効にすると、トラブルシューティングのために完全な実行結果を取得できます。

• リトライメカニズム：稀に、バッチ操作の実行中に問題が発生した場合、数回リトライされることがあります。課金は、最終的に行われた API 呼び出しの回数に基づきます。

• 失敗のしきい値：ジョブ内のアイテムの 20% 以上が失敗した場合、ジョブ全体が即座に失敗し、処理を停止します。

• ステータス確認の異常：稀に、一部の操作が成功したにもかかわらず、完了レポートで失敗とマークされることがあります。失敗と報告されたアイテムは再確認してください。

ジョブ結果の検証

• 実行整合性の検証：ジョブが終了した後、一部のオブジェクトは正常に処理され、他のオブジェクトは失敗している可能性があります。これは、最終的なジョブステータス (Complete、Failed、Cancelled など) にかかわらず発生する可能性があります。完了レポートの成功数と失敗数を確認し、結果が期待通りであることを常に確認してください。

• 失敗処理の推奨事項：

  • ジョブステータスが Complete であっても、それはジョブのライフサイクルが終了したことを意味するだけで、すべてのオブジェクト操作が成功したことを保証するものではありません。詳細については、完了レポートを確認する必要があります。

  • 失敗したタスクについては、失敗の原因を分析してリトライしてください。部分的に失敗したジョブについては、失敗レポートに基づいて新しいリトライジョブを作成できます。

  • Cancelled、Paused、または Failed ステータスのジョブについては、レポートを確認し、ジョブが停止する前に正常に処理されたオブジェクトがあるかどうかを確認してください。

マニフェストファイル

実行順序とデータ整合性

• 実行順序：バッチ操作はマニフェストファイルにリストされたアイテムに対して実行されますが、実行順序は保証されません。

• ファイルの更新：操作が実行される前にオブジェクトが更新された場合、ジョブは更新後のバージョンに対して実行されます。バッチジョブの実行中はオブジェクトを変更しないでください。

• プレフィックス使用時の制限：プレフィックスを使用してマニフェストを指定した場合、バッチ操作はジョブ開始後に追加または削除されたオブジェクトを無視します。ジョブの実行中はプレフィックス内のオブジェクトを追加または削除しないでください。

マニフェストファイルの形式

• URL エンコーディング：CSV 形式のマニフェストファイル内のオブジェクトは URL エンコーディングされている必要があります。そうでない場合、解析が失敗する可能性があります。

• 重複キーの処理：マニフェストファイルに重複キーが含まれている場合、各エントリに対して操作が 1 回実行されます。これらの実行順序は保証されません。

リソーススケジューリング

優先度スケジューリング

優先度の範囲は 0 から 2,147,483,647 です。

同時実行制御

1 つのアカウントで同時に実行できるジョブは最大 6 つです。追加のジョブは待機キューに入れられます。

ジョブステータス

クォータと制限

課金

バッチ操作は、処理されたオブジェクト100万個あたり 1 人民元 (CNY) の従量課金制です。ジョブの作成や管理には料金は発生せず、追加のデータ転送料金も適用されません。

課金例：

• 500万個のオブジェクトのタグ付け：500万 / 100万 * CNY 1 = CNY 5

• 50億個のオブジェクトの処理：50億 / 100万 * CNY 1 = CNY 5,000

コスト最適化のヒント：関連するバッチ操作を単一のジョブに結合して、オーバーヘッドを削減します。正確なプレフィックスまたはマニフェストファイルを使用して、不要なオブジェクトの処理を回避します。緊急性の低いバッチ操作は、オフピーク時間中にスケジュールします。

よくある質問

ジョブが準備中状態のままになる

主な原因は次のとおりです。

• マニフェストファイルが大きく、解析に時間がかかるため。

• プレフィックススキャンが多数のオブジェクトを対象としているため。

• システム負荷が高く、処理キューが混雑しているため。

この問題を解決するには、大規模なジョブをより小さなジョブに分割するか、事前に生成されたマニフェストファイルを使用してください。

失敗したオブジェクト操作の処理

次の手順に従ってください。

1. 完了レポートをダウンロードして、失敗の原因を分析してください。

2. 新しいジョブを作成し、失敗したオブジェクトに対する操作をリトライしてください。

3. 権限設定を確認し、Resource Access Management (RAM) ロールに必要な権限が付与されていることを確認してください。

実行中のジョブのキャンセル

次のリクエストを使用します。

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

AccessDenied エラーの発生

次の権限を確認してください。

1. RAM ユーザーに oss:CreateBatchJob 権限が付与されていること。

2. RAM ロールが操作に必要な権限を持っていること。

3. クロスバケット操作の場合、送信先バケットに正しい権限が設定されていること。

RAM ロールの権限

RAM ロールには、以下を含める必要があります。

• OSS リソースに対する読み取りおよび書き込み権限。

• バッチ操作 API を呼び出す権限。

• 完了レポートの送信先バケットへの書き込み権限。

信頼ポリシーでは、OSS サービスがロールを引き受けることを許可する必要があります。 以下に例を示します。

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

バッチ操作のパフォーマンス向上

次のベストプラクティスを検討してください。

1. マニフェストファイルを効率的に整理し、単一の過度に大きいファイルの使用を避けてください。

2. ビジネスのピーク時間帯に大規模なジョブを実行することは避けてください。

3. 重要なジョブを先に処理するために、より高い優先度を割り当ててください。

4. 長時間の実行を防ぐため、単一ジョブ内のオブジェクト数を 1 億個に制限してください。

5. 大規模なジョブを過度に多数の小さなジョブに分割することは避けてください。たとえば、100 万個のオブジェクトを 1,000 個のジョブに分割するなどです。これにより、スケジューリングのオーバーヘッドが増加します。

ジョブ完了の遅延

主な原因は次のとおりです。

• オブジェクトの分散が不均一で、一部のデータシャードの処理に時間がかかるため。

• ソースまたは送信先バケットのいずれかにデータホットスポットが存在し、処理速度が低下するため。

• 同時実行ジョブが多すぎて、リソース競合が発生するため。

この問題を解決するには、ジョブのスケジューリング戦略を調整するか、同時実行ジョブの数を減らしてください。