As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Usando uploads de várias partes do Amazon S3 com a versão 3 AWS SDK para PHP
<a name="s3-multipart-upload"></a>

Com uma única operação `PutObject`, você pode fazer upload de objetos de até 5 GB. No entanto, usando os métodos de multipart upload (por exemplo `CreateMultipartUpload`, `UploadPart`, `CompleteMultipartUpload`, `AbortMultipartUpload`), você pode fazer upload de objetos de 5 MB a 5 TB.

O exemplo a seguir mostra como:
+ Faça upload de um objeto para o Amazon S3, usando. [ObjectUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectUploader.html)
+ Crie um upload de várias partes para um objeto do Amazon S3 usando o. [MultipartUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.MultipartUploader.html)
+ Copie objetos de um local do Amazon S3 para outro usando. [ObjectCopier](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectCopier.html)

Todo o código de exemplo para o AWS SDK para PHP está disponível [aqui em GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).

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

Antes de executar o código de exemplo, configure suas AWS credenciais, conforme descrito em[Autenticando com o AWS uso da AWS SDK para PHP versão 3](credentials.md). Em seguida, importe o AWS SDK para PHP, conforme descrito em[Instalando a AWS SDK para PHP versão 3](getting-started_installation.md).

## Uploader de objeto
<a name="object-uploader"></a>

Se você não tiver certeza se `PutObject` ou `MultipartUploader` é melhor para a tarefa, use `ObjectUploader`. O `ObjectUploader` fará upload de um arquivo grande no Amazon S3 usando `PutObject` ou `MultipartUploader`, dependendo do tamanho da 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 exemplo** 

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

### Configuração
<a name="object-uploader-configuration"></a>

O construtor do objeto `ObjectUploader` aceita os seguintes argumentos:

**`$client`**  
O objeto `Aws\ClientInterface` a ser usado para executar as transferências. Deve ser uma instância de `Aws\S3\S3Client`.

**`$bucket`**  
(`string`, *obrigatório*) Nome do bucket para o qual o objeto está sendo enviado.

**`$key`**  
(`string`, *obrigatório*) Chave a ser usada para o objeto que está sendo enviado.

**`$body`**  
(`mixed`, *obrigatório*) Dados do objeto a serem carregados. Pode ser um `StreamInterface`, um recurso de fluxo de PHP ou uma string de dados a ser carregada.

**`$acl`**  
(`string`) Lista de controle de acesso (ACL) a ser definida no objeto que está sendo obtido por upload. Por padrão, os objetos são privados.

**`$options`**  
Uma matriz associativa de opções de configuração para o multipart upload. As seguintes opções de configuração são válidas:    
**`add_content_md5`**  
(`bool`) Defina como verdadeiro para calcular automaticamente a MD5 soma de verificação do upload.  
**`mup_threshold`**  
(`int`, *padrão*: `int(16777216)`) O número de bytes para o tamanho do arquivo. Se o tamanho do arquivo exceder esse limite, será usado um carregamento fracionado.  
**`before_complete`**  
(`callable`) Retorno de chamada a ser invocado antes da operação `CompleteMultipartUpload`. O retorno de chamada deve ter uma assinatura de função similar a: `function (Aws\Command $command) {...}`. Consulte a [referência CompleteMultipartUpload da API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#completemultipartupload) para ver os parâmetros que você pode adicionar ao `CommandInterface` objeto.  
**`before_initiate`**  
(`callable`) Retorno de chamada a ser invocado antes da operação `CreateMultipartUpload`. O retorno de chamada deve ter uma assinatura de função similar a: `function (Aws\Command $command) {...}`. O SDK invocará esse retorno de chamada se o tamanho do arquivo exceder o valor de `mup_threshold`. Consulte a [referência CreateMultipartUpload da API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#createmultipartupload) para ver os parâmetros que você pode adicionar ao `CommandInterface` objeto.  
**`before_upload`**  
(`callable`) Retorno de chamada a ser invocado antes de qualquer operação `PutObject` ou `UploadPart`. O retorno de chamada deve ter uma assinatura de função similar a: `function (Aws\Command $command) {...}`. O SDK invocará esse retorno de chamada se o tamanho do arquivo for inferior ou igual ao valor de `mup_threshold`. Consulte a [referência PutObject da API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) para ver os parâmetros que você pode aplicar à `PutObject` solicitação. Para os parâmetros que se aplicam a uma `UploadPart` solicitação, consulte a [referência UploadPart da API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#uploadpart). O SDK ignora qualquer parâmetro que não seja aplicável à operação representada pelo objeto `CommandInterface`.  
**`concurrency`**  
(`int`, *padrão*: `int(3)`) O número máximo de operações `UploadPart` simultâneas permitidas durante o multipart upload.  
**`part_size`**  
(`int`, *padrão*: `int(5242880)`) Tamanho da parte, em bytes, a ser usado ao fazer um multipart upload. Esse valor deve ser de 5 MB a 5 GB, inclusive.  
**`state`**  
(`Aws\Multipart\UploadState`) Um objeto que representa o estado do multipart upload e que é usado para retomar um upload anterior. Quando essa opção for fornecida, os argumentos `$bucket` e `$key` e a opção `part_size` serão ignoradas.  
**`params`**  
Uma matriz associativa que fornece opções de configuração para cada subcomando. Por exemplo:  

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

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

Os multipart uploads são projetados para melhorar a experiência de upload de objetos maiores. Eles permitem fazer upload de objetos em partes independentemente, em qualquer ordem e em paralelo.

Os clientes do Amazon S3 são incentivados a usar os carregamentos fracionados para objetos maiores que 100 MB.

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

O SDK tem um objeto `MultipartUploader` especial que simplifica o processo de multipart upload.

 **Importações** 

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

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

 **Código de exemplo** 

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

O carregador cria um gerador de dados da parte, com base na origem fornecida e na configuração e tenta fazer upload de todas as partes. Se houver falha em alguma parte do upload, o uploader continuará a fazer upload das partes até que todos os dados de origem tenham sido lidos. Posteriormente, o uploader tentará novamente fazer upload das partes com falha ou lançará uma exceção que contém informações sobre as partes com falha de upload.

## Personalização de um carregamento fracionado
<a name="customizing-a-multipart-upload"></a>

Você pode definir opções personalizadas nas operações `CreateMultipartUpload`, `UploadPart` e `CompleteMultipartUpload` executadas pelo multipart uploader por meio de retornos de chamada passados para o construtor.

 **Importações** 

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

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

 **Código de exemplo** 

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

### Coleta de resíduos manual entre carregamentos de partes
<a name="manual-garbage-collection-between-part-uploads"></a>

Se você atingir o limite de memória com grandes uploads, isso pode ser devido a referências cíclicas geradas pelo SDK ainda não terem sido coletadas pelo [coletor de lixo do PHP](https://www.php.net/manual/en/features.gc.php) quando o limite de memória foi atingido. Invocar manualmente o algoritmo de coleta entre operações pode permitir que os ciclos sejam coletados antes que esse limite seja atingido. O exemplo a seguir que invoca o algoritmo de coleta usando um retorno de chamada antes de fazer upload de cada parte. Observe que a invocação do coletor de lixo não vêm com um custo de desempenho e o uso ideal dependerá do seu caso de uso e do ambiente.

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

## Recuperação de erros
<a name="recovering-from-errors"></a>

Quando ocorre um erro durante o processo de multipart upload, é lançada uma `MultipartUploadException`. Essa exceção fornece acesso ao objeto `UploadState`, que contém informações sobre o andamento do multipart upload. O `UploadState` pode ser usado para retomar um upload que não foi concluído.

 **Importações** 

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

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

 **Código de exemplo** 

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

A retomada de um upload de um `UploadState` tenta fazer upload das partes que ainda não foram obtidas por upload. O objeto de estado rastreia a partes ausentes, mesmo que sejam consecutivas. O uploader lê ou procura no arquivo de origem fornecido os intervalos de bytes que pertencem às partes que ainda precisam ser obtidas por upload.

 Os objetos `UploadState` são serializáveis, portanto, você também pode retomar um upload em um outro processo. Você também pode obter o objeto `UploadState`, mesmo quando não estiver tratando de uma exceção, chamando `$uploader->getState()`.

**Importante**  
Streams passados como uma origem para um `MultipartUploader` não são automaticamente retrocedidos antes do upload. Se estiver usando um stream em vez de um caminho de arquivo em um loop semelhante ao exemplo anterior, será necessário redefinir a variável `$source` dentro do bloco `catch`.

 **Importações** 

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

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

 **Código de exemplo** 

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

### Abortar um multipart upload
<a name="aborting-a-multipart-upload"></a>

Um multipart upload pode ser anulado recuperando o `UploadId` contido no objeto `UploadState` e passando-o para `abortMultipartUpload`.

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

## Carregamentos fracionados assíncronos
<a name="asynchronous-multipart-uploads"></a>

Chamar `upload()` no `MultipartUploader` é uma solicitação de bloqueio. Se estiver trabalhando em um contexto assíncrono, você poderá obter uma [promessa](guide_promises.md) para o multipart upload.

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

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

 **Código de exemplo** 

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

### Configuração
<a name="asynchronous-multipart-uploads-configuration"></a>

O construtor do objeto `MultipartUploader` aceita os seguintes argumentos:

** `$client` **  
O objeto `Aws\ClientInterface` a ser usado para executar as transferências. Deve ser uma instância de `Aws\S3\S3Client`.

** `$source` **  
A origem dos dados que estão sendo carregados. Isso pode ser um caminho ou um URL (por exemplo, `/path/to/file.jpg`), um identificador de recurso (por exemplo, `fopen('/path/to/file.jpg', 'r)`) ou uma instância de um [stream PSR-7](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Psr.Http.Message.StreamInterface.html).

** `$config` **  
Uma matriz associativa de opções de configuração para o multipart upload.  
As seguintes opções de configuração são válidas:    
** `acl` **  
(`string`) Lista de controle de acesso (ACL) a ser definida no objeto que está sendo obtido por upload. Por padrão, os objetos são privados.  
** `before_complete` **  
(`callable`) Retorno de chamada a ser invocado antes da operação `CompleteMultipartUpload`. O retorno de chamada deve ter uma assinatura de função como `function (Aws\Command $command) {...}`.  
** `before_initiate` **  
(`callable`) Retorno de chamada a ser invocado antes da operação `CreateMultipartUpload`. O retorno de chamada deve ter uma assinatura de função como `function (Aws\Command $command) {...}`.  
** `before_upload` **  
(`callable`) Retorno de chamada a ser invocado antes de qualquer operação `UploadPart`. O retorno de chamada deve ter uma assinatura de função como `function (Aws\Command $command) {...}`.  
** `bucket` **  
(`string`, *obrigatório*) Nome do bucket para o qual o objeto está sendo enviado.  
** `concurrency` **  
(`int`, *padrão*: `int(5)`) O número máximo de operações `UploadPart` simultâneas permitidas durante o multipart upload.  
** `key` **  
(`string`, *obrigatório*) Chave a ser usada para o objeto que está sendo enviado.  
** `part_size` **  
(`int`, *padrão*: `int(5242880)`) Tamanho da parte, em bytes, a ser usado ao fazer um multipart upload. Esse tamanho deve ser de 5 MB a 5 GB, inclusive.  
** `state` **  
(`Aws\Multipart\UploadState`) Um objeto que representa o estado do multipart upload e que é usado para retomar um upload anterior. Quando essa opção for fornecida, as opções `bucket`, `key` e `part_size` serão ignoradas.  
**`add_content_md5`**  
(`boolean`) Defina como verdadeiro para calcular automaticamente a MD5 soma de verificação do upload.  
**`params`**  
Uma matriz associativa que fornece opções de configuração para cada subcomando. Por exemplo:  

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

## Cópias de várias partes
<a name="multipart-copies"></a>

Isso AWS SDK para PHP também inclui um `MultipartCopy` objeto que é usado de forma semelhante ao`MultipartUploader`, mas foi projetado para copiar objetos entre 5 GB e 5 TB de tamanho no Amazon S3.

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

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

 **Código de exemplo** 

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