Utilizzo dei caricamenti multiparte di Amazon S3 con la versione 3 AWS SDK for PHP - AWS SDK for PHP
CredenzialiCaricatore di oggettiMultipartUploaderMultipartUploader oggettoPersonalizzazione di un caricamento in più partiRipristino da erroriCaricamenti asincroni multiparteCopie in più parti

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

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

  • Crea un caricamento multiparte per un oggetto Amazon S3 utilizzando. MultipartUploader

  • Copia oggetti da una posizione Amazon S3 a un'altra utilizzando. ObjectCopier

Tutto il codice di esempio per AWS SDK for PHP è disponibile qui. GitHub

Credenziali

Prima di eseguire il codice di esempio, configurate AWS le vostre credenziali, come descritto inCredenziali. Quindi importate il fileAWS SDK for PHP, come descritto inUtilizzo di base.

Caricatore di oggetti

Se non sei sicuro che MultipartUploader sia PutObject o meno la soluzione migliore per l'attività, usaObjectUploader. ObjectUploadercarica un file di grandi dimensioni su Amazon S3 utilizzando PutObject uno dei due MultipartUploader o, a seconda di ciò che è meglio 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

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 checksum MD5 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) {...}

before_initiate

(callable) Callback da richiamare prima dell'operazione CreateMultipartUpload. Il callback dovrebbe avere una firma di funzione simile a:. function (Aws\Command $command) {...}

before_upload

(callable) Richiamata da richiamare prima di qualsiasi PutObject operazione. UploadPart Il callback dovrebbe avere una firma di funzione simile a:. function (Aws\Command $command) {...}

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_sizeopzione vengono ignorati.

MultipartUploader

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

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

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

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 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();
   }
]);

Ripristino da errori

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

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

La chiamata di upload() sul MultipartUploader corrisponde a una richiesta di blocco. Se stai lavorando in un contesto asincrono, potresti ricevere una promessa 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

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.

$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 MD5 per il caricamento.

Copie in più parti

Include AWS SDK for PHP anche un MultipartCopy oggetto che viene utilizzato in modo simile aMultipartUploader, 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";
}