Rastreando todas as operações Rastreando uma operação de arquivo único Rastreando uma única operação de diretório Rastreamento de progresso personalizado Personalize um rastreador de progresso integrado

Acompanhamento do progresso

O S3 Transfer Manager fornece recursos integrados de rastreamento de progresso.

Rastreando todas as operações

Você pode ativar o rastreamento para todas as operações (arquivo e diretório) configurando track_progress como true na S3TransferManager instância.


<?php

use Aws\S3\S3Transfer\S3TransferManager;

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


$transferManager = new S3TransferManager(
    null,
    [
        'track_progress' => true,
    ]
);

Com essa configuração, o SDK usa o integrado SingleProgressTracker <add link> para operações de arquivo e usa o MultiProgressTracker <add link>para operações de diretório.

Rastreando uma operação de arquivo único

Se você não ativou o rastreamento de progresso no gerenciador de transferências, poderá ativar o rastreamento em um método individual de duas maneiras.

track_progressDefina como true na $config matriz para uma operação de arquivo específica.


<?php

use Aws\S3\S3Transfer\Models\UploadDirectoryRequest;
use Aws\S3\S3Transfer\S3TransferManager;

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


$transferManager = new S3TransferManager(
    null, []
);

$uploadDirPromise = $transferManager->uploadDirectory(
    new UploadDirectoryRequest(
        '/path/to/directory',
        'amzn-s3-demo-bucket',
        [],
        [   // $config array
            'track_progress' => true,
        ],
        []
    )
);

Crie uma nova SingleProgressTracker instância ou forneça uma implementação personalizada doAbstractTransferListener. Passe seu rastreador para as operações do arquivo como $progressTracker parâmetro.


<?php

use Aws\S3\S3Transfer\Models\UploadRequest;
use Aws\S3\S3Transfer\Progress\SingleProgressTracker;
use Aws\S3\S3Transfer\S3TransferManager;

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

$transferManager = new S3TransferManager(
    null, []
);

$uploadPromise = $transferManager->upload(
    new UploadRequest(
        '/path/to/Myfile.txt',  // Or an instance of StreamInterface.
        [
            'Bucket' => 'amzn-s3-demo-bucket',
            'Key' => 'file.txt',
        ],
        [],
        [],
        new SingleProgressTracker()  // Or custom implementation of the TransferLister interface.
    )
);

O exemplo a seguir mostra um exemplo de saída do console integrado SingleProgressTracker para o progresso do upload de um arquivo chamadoMyFile.txt:

Saída do console mostrando uma barra de progresso para o upload de MyFile .txt com porcentagem de conclusão e velocidade de transferência

Rastreando uma única operação de diretório

Se você não habilitou o controle de progresso no gerenciador de transferências, você pode habilitá-lo para operações de diretório de duas maneiras.

Defina 'track_progress' como true no argumento da matriz do $config método.


<?php

use Aws\S3\S3Transfer\Models\UploadDirectoryRequest;
use Aws\S3\S3Transfer\S3TransferManager;

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


$transferManager = new S3TransferManager(
    null, []
);

$uploadDirPromise = $transferManager->uploadDirectory(
    new UploadDirectoryRequest(
        '/path/to/directory',
        'amzn-s3-demo-bucket',
        [],
        [   // $config array
            'track_progress' => true,
        ],
        []
    )
);

Crie uma nova MultiProgressTracker instância e passe-a para as operações do diretório como $progressTracker parâmetro.


<?php

use Aws\S3\S3Transfer\Models\UploadDirectoryRequest;
use Aws\S3\S3Transfer\Progress\MultiProgressTracker;
use Aws\S3\S3Transfer\S3TransferManager;

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

$transferManager = new S3TransferManager(
    null, []
);

$uploadDirPromise = $transferManager->uploadDirectory(
    new UploadDirectoryRequest(
        '/path/to/directory',
        'amzn-s3-demo-bucket',
        [],
        [],
        [],
        new MultiProgressTracker()
    )
);

O exemplo a seguir mostra um exemplo de saída do console integrado MultiProgressTracker para o progresso do upload de um diretório:

Saída do console mostrando várias barras de progresso para carregar vários arquivos com uma barra de progresso resumida na parte inferior

O progresso de cada arquivo é listado junto com o progresso resumido na última linha.

Rastreamento de progresso personalizado

Você pode implementar seu próprio acompanhamento de progresso para operações de arquivos. Crie uma classe que estenda a AbstractTransferListener interface e a transmita para o método na solicitação.

A implementação a seguir exibe informações de progresso em formato de texto para uma única operação de arquivo:


<?php

use Aws\S3\S3Transfer\Models\UploadRequest;
use Aws\S3\S3Transfer\Progress\AbstractTransferListener;
use Aws\S3\S3Transfer\S3TransferManager;

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

class MyProgressTracker extends AbstractTransferListener 
{
    public function transferInitiated(array $context): void
    {
        $key = $context['request_args']['Key'] ?? 'unknown';
        echo "Starting transfer of {$key}...\n";
    }

    public function bytesTransferred(array $context): bool
    {
        $snapshot = $context['progress_snapshot'];
        $percent = round($snapshot->ratioTransferred() * 100, 2);
        $transferred = round($snapshot->getTransferredBytes() / 1024 / 1024, 2);
        $total = round($snapshot->getTotalBytes() / 1024 / 1024, 2);

        echo "Progress: {$percent}% ({$transferred}MB of {$total}MB)\n";
    }

    public function transferComplete(array $context): void
    {
        $key = $context['request_args']['Key'] ?? 'unknown';
        echo "Transfer complete for {$key}!\n";
    }

    public function transferFail(array $context): void
    {
        $key = $context['request_args']['Key'] ?? 'unknown';
        $reason = $context['reason']->getMessage();
        echo "Transfer failed for {$key}: {$reason}\n";
    }
}

$transferManager = new S3TransferManager(
    null, []
);

// Use your custom tracker.
$uploadPromise = $transferManager->upload(
    new UploadRequest(
        '/path/to/file.txt', // Or an instance of StreamInterface.
        [
            'Bucket' => 'amzn-s3-demo-bucket',
            'Key'    => 'file.txt',
        ],
        [],
        [],
        new MyProgressTracker()
    )
);

O exemplo a seguir mostra um exemplo de saída para o console para o upload de arquivos em andamento:


Starting transfer of file.txt...
Progress: 42% (16.8MB of 40MB)

Personalize um rastreador de progresso integrado

Você pode personalizar o acompanhamento do progresso de algumas maneiras:

Crie uma implementação personalizada estendendo AbstractTransferListener e ProgressTrackerInterface <add link> implementando.
Personalize as implementações existentes configurando o ConsoleProgressBar <add link> que é passado para os rastreadores integrados.
Implemente um personalizado ProgressBar <add link> e passe-o para os rastreadores integrados.

Os exemplos a seguir mostram como personalizar o acompanhamento do progresso. Consulte o diagrama de classes para ver a relação entre os componentes de acompanhamento do progresso no SDK.

Personalize um `ConsoleProgressBar`

Personalize o formato de barra padrão

O exemplo a seguir personaliza o formato padrão da barra de progresso, que é ColoredTransferProgressBarFormat<add link>. Esse formato mostra o progresso com cores diferentes, dependendo do estado da transferência.

O exemplo muda:

o caractere do padrão “#” para “=”
largura da barra do padrão de 50 a 100


<?php

use Aws\S3\S3Client;
use Aws\S3\S3Transfer\Models\UploadRequest;
use Aws\S3\S3Transfer\Progress\ConsoleProgressBar;
use Aws\S3\S3Transfer\Progress\SingleProgressTracker;
use Aws\S3\S3Transfer\S3TransferManager;

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

$progressBar = new ConsoleProgressBar(
    progressBarChar: '=',
    progressBarWidth: 100,
// Default `ColoredTransferProgressBarFormat` is used.
);
$progressTracker = new SingleProgressTracker(
    progressBar: $progressBar,
);
$s3Client = new S3Client([
    'region' => 'us-east-2',
]);
$s3TransferManager = new S3TransferManager($s3Client);
$source = "/path/file.txt";

$result = $s3TransferManager->upload(
    new UploadRequest(
        source: $source,
        uploadRequestArgs: [
            'Bucket' => 'amzn-s3-demo-bucket',
            'Key'    => 'key',
        ],
        progressTracker: $progressTracker,
    )
)->wait();
print_r($result);

A imagem a seguir mostra a saída do console para um embutido personalizado ConsoleProgressBar com uma largura de 100 e o caractere de “=”:

Saída do console mostrando uma barra de progresso personalizada usando sinais de igualdade com largura de 100 caracteres

Personalize usando o formato simples da barra de progresso

O exemplo a seguir personaliza a barra de progresso padrão usando a incorporada PlainProgressBarFormat <add link> com caracteres e largura personalizados. As PlainProgressBarFormat telas são somente em preto. A cor não muda com base no estado da transferência.

O exemplo muda:

o caractere do padrão “#” até “*”
largura da barra do padrão de 50 a 25
a progressBarFormat instância padrão de ColoredTransferProgressBarFormat até PlainProgressBarFormat


<?php

use Aws\S3\S3Client;
use Aws\S3\S3Transfer\Models\UploadRequest;
use Aws\S3\S3Transfer\Progress\ConsoleProgressBar;
use Aws\S3\S3Transfer\Progress\PlainProgressBarFormat;
use Aws\S3\S3Transfer\Progress\SingleProgressTracker;
use Aws\S3\S3Transfer\S3TransferManager;

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

$progressBar = new ConsoleProgressBar(
    progressBarChar: '*',
    progressBarWidth: 25,
    progressBarFormat: new PlainProgressBarFormat(),
);
$progressTracker = new SingleProgressTracker(
    progressBar: $progressBar,
);
$s3Client = new S3Client([
    'region' => 'us-east-2',
]);
$s3TransferManager = new S3TransferManager($s3Client);
$source = "/path/file.txt";

$result = $s3TransferManager->upload(
    new UploadRequest(
        source: $source,
        uploadRequestArgs: [
            'Bucket' => 'amzn-s3-demo-bucket',
            'Key'    => 'key',
        ],
        progressTracker: $progressTracker,
    )
)->wait();
print_r($result);

A imagem a seguir mostra a saída do console para um embutido personalizado ConsoleProgressBar usando um formato de barra de progresso simples com uma largura de 25 e o caractere de “*”:

Saída do console mostrando uma barra de progresso preta simples usando asteriscos com largura de 25 caracteres

Personalize criando um novo formato de barra

O exemplo a seguir personaliza a barra de progresso padrão usando um novo formato de barra (extensão ProgressBarFormat<add link>) em vez de personalizar um formato incorporado.


<?php

use Aws\S3\S3Client;
use Aws\S3\S3Transfer\Models\UploadRequest;
use Aws\S3\S3Transfer\Progress\ConsoleProgressBar;
use Aws\S3\S3Transfer\Progress\ProgressBarFormat;
use Aws\S3\S3Transfer\Progress\SingleProgressTracker;
use Aws\S3\S3Transfer\S3TransferManager;

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

// Implement a custom bar format.
class PercentBarFormat extends ProgressBarFormat
{
    public const FORMAT_TEMPLATE = "|object_name| - |percent|% [|transferred| |unit|ytes]";
    public const FORMAT_PARAMETERS = [
        'object_name',       // `uploadRequestArgs` Key parameter.
        'percent',           //  Percent transferred.
        // 'progress_bar',      Optional, if used, default is a `ConsoleProgressBar`.
        // 'to_be_transferred', Optional.
        'transferred',       //  Default is bytes transferred.
        'unit',              //  Default is 'B'.
    ];

    public function getFormatTemplate(): string
    {
        return self::FORMAT_TEMPLATE;
    }

    public function getFormatParameters(): array
    {
        return self::FORMAT_PARAMETERS;
    }

    protected function getFormatDefaultParameterValues(): array
    {
        return [];
    }
}

// Create an instance of the custom implemention
$progressBarFormat = new PercentBarFormat();
$progressBar = new ConsoleProgressBar(
    progressBarFormat: $progressBarFormat,
);
$progressTracker = new SingleProgressTracker(
    progressBar: $progressBar,
);
$s3Client = new S3Client([
    'region' => 'us-east-2',
]);
$s3TransferManager = new S3TransferManager($s3Client);
$source = "/path/file";

$result = $s3TransferManager->upload(
    new UploadRequest(
        source: $source,
        uploadRequestArgs: [
            'Bucket' => 'amzn-s3-demo-bucket',
            'Key'    => 'key',
        ],
        progressTracker: $progressTracker,
    )
)->wait();
print_r($result);

A imagem a seguir mostra a saída do console para uma versão integrada personalizada ConsoleProgressBar usando um formato de barra de progresso personalizado:

Saída do console mostrando um formato de progresso personalizado baseado em porcentagem, exibindo o nome do objeto e os bytes transferidos

Um formato de barra personalizado aceita vários parâmetros:

nome_objeto
percentual
barra de progresso
a ser transferido
transferido
unidade

Você pode combinar os nomes dos parâmetros delimitados (caracteres de barra vertical) para personalizar a saída. O exemplo usa o modelo a seguir. O getFormatTemplate método da PercentBarFormat classe retorna este modelo:


"|object_name| - |percent|% [|transferred| |unit|ytes]"

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Transferir ouvintes

Diagrama de classes