Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Utilizzo dei caricamenti multiparte di Amazon S3 con la versione 3 AWS SDK per PHP
<a name="s3-multipart-upload"></a>

Con una singola operazione `PutObject`, puoi caricare oggetti di una dimensione massima di 5 GB. Tuttavia, tramite i metodi di caricamento in più parti (ad esempio, `CreateMultipartUpload`, `UploadPart`, `CompleteMultipartUpload`, `AbortMultipartUpload`), puoi caricare oggetti di dimensioni comprese tra 5 MB e 5 TB.

Gli esempi seguenti mostrano come:
+ Carica un oggetto su Amazon S3, utilizzando. [ObjectUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectUploader.html)
+ Crea un caricamento multiparte per un oggetto Amazon S3 utilizzando. [MultipartUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.MultipartUploader.html)
+ Copia oggetti da una posizione Amazon S3 a un'altra utilizzando. [ObjectCopier](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectCopier.html)

Tutto il codice di esempio per AWS SDK per PHP è disponibile [qui](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code). GitHub

## Credenziali
<a name="examplecredentials"></a>

Prima di eseguire il codice di esempio, configurate AWS le vostre credenziali, come descritto in[Autenticazione con l' AWS utilizzo AWS SDK per PHP della versione 3](credentials.md). Quindi importate il file AWS SDK per PHP, come descritto in[Installazione della AWS SDK per PHP versione 3](getting-started_installation.md).

## Caricatore di oggetti
<a name="object-uploader"></a>

Se non sei sicuro che sia `PutObject` o `MultipartUploader` meno la soluzione migliore per l'attività, usa. `ObjectUploader` `ObjectUploader`carica un file di grandi dimensioni su Amazon S3 utilizzando `PutObject` `MultipartUploader` o, in base alla dimensione del payload.

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

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

 **Codice di esempio** 

```
// 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);
```

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

Il costruttore dell'oggetto `ObjectUploader` accetta i seguenti argomenti:

**`$client`**  
L'oggetto `Aws\ClientInterface` da utilizzare per eseguire i trasferimenti. Deve essere un'istanza di `Aws\S3\S3Client`.

**`$bucket`**  
(`string`, *obbligatorio*) Nome del bucket in cui è in corso il caricamento dell'oggetto.

**`$key`**  
(`string`, *obbligatorio*) Chiave da utilizzare per l'oggetto in fase di caricamento.

**`$body`**  
(`mixed`, *obbligatorio*) Dati dell'oggetto da caricare. Può essere una `StreamInterface` risorsa di flusso PHP o una stringa di dati da caricare.

**`$acl`**  
(`string`) Lista di controllo accessi (ACL) da impostare sull'oggetto in fase di caricamento. Gli oggetti sono privati per impostazione predefinita.

**`$options`**  
Un array associativo delle opzioni di configurazione del caricamento in più parti. Le seguenti opzioni di configurazione sono valide:    
**`add_content_md5`**  
(`bool`) Imposta su true per calcolare automaticamente il MD5 checksum per il caricamento.  
**`mup_threshold`**  
(`int`, *impostazione predefinita*:`int(16777216)`) Il numero di byte per la dimensione del file. Se la dimensione del file supera questo limite, viene utilizzato un caricamento in più parti.  
**`before_complete`**  
(`callable`) Callback da richiamare prima dell'operazione `CompleteMultipartUpload`. Il callback dovrebbe avere una firma di funzione simile a:. `function (Aws\Command $command) {...}` Consulta il [riferimento CompleteMultipartUpload API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#completemultipartupload) per i parametri che puoi aggiungere all'`CommandInterface`oggetto.  
**`before_initiate`**  
(`callable`) Callback da richiamare prima dell'operazione `CreateMultipartUpload`. Il callback dovrebbe avere una firma di funzione simile a:`function (Aws\Command $command) {...}`. L'SDK richiama questo callback se la dimensione del file supera il valore. `mup_threshold` Consulta il [riferimento all'CreateMultipartUpload API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#createmultipartupload) per i parametri che puoi aggiungere all'oggetto. `CommandInterface`  
**`before_upload`**  
(`callable`) Richiamata da richiamare prima di `PutObject` qualsiasi `UploadPart` operazione. Il callback dovrebbe avere una firma di funzione simile a:. `function (Aws\Command $command) {...}` L'SDK richiama questo callback se la dimensione del file è inferiore o uguale al valore. `mup_threshold` Consulta il [riferimento all'PutObject API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) per i parametri che puoi applicare alla richiesta. `PutObject` Per i parametri che si applicano a una `UploadPart` richiesta, consulta il [riferimento all'UploadPart API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#uploadpart). L'SDK ignora qualsiasi parametro non applicabile all'operazione rappresentata dall'`CommandInterface`oggetto.  
**`concurrency`**  
(`int`, *impostazione predefinita*: `int(3)`) Numero massimo di operazioni `UploadPart` simultanee consentite durante il caricamento in più parti.  
**`part_size`**  
(`int`, *impostazione predefinita*: `int(5242880)`) Dimensioni, in byte, della parte da utilizzare durante il caricamento in più parti. Il valore deve essere compreso tra 5 MB e 5 GB, inclusi.  
**`state`**  
(`Aws\Multipart\UploadState`) Un oggetto che rappresenta lo stato del caricamento in più parti e che viene utilizzato per riprendere un caricamento precedente. Quando viene fornita questa opzione, gli `$key` argomenti `$bucket` and e l'`part_size`opzione vengono ignorati.  
**`params`**  
Un array associativo che fornisce opzioni di configurazione per ogni sottocomando. Esempio:  

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

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

I caricamenti in più parti sono concepiti per migliorare l'esperienza di caricamento degli oggetti di maggiori dimensioni. Consentono di caricare gli oggetti in parti indipendenti, in qualsiasi ordine e in parallelo.

I clienti di Amazon S3 sono incoraggiati a utilizzare caricamenti multiparte per oggetti di dimensioni superiori a 100 MB.

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

L'SDK contiene un oggetto `MultipartUploader` speciale che semplifica il processo di caricamento in più parti.

 **Importazioni** 

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

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

 **Codice di esempio** 

```
$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";
}
```

L'uploader crea un generatore di dati della parte, basato sulla sorgente e sulla configurazione specificate, e tenta di caricare tutte le parti. Se il caricamento di alcune parti non riesce, l'uploader continua con il caricamento delle parti successive fino a quando non vengono letti tutti i dati di origine. Successivamente, l'uploader riprova a caricare le parti non riuscite o genera un'eccezione contenente informazioni sulle parti che non è stato possibile caricare.

## Personalizzazione di un caricamento in più parti
<a name="customizing-a-multipart-upload"></a>

Puoi impostare opzioni personalizzate nelle operazioni `CreateMultipartUpload`, `UploadPart` e `CompleteMultipartUpload` eseguite dall'uploader in più parti tramite i callback trasmessi al relativo costruttore.

 **Importazioni** 

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

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

 **Codice di esempio** 

```
// 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';
    },
]);
```

### Raccolta manuale dei rifiuti tra i caricamenti delle parti
<a name="manual-garbage-collection-between-part-uploads"></a>

Se caricamenti di grandi dimensioni causano il raggiungimento del limite di memoria, la causa è da ricercarsi nei riferimenti ciclici generati dall'SDK che non sono ancora stati raccolti dal [garbage collector PHP](https://www.php.net/manual/en/features.gc.php) quando il limite di memoria è stato raggiunto. L'invocazione manuale dell'algoritmo di raccolta tra operazioni può consentire la raccolta dei cicli prima del raggiungimento di tale limite. L'esempio seguente richiama l'algoritmo di raccolta utilizzando un callback prima del caricamento di ogni parte. L'invocazione di garbage collector comporta costi di prestazioni e l'uso ottimale dipende dal caso d'uso e dall'ambiente.

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

## Recupero da errori
<a name="recovering-from-errors"></a>

Quando si verifica un errore durante il processo di caricamento in più parti, viene generata una `MultipartUploadException`. Questa eccezione consente l'accesso all'oggetto `UploadState`, contenente le informazioni sull'avanzamento del caricamento in più parti. L'oggetto `UploadState` può essere utilizzato per riprendere un caricamento che non è stato possibile completare.

 **Importazioni** 

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

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

 **Codice di esempio** 

```
// 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);
}
```

La ripresa di un caricamento da un oggetto `UploadState` tenta di caricare le parti che non sono già state caricate. L'oggetto stato tiene traccia delle parti mancanti, anche se non sono consecutive. L'uploader legge o cerca nel file sorgente fornito negli intervalli di byte appartenenti alle parti che devono ancora essere caricate.

 Gli oggetti `UploadState` sono serializzabili, quindi puoi riprendere un caricamento anche in un processo diverso. Puoi ottenere inoltre l'oggetto `UploadState`, anche quando non stai gestendo un'eccezione, richiamando `$uploader->getState()`.

**Importante**  
I flussi trasmessi come sorgente a `MultipartUploader` non vengono riavvolti automaticamente prima del caricamento. Se utilizzi un flusso al posto di un percorso di file in un loop simile a quello dell'esempio precedente, ripristina la variabile `$source` all'interno del blocco `catch`.

 **Importazioni** 

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

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

 **Codice di esempio** 

```
// 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);
```

### Interruzione di un caricamento in più parti
<a name="aborting-a-multipart-upload"></a>

Un caricamento in più parti può essere interrotto recuperando l'`UploadId` contenuto nell'oggetto `UploadState` e passandolo a `abortMultipartUpload`.

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

## Caricamenti asincroni multiparte
<a name="asynchronous-multipart-uploads"></a>

La chiamata di `upload()` sul `MultipartUploader` corrisponde a una richiesta di blocco. Se stai lavorando in un contesto asincrono, potresti ricevere una [promessa](guide_promises.md) per il caricamento in più parti.

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

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

 **Codice di esempio** 

```
// 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();
```

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

Il costruttore dell'oggetto `MultipartUploader` accetta i seguenti argomenti:

** `$client` **  
L'oggetto `Aws\ClientInterface` da utilizzare per eseguire i trasferimenti. Deve essere un'istanza di `Aws\S3\S3Client`.

** `$source` **  
I dati di origine in fase di caricamento. Può essere un percorso o un URL (ad esempio, `/path/to/file.jpg`), un gestore di risorse (ad esempio, `fopen('/path/to/file.jpg', 'r)`) o un'istanza di un [flusso PSR-7](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Psr.Http.Message.StreamInterface.html).

** `$config` **  
Un array associativo delle opzioni di configurazione del caricamento in più parti.  
Le seguenti opzioni di configurazione sono valide:    
** `acl` **  
(`string`) Lista di controllo accessi (ACL) da impostare sull'oggetto in fase di caricamento. Gli oggetti sono privati per impostazione predefinita.  
** `before_complete` **  
(`callable`) Callback da richiamare prima dell'operazione `CompleteMultipartUpload`. Il callback deve disporre di una firma della funzione, come `function (Aws\Command $command) {...}`.  
** `before_initiate` **  
(`callable`) Callback da richiamare prima dell'operazione `CreateMultipartUpload`. Il callback deve disporre di una firma della funzione, come `function (Aws\Command $command) {...}`.  
** `before_upload` **  
(`callable`) Callback da richiamare prima delle operazioni `UploadPart`. Il callback deve disporre di una firma della funzione, come `function (Aws\Command $command) {...}`.  
** `bucket` **  
(`string`, *obbligatorio*) Nome del bucket in cui è in corso il caricamento dell'oggetto.  
** `concurrency` **  
(`int`, *impostazione predefinita*: `int(5)`) Numero massimo di operazioni `UploadPart` simultanee consentite durante il caricamento in più parti.  
** `key` **  
(`string`, *obbligatorio*) Chiave da utilizzare per l'oggetto in fase di caricamento.  
** `part_size` **  
(`int`, *impostazione predefinita*: `int(5242880)`) Dimensioni, in byte, della parte da utilizzare durante il caricamento in più parti. Le dimensioni devono essere comprese tra 5 MB e 5 GB, inclusi.  
** `state` **  
(`Aws\Multipart\UploadState`) Un oggetto che rappresenta lo stato del caricamento in più parti e che viene utilizzato per riprendere un caricamento precedente. Quando questa opzione è disponibile, le opzioni `bucket`, `key` e `part_size` vengono ignorate.  
**`add_content_md5`**  
(`boolean`) Imposta su true per calcolare automaticamente il checksum per il MD5 caricamento.  
**`params`**  
Un array associativo che fornisce opzioni di configurazione per ogni sottocomando. Esempio:  

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

## Copie in più parti
<a name="multipart-copies"></a>

Include AWS SDK per PHP anche un `MultipartCopy` oggetto che viene utilizzato in modo simile a`MultipartUploader`, ma è progettato per copiare oggetti di dimensioni comprese tra 5 GB e 5 TB all'interno di Amazon S3.

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

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

 **Codice di esempio** 

```
// 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";
}
```