Object Storage Service:Process billions of objects using Batch Operations

Périmètre

La fonctionnalité Opérations par lot est entièrement disponible dans les régions Chine (Hangzhou), Singapour et Allemagne (Francfort). Pour utiliser cette fonctionnalité dans les régions Chine (Shanghai), Chine (Shenzhen), Chine (Guangzhou), Chine (Qingdao), Chine (Pékin), Chine (Zhangjiakou), Chine (Hohhot), Chine (Ulanqab), Chine (Chengdu), Chine (Hong Kong) ou Indonésie (Jakarta), contactez le support technique pour demander l'accès.

Présentation des opérations

1. Créez un rôle RAM : autorisez le service OSS à lire le fichier manifeste, à exécuter les opérations par lot et à générer un rapport.

2. Préparez un manifeste d'entrée : spécifiez les objets à traiter à l'aide d'un fichier d'inventaire de bucket (manifest.json), d'un préfixe ou d'un fichier manifeste CSV (manifest.csv).

3. Créez une tâche : configurez des opérations spécifiques, telles que l'ajout de tags, la définition des permissions ou la restauration d'objets, puis soumettez la tâche.

4. Gérez et maintenez la tâche : surveillez l'état de la tâche, confirmez les tâches en attente, consultez le rapport d'exécution et ajustez la priorité ou annulez la tâche si nécessaire.

Étape 1 : Créer un rôle RAM

1. Accédez à la console RAM pour créer un rôle. Sélectionnez Alibaba Cloud Service comme type d'entité de confiance et Object Storage Service comme service de confiance.

2. Créez et associez une stratégie personnalisée au rôle. Le contenu de la stratégie est le suivant. Remplacez your-bucket par le nom réel de votre 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/*"
         ]
       }
     ]
   }

   Description des permissions

   • Permissions requises

     • oss:GetBucketInfo : récupère les informations du bucket.

   • Permissions liées au manifeste d'entrée

     • oss:ListObjects : requis pour générer une liste d'objets à partir d'un préfixe.

     • oss:GetObject : requis pour utiliser un fichier d'inventaire de bucket ou un fichier manifeste CSV.

   • Permissions liées aux opérations par lot

     • oss:GetObjectTagging : requis pour lire les tags existants lors du remplacement par lot des tags.

     • oss:PutObjectTagging : requis pour l'ajout ou le remplacement par lot des tags.

     • oss:DeleteObjectTagging : requis pour la suppression par lot des tags.

     • oss:PutObjectAcl : requis pour la modification par lot des permissions.

     • oss:RestoreObject : requis pour la restauration par lot des objets archivés.

   • Permissions pour la sortie du rapport

     • oss:PutObject : requis pour télécharger le rapport d'opération par lot.

3. Enregistrez l'ARN du rôle, par exemple acs:ram::<your-account-uid>:role/BatchRole. Vous l'utiliserez dans les étapes suivantes.

Étape 2 : Préparer un manifeste d'entrée

Les opérations par lot nécessitent de spécifier les objets à traiter. Vous pouvez choisir l'une des trois méthodes suivantes en fonction de votre scénario :

• Fichier d'inventaire de bucket : adapté aux opérations par lot à grande échelle et régulièrement répétées.

• Préfixe : traite tous les objets d'un dossier spécifique.

• Fichier manifeste CSV : un fichier CSV qui répertorie les objets à traiter.

Fichier d'inventaire de bucket

Utilisez un fichier manifeste généré automatiquement par Inventaire de bucket.

<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 de la configuration

• ETag : la valeur ETag du fichier manifest.json.

• Format : OSS_InventoryReport_CSV_20250611

Préfixe

Génère une liste d'objets basée sur un préfixe spécifié.

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

Fichier manifeste CSV

Répertorie des objets spécifiques à l'aide d'un fichier CSV. Le fichier manifeste CSV doit être téléchargé vers OSS et se trouver dans la même région que la tâche par lot.

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

Description de la configuration

• ETag : la valeur ETag de manifest.csv.

• Fields : les colonnes du fichier CSV.

  • Versioning non activé : Bucket,Key

  • Versioning activé : Bucket,Key,VersionId

• Format : OSS_BatchOperations_CSV_20250611

Exigences de format du fichier CSV

• Encodage du fichier : UTF-8.

• Séparateur de champ : virgule (,).

• Encodage de la clé d'objet : encodé URL (par exemple, documents%2Freport1.pdf).

• Commentaires : le fichier CSV ne peut pas contenir de lignes de commentaire.

Exemples de fichiers CSV

• Versioning non activé

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

• Versioning activé

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

Étape 3 : Créer une tâche

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>Batch replace tags using Inventory manifest</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>Batch replace tags for documents</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>Batch replace tags 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>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>Batch add tags using Inventory manifest</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>Batch add tags to documents</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>Batch add tags to 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>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>Batch delete tags using Inventory manifest</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>Batch delete tags for documents</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>Batch delete tags 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>NTVlYmQ4ZmQyOTM0NDJmY2E2NmNjYTUwNjU1ZGRkMGM=</JobId>
</CreateJobResult>

Modifier les autorisations par lot

La modification des autorisations par lot prend en charge quatre types de listes de contrôle d'accès (ACL) : private (lecture et écriture réservées au propriétaire), public-read (lecture publique, écriture réservée au propriétaire), public-read-write (lecture et écriture publiques) et default (hérite des autorisations du bucket). Les modifications des autorisations prennent effet immédiatement et influent directement sur l'accès aux objets. Choisissez le type d'autorisation approprié avec soin en fonction de vos besoins métier.

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>

Restaurer les données par lot

L'opération de restauration par lot prend en charge les objets des classes de stockage Archive, ColdArchive et DeepColdArchive. La restauration des objets Archive s'effectue généralement en moins d'une heure et les objets restaurés restent accessibles pendant 1 à 7 jours. La classe de stockage ColdArchive prend en charge le mode Standard (2 à 5 heures) et le mode Bulk (5 à 12 heures). La classe de stockage DeepColdArchive ne prend en charge que le mode Standard, dont l'exécution peut prendre jusqu'à 48 heures. Vous pouvez définir la durée d'accessibilité de l'objet restauré sur une valeur comprise entre 1 et 365 jours.

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>Batch restore using Inventory manifest for 7 days</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>Batch restore archive objects for 7 days</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>Batch restore specified archive objects for 7 days</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>

Étape 4 : Gestion et exploitation/maintenance des tâches

Consulter le statut d'une tâche

Après avoir créé une tâche, vous pouvez surveiller et confirmer son statut en interrogeant ses détails. Ces derniers fournissent une vue d'ensemble complète du statut de la tâche, y compris sa progression d'exécution et ses paramètres de configuration.

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>

Confirmer une tâche en attente

Vous pouvez faire passer le statut de la tâche de Suspended à Ready afin de la placer dans la file d'attente d'exécution. Si une tâche n'est pas confirmée dans un délai de 14 jours, son statut passe automatiquement à 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>

Lister les tâches par lot

Vous pouvez afficher toutes les tâches et utiliser la fonctionnalité de requête par lot pour filtrer la liste par statut et par plage de dates de création. Vous pouvez également limiter le nombre de résultats et utiliser des requêtes paginées pour gérer un grand nombre de tâches. Par défaut, les résultats sont triés par date de création décroissante, les tâches les plus récentes apparaissant en premier.

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>

Ajuster la priorité d'une tâche

La valeur de priorité varie de 0 à 2147483647, une valeur plus élevée indiquant une priorité plus grande. La priorité d'une tâche ne garantit pas un ordre d'exécution strict. OSS tente plutôt d'allouer davantage de ressources aux tâches de priorité élevée.

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>

Annuler une tâche

Vous pouvez mettre fin à une tâche en cours d'exécution ou en attente. Les opérations déjà effectuées sur les objets ne peuvent pas être annulées.

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>

Consulter un rapport de tâche

Une fois la tâche terminée, le système génère un rapport d'exécution détaillé dans le chemin spécifié. Le rapport contient deux fichiers clés : un manifest nommé manifest.json et un rapport détaillé au format CSV. Ces fichiers fournissent le statut de traitement, le code de réponse HTTP et la raison de l'échec pour chaque objet, ce qui vous permet d'effectuer un dépannage et de valider les résultats.

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

# 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 ./

Mise en production

Bonnes pratiques

Stratégies de planification des tâches

• Contrôle de l'échelle : limitez le nombre d'objets dans une seule tâche à moins de 100 millions pour garantir une exécution stable. Divisez le traitement des données à grande échelle en plusieurs tâches afin d'atténuer les points de défaillance uniques.

• Gestion des priorités : définissez des priorités de tâche raisonnables pour éviter que les tâches importantes ne soient bloquées. Estimez les durées d'exécution afin de planifier correctement les fenêtres de maintenance.

• Remarques sur les opérations concurrentes : lorsque plusieurs tâches opèrent simultanément sur le même lot d'objets, l'ordre d'exécution n'est pas garanti. Évitez d'effectuer des opérations concurrentes sur le même objet.

Mesures d'optimisation des performances

• Optimisation du fichier manifeste : organisez la structure du fichier manifeste pour éviter de créer des fichiers uniques excessivement volumineux, ce qui ralentirait l'analyse.

• Utilisation du quota QPS : tirez pleinement parti du quota QPS indépendant pour garantir que les appels d'API métier ne soient pas affectés. Les opérations par lot ne consomment pas votre quota QPS.

• Contrôle de la concurrence : limitez le nombre de tâches s'exécutant simultanément à trois ou moins afin d'éviter la compétition pour les ressources.

• Évitement des points chauds : si des points chauds, tels qu'un préfixe ordonné lexicographiquement, existent dans la plage d'opération, la vitesse d'exécution de l'opération par lot peut être affectée. Dans les cas graves, cela peut entraîner l'échec de certaines opérations sur les fichiers.

Mécanismes de gestion des erreurs

• Rapports détaillés : activez les rapports détaillés (ReportScope=AllTasks) pour obtenir des résultats d'exécution complets facilitant le dépannage.

• Mécanisme de nouvelle tentative : dans de rares cas, si une opération par lot rencontre un problème lors de l'exécution, elle effectue automatiquement plusieurs nouvelles tentatives. Les frais finaux pour les requêtes API sont basés sur le nombre total d'appels API effectués.

• Seuil d'échec : si le taux d'échec des tâches d'une job dépasse 20 %, l'intégralité de la tâche échoue immédiatement et s'arrête.

• Anomalies de confirmation d'état : dans de rares cas, certaines opérations peuvent réussir mais être enregistrées comme ayant échoué dans le rapport d'exécution. Vérifiez systématiquement les éléments enregistrés comme ayant échoué.

Points clés pour la confirmation des résultats

• Vérification de l'intégrité de l'exécution : une tâche peut avoir l'un des statuts suivants : Running, Complete, Failed, Paused ou Cancelled. Certains objets peuvent avoir été traités avec succès, tandis que d'autres ont pu échouer. Vérifiez le nombre de tâches réussies et échouées dans le rapport pour vous assurer que les résultats correspondent à vos attentes.

• Suggestions pour la gestion des échecs :

  • Un statut Complete indique uniquement que la tâche est terminée, et non que tous les objets ont été traités avec succès. Vous devez consulter le rapport d'exécution pour plus de détails.

  • Analysez la cause des tâches ayant échoué et relancez-les. Pour les tâches partiellement échouées, vous pouvez créer une tâche de nouvelle tentative basée sur le rapport d'échec.

  • Pour les tâches ayant un statut Cancelled, Paused ou Failed, certains objets peuvent déjà avoir été traités avec succès. Vous devez vérifier les résultats.

Remarques sur les fichiers manifestes

Ordre d'exécution et cohérence des données

• Ordre d'exécution : les opérations par lot sont effectuées sur les éléments de la liste du manifeste, mais l'ordre d'exécution n'est pas garanti.

• Mises à jour de fichiers : si un objet est mis à jour avant que l'action ne soit effectuée, la tâche opère sur le fichier mis à jour. Ne modifiez pas les fichiers pendant l'exécution d'une tâche par lot.

• Limitations de la méthode par préfixe : si vous utilisez un préfixe pour fournir le manifeste d'entrée, l'opération par lot ne peut pas détecter les fichiers ajoutés ou supprimés pendant son exécution. N'ajoutez ni ne supprimez de fichiers sous le préfixe pendant l'exécution d'une tâche par lot.

Exigences de format des fichiers manifestes

• Encodage URL : les clés d'objet dans le fichier manifeste CSV doivent être encodées en URL. Sinon, l'analyse peut échouer.

• Gestion des clés en double : si le fichier manifeste contient des clés en double, l'opération par lot est effectuée plusieurs fois, mais l'ordre des opérations n'est pas garanti.

Mécanisme de planification des ressources

Planification par priorité

Les priorités de tâche sont prises en charge, avec des valeurs allant de 0 à 2147483647.

Contrôle de la concurrence

Un seul compte peut exécuter un maximum de six tâches simultanées. Les tâches supplémentaires sont placées dans une file d'attente.

Transitions d'état des tâches

Quotas et limites

Description de la facturation

OSS Batch Operations est un service de paiement à l'utilisation. Vous êtes facturé 1 CNY pour chaque million d'objets traités, sans frais supplémentaires pour la création de tâches, la gestion ou le transfert de données.

Exemples de facturation :

• Tagging par lot de 5 millions d'objets : 5 millions / 1 million × 1 CNY = 5 CNY

• Traitement de données à grande échelle de 5 milliards d'objets : 5 milliards / 1 million × 1 CNY = 5 000 CNY

Suggestions d'optimisation des coûts : regroupez les opérations par lot connexes en une seule tâche pour réduire la charge de gestion. Utilisez des préfixes précis ou des fichiers manifestes pour éviter de traiter des objets inutiles. Planifiez les opérations par lot non urgentes pendant les heures creuses.

FAQ

Pourquoi ma tâche reste-t-elle bloquée longtemps dans l'état Preparing ?

Les raisons possibles incluent les suivantes :

• Le fichier manifeste est trop volumineux et prend beaucoup de temps à analyser.

• L'analyse du préfixe couvre de nombreux objets.

• La charge du système est élevée et la file d'attente de traitement est saturée.

Pour résoudre ce problème, vous pouvez diviser les grandes tâches en tâches plus petites ou utiliser un fichier manifeste pré-généré.

Que faire si certains objets ne parviennent pas à être traités ?

Suivez ces étapes :

1. Téléchargez le rapport d'exécution de la tâche et analysez la cause de l'échec.

2. Créez une nouvelle tâche de nouvelle tentative basée sur la liste des objets ayant échoué.

3. Vérifiez que la configuration des autorisations est correcte et que le rôle IAM dispose des autorisations complètes.

Comment annuler une tâche en cours d'exécution ?

Vous pouvez utiliser la commande suivante :

POST /?batchJobStatus&batchJobId=<JobId>&requestedJobStatus=Cancelled&statusUpdateReason=User cancelled HTTP/1.1
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: <Signature information>

Pourquoi obtiens-je une erreur d'autorisation refusée ?

Vérifiez les configurations d'autorisation suivantes :

1. Assurez-vous que l'utilisateur RAM dispose de l'autorisation oss:CreateBatchJob.

2. Vérifiez que le rôle IAM dispose des autorisations requises pour l'opération.

3. Vérifiez les paramètres d'autorisation du bucket de destination pour les opérations inter-buckets.

Exigences de configuration du rôle IAM ?

Le rôle IAM doit inclure les éléments suivants :

• Autorisations de lecture et d'écriture pour les ressources OSS.

• Autorisations pour appeler les API Batch Operations.

• Autorisations d'écriture pour le bucket de stockage des rapports.

Exemple de politique de confiance :

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

Comment puis-je améliorer la vitesse d'exécution des opérations par lot ?

Recommandations d'optimisation :

1. Structurez vos fichiers manifestes pour éviter de créer des fichiers uniques trop volumineux.

2. Évitez d'exécuter de grandes tâches pendant les heures de pointe.

3. Attribuez des priorités aux tâches pour garantir que les tâches importantes soient exécutées en premier.

4. Évitez d'inclure trop d'objets dans une seule tâche pour prévenir des durées d'exécution prolongées. Nous recommandons une limite de 100 millions d'objets par tâche.

5. Évitez de diviser une grande tâche en trop nombreuses petites tâches, comme diviser 1 million d'objets en 1 000 tâches. Cela augmente le temps consacré à la planification des tâches.

Pourquoi la tâche prend-elle plus de temps que prévu pour s'exécuter ?

Les raisons possibles incluent les suivantes :

• Les objets sont répartis de manière inégale, ce qui entraîne un temps de traitement plus long pour certains shards.

• Les objets source ou de destination présentent des points chauds, ce qui peut ralentir le traitement.

• Trop de tâches s'exécutent simultanément, ce qui entraîne une compétition pour les ressources.

Nous vous recommandons d'ajuster la stratégie de planification des tâches ou de réduire le nombre de tâches simultanées.