Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Uso de cargas multiparte de Amazon S3 con la versión 3 de AWS SDK for PHP

Puede cargar objetos de hasta 5 GB en una única operación PutObject. Sin embargo, si utiliza los métodos de carga multiparte (por ejemplo, CreateMultipartUpload, UploadPart, CompleteMultipartUpload, AbortMultipartUpload), podrá cargar objetos de entre 5 MB y 5 TB.

El siguiente ejemplo muestra cómo:

Todo el código de ejemplo para el AWS SDK for PHP está disponible aquí en GitHub.

Credenciales

Antes de ejecutar el código de ejemplo, configure sus credenciales de AWS, como se indica en Credentials. A continuación, importe AWS SDK for PHP, como se indica en Uso básico.

Cargador de objetos

Si no está seguro de si PutObject o MultipartUploader es mejor opción para la tarea, utilice ObjectUploader. ObjectUploader carga un archivo de gran tamaño a Amazon S3 utilizando PutObject o MultipartUploader, en función de lo que sea mejor para el tamaño de la carga.

require 'vendor/autoload.php';

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

Código de muestra

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

Configuración

El constructor del objeto ObjectUploader acepta los siguientes argumentos:

MultipartUploader

Las cargas multiparte están diseñadas para mejorar la experiencia de carga de los objetos más grandes. Estas permiten cargar objetos en partes independientes, en cualquier orden y en paralelo.

Se recomienda a los clientes de Amazon S3 que utilicen cargas multiparte para objetos de más de 100 MB.

MultipartUploader objeto

El SDK tiene un objeto MultipartUploader especial que simplifica el proceso de carga multiparte.

Importaciones

require 'vendor/autoload.php';

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

Código de muestra

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

El cargador crea un generador de datos de la parte, en función del origen que se haya proporcionado y de la configuración, e intenta cargar todas las partes. Si falla la carga de algunas partes, el cargador continúa cargando otras partes hasta que se haya leído todo el origen de datos. A continuación, el cargador vuelve a intentar cargar las partes que han dado error o genera una excepción que contiene información acerca de las partes que no se han podido cargar.

Personalización de una carga multiparte

Puede configurar las opciones personalizadas en las operaciones CreateMultipartUpload, UploadPart y CompleteMultipartUpload ejecutadas por el cargador multiparte mediante devoluciones de llamada transferidas a su constructor.

Importaciones

require 'vendor/autoload.php';

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

Código de muestra

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

Recopilación manual de elementos no utilizados entre cargas de partes

Si se alcanza el límite de memoria al realizar cargas de gran tamaño, puede deberse a las referencias cíclicas generadas por el SDK que el recolector de elementos no utilizados de PHP todavía no había recopilado cuando se alcanzó el límite de memoria. Si se invoca manualmente el algoritmo de recopilación entre las operaciones, es posible que los ciclos se recopilen antes de alcanzar dicho límite. En el siguiente ejemplo, se invoca el algoritmo de recopilación mediante una devolución de llamada antes de la carga de cada parte. Tenga en cuenta que invocar el recolector de elementos no utilizados conlleva un costo de rendimiento y su uso óptimo dependerá de su caso de uso y su entorno.

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

Recuperación tras sufrir errores

Cuando se produce un error durante el proceso de carga multiparte, se lanza una excepción MultipartUploadException. Esta excepción proporciona acceso al objeto UploadState, que contiene información sobre el progreso de la carga multiparte. El objeto UploadState puede utilizarse para reanudar una carga que no se ha completado.

Importaciones

require 'vendor/autoload.php';

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

Código de muestra

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

Si se reanuda una carga a partir de un objeto UploadState, se intenta cargar las partes que todavía no se han cargado. El objeto de estado realiza un seguimiento de las partes que faltan, aunque no sean consecutivas. El cargador lee o busca en el archivo de origen facilitado los rangos de bytes que pertenecen a las partes que todavía deben cargarse.

Los objetos UploadState se pueden serializar, por lo que también puede reanudar una carga en un proceso diferente. También puede obtener el objeto UploadState, incluso si no gestiona una excepción, llamando a $uploader->getState().

Importaciones

require 'vendor/autoload.php';

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

Código de muestra

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

Anulación de la carga multiparte

Una carga multiparte se puede anular al recuperar el UploadId que se encuentra en el objeto UploadState y transferirlo a abortMultipartUpload.

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

Cargas multiparte asíncronas

Llamar a upload() en el MultipartUploader es una solicitud de bloqueo. Si está trabajando en un contexto asíncrono, puede obtener una promesa para la carga multiparte.

require 'vendor/autoload.php';

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

Código de muestra

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

Configuración

El constructor del objeto MultipartUploader acepta los siguientes argumentos:

Copias multiparte

El AWS SDK for PHP también incluye un objeto MultipartCopy que se utiliza de forma similar al MultipartUploader, pero está diseñado para copiar objetos de entre 5 GB y 5 TB en Amazon S3.

require 'vendor/autoload.php';

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

Código de muestra

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