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 AWS SDK para PHP la versión 3
<a name="s3-multipart-upload"></a>

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:
+ Cargue un objeto en Amazon S3 mediante [ObjectUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectUploader.html).
+ Cree una carga multiparte para un objeto de Amazon S3 mediante [MultipartUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.MultipartUploader.html).
+ Copie objetos de una ubicación de Amazon S3 a otra utilizando [ObjectCopier](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectCopier.html).

Todo el código de ejemplo para el AWS SDK para PHP está disponible [aquí en GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).

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

Antes de ejecutar el código de ejemplo, configure sus AWS credenciales, tal y como se describe en[Autenticación AWS con la AWS SDK para PHP versión 3](credentials.md). A continuación, importe las AWS SDK para PHP, tal y como se describe en[Instalación de la AWS SDK para PHP versión 3](getting-started_installation.md).

## Cargador de objetos
<a name="object-uploader"></a>

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 en Amazon S3 utilizando `PutObject` o `MultipartUploader`, en función del tamaño de la carga útil.

```
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
<a name="object-uploader-configuration"></a>

El constructor del objeto `ObjectUploader` acepta los siguientes argumentos:

**`$client`**  
Es el objeto `Aws\ClientInterface` que hay que utilizar para ejecutar las transferencias. Debería ser una instancia de `Aws\S3\S3Client`.

**`$bucket`**  
(`string`, *obligatorio*) Es el nombre del bucket al que se está cargando el objeto.

**`$key`**  
(`string`, *obligatorio*) Es la clave que se utiliza para el objeto que se está cargando.

**`$body`**  
(`mixed`, *obligatorio*) Datos del objeto que se van a cargar. Puede ser un `StreamInterface`, un recurso de flujo de PH, o una cadena de datos a cargar.

**`$acl`**  
(`string`) Es la lista de control de acceso (ACL) para establecer el objeto que se carga. De forma predeterminada, los objetos son privados.

**`$options`**  
Es una matriz asociativa de opciones de configuración para la carga multiparte. Las siguientes opciones de configuración son válidas:    
**`add_content_md5`**  
(`bool`) Configúrelo en true para calcular automáticamente la MD5 suma de verificación de la carga.  
**`mup_threshold`**  
(`int`, *predeterminado*:`int(16777216)`) El número de bytes del tamaño del archivo. Si el tamaño del archivo supera este límite, se utiliza una carga multiparte.  
**`before_complete`**  
(`callable`) Es la devolución de llamada a invocar antes de la operación `CompleteMultipartUpload`. La devolución de llamada debe tener una firma de función similar a: `function (Aws\Command $command) {...}`. Consulta la [referencia de la CompleteMultipartUpload API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#completemultipartupload) para ver los parámetros que puedes añadir al `CommandInterface` objeto.  
**`before_initiate`**  
(`callable`) Es la devolución de llamada a invocar antes de la operación `CreateMultipartUpload`. La devolución de llamada debe tener una firma de función similar a: `function (Aws\Command $command) {...}`. El SDK invoca esta devolución de llamada si el tamaño del archivo supera el valor de `mup_threshold`. Consulta la [referencia de la CreateMultipartUpload API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#createmultipartupload) para ver los parámetros que puedes añadir al `CommandInterface` objeto.  
**`before_upload`**  
(`callable`) Es la devolución de llamada a invocar antes de cualquier operación `PutObject` o `UploadPart`. La devolución de llamada debe tener una firma de función similar a: `function (Aws\Command $command) {...}`. El SDK invoca esta devolución de llamada si el tamaño del archivo es igual o mayor que el valor de `mup_threshold`. Consulta la [referencia de la PutObject API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) para ver los parámetros que puedes aplicar a la `PutObject` solicitud. Para ver los parámetros que se aplican a una `UploadPart` solicitud, consulta la [referencia de la UploadPart API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#uploadpart). El SDK ignora cualquier parámetro que no sea aplicable a la operación representada por el objeto `CommandInterface`.  
**`concurrency`**  
(`int`, *predeterminado*: `int(3)`) Es el número máximo de operaciones `UploadPart` simultáneas permitido durante la carga multiparte.  
**`part_size`**  
(`int`, *predeterminado*: `int(5242880)`) Es el tamaño de la parte, en bytes, que se debe utilizar al realizar una carga multiparte. El valor debe estar comprendido entre 5 MB y 5 GB, ambos incluidos.  
**`state`**  
(`Aws\Multipart\UploadState`) Es un objeto que representa el estado de la carga multiparte y que se utiliza para reanudar una carga previa. Si se proporciona esta opción, se ignoran los argumentos `$bucket` y `$key` arguments y la opción `part_size`.  
**`params`**  
Una matriz asociativa que proporciona opciones de configuración para cada subcomando. Por ejemplo:  

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

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

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
<a name="multipartuploader-object"></a>

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
<a name="customizing-a-multipart-upload"></a>

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
<a name="manual-garbage-collection-between-part-uploads"></a>

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](https://www.php.net/manual/en/features.gc.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
<a name="recovering-from-errors"></a>

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()`.

**importante**  
Los flujos que se transfieren como un origen a un `MultipartUploader` no se rebobinan automáticamente antes de cargarlos. Si utiliza un flujo en lugar de una ruta de archivo en un bucle similar al del ejemplo anterior, restablezca la variable `$source` dentro del bloque `catch`.

 **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
<a name="aborting-a-multipart-upload"></a>

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
<a name="asynchronous-multipart-uploads"></a>

Llamar a `upload()` en el `MultipartUploader` es una solicitud de bloqueo. Si está trabajando en un contexto asíncrono, puede obtener una [promesa](guide_promises.md) 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
<a name="asynchronous-multipart-uploads-configuration"></a>

El constructor del objeto `MultipartUploader` acepta los siguientes argumentos:

** `$client` **  
Es el objeto `Aws\ClientInterface` que hay que utilizar para ejecutar las transferencias. Debería ser una instancia de `Aws\S3\S3Client`.

** `$source` **  
Son los datos de origen que se están cargando. Esto puede ser una ruta o una URL (por ejemplo, `/path/to/file.jpg`), un controlador de recursos (por ejemplo, `fopen('/path/to/file.jpg', 'r)`) o una instancia de un [flujo PSR-7](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Psr.Http.Message.StreamInterface.html).

** `$config` **  
Es una matriz asociativa de opciones de configuración para la carga multiparte.  
Las siguientes opciones de configuración son válidas:    
** `acl` **  
(`string`) Es la lista de control de acceso (ACL) para establecer el objeto que se carga. De forma predeterminada, los objetos son privados.  
** `before_complete` **  
(`callable`) Es la devolución de llamada a invocar antes de la operación `CompleteMultipartUpload`. La devolución de llamada debería tener una firma de la función del tipo `function (Aws\Command $command) {...}`.  
** `before_initiate` **  
(`callable`) Es la devolución de llamada a invocar antes de la operación `CreateMultipartUpload`. La devolución de llamada debería tener una firma de la función del tipo `function (Aws\Command $command) {...}`.  
** `before_upload` **  
(`callable`) Es la devolución de llamada a invocar antes de cualquier operación `UploadPart`. La devolución de llamada debería tener una firma de la función del tipo `function (Aws\Command $command) {...}`.  
** `bucket` **  
(`string`, *obligatorio*) Es el nombre del bucket al que se está cargando el objeto.  
** `concurrency` **  
(`int`, *predeterminado*: `int(5)`) Es el número máximo de operaciones `UploadPart` simultáneas permitido durante la carga multiparte.  
** `key` **  
(`string`, *obligatorio*) Es la clave que se utiliza para el objeto que se está cargando.  
** `part_size` **  
(`int`, *predeterminado*: `int(5242880)`) Es el tamaño de la parte, en bytes, que se debe utilizar al realizar una carga multiparte. Debe ser de entre 5 MB y 5 GB, ambos incluidos.  
** `state` **  
(`Aws\Multipart\UploadState`) Es un objeto que representa el estado de la carga multiparte y que se utiliza para reanudar una carga previa. Si se proporciona esta opción, se omiten las opciones `bucket`, `key` y `part_size`.  
**`add_content_md5`**  
(`boolean`) Configúrelo en true para calcular automáticamente la MD5 suma de verificación de la carga.  
**`params`**  
Una matriz asociativa que proporciona opciones de configuración para cada subcomando. Por ejemplo:  

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

## Copias multiparte
<a name="multipart-copies"></a>

 AWS SDK para PHP También incluye un `MultipartCopy` objeto que se utiliza de forma similar al`MultipartUploader`, pero que está diseñado para copiar objetos de entre 5 GB y 5 TB de tamaño 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";
}
```