Utilisation de téléchargements partitionnés avec des compartiments de répertoires

Vous pouvez utiliser le processus de téléchargement en plusieurs parties pour télécharger un seul objet sous la forme d'un ensemble de parties. Chaque partie est une portion contiguë des données de l'objet. Vous pouvez charger ces parties d'objet indépendamment et dans n'importe quel ordre. Si le transfert d'une partie échoue, vous pouvez la retransférer sans affecter les autres. Une fois toutes les parties de l'objet chargées, Amazon S3 les assemble et crée l'objet. En général, lorsque l'objet atteint la taille de 100 Mo, vous devez préférer les chargements partitionnés au chargement d'objet en une seule opération.

L'utilisation du chargement partitionné offre les avantages suivants :

• Improved throughput (Meilleur débit) — vous pouvez charger des parties en parallèle pour améliorer le débit.

• Restauration rapide en cas de problème réseau : les pièces de petite taille minimisent l'impact du redémarrage d'un téléchargement échoué en raison d'une erreur réseau.

• Pause and resume object uploads (Interruption et reprise des chargements d'objet) — vous pouvez charger des parties d'objet au fil du temps. Une fois que vous avez lancé un téléchargement en plusieurs parties, il n'y a aucune date d'expiration. Vous devez explicitement terminer ou abandonner le téléchargement partitionné.

• Begin an upload before you know the final object size (Lancement d'un chargement avant de connaître la taille finale de l'objet) — vous pouvez charger un objet à mesure que vous le créez.

Nous vous recommandons d'utiliser les téléchargements partitionnés de la manière suivante :

• Si vous chargez des objets volumineux sur un réseau stable à large bande passante, utilisez les téléchargements partitionnés pour optimiser l'utilisation de la bande passante disponible en téléchargeant des parties d'objets en parallèle pour des performances multithread.

• Si vous effectuez un téléchargement sur un réseau irrégulier, utilisez les téléchargements partitionnés pour augmenter la résilience face aux erreurs réseau en évitant les redémarrages de téléchargement. Lorsque vous utilisez des téléchargements partitionnés, vous devez réessayer de télécharger uniquement les parties interrompues pendant le téléchargement. Vous n'avez pas besoin de redémarrer le chargement de vos objets depuis le début.

Lorsque vous utilisez des chargements partitionnés pour charger des objets vers la classe de stockage Amazon S3 Express One Zone dans des compartiments de répertoire, le processus de téléchargement partitionné est similaire au processus d'utilisation du téléchargement partitionné pour télécharger des objets dans des compartiments à usage général. Cependant, il existe quelques différences importantes.

Pour plus d'informations sur l'utilisation des téléchargements partitionnés pour télécharger des objets dans S3 Express One Zone, consultez les rubriques suivantes.

Le processus de téléchargement en plusieurs parties

Un téléchargement en plusieurs parties est un processus en trois étapes :

• Vous lancez le téléchargement.

• Vous chargez les parties de l'objet.

• Après avoir chargé toutes les parties, vous pouvez terminer le téléchargement en plusieurs parties.

Dès réception de la demande de téléchargement en plusieurs parties complète, Amazon S3 construit l'objet à partir des parties téléchargées, et vous pouvez ensuite accéder à l'objet comme vous le feriez pour n'importe quel autre objet de votre compartiment.

Lancement du chargement partitionné

Lorsque vous envoyez une demande pour lancer un chargement partitionné, Amazon S3 renvoie une réponse avec un ID de chargement, qui est un identifiant unique pour le chargement partitionné. Vous devez inclure cet ID de chargement dès que vous chargez les parties, listez les parties, terminez un chargement ou interrompez un chargement.

Chargement de parties

Lorsque vous chargez une partie, outre l'ID de chargement, vous devez spécifier un numéro de partie. Lorsque vous utilisez un téléchargement partitionné avec S3 Express One Zone, les numéros de pièce partitionnés doivent être des numéros de pièce consécutifs. Si vous essayez de traiter une demande de téléchargement en plusieurs parties avec des numéros de pièce non consécutifs, une erreur HTTP 400 Bad Request (commande de pièce non valide) est générée.

Un numéro de pièce identifie de manière unique une pièce et sa position dans l'objet que vous chargez. Si vous chargez une nouvelle pièce en utilisant le même numéro de pièce qu'une pièce précédemment téléchargée, la pièce précédemment téléchargée est remplacée.

Chaque fois que vous chargez une partie, Amazon S3 renvoie un en-tête entity tag (ETag) dans sa réponse. Pour chaque téléchargement partiel, vous devez enregistrer le numéro de pièce et la ETag valeur. Les ETag valeurs de tous les chargements de parties d'objets resteront les mêmes, mais un numéro de pièce différent sera attribué à chaque partie. Vous devez inclure ces valeurs dans la demande ultérieure pour terminer le chargement partitionné.

Amazon S3 chiffre automatiquement tous les nouveaux objets chargés dans un compartiment S3. Dans le cadre d’un chargement partitionné, si vous ne spécifiez pas d’informations de chiffrement dans votre demande, le paramètre de chiffrement des parties chargées est défini sur la configuration de chiffrement par défaut du compartiment de destination. La configuration de chiffrement par défaut d'un compartiment Amazon S3 est toujours activée et est au minimum définie sur le chiffrement côté serveur avec des clés gérées par Amazon S3 (SSE-S3). Pour les compartiments de répertoire, SSE -S3 et le chiffrement côté serveur à l'aide de AWS KMS clés (SSE-KMS) sont pris en charge. Pour de plus amples informations, veuillez consulter Protection et chiffrement des données.

Fin du chargement partitionné

Lorsque vous effectuez un chargement partitionné, Amazon S3 crée l'objet en concaténant les parties par ordre croissant en fonction du numéro de pièce. À l'issue d'une demande de chargement complet, les parties n'existent plus.

Votre demande complète de téléchargement en plusieurs parties doit inclure l'ID de téléchargement et une liste des deux numéros de pièce et de leurs ETag valeurs correspondantes. La réponse Amazon S3 inclut un ETag identifiant unique les données d'objet combinées. Il ne ETag s'agit pas d'un MD5 hachage des données de l'objet.

Listes de chargement partitionné

Vous pouvez lister les parties d'un chargement partitionné spécifique ou de tous les chargements partitionnés en cours. L'opération de liste des parties renvoie des informations sur les parties que vous avez chargées pour un chargement partitionné spécifique. Pour chaque demande de liste des parties, Amazon S3 renvoie des informations sur les parties pour le chargement partitionné spécifié, pour 1 000 parties maximum. Si le chargement partitionné compte plus de 1 000 parties, vous devez utiliser la pagination pour récupérer toutes les parties.

La liste des pièces renvoyée n'inclut pas les pièces dont le téléchargement n'est pas terminé. En utilisant l'opération d'affichage des chargements partitionnés, vous pouvez obtenir la liste des chargements partitionnés qui sont en cours.

Un chargement partitionné en cours est un chargement que vous avez lancé, mais que vous n'avez pas encore terminé ou interrompu. Chaque demande renvoie 1,000 chargements partitionnés maximum. S'il y a plus de 1 000 chargements partitionnés en cours, vous devez envoyer des demandes supplémentaires pour récupérer les chargements partitionnés restants. Utilisez la liste renvoyée uniquement pour la vérification. N'utilisez pas le résultat de la liste lorsque vous envoyez une requête de chargement partitionné complet. Conservez plutôt votre propre liste des numéros de pièce que vous avez spécifiés lors du chargement des pièces et des ETag valeurs correspondantes renvoyées par Amazon S3.

Pour plus d'informations sur les listes de téléchargement partitionné, voir ListPartsdans le Amazon Simple Storage Service API Reference.

Totaux de contrôle avec les opérations de chargement partitionné

Lorsque vous chargez un objet, vous pouvez spécifier un algorithme de somme de contrôle pour vérifier l’intégrité de l’objet. MD5n'est pas pris en charge pour les compartiments de répertoire. Vous pouvez spécifier l'un des algorithmes de hachage sécurisé (SHA) ou de contrôle de redondance cyclique () suivants pour vérifier l'intégrité des données CRC :

• CRC32

• CRC32C

• SHA-1

• SHA-256

Vous pouvez utiliser Amazon S3 REST API ou le AWS SDKs pour récupérer la valeur de la somme de contrôle pour des parties individuelles en utilisant GetObject ouHeadObject. Pour récupérer les valeurs de contrôle des parties individuelles de téléchargements partitionnés toujours en cours, vous pouvez utiliser ListParts.

Important

Lorsque vous utilisez les algorithmes de somme de contrôle précédents, les numéros de pièce en plusieurs parties doivent utiliser des numéros de pièce consécutifs. Si vous essayez de traiter une demande de téléchargement partitionné avec des numéros de pièce non consécutifs, Amazon S3 génère une erreur HTTP 400 Bad Request (commande de pièces non valide).

Pour plus d'informations sur le fonctionnement des checksums avec les objets de téléchargement partitionné, consultez. Vérification de l'intégrité des objets

Opérations simultanées de chargement partitionné

Dans un environnement de développement distribué, votre application peut lancer plusieurs mises à jour sur le même objet en même temps. Par exemple, votre application peut lancer plusieurs téléchargements partitionnés à l'aide de la même clé d'objet. Pour chacun de ces chargements, l'application peut ensuite charger des parties et envoyer une demande de chargement complet à Amazon S3 pour créer l'objet. Pour S3 Express One Zone, l’instant de création de l’objet correspond à la date d’achèvement du chargement partitionné.

Important

La gestion des versions n'est pas prise en charge pour les objets stockés dans des compartiments de répertoire.

Téléchargements en plusieurs parties et tarification

Lorsque vous lancez un chargement partitionné, Amazon S3 conserve toutes les parties jusqu’à ce que vous terminiez ou annuliez le chargement. Tout au long de sa durée de vie, le stockage, la bande passante et les demandes pour ce chargement partitionné ainsi que ses parties associées vous sont facturés. Si vous annulez le téléchargement en plusieurs parties, Amazon S3 supprime les artefacts de téléchargement et toutes les parties que vous avez chargées, et ils ne vous sont plus facturés. Aucuns frais de suppression anticipée ne sont facturés pour la suppression de téléchargements partitionnés incomplets, quelle que soit la classe de stockage spécifiée. Pour plus d’informations sur la tarification, consultez Tarification Amazon S3.

Important

Si la demande complète de téléchargement en plusieurs parties n'est pas envoyée correctement, les parties de l'objet ne sont pas assemblées et aucun objet n'est créé. Vous êtes facturé pour tout le stockage associé aux parties chargées. Il est important de terminer le téléchargement partitionné pour créer l'objet ou d'abandonner le téléchargement partitionné pour supprimer toutes les parties téléchargées.

Avant de pouvoir supprimer un bucket de répertoire, vous devez terminer ou abandonner tous les téléchargements partitionnés en cours. Les compartiments d'annuaire ne prennent pas en charge les configurations S3 Lifecycle. Si nécessaire, vous pouvez répertorier vos téléchargements partitionnés actifs, puis annuler les téléchargements, puis supprimer votre bucket.

APIOpérations et autorisations de téléchargement partitionné

Pour autoriser l'accès aux API opérations de gestion des objets sur un compartiment d'annuaire, vous accordez l's3express:CreateSessionautorisation dans le cadre d'une politique de compartiment ou d'une politique basée sur l'identité AWS Identity and Access Management (IAM).

Vous devez posséder les autorisations nécessaires pour utiliser les opérations de chargement partitionné. Vous pouvez utiliser des politiques de compartiment ou des politiques IAM basées sur l'identité pour accorder aux IAM principaux les autorisations nécessaires pour effectuer ces opérations. Le tableau suivant répertorie les autorisations nécessaires pour diverses opérations de chargement partitionné.

Vous pouvez identifier l'initiateur d'un téléchargement partitionné via l'Initiatorélément. Si l'initiateur est un Compte AWS, cet élément fournit les mêmes informations que l'Ownerélément. Si l'initiateur est un IAM utilisateur, cet élément fournit l'utilisateur ARN et le nom d'affichage.

Action	Autorisations nécessaires
Créer un chargement partitionné	Pour créer le téléchargement partitionné, vous devez être autorisé à effectuer l's3express:CreateSessionaction sur le bucket de répertoire.
Lancer un téléchargement partitionné	Pour lancer le téléchargement partitionné, vous devez être autorisé à effectuer l's3express:CreateSessionaction sur le bucket de répertoire.
Téléchargez une pièce	Pour télécharger une partie, vous devez être autorisé à effectuer l's3express:CreateSessionaction sur le bucket du répertoire. Pour que l'initiateur puisse télécharger une partie, le propriétaire du compartiment doit autoriser l'initiateur à effectuer l's3express:CreateSessionaction sur le compartiment de répertoire.
Télécharger une pièce (copie)	Pour télécharger une partie, vous devez être autorisé à effectuer l's3express:CreateSessionaction sur le bucket du répertoire. Pour que l'initiateur puisse charger une partie pour un objet, le propriétaire du compartiment doit l'autoriser à effectuer l'action s3express:CreateSession sur l'objet.
Terminer un chargement partitionné	Pour effectuer un téléchargement partitionné, vous devez être autorisé à effectuer l's3express:CreateSessionaction sur le bucket du répertoire. Pour que l'initiateur puisse effectuer un téléchargement en plusieurs parties, le propriétaire du compartiment doit autoriser l'initiateur à effectuer l's3express:CreateSessionaction sur l'objet.
Abandonner un chargement partitionné	Pour annuler un téléchargement partitionné, vous devez être autorisé à effectuer l's3express:CreateSessionaction. Pour que l'initiateur puisse abandonner un téléchargement partitionné, il doit disposer d'un accès autorisé explicite pour effectuer l'action. s3express:CreateSession
Lister les pièces	Pour répertorier les parties d'un téléchargement partitionné, vous devez être autorisé à effectuer l's3express:CreateSessionaction sur le bucket du répertoire.
Lister des chargements partitionnés en cours	Pour répertorier les téléchargements partitionnés en cours vers un bucket, vous devez être autorisé à effectuer l's3:ListBucketMultipartUploadsaction sur ce bucket.

APIsupport opérationnel pour les téléchargements partitionnés

Les sections suivantes du manuel Amazon Simple Storage Service API Reference décrivent les REST API opérations Amazon S3 pour les téléchargements partitionnés.

• CreateMultipartUpload

• UploadPart

• UploadPartCopy

• CompleteMultipartUpload

• AbortMultipartUpload

• ListParts

• ListMultipartUploads

Exemples

Pour utiliser un téléchargement partitionné pour charger un objet dans S3 Express One Zone dans un compartiment de répertoire, consultez les exemples suivants.

Rubriques

• Création d’un chargement partitionné
• Chargement des parties d'un téléchargement en plusieurs parties
• Achèvement d’un chargement partitionné
• Interruption d'un chargement partitionné
• Création d’une opération de copie d’un chargement partitionné
• Liste des téléchargements partitionnés en cours
• Répertorier les parties d'un téléchargement en plusieurs parties

Création d’un chargement partitionné

Note

Pour les compartiments de répertoire, lorsque vous effectuez une CreateMultipartUpload opération et une UploadPartCopy opération, le chiffrement par défaut du compartiment doit utiliser la configuration de chiffrement souhaitée, et les en-têtes de demande que vous fournissez dans la CreateMultipartUpload demande doivent correspondre à la configuration de chiffrement par défaut du compartiment de destination.

Les exemples suivants montrent comment créer un téléchargement partitionné.

En utilisant le AWS SDKs

SDK for Java 2.x

/**
 * This method creates a multipart upload request that generates a unique upload ID that is used to track
 * all the upload parts
 *
 * @param s3
 * @param bucketName - for example, 'doc-example-bucket--use1-az4--x-s3'
 * @param key
 * @return
 */
 private static String createMultipartUpload(S3Client s3, String bucketName, String key) {
 
     CreateMultipartUploadRequest createMultipartUploadRequest = CreateMultipartUploadRequest.builder() 
             .bucket(bucketName)
             .key(key)
             .build();
             
     String uploadId = null;
     
     try {
         CreateMultipartUploadResponse response = s3.createMultipartUpload(createMultipartUploadRequest);
         uploadId = response.uploadId();
     }
     catch (S3Exception e) {
         System.err.println(e.awsErrorDetails().errorMessage());
         System.exit(1);
     }
     return uploadId;

SDK for Python

def create_multipart_upload(s3_client, bucket_name, key_name):
    '''
   Create a multipart upload to a directory bucket
   
   :param s3_client: boto3 S3 client
   :param bucket_name: The destination bucket for the multipart upload
   :param key_name: The key name for the object to be uploaded
   :return: The UploadId for the multipart upload if created successfully, else None
   '''
   
   try:
        mpu = s3_client.create_multipart_upload(Bucket = bucket_name, Key = key_name)
        return mpu['UploadId'] 
    except ClientError as e:
        logging.error(e)
        return None

En utilisant le AWS CLI

Cet exemple montre comment créer un téléchargement partitionné vers un bucket de répertoire à l'aide du AWS CLI. Cette commande lance un téléchargement en plusieurs parties vers le bucket du répertoire. bucket-base-name--zone-id--x-s3 pour l'objet KEY_NAME. Pour utiliser la commande, remplacez le user input placeholders avec vos propres informations.

aws s3api create-multipart-upload --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME

Pour plus d'informations, consultez create-multipart-uploadle AWS Command Line Interface.

Chargement des parties d'un téléchargement en plusieurs parties

Les exemples suivants montrent comment télécharger des parties d'un téléchargement partitionné.

En utilisant le AWS SDKs

SDK for Java 2.x

L'exemple suivant montre comment diviser un seul objet en plusieurs parties, puis télécharger ces parties dans un bucket de répertoire à l'aide de la version 2.x SDK pour Java.

/**
 * This method creates part requests and uploads individual parts to S3 and then returns all the completed parts
 *
 * @param s3
 * @param bucketName
 * @param key
 * @param uploadId
 * @throws IOException
 */
 private static ListCompletedPartmultipartUpload(S3Client s3, String bucketName, String key, String uploadId, String filePath) throws IOException {

        int partNumber = 1;
        ListCompletedPart completedParts = new ArrayList<>();
        ByteBuffer bb = ByteBuffer.allocate(1024 * 1024 * 5); // 5 MB byte buffer

        // read the local file, breakdown into chunks and process
        try (RandomAccessFile file = new RandomAccessFile(filePath, "r")) {
            long fileSize = file.length();
            int position = 0;
            while (position < fileSize) {
                file.seek(position);
                int read = file.getChannel().read(bb);

                bb.flip(); // Swap position and limit before reading from the buffer.
                UploadPartRequest uploadPartRequest = UploadPartRequest.builder()
                        .bucket(bucketName)
                        .key(key)
                        .uploadId(uploadId)
                        .partNumber(partNumber)
                        .build();

                UploadPartResponse partResponse = s3.uploadPart(
                        uploadPartRequest,
                        RequestBody.fromByteBuffer(bb));

                CompletedPart part = CompletedPart.builder()
                        .partNumber(partNumber)
                        .eTag(partResponse.eTag())
                        .build();
                completedParts.add(part);

                bb.clear();
                position += read;
                partNumber++;
            }
        } 
        
        catch (IOException e) {
            throw e;
        }
        return completedParts;
    }

SDK for Python

L'exemple suivant montre comment diviser un seul objet en plusieurs parties, puis télécharger ces parties dans un bucket de répertoire à l'aide de SDK for Python.

def multipart_upload(s3_client, bucket_name, key_name, mpu_id, part_size):
    '''
    Break up a file into multiple parts and upload those parts to a directory bucket

    :param s3_client: boto3 S3 client
    :param bucket_name: Destination bucket for the multipart upload
    :param key_name: Key name for object to be uploaded and for the local file that's being uploaded
    :param mpu_id: The UploadId returned from the create_multipart_upload call
    :param part_size: The size parts that the object will be broken into, in bytes. 
                      Minimum 5 MiB, Maximum 5 GiB. There is no minimum size for the last part of your multipart upload.
    :return: part_list for the multipart upload if all parts are uploaded successfully, else None
    '''
    
    part_list = []
    try:
        with open(key_name, 'rb') as file:
            part_counter = 1
            while True:
                file_part = file.read(part_size)
                if not len(file_part):
                    break
                upload_part = s3_client.upload_part(
                    Bucket = bucket_name,
                    Key = key_name,
                    UploadId = mpu_id,
                    Body = file_part,
                    PartNumber = part_counter
                )
                part_list.append({'PartNumber': part_counter, 'ETag': upload_part['ETag']})
                part_counter += 1
    except ClientError as e:
        logging.error(e)
        return None
    return part_list

En utilisant le AWS CLI

Cet exemple montre comment diviser un seul objet en plusieurs parties, puis télécharger ces parties dans un bucket de répertoire à l'aide du AWS CLI. Pour utiliser la commande, remplacez le user input placeholders avec vos propres informations.

aws s3api upload-part --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME --part-number 1 --body LOCAL_FILE_NAME --upload-id "AS_mgt9RaQE9GEaifATue15dAAAAAAAAAAEMAAAAAAAAADQwNzI4MDU0MjUyMBYAAAAAAAAAAA0AAAAAAAAAAAH2AfYAAAAAAAAEBSD0WBKMAQAAAABneY9yBVsK89iFkvWdQhRCcXohE8RbYtc9QvBOG8tNpA"

Pour plus d'informations, consultez la section upload-part dans le. AWS Command Line Interface

Achèvement d’un chargement partitionné

Les exemples suivants montrent comment effectuer un téléchargement partitionné.

En utilisant le AWS SDKs

SDK for Java 2.x

Les exemples suivants montrent comment effectuer un téléchargement partitionné à l'aide de la version SDK 2.x pour Java.

/**
 * This method completes the multipart upload request by collating all the upload parts
 * @param s3
 * @param bucketName - for example, 'doc-example-bucket--usw2-az1--x-s3'
 * @param key
 * @param uploadId
 * @param uploadParts
 */
 private static void completeMultipartUpload(S3Client s3, String bucketName, String key, String uploadId, ListCompletedPart uploadParts) {
        CompletedMultipartUpload completedMultipartUpload = CompletedMultipartUpload.builder()
                .parts(uploadParts)
                .build();

        CompleteMultipartUploadRequest completeMultipartUploadRequest =
                CompleteMultipartUploadRequest.builder()
                        .bucket(bucketName)
                        .key(key)
                        .uploadId(uploadId)
                        .multipartUpload(completedMultipartUpload)
                        .build();

        s3.completeMultipartUpload(completeMultipartUploadRequest);
    }

    public static void multipartUploadTest(S3Client s3, String bucketName, String key, String localFilePath)  {
        System.out.println("Starting multipart upload for: " + key);
        try {
            String uploadId = createMultipartUpload(s3, bucketName, key);
            System.out.println(uploadId);
            ListCompletedPart parts = multipartUpload(s3, bucketName, key, uploadId, localFilePath);
            completeMultipartUpload(s3, bucketName, key, uploadId, parts);
            System.out.println("Multipart upload completed for: " + key);
        } 
        
        catch (Exception e) {
            System.err.println(e.getMessage());
            System.exit(1);
        }
    }

SDK for Python

Les exemples suivants montrent comment effectuer un téléchargement en plusieurs parties à l'aide de SDK for Python.

def complete_multipart_upload(s3_client, bucket_name, key_name, mpu_id, part_list):
    '''
    Completes a multipart upload to a directory bucket

    :param s3_client: boto3 S3 client
    :param bucket_name: The destination bucket for the multipart upload
    :param key_name: The key name for the object to be uploaded
    :param mpu_id: The UploadId returned from the create_multipart_upload call
    :param part_list: The list of uploaded part numbers with their associated ETags 
    :return: True if the multipart upload was completed successfully, else False
    '''
    
    try:
        s3_client.complete_multipart_upload(
            Bucket = bucket_name,
            Key = key_name,
            UploadId = mpu_id,
            MultipartUpload = {
                'Parts': part_list
            }
        )
    except ClientError as e:
        logging.error(e)
        return False
    return True
    
if __name__ == '__main__':
    MB = 1024 ** 2
    region = 'us-west-2'
    bucket_name = 'BUCKET_NAME'
    key_name = 'OBJECT_NAME'
    part_size = 10 * MB
    s3_client = boto3.client('s3', region_name = region)
    mpu_id = create_multipart_upload(s3_client, bucket_name, key_name)
    if mpu_id is not None:
        part_list = multipart_upload(s3_client, bucket_name, key_name, mpu_id, part_size)
        if part_list is not None:
            if complete_multipart_upload(s3_client, bucket_name, key_name, mpu_id, part_list):
                print (f'{key_name} successfully uploaded through a ultipart upload to {bucket_name}')
            else:
                print (f'Could not upload {key_name} hrough a multipart upload to {bucket_name}')

En utilisant le AWS CLI

Cet exemple montre comment effectuer un téléchargement partitionné pour un bucket de répertoire à l'aide du AWS CLI. Pour utiliser la commande, remplacez le user input placeholders avec vos propres informations.

aws s3api complete-multipart-upload --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME --upload-id "AS_mgt9RaQE9GEaifATue15dAAAAAAAAAAEMAAAAAAAAADQwNzI4MDU0MjUyMBYAAAAAAAAAAA0AAAAAAAAAAAH2AfYAAAAAAAAEBSD0WBKMAQAAAABneY9yBVsK89iFkvWdQhRCcXohE8RbYtc9QvBOG8tNpA" --multipart-upload file://parts.json

Cet exemple utilise une JSON structure qui décrit les parties du téléchargement partitionné qui doivent être réassemblées dans le fichier complet. Dans cet exemple, le file:// préfixe est utilisé pour charger la JSON structure à partir d'un fichier du dossier local nomméparts.

parts.json :

parts.json
{
  "Parts": [
    {
      "ETag": "6b78c4a64dd641a58dac8d9258b88147",
      "PartNumber": 1
    }
  ]
}

Pour plus d'informations, consultez complete-multipart-uploadle AWS Command Line Interface.

Interruption d'un chargement partitionné

Les exemples suivants montrent comment annuler un téléchargement partitionné.

En utilisant le AWS SDKs

SDK for Java 2.x

L'exemple suivant montre comment annuler un téléchargement partitionné à l'aide de la version 2.x SDK pour Java.

public static void abortMultiPartUploads( S3Client s3, String bucketName ) {

         try {
             ListMultipartUploadsRequest listMultipartUploadsRequest = ListMultipartUploadsRequest.builder()
                     .bucket(bucketName)
                     .build();

             ListMultipartUploadsResponse response = s3.listMultipartUploads(listMultipartUploadsRequest);
             ListMultipartUpload uploads = response.uploads();

             AbortMultipartUploadRequest abortMultipartUploadRequest;
             for (MultipartUpload upload: uploads) {
                 abortMultipartUploadRequest = AbortMultipartUploadRequest.builder()
                         .bucket(bucketName)
                         .key(upload.key())
                         .uploadId(upload.uploadId())
                         .build();

                 s3.abortMultipartUpload(abortMultipartUploadRequest);
             }

         } 
         
         catch (S3Exception e) {
             System.err.println(e.getMessage());
             System.exit(1);
         }
     }

SDK for Python

L'exemple suivant montre comment annuler un téléchargement partitionné à l'aide de for SDK Python.

import logging
import boto3
from botocore.exceptions import ClientError


def abort_multipart_upload(s3_client, bucket_name, key_name, upload_id):
    '''
    Aborts a partial multipart upload in a directory bucket.
    
    :param s3_client: boto3 S3 client
    :param bucket_name: Bucket where the multipart upload was initiated - for example, 'doc-example-bucket--usw2-az1--x-s3'
    :param key_name: Name of the object for which the multipart upload needs to be aborted
    :param upload_id: Multipart upload ID for the multipart upload to be aborted
    :return: True if the multipart upload was successfully aborted, False if not
    '''
    try:
        s3_client.abort_multipart_upload(
            Bucket = bucket_name,
            Key = key_name,
            UploadId = upload_id
        )
    except ClientError as e:
        logging.error(e)
        return False
    return True


if __name__ == '__main__':
    region = 'us-west-2'
    bucket_name = 'BUCKET_NAME'
    key_name = 'KEY_NAME'
        upload_id = 'UPLOAD_ID'
    s3_client = boto3.client('s3', region_name = region)
    if abort_multipart_upload(s3_client, bucket_name, key_name, upload_id):
        print (f'Multipart upload for object {key_name} in {bucket_name} bucket has been aborted')
    else:
        print (f'Unable to abort multipart upload for object {key_name} in {bucket_name} bucket')

En utilisant le AWS CLI

L'exemple suivant montre comment annuler un téléchargement partitionné à l'aide du. AWS CLI Pour utiliser la commande, remplacez le user input placeholders avec vos propres informations.

aws s3api abort-multipart-upload --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME --upload-id "AS_mgt9RaQE9GEaifATue15dAAAAAAAAAAEMAAAAAAAAADQwNzI4MDU0MjUyMBYAAAAAAAAAAA0AAAAAAAAAAAH2AfYAAAAAAAAEAX5hFw-MAQAAAAB0OxUFeA7LTbWWFS8WYwhrxDxTIDN-pdEEq_agIHqsbg"

Pour plus d'informations, consultez abort-multipart-uploadle AWS Command Line Interface.

Création d’une opération de copie d’un chargement partitionné

Note

• Pour chiffrer de nouvelles copies partielles d'objets dans un compartiment de répertoire avec SSE -KMS, vous devez spécifier SSE - KMS comme configuration de chiffrement par défaut du compartiment d'annuaire avec une KMS clé (en particulier, une clé gérée par le client). Le Clé gérée par AWS(aws/s3) n'est pas pris en charge. Votre SSE KMS configuration ne peut prendre en charge qu'une seule clé gérée par le client par compartiment de répertoire pendant toute la durée de vie du compartiment. Une fois que vous avez spécifié une clé gérée par le client pour SSE -KMS, vous ne pouvez pas remplacer la clé gérée par le client pour la KMS configuration du SSE compartiment. Vous ne pouvez pas spécifier de paramètres de chiffrement côté serveur pour les nouvelles copies partielles d'objets avec SSE - KMS dans les en-têtes de UploadPartCopydemande. En outre, les en-têtes de demande que vous fournissez dans la CreateMultipartUpload demande doivent correspondre à la configuration de chiffrement par défaut du compartiment de destination.

• Les clés de compartiment S3 ne sont pas prises en charge lorsque vous copiez SSE des objets KMS chiffrés depuis des compartiments à usage général vers des compartiments de répertoire, des compartiments de répertoire vers des compartiments à usage général, ou entre des compartiments de répertoire, via UploadPartCopy. Dans ce cas, Amazon S3 effectue un appel à AWS KMS chaque fois qu'une demande de copie est faite pour un objet KMS chiffré.

Les exemples suivants montrent comment copier des objets d'un compartiment à un autre à l'aide d'un téléchargement partitionné.

En utilisant le AWS SDKs

SDK for Java 2.x

L'exemple suivant montre comment utiliser un téléchargement partitionné pour copier par programmation un objet d'un bucket à un autre à l'aide de la version 2.x SDK pour Java.

/**
 * This method creates a multipart upload request that generates a unique upload ID that is used to track
 * all the upload parts.
 *
 * @param s3
 * @param bucketName
 * @param key
 * @return
 */
 private static String createMultipartUpload(S3Client s3, String bucketName, String key) {
        CreateMultipartUploadRequest createMultipartUploadRequest = CreateMultipartUploadRequest.builder()
                .bucket(bucketName)
                .key(key)
                .build();
        String uploadId = null;
        try {
            CreateMultipartUploadResponse response = s3.createMultipartUpload(createMultipartUploadRequest);
            uploadId = response.uploadId();
        } catch (S3Exception e) {
            System.err.println(e.awsErrorDetails().errorMessage());
            System.exit(1);
        }
        return uploadId;
  }

  /**
   * Creates copy parts based on source object size and copies over individual parts
   *
   * @param s3
   * @param sourceBucket
   * @param sourceKey
   * @param destnBucket
   * @param destnKey
   * @param uploadId
   * @return
   * @throws IOException
   */
    public static ListCompletedPart multipartUploadCopy(S3Client s3, String sourceBucket, String sourceKey, String destnBucket, String destnKey, String uploadId) throws IOException {

        // Get the object size to track the end of the copy operation.
        HeadObjectRequest headObjectRequest = HeadObjectRequest
                .builder()
                .bucket(sourceBucket)
                .key(sourceKey)
                .build();
        HeadObjectResponse response = s3.headObject(headObjectRequest);
        Long objectSize = response.contentLength();

        System.out.println("Source Object size: " + objectSize);

        // Copy the object using 20 MB parts.
        long partSize = 20 * 1024 * 1024;
        long bytePosition = 0;
        int partNum = 1;
        ListCompletedPart completedParts = new ArrayList<>();
        while (bytePosition < objectSize) {
            // The last part might be smaller than partSize, so check to make sure
            // that lastByte isn't beyond the end of the object.
            long lastByte = Math.min(bytePosition + partSize - 1, objectSize - 1);

            System.out.println("part no: " + partNum + ", bytePosition: " + bytePosition + ", lastByte: " + lastByte);

            // Copy this part.
            UploadPartCopyRequest req = UploadPartCopyRequest.builder()
                    .uploadId(uploadId)
                    .sourceBucket(sourceBucket)
                    .sourceKey(sourceKey)
                    .destinationBucket(destnBucket)
                    .destinationKey(destnKey)
                    .copySourceRange("bytes="+bytePosition+"-"+lastByte)
                    .partNumber(partNum)
                    .build();
            UploadPartCopyResponse res = s3.uploadPartCopy(req);
            CompletedPart part = CompletedPart.builder()
                    .partNumber(partNum)
                    .eTag(res.copyPartResult().eTag())
                    .build();
            completedParts.add(part);
            partNum++;
            bytePosition += partSize;
        }
        return completedParts;
    }


    public static void multipartCopyUploadTest(S3Client s3, String srcBucket, String srcKey, String destnBucket, String destnKey)  {
        System.out.println("Starting multipart copy for: " + srcKey);
        try {
            String uploadId = createMultipartUpload(s3, destnBucket, destnKey);
            System.out.println(uploadId);
            ListCompletedPart parts = multipartUploadCopy(s3, srcBucket, srcKey,destnBucket,  destnKey, uploadId);
            completeMultipartUpload(s3, destnBucket, destnKey, uploadId, parts);
            System.out.println("Multipart copy completed for: " + srcKey);
        } catch (Exception e) {
            System.err.println(e.getMessage());
            System.exit(1);
        }
    }

SDK for Python

L'exemple suivant montre comment utiliser un téléchargement partitionné pour copier par programmation un objet d'un bucket à un autre à l'aide de for SDK Python.

import logging
import boto3
from botocore.exceptions import ClientError

def head_object(s3_client, bucket_name, key_name):
    '''
    Returns metadata for an object in a directory bucket

    :param s3_client: boto3 S3 client
    :param bucket_name: Bucket that contains the object to query for metadata
    :param key_name: Key name to query for metadata
    :return: Metadata for the specified object if successful, else None
    '''

    try:
        response = s3_client.head_object(
            Bucket = bucket_name,
            Key = key_name
        )
        return response
    except ClientError as e:
        logging.error(e)
        return None
    
def create_multipart_upload(s3_client, bucket_name, key_name):
    '''
    Create a multipart upload to a directory bucket

    :param s3_client: boto3 S3 client
    :param bucket_name: Destination bucket for the multipart upload
    :param key_name: Key name of the object to be uploaded
    :return: UploadId for the multipart upload if created successfully, else None
    '''
    
    try:
        mpu = s3_client.create_multipart_upload(Bucket = bucket_name, Key = key_name)
        return mpu['UploadId'] 
    except ClientError as e:
        logging.error(e)
        return None

def multipart_copy_upload(s3_client, source_bucket_name, key_name, target_bucket_name, mpu_id, part_size):
    '''
    Copy an object in a directory bucket to another bucket in multiple parts of a specified size
    
    :param s3_client: boto3 S3 client
    :param source_bucket_name: Bucket where the source object exists
    :param key_name: Key name of the object to be copied
    :param target_bucket_name: Destination bucket for copied object
    :param mpu_id: The UploadId returned from the create_multipart_upload call
    :param part_size: The size parts that the object will be broken into, in bytes. 
                      Minimum 5 MiB, Maximum 5 GiB. There is no minimum size for the last part of your multipart upload.
    :return: part_list for the multipart copy if all parts are copied successfully, else None
    '''
    
    part_list = []
    copy_source = {
        'Bucket': source_bucket_name,
        'Key': key_name
    }
    try:
        part_counter = 1
        object_size = head_object(s3_client, source_bucket_name, key_name)
        if object_size is not None:
            object_size = object_size['ContentLength']
        while (part_counter - 1) * part_size <object_size:
            bytes_start = (part_counter - 1) * part_size
            bytes_end = (part_counter * part_size) - 1
            upload_copy_part = s3_client.upload_part_copy (
                Bucket = target_bucket_name,
                CopySource = copy_source,
                CopySourceRange = f'bytes={bytes_start}-{bytes_end}',
                Key = key_name,
                PartNumber = part_counter,
                UploadId = mpu_id
            )
            part_list.append({'PartNumber': part_counter, 'ETag': upload_copy_part['CopyPartResult']['ETag']})
            part_counter += 1
    except ClientError as e:
        logging.error(e)
        return None
    return part_list

def complete_multipart_upload(s3_client, bucket_name, key_name, mpu_id, part_list):
    '''
    Completes a multipart upload to a directory bucket

    :param s3_client: boto3 S3 client
    :param bucket_name: Destination bucket for the multipart upload
    :param key_name: Key name of the object to be uploaded
    :param mpu_id: The UploadId returned from the create_multipart_upload call
    :param part_list: List of uploaded part numbers with associated ETags 
    :return: True if the multipart upload was completed successfully, else False
    '''
    
    try:
        s3_client.complete_multipart_upload(
            Bucket = bucket_name,
            Key = key_name,
            UploadId = mpu_id,
            MultipartUpload = {
                'Parts': part_list
            }
        )
    except ClientError as e:
        logging.error(e)
        return False
    return True

if __name__ == '__main__':
    MB = 1024 ** 2
    region = 'us-west-2'
    source_bucket_name = 'SOURCE_BUCKET_NAME'
    target_bucket_name = 'TARGET_BUCKET_NAME'
    key_name = 'KEY_NAME'
    part_size = 10 * MB
    s3_client = boto3.client('s3', region_name = region)
    mpu_id = create_multipart_upload(s3_client, target_bucket_name, key_name)
    if mpu_id is not None:
        part_list = multipart_copy_upload(s3_client, source_bucket_name, key_name, target_bucket_name, mpu_id, part_size)
        if part_list is not None:
            if complete_multipart_upload(s3_client, target_bucket_name, key_name, mpu_id, part_list):
                print (f'{key_name} successfully copied through multipart copy from {source_bucket_name} to {target_bucket_name}')
            else:
                print (f'Could not copy {key_name} through multipart copy from {source_bucket_name} to {target_bucket_name}')

En utilisant le AWS CLI

L'exemple suivant montre comment utiliser un téléchargement partitionné pour copier par programmation un objet d'un compartiment vers un compartiment de répertoire à l'aide du. AWS CLI Pour utiliser la commande, remplacez le user input placeholders avec vos propres informations.

aws s3api upload-part-copy --bucket bucket-base-name--zone-id--x-s3 --key TARGET_KEY_NAME --copy-source SOURCE_BUCKET_NAME/SOURCE_KEY_NAME --part-number 1 --upload-id "AS_mgt9RaQE9GEaifATue15dAAAAAAAAAAEMAAAAAAAAADQwNzI4MDU0MjUyMBYAAAAAAAAAAA0AAAAAAAAAAAH2AfYAAAAAAAAEBnJ4cxKMAQAAAABiNXpOFVZJ1tZcKWib9YKE1C565_hCkDJ_4AfCap2svg"

Pour plus d'informations, consultez upload-part-copyle AWS Command Line Interface.

Liste des téléchargements partitionnés en cours

Pour répertorier les téléchargements partitionnés en cours vers un bucket de répertoire, vous pouvez utiliser le AWS SDKs, ou le. AWS CLI

En utilisant le AWS SDKs

SDK for Java 2.x

Les exemples suivants montrent comment répertorier les téléchargements partitionnés en cours (incomplets) à l'aide de la version 2.x SDK pour Java.

 public static void listMultiPartUploads( S3Client s3, String bucketName) {
        try {
            ListMultipartUploadsRequest listMultipartUploadsRequest = ListMultipartUploadsRequest.builder()
                .bucket(bucketName)
                .build();
                
            ListMultipartUploadsResponse response = s3.listMultipartUploads(listMultipartUploadsRequest);
            List MultipartUpload uploads = response.uploads();
            for (MultipartUpload upload: uploads) {
                System.out.println("Upload in progress: Key = \"" + upload.key() + "\", id = " + upload.uploadId());
            }
      }
      catch (S3Exception e) {
            System.err.println(e.getMessage());
            System.exit(1);
      }
  }

SDK for Python

Les exemples suivants montrent comment répertorier les téléchargements partitionnés en cours (incomplets) à l'aide de for SDK Python.

import logging
import boto3
from botocore.exceptions import ClientError

def list_multipart_uploads(s3_client, bucket_name):
    '''
    List any incomplete multipart uploads in a directory bucket in e specified gion

    :param s3_client: boto3 S3 client
    :param bucket_name: Bucket to check for incomplete multipart uploads
    :return: List of incomplete multipart uploads if there are any, None if not
    '''
    
    try:
        response = s3_client.list_multipart_uploads(Bucket = bucket_name)
        if 'Uploads' in response.keys():
            return response['Uploads']
        else:
            return None 
    except ClientError as e:
        logging.error(e)

if __name__ == '__main__':
    bucket_name = 'BUCKET_NAME'
    region = 'us-west-2'
    s3_client = boto3.client('s3', region_name = region)
    multipart_uploads = list_multipart_uploads(s3_client, bucket_name)
    if multipart_uploads is not None:
        print (f'There are {len(multipart_uploads)} ncomplete multipart uploads for {bucket_name}')
    else:
        print (f'There are no incomplete multipart uploads for {bucket_name}')

En utilisant le AWS CLI

Les exemples suivants montrent comment répertorier les téléchargements partitionnés en cours (incomplets) à l'aide du. AWS CLI Pour utiliser la commande, remplacez le user input placeholders avec vos propres informations.

aws s3api list-multipart-uploads --bucket bucket-base-name--zone-id--x-s3

Pour plus d'informations, consultez list-multipart-uploadsle AWS Command Line Interface.

Répertorier les parties d'un téléchargement en plusieurs parties

Les exemples suivants montrent comment répertorier les parties d'un téléchargement partitionné vers un bucket de répertoire.

En utilisant le AWS SDKs

SDK for Java 2.x

Les exemples suivants montrent comment répertorier les parties d'un téléchargement partitionné vers un bucket de répertoire à l'aide SDK de Java 2.x.

public static void listMultiPartUploadsParts( S3Client s3, String bucketName, String objKey, String uploadID) {
         
         try {
             ListPartsRequest listPartsRequest = ListPartsRequest.builder()
                 .bucket(bucketName)
                 .uploadId(uploadID)
                 .key(objKey)
                 .build();

             ListPartsResponse response = s3.listParts(listPartsRequest);
             ListPart parts = response.parts();
             for (Part part: parts) {
                 System.out.println("Upload in progress: Part number = \"" + part.partNumber() + "\", etag = " + part.eTag());
             }

         } 
         
         catch (S3Exception e) {
             System.err.println(e.getMessage());
             System.exit(1);
         }
         
         
     }

SDK for Python

Les exemples suivants montrent comment répertorier les parties d'un téléchargement partitionné vers un bucket de répertoire à l'aide de SDK for Python.

import logging
import boto3
from botocore.exceptions import ClientError

def list_parts(s3_client, bucket_name, key_name, upload_id):
    '''
    Lists the parts that have been uploaded for a specific multipart upload to a directory bucket.
    
    :param s3_client: boto3 S3 client
    :param bucket_name: Bucket that multipart uploads parts have been uploaded to
    :param key_name: Name of the object that has parts uploaded
    :param upload_id: Multipart upload ID that the parts are associated with
    :return: List of parts associated with the specified multipart upload, None if there are no parts
    '''
    parts_list = []
    next_part_marker = ''
    continuation_flag = True
    try:
        while continuation_flag:
            if next_part_marker == '':
                response = s3_client.list_parts(
                    Bucket = bucket_name,
                    Key = key_name,
                    UploadId = upload_id
                )
            else:
                response = s3_client.list_parts(
                    Bucket = bucket_name,
                    Key = key_name,
                    UploadId = upload_id,
                    NextPartMarker = next_part_marker
                )
            if 'Parts' in response:
                for part in response['Parts']:
                    parts_list.append(part)
                if response['IsTruncated']:
                    next_part_marker = response['NextPartNumberMarker']
                else:
                    continuation_flag = False
            else:
                continuation_flag = False
        return parts_list
    except ClientError as e:
        logging.error(e)
        return None

if __name__ == '__main__':
    region = 'us-west-2'
    bucket_name = 'BUCKET_NAME'
    key_name = 'KEY_NAME'
    upload_id = 'UPLOAD_ID'
    s3_client = boto3.client('s3', region_name = region)
    parts_list = list_parts(s3_client, bucket_name, key_name, upload_id)
    if parts_list is not None:
        print (f'{key_name} has {len(parts_list)} parts uploaded to {bucket_name}')
    else:
        print (f'There are no multipart uploads with that upload ID for {bucket_name} bucket')

En utilisant le AWS CLI

Les exemples suivants montrent comment répertorier les parties d'un téléchargement partitionné vers un bucket de répertoire à l'aide du AWS CLI. Pour utiliser la commande, remplacez le user input placeholders avec vos propres informations.

aws s3api list-parts --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME --upload-id "AS_mgt9RaQE9GEaifATue15dAAAAAAAAAAEMAAAAAAAAADQwNzI4MDU0MjUyMBYAAAAAAAAAAA0AAAAAAAAAAAH2AfYAAAAAAAAEBSD0WBKMAQAAAABneY9yBVsK89iFkvWdQhRCcXohE8RbYtc9QvBOG8tNpA"

Pour plus d'informations, voir list-parts dans le. AWS Command Line Interface