Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Utilisation des téléchargements partitionnés sur Amazon S3 avec AWS SDK pour PHP la version 3
<a name="s3-multipart-upload"></a>

Vous pouvez charger des objets de taille inférieure ou égale à 5 Go à l'aide d'une simple opération `PutObject`. Cependant, les méthodes de chargement partitionné (par exemple, `CreateMultipartUpload`, `UploadPart`, `CompleteMultipartUpload` et `AbortMultipartUpload`) vous permettent de charger des objets dont la taille est comprise entre 5 Mo et 5 To.

L’exemple suivant indique comment :
+ Chargez un objet sur Amazon S3 à l'aide de [ObjectUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectUploader.html).
+ Créez un téléchargement partitionné pour un objet Amazon S3 à l'aide [MultipartUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.MultipartUploader.html)de.
+ Copiez des objets d'un emplacement Amazon S3 à un autre en utilisant [ObjectCopier](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectCopier.html).

Tous les exemples de code pour le AWS SDK pour PHP sont [disponibles ici GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).

## Informations d’identification
<a name="examplecredentials"></a>

Avant d'exécuter l'exemple de code, configurez vos AWS informations d'identification, comme décrit dans[Authentification à l' AWS aide de AWS SDK pour PHP la version 3](credentials.md). Importez ensuite le AWS SDK pour PHP, comme décrit dans[Installation de la AWS SDK pour PHP version 3](getting-started_installation.md).

## Uploader des objets
<a name="object-uploader"></a>

Si vous n'êtes pas sûr de la solution la mieux adaptée à la tâche, utilisez`ObjectUploader`. `PutObject` `MultipartUploader` `ObjectUploader`télécharge un fichier volumineux sur Amazon S3 en utilisant l'un ou l'autre `PutObject` ou `MultipartUploader` en fonction de la taille de la charge utile.

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\ObjectUploader;
use Aws\S3\S3Client;
```

 **Exemple de code** 

```
// Create an S3Client.
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-east-2',
    'version' => '2006-03-01'
]);

$bucket = 'your-bucket';
$key = 'my-file.zip';

// Use a stream instead of a file path.
$source = fopen('/path/to/large/file.zip', 'rb');

$uploader = new ObjectUploader(
    $s3Client,
    $bucket,
    $key,
    $source
);

do {
    try {
        $result = $uploader->upload();
        if ($result["@metadata"]["statusCode"] == '200') {
            print('<p>File successfully uploaded to ' . $result["ObjectURL"] . '.</p>');
        }
        print($result);
        // If the SDK chooses a multipart upload, try again if there is an exception.
        // Unlike PutObject calls, multipart upload calls are not automatically retried.
    } catch (MultipartUploadException $e) {
        rewind($source);
        $uploader = new MultipartUploader($s3Client, $source, [
            'state' => $e->getState(),
        ]);
    }
} while (!isset($result));

fclose($source);
```

### Configuration
<a name="object-uploader-configuration"></a>

Le constructeur de l'objet `ObjectUploader` accepte les arguments suivants :

**`$client`**  
L'objet `Aws\ClientInterface` à utiliser pour effectuer les transferts. Il doit s'agir d'une instance de `Aws\S3\S3Client`.

**`$bucket`**  
(`string`, *obligatoire*) Nom du compartiment vers lequel l’objet est chargé.

**`$key`**  
(`string`, *obligatoire*) Clé à utiliser pour l’objet concerné par le chargement.

**`$body`**  
(`mixed`, *obligatoire*) Données d'objet à télécharger. Il peut s'agir `StreamInterface` d'une ressource de flux PHP ou d'une chaîne de données à télécharger.

**`$acl`**  
(`string`) Liste de contrôle d'accès (ACL) à définir sur l'objet concerné par le chargement. Les objets sont privés par défaut.

**`$options`**  
Un tableau associatif d'options de configuration pour le chargement partitionné. Les options de configuration suivantes sont valides :    
**`add_content_md5`**  
(`bool`) Réglez sur true pour calculer automatiquement la MD5 somme de contrôle pour le téléchargement.  
**`mup_threshold`**  
(`int`, *par défaut* :`int(16777216)`) Le nombre d'octets correspondant à la taille du fichier. Si la taille du fichier dépasse cette limite, un téléchargement partitionné est utilisé.  
**`before_complete`**  
(`callable`) Rappel à invoquer avant l'opération `CompleteMultipartUpload`. Le rappel doit avoir une signature de fonction similaire à :`function (Aws\Command $command) {...}`. Consultez la [référence de l'CompleteMultipartUpload API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#completemultipartupload) pour connaître les paramètres que vous pouvez ajouter à l'`CommandInterface`objet.  
**`before_initiate`**  
(`callable`) Rappel à invoquer avant l'opération `CreateMultipartUpload`. Le rappel doit avoir une signature de fonction similaire à :`function (Aws\Command $command) {...}`. Le SDK invoque ce rappel si la taille du fichier dépasse la valeur. `mup_threshold` Consultez la [référence de l'CreateMultipartUpload API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#createmultipartupload) pour connaître les paramètres que vous pouvez ajouter à l'`CommandInterface`objet.  
**`before_upload`**  
(`callable`) Rappel à invoquer avant `PutObject` toute `UploadPart` opération. Le rappel doit avoir une signature de fonction similaire à :`function (Aws\Command $command) {...}`. Le SDK invoque ce rappel si la taille du fichier est inférieure ou égale à la valeur. `mup_threshold` Consultez la [référence de l'PutObject API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) pour connaître les paramètres que vous pouvez appliquer à la `PutObject` demande. Pour les paramètres qui s'appliquent à une `UploadPart` demande, consultez la [référence de l'UploadPart API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#uploadpart). Le SDK ignore tout paramètre non applicable à l'opération représentée par l'`CommandInterface`objet.  
**`concurrency`**  
(`int`, *par défaut* : `int(3)`) Nombre maximal d’opérations `UploadPart` simultanées autorisées pendant le chargement partitionné.  
**`part_size`**  
(`int`, *par défaut* : `int(5242880)`) Taille de partie, en octets, à utiliser lors d’un chargement partitionné. La valeur doit être comprise entre 5 Mo et 5 Go inclus.  
**`state`**  
(`Aws\Multipart\UploadState`) Objet représentant l'état du chargement partitionné et utilisé pour reprendre un chargement précédent. Lorsque cette option est fournie, les `$key` arguments `$bucket` et et l'`part_size`option sont ignorés.  
**`params`**  
Tableau associatif qui fournit des options de configuration pour chaque sous-commande. Par exemple :  

```
new ObjectUploader($bucket, $key, $body, $acl, ['params' => ['CacheControl' => {{<some_value>}}])
```

## MultipartUploader
<a name="multipartuploader"></a>

Les chargements partitionnés sont conçus pour améliorer l'expérience de chargement pour les objets volumineux. Ils vous permettent de charger des parties d'objets indépendamment, dans n'importe quel ordre, et en parallèle.

Les clients Amazon S3 sont invités à utiliser les téléchargements partitionnés pour les objets de plus de 100 Mo.

## MultipartUploader objet
<a name="multipartuploader-object"></a>

Le kit SDK dispose d'un objet `MultipartUploader` spécial qui simplifie le processus de chargement partitionné.

 **Importations** 

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **Exemple de code** 

```
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

// Use multipart upload
$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

try {
    $result = $uploader->upload();
    echo "Upload complete: {$result['ObjectURL']}\n";
} catch (MultipartUploadException $e) {
    echo $e->getMessage() . "\n";
}
```

Le chargeur crée un générateur de données partitionnées, en fonction de la source et de la configuration fournies, et tente de charger toutes les parties. Si le chargement de certaines parties échoue, le chargeur continue le chargement des autres parties jusqu'à ce que l'ensemble des données source soient lues. Par la suite, le chargeur tente de charger les parties ayant échoué ou lève une exception contenant des informations sur ces dernières.

## Personnalisation d'un téléchargement en plusieurs parties
<a name="customizing-a-multipart-upload"></a>

Vous pouvez définir des options personnalisées sur les opérations `CreateMultipartUpload`, `UploadPart` et `CompleteMultipartUpload` exécutées par le programme de chargement partitionné via des rappels transmis à son constructeur.

 **Importations** 

```
require 'vendor/autoload.php';

use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **Exemple de code** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

// Customizing a multipart upload
$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
    'before_initiate' => function (Command $command) {
        // $command is a CreateMultipartUpload operation
        $command['CacheControl'] = 'max-age=3600';
    },
    'before_upload' => function (Command $command) {
        // $command is an UploadPart operation
        $command['RequestPayer'] = 'requester';
    },
    'before_complete' => function (Command $command) {
        // $command is a CompleteMultipartUpload operation
        $command['RequestPayer'] = 'requester';
    },
]);
```

### Collecte manuelle des déchets entre les chargements partiels
<a name="manual-garbage-collection-between-part-uploads"></a>

Si vous atteignez la limite de mémoire lors de chargements volumineux, c'est peut-être parce que des références cycliques générées par le kit SDK n'ont pas encore été traitées par le [nettoyage de mémoire de PHP](https://www.php.net/manual/en/features.gc.php). L'appel manuel de l'algorithme de nettoyage entre les opérations peut permettre le traitement des cycles avant que cette limite ne soit atteinte. L'exemple suivant appelle l'algorithme de nettoyage en utilisant un rappel avant le chargement de chaque partie. Notez que l'appel du nettoyage de mémoire représente un coût en termes de performances, et que l'utilisation optimale dépendra de votre cas d'utilisation et de l'environnement.

```
$uploader = new MultipartUploader($client, $source, [
   'bucket' => 'your-bucket',
   'key' => 'your-key',
   'before_upload' => function(\Aws\Command $command) {
      gc_collect_cycles();
   }
]);
```

## Récupération après des erreurs
<a name="recovering-from-errors"></a>

Lorsqu'une erreur se produit au cours du processus de chargement partitionné, une exception `MultipartUploadException` est levée. Cette exception donne accès à l'objet `UploadState`, qui contient des informations sur la progression du chargement partitionné. L'objet `UploadState` peut être utilisé pour reprendre un chargement qui n'a pas pu aboutir.

 **Importations** 

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **Exemple de code** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

//Recover from errors
do {
    try {
        $result = $uploader->upload();
    } catch (MultipartUploadException $e) {
        $uploader = new MultipartUploader($s3Client, $source, [
            'state' => $e->getState(),
        ]);
    }
} while (!isset($result));

//Abort a multipart upload if failed
try {
    $result = $uploader->upload();
} catch (MultipartUploadException $e) {
    // State contains the "Bucket", "Key", and "UploadId"
    $params = $e->getState()->getId();
    $result = $s3Client->abortMultipartUpload($params);
}
```

Reprendre un chargement à partir d'un objet `UploadState` permet de tenter de charger les parties qui n'ont pas encore été chargées. L'objet d'état assure le suivi des parties manquantes, même si elles ne se suivent pas. Le chargeur lit ou recherche dans le fichier source fourni les plages d'octets appartenant aux parties qui n'ont pas encore été chargées.

 Les objets `UploadState` étant sérialisables, vous pouvez également reprendre un chargement dans un processus différent. De plus, vous pouvez récupérer l'objet `UploadState`, même en l'absence d'exception, en appelant la méthode `$uploader->getState()`.

**Important**  
Les flux transmis comme source à un `MultipartUploader` ne sont pas automatiquement rembobinés avant le chargement. Si vous utilisez un flux à la place d'un chemin d'accès dans une boucle similaire à celle de l'exemple précédent, réinitialisez la variable `$source` à l'intérieur du bloc `catch`.

 **Importations** 

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **Exemple de code** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

//Using stream instead of file path
$source = fopen('/path/to/large/file.zip', 'rb');
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

do {
    try {
        $result = $uploader->upload();
    } catch (MultipartUploadException $e) {
        rewind($source);
        $uploader = new MultipartUploader($s3Client, $source, [
            'state' => $e->getState(),
        ]);
    }
} while (!isset($result));
fclose($source);
```

### Interruption d’un chargement partitionné
<a name="aborting-a-multipart-upload"></a>

Un chargement partitionné peut être interrompu en récupérant le `UploadId` contenu dans l'objet `UploadState` et en le trnasmettant à `abortMultipartUpload`.

```
try {
    $result = $uploader->upload();
} catch (MultipartUploadException $e) {
    // State contains the "Bucket", "Key", and "UploadId"
    $params = $e->getState()->getId();
    $result = $s3Client->abortMultipartUpload($params);
}
```

## Chargements partitionnés asynchrones
<a name="asynchronous-multipart-uploads"></a>

Appeler `upload()` sur le `MultipartUploader` constitue une demande de blocage. Si vous travaillez dans un contexte asynchrone, vous pouvez obtenir une [promesse](guide_promises.md) pour le chargement partitionné.

```
require 'vendor/autoload.php';

use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```

 **Exemple de code** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

$promise = $uploader->promise();
```

### Configuration
<a name="asynchronous-multipart-uploads-configuration"></a>

Le constructeur de l'objet `MultipartUploader` accepte les arguments suivants :

** `$client` **  
L'objet `Aws\ClientInterface` à utiliser pour effectuer les transferts. Il doit s'agir d'une instance de `Aws\S3\S3Client`.

** `$source` **  
Les données source concernées par le chargement. Il peut s'agir d'un chemin d'accès ou d'une URL (par exemple, `/path/to/file.jpg`), d'un gestionnaire de ressources (par exemple, `fopen('/path/to/file.jpg', 'r)`) ou d'une instance d'un [flux PSR-7](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Psr.Http.Message.StreamInterface.html).

** `$config` **  
Un tableau associatif d'options de configuration pour le chargement partitionné.  
Les options de configuration suivantes sont valides :    
** `acl` **  
(`string`) Liste de contrôle d'accès (ACL) à définir sur l'objet concerné par le chargement. Les objets sont privés par défaut.  
** `before_complete` **  
(`callable`) Rappel à invoquer avant l'opération `CompleteMultipartUpload`. Les rappels doivent avoir une signature de fonction telle que `function (Aws\Command $command) {...}`.  
** `before_initiate` **  
(`callable`) Rappel à invoquer avant l'opération `CreateMultipartUpload`. Les rappels doivent avoir une signature de fonction telle que `function (Aws\Command $command) {...}`.  
** `before_upload` **  
(`callable`) Rappel à invoquer avant toute opération `UploadPart`. Les rappels doivent avoir une signature de fonction telle que `function (Aws\Command $command) {...}`.  
** `bucket` **  
(`string`, *obligatoire*) Nom du compartiment vers lequel l’objet est chargé.  
** `concurrency` **  
(`int`, *par défaut* : `int(5)`) Nombre maximal d’opérations `UploadPart` simultanées autorisées pendant le chargement partitionné.  
** `key` **  
(`string`, *obligatoire*) Clé à utiliser pour l’objet concerné par le chargement.  
** `part_size` **  
(`int`, *par défaut* : `int(5242880)`) Taille de partie, en octets, à utiliser lors d’un chargement partitionné. Doit être comprise entre 5 Mo et 5 Go (inclus).  
** `state` **  
(`Aws\Multipart\UploadState`) Objet représentant l'état du chargement partitionné et utilisé pour reprendre un chargement précédent. Lorsque cette option est fournie, les options `bucket`, `key` et `part_size` sont ignorées.  
**`add_content_md5`**  
(`boolean`) Réglez sur true pour calculer automatiquement la MD5 somme de contrôle pour le téléchargement.  
**`params`**  
Tableau associatif qui fournit des options de configuration pour chaque sous-commande. Par exemple :  

```
new MultipartUploader($client, $source, ['params' => ['CacheControl' => {{<some_value>}}]])
```

## Copies en plusieurs parties
<a name="multipart-copies"></a>

 AWS SDK pour PHP Il inclut également un `MultipartCopy` objet qui est utilisé de la même manière que le`MultipartUploader`, mais qui est conçu pour copier des objets d'une taille comprise entre 5 Go et 5 To dans Amazon S3.

```
require 'vendor/autoload.php';

use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartCopy;
use Aws\S3\S3Client;
```

 **Exemple de code** 

```
// Create an S3Client
$s3Client = new S3Client([
    'profile' => 'default',
    'region' => 'us-west-2',
    'version' => '2006-03-01'
]);

//Copy objects within S3
$copier = new MultipartCopy($s3Client, '/bucket/key?versionId=foo', [
    'bucket' => 'your-bucket',
    'key' => 'my-file.zip',
]);

try {
    $result = $copier->copy();
    echo "Copy complete: {$result['ObjectURL']}\n";
} catch (MultipartUploadException $e) {
    echo $e->getMessage() . "\n";
}
```