Création d'une tâche d'opérations par lot S3 - Amazon Simple Storage Service

Création d'une tâche d'opérations par lot S3

La fonctionnalité d’opérations par lot S3 vous permet d’effectuer des opérations par lot à grande échelle sur une liste d’objets Amazon S3 spécifiques. Cette section décrit les informations dont vous avez besoin pour créer une tâche d’opérations par lot S3 ainsi que les résultats d’une demande Create Job. Elle fournit également des instructions sur la création d’une tâche d’opérations par lot à l'aide de la AWS Management Console, de la AWS Command Line Interface (AWS CLI) et du kit AWS SDK for Java.

Lorsque vous créez une tâche d'opérations par lot S3, vous pouvez demander un rapport de fin de tâche pour toutes les tâches ou uniquement pour les tâches qui ont échoué. Tant qu'au moins une tâche a été appelée avec succès, la fonctionnalité d'opérations par lot S3 génère un rapport pour les tâches qui ont été achevées, qui ont échoué ou qui ont été annulées. Pour de plus amples informations, veuillez consulter Exemples : Rapports de fin de tâche d'opérations par lot S3.

La vidéo suivante fournit une brève démonstration sur la manière pour créer une tâche d'opérations par lot à l'aide de la AWS Management Console.

Éléments d'une demande de tâche d'opération par lot

Pour créer une tâche d'opérations par lot S3, vous devez fournir les informations suivantes :

Opération

Spécifiez l'opération que la tâche d'opérations par lot S3 doit exécuter sur les objets du manifeste. Chaque type d'opération accepte des paramètres spécifiques à cette opération. Vous pouvez ainsi effectuer les mêmes travaux que si vous aviez effectué l'opération sur chaque objet un par un.

Manifeste

Le manifeste est la liste de tous les objets sur lesquels la tâche d'opérations par lot S3 doit exécuter l'action spécifiée. Vous pouvez utiliser un rapport Inventaire Simple Storage Service (Amazon S3) au format CSV comme manifeste ou utiliser votre propre liste d'objets CSV personnalisée.

Si les objets de votre manifeste sont dans un compartiment versionné, vous devez spécifier les ID de version des objets. Pour plus d'informations, consultez Spécification d'un manifeste.

Priority

Utilisez les priorités pour indiquer la priorité relative de cette tâche par rapport aux autres s'exécutant dans votre compte. Un nombre plus élevé indique une priorité plus élevée.

Les priorités n'ont de sens que par rapport aux priorités établies pour d'autres tâches dans le même compte et la même Région. Ainsi, vous pouvez choisir le système de numérotation qui vous convient. Par exemple, vous pouvez affecter à toutes les tâches Initiate Restore Object la priorité 1, à toutes les tâches PUT Object Copy la priorité 2 et à toutes les tâches Put Object ACL la priorité 3.

Bien que la fonctionnalité d'opérations par lot S3 traite les tâches en fonction de leur numéro de priorité, il n'est pas garanti que l'ordre soit strictement respecté. Par conséquent, n'utilisez pas les priorités de tâche pour vous assurer qu'une tâche commence ou finit avant une autre tâche. Si vous devez garantir un classement strict, attendez qu'une tâche se soit terminée avant de démarrer la suivante.

RoleArn

Spécifiez un rôle AWS Identity and Access Management (IAM) pour exécuter la tâche. Le rôle IAM que vous utilisez doit avoir les autorisations suffisantes pour exécuter l'opération spécifiée dans la tâche. Par exemple, pour exécuter une tâche PUT Object Copy, le rôle IAM doit avoir les autorisations s3:GetObject pour le compartiment source et les autorisations s3:PutObject pour le compartiment de destination. Le rôle a également besoin des autorisations pour lire le manifeste et écrire le rapport de fin de tâche.

Pour de plus amples informations sur les rôles IAM, veuillez consulter Rôles IAM dans le Guide de l'utilisateur IAM.

Pour de plus amples informations sur les autorisations Amazon S3, veuillez consulter Actions Amazon S3.

Rapport

Indiquez si vous souhaitez que la fonctionnalité d'opérations par lot S3 génère un rapport d'achèvement. Si vous demandez un rapport de fin de tâche, vous devez également fournir les paramètres du rapport dans cet élément. Les informations nécessaires sont les suivantes :

  • Le compartiment dans lequel vous souhaitez stocker le rapport

  • Le format du rapport

  • Si vous souhaitez que le rapport comprenne les détails de toutes les tâches ou uniquement de celles ayant échoué

  • Une chaîne de préfixe facultative

Les balises (facultatif)

Vous pouvez étiqueter et contrôler l'accès à vos tâches d'opérations par lot S3 en ajoutant des étiquettes. Les étiquettes peuvent être utilisées pour identifier la personne qui est responsable d'une tâche d'opérations par lot. Vous pouvez créer des tâches avec des étiquettes qui leur sont attachées et ajouter des étiquettes aux travaux après les avoir créés. Par exemple, vous pouvez accorder à un utilisateur IAM l'autorisation d'appeler CreateJob à condition que la tâche soit créée avec l'étiquette "Department=Finance".

Pour de plus amples informations, veuillez consulter Contrôle de l'accès et étiquetage des tâches à l'aide d'étiquettes.

Description (facultative)

Pour suivre et surveiller votre tâche, vous pouvez également fournir une description de 256 caractères maximum. Amazon S3 inclut cette description chaque fois qu'il renvoie des informations sur une tâche ou affiche les détails de la tâche sur la console Amazon S3. Cela vous permet de trier et filtrer facilement les tâches en fonction des descriptions que vous avez allouées. Comme les descriptions n'ont pas à être uniques, vous pouvez utiliser les descriptions comme catégories (par exemple, « Tâches hebdomadaires de copie des journaux ») pour vous aider à suivre les groupes de tâches similaires.

Spécification d'un manifeste

Un manifeste est un objet Simple Storage Service (Amazon S3) qui contient les clés d'objet sur lesquelles Simple Storage Service (Amazon S3) doit agir. Pour spécifier un manifeste pour une tâche, vous devez définir la clé d'objet du manifeste, l'ETag et l'ID de version facultatif. Les contenus du manifeste doivent être codés au format URL. Les manifestes qui utilisent un chiffrement côté serveur avec des clés fournies par le client (SSE-C) ne sont pas pris en charge. Les manifestes qui utilisent le chiffrement côté serveur avec les clés AWS Key Management Service(SE-KMS)AWS KMS ne sont pris en charge que si des rapports d'inventaire au format CSV sont utilisés. Votre manifeste doit contenir le nom du compartiment, la clé d'objet et, facultativement, la version de chaque objet. Les autres champs du manifeste ne sont pas utilisés lors des opérations par lot S3.

Vous pouvez spécifier un fichier manifeste dans une demande de création de tâche dans l'un des deux formats suivants.

  • Rapport Amazon S3 Inventory – Il doit s'agir d'un rapport Amazon S3 Inventory au format CSV. Vous devez spécifier le fichier manifest.json associé au rapport d'inventaire. Pour de plus amples informations sur les rapports d'inventaire, veuillez consulter Inventaire Simple Storage Service (Amazon S3). Si le rapport d’inventaire inclut des ID de version, les opérations par lot S3 s’exécutent sur les versions d’objets spécifiques.

    Note

    Les opérations par lot S3 prennent en charge les rapports d'inventaire CSV chiffrés par AWS KMS.

  • Fichier CSV - Chaque ligne du fichier doit inclure le nom du compartiment, la clé d'objet et, éventuellement, la version de l'objet. Les clés d'objets doivent être encodées en URL, comme montré dans les exemples suivants. Le manifeste doit inclure soit des ID de version pour tous les objets ou omettre les ID de version pour tous les objets. Pour de plus amples informations sur le format de manifeste CSV, veuillez consulter JobManifestSpec dans la Référence d'API Amazon Simple Storage Service.

    Note

    Les opérations par lot S3 ne prennent pas en charge les fichiers manifestes CSV chiffrés par AWS KMS.

    Voici un exemple de manifeste au format CSV sans ID de version.

    Examplebucket,objectkey1 Examplebucket,objectkey2 Examplebucket,objectkey3 Examplebucket,photos/jpgs/objectkey4 Examplebucket,photos/jpgs/newjersey/objectkey5 Examplebucket,object%20key%20with%20spaces

    Voici un exemple de manifeste au format CSV avec ID de version.

    Examplebucket,objectkey1,PZ9ibn9D5lP6p298B7S9_ceqx1n5EJ0p Examplebucket,objectkey2,YY_ouuAJByNW1LRBfFMfxMge7XQWxMBF Examplebucket,objectkey3,jbo9_jhdPEyB4RrmOxWS0kU0EoNrU_oI Examplebucket,photos/jpgs/objectkey4,6EqlikJJxLTsHsnbZbSRffn24_eh5Ny4 Examplebucket,photos/jpgs/newjersey/objectkey5,imHf3FAiRsvBW_EHB8GOu.NHunHO1gVs Examplebucket,object%20key%20with%20spaces,9HkPvDaZY5MVbMhn6TMn1YTb5ArQAo3w
Important

Lorsque vous utilisez un manifeste fourni par l'utilisateur et un compartiment versionné, nous vous recommandons de spécifier les ID de version des objets. Lorsque vous créez une tâche, les opérations par lot S3 analysent l’intégralité du manifeste avant d’exécuter la tâche. Cependant, cela ne crée pas d'instantané de l'état de ce compartiment.

Comme les manifestes peuvent contenir des milliards d'objets, l'exécution des tâches peut prendre beaucoup de temps. Si vous remplacez un objet par une nouvelle version pendant qu'une tâche s'exécute et que vous n'avez pas spécifié d'ID de version pour cet objet, Simple Storage Service (Amazon S3) effectue l'opération sur la dernière version de l'objet, et non sur la version qui existait quand vous avez créé la tâche. Le seul moyen d'éviter ce comportement consiste à spécifier des ID de version pour les objets répertoriés dans le manifeste.

Note

Simple Storage Service (Amazon S3) vous offre la possibilité de créer un manifeste pour la tâche de réplication par lot S3. La réplication par lot est une opération à la demande qui réplique des objets existants. Pour en savoir plus sur la réplication par lot, consultez Réplication d'objets existants via la réplication par lot S3.

Création d'une tâche

Vous pouvez créer des tâches d'opérations par lot S3 via la AWS Management Console, la AWS CLI, les kits SDK Amazon ou l'API REST.

Pour de plus amples informations sur la création d'une demande de tâche, consultez Éléments d'une demande de tâche d'opération par lot.

Prérequis

Avant de créer une tâche d'opérations par lot, vérifiez que vous avez configuré les autorisations pertinentes. Pour de plus amples informations, veuillez consulter Octroi d'autorisations pour les opérations par lot Amazon S3.

Pour créer une tâche par lot

  1. Connectez-vous à la AWS Management Console et ouvrez la console Amazon S3 à l'adresse https://console.aws.amazon.com/s3/.

  2. Choisissez Opérations par lot dans le panneau de navigation de la console Amazon S3.

  3. Choisissez Create job (Créer une tâche).

  4. Choisissez la Région dans laquelle vous souhaitez créer la tâche.

  5. Sous Format du manifeste, choisissez le type d'objet manifeste à utiliser.

    • Si vous choisissez S3 inventory report (Rapport sur l'inventaire S3), entrez le chemin de l'objet manifest.json généré par Amazon S3 dans le cadre du rapport d'inventaire au format CSV et éventuellement l'ID de version de l'objet manifeste si vous souhaitez utiliser une version autre que la version la plus récente.

    • Si vous choisissez CSV, entrez le chemin vers un objet manifeste au format CSV. L'objet manifeste doit respecter le format décrit dans la console. Vous pouvez éventuellement inclure l'ID de version de l'objet manifeste si vous souhaitez utiliser une version autre que la plus récente.

  6. Choisissez Suivant.

  7. Sous Operation (Opération), choisissez l'opération que vous souhaitez effectuer sur tous les objets répertoriés dans le manifeste. Remplissez les informations relatives à l'opération choisie, puis sélectionnez Suivant.

  8. Remplissez les informations relatives à l'option Configure additional options (Configurer les options supplémentaires), puis sélectionnez Suivant.

  9. Sous Vérification, vérifiez les paramètres. Si vous devez apporter des modifications, choisissez Précédent. Sinon, choisissez Create Job (Créer la tâche).

L'exemple suivant crée une tâche S3PutObjectTagging d'opérations par lot S3 à l'aide de la AWS CLI.

Pour créer une tâche d'opérations par lot S3PutObjectTagging

  1. Créez un rôle AWS Identity and Access Management (IAM) et attribuez-lui des autorisations. Ce rôle autorise Amazon S3 à ajouter les étiquettes d'objets pour lesquelles vous créerez une tâche à l'étape suivante.

    1. Créez un rôle IAM comme suit.

      aws iam create-role \ --role-name S3BatchJobRole \ --assume-role-policy-document '{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":"batchoperations.s3.amazonaws.com" }, "Action":"sts:AssumeRole" } ] }'

      Prenez note de l'Amazon Resource Name (ARN) du rôle. Vous aurez besoin de l'ARN lors de la création d'une tâche.

    2. Créez une stratégie IAM avec des autorisations et associez-la au rôle IAM que vous avez créé à l'étape précédente. Pour plus d'informations sur les autorisations, consultez Octroi d'autorisations pour les opérations par lot Amazon S3.

      aws iam put-role-policy \ --role-name S3BatchJobRole \ --policy-name PutObjectTaggingBatchJobPolicy \ --policy-document '{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "s3:PutObjectTagging", "s3:PutObjectVersionTagging" ], "Resource": "arn:aws:s3:::{{TargetResource}}/*" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectVersion", "s3:GetBucketLocation" ], "Resource": [ "arn:aws:s3:::{{ManifestBucket}}", "arn:aws:s3:::{{ManifestBucket}}/*" ] }, { "Effect":"Allow", "Action":[ "s3:PutObject", "s3:GetBucketLocation" ], "Resource":[ "arn:aws:s3:::{{ReportBucket}}", "arn:aws:s3:::{{ReportBucket}}/*" ] } ] }'

  2. Créez une tâche S3PutObjectTagging.

    Le fichier manifest.csv fournit une liste des valeurs de compartiment et de clé d'objet. La tâche applique les étiquettes spécifiées aux objets identifiés dans le manifeste. ETag est l'ETag de l'objet manifest.csv que vous pouvez obtenir à partir de la console Amazon S3. La requête spécifie le paramètre no-confirmation-required. Dès lors, Amazon S3 rend la tâche éligible à l'exécution sans que vous n'ayez à le confirmer avec la commande udpate-job-status.

    aws s3control create-job \ --region us-west-2 \ --account-id acct-id \ --operation '{"S3PutObjectTagging": { "TagSet": [{"Key":"keyOne", "Value":"ValueOne"}] }}' \ --manifest '{"Spec":{"Format":"S3BatchOperations_CSV_20180820","Fields":["Bucket","Key"]},"Location":{"ObjectArn":"arn:aws:s3:::my_manifests/manifest.csv","ETag":"60e460c9d1046e73f7dde5043ac3ae85"}}' \ --report '{"Bucket":"arn:aws:s3:::bucket-where-completion-report-goes","Prefix":"final-reports", "Format":"Report_CSV_20180820","Enabled":true,"ReportScope":"AllTasks"}' \ --priority 42 \ --role-arn IAM-role \ --client-request-token $(uuidgen) \ --description "job Description" \ --no-confirmation-required

    En réponse, Amazon S3 renvoie un ID de tâche (par exemple, 00e123a4-c0d8-41f4-a0eb-b46f9ba5b07c). Vous aurez besoin de l'ID dans les commandes suivantes.

L'exemple suivant crée une tâche d'opérations par lot S3 à l'aide du kit AWS SDK for Java.

package aws.example.s3control; import com.amazonaws.AmazonServiceException; import com.amazonaws.SdkClientException; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.services.s3control.AWSS3Control; import com.amazonaws.services.s3control.AWSS3ControlClient; import com.amazonaws.services.s3control.model.*; import java.util.UUID; import java.util.ArrayList; import static com.amazonaws.regions.Regions.US_WEST_2; public class CreateJob { public static void main(String[] args) { String accountId = "Account ID"; String iamRoleArn = "IAM Role ARN"; String reportBucketName = "arn:aws:s3:::bucket-where-completion-report-goes"; String uuid = UUID.randomUUID().toString(); ArrayList tagSet = new ArrayList<S3Tag>(); tagSet.add(new S3Tag().withKey("keyOne").withValue("ValueOne")); try { JobOperation jobOperation = new JobOperation() .withS3PutObjectTagging(new S3SetObjectTaggingOperation() .withTagSet(tagSet) ); JobManifest manifest = new JobManifest() .withSpec(new JobManifestSpec() .withFormat("S3BatchOperations_CSV_20180820") .withFields(new String[]{ "Bucket", "Key" })) .withLocation(new JobManifestLocation() .withObjectArn("arn:aws:s3:::my_manifests/manifest.csv") .withETag("60e460c9d1046e73f7dde5043ac3ae85")); JobReport jobReport = new JobReport() .withBucket(reportBucketName) .withPrefix("reports") .withFormat("Report_CSV_20180820") .withEnabled(true) .withReportScope("AllTasks"); AWSS3Control s3ControlClient = AWSS3ControlClient.builder() .withCredentials(new ProfileCredentialsProvider()) .withRegion(US_WEST_2) .build(); s3ControlClient.createJob(new CreateJobRequest() .withAccountId(accountId) .withOperation(jobOperation) .withManifest(manifest) .withReport(jobReport) .withPriority(42) .withRoleArn(iamRoleArn) .withClientRequestToken(uuid) .withDescription("job description") .withConfirmationRequired(false) ); } catch (AmazonServiceException e) { // The call was transmitted successfully, but Amazon S3 couldn't process // it and returned an error response. e.printStackTrace(); } catch (SdkClientException e) { // Amazon S3 couldn't be contacted for a response, or the client // couldn't parse the response from Amazon S3. e.printStackTrace(); } } }

Vous pouvez utiliser l'API REST pour créer une tâche d'opérations par lot. Pour de plus amples informations, veuillez consulter l’API REST CreateJob dans la Référence de l'API Amazon Simple Storage Service.

Réponses à la tâche

Si la demande Create Job aboutit, Amazon S3 renvoie un ID de tâche. L'ID de tâche est un identifiant unique généré automatiquement par Amazon S3 afin que vous puissiez identifier votre tâche d'opérations par lot et surveiller son statut.

Lorsque vous créez une tâche via la AWS CLI, les kits SDK Amazon ou l'API REST, vous pouvez définir les opérations par lot S3 pour qu'elle commencent automatiquement le traitement de la tâche. La tâche s'exécute dès qu'elle est prête et ne doit pas attendre que des tâches de plus haute priorité soient traitées en premier.

Lorsque vous créez une tâche via la AWS Management Console, vous devez vérifier les détails de la tâche et confirmer que vous voulez l'exécuter avant que les opérations par lot commencent à la traiter. Après avoir confirmé que vous souhaitez exécuter la tâche, celle-ci progresse comme si vous l'aviez créée via l'une des autres méthodes. Si une tâche conserve l’état Suspendu pendant plus de 30 jours, cette tâche échouera.