Waiters no AWS SDK for PHP Versão 3 - AWS SDK for PHP
Configuração do waiterEspera assíncrona

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á.

Waiters no AWS SDK for PHP Versão 3

Os waiters ajudam a facilitar o trabalho com sistemas eventualmente consistentes fornecendo uma maneira abstraída de esperar até que um recurso entre em um estado específico sondando o recurso. Você pode encontrar uma lista de waiters compatíveis com um cliente visualizando a documentação da API para uma única versão de um cliente de serviço. Para navegar até lá, acesse a página do cliente na documentação da API e navegue até o número da versão específica (representado por uma data) e role para baixo até a seção “Waiters”. Este link o levará à seção de waiters do S3.

No exemplo a seguir, o cliente do Amazon S3 é usado para criar um bucket. Em seguida, o waiter é usado para aguardar até que o bucket exista.

// Create a bucket
$s3Client->createBucket(['Bucket' => 'my-bucket']);

// Wait until the created bucket is available
$s3Client->waitUntil('BucketExists', ['Bucket' => 'my-bucket']);

Se o waiter precisar sondar o bucket por um número excessivo de vezes, ele gerará uma exceção \RuntimeException.

Configuração do waiter

Os waiters são acionados por uma matriz associativa de opções de configuração. Todas as opções usadas por um determinado waiter têm valores padrão, mas eles podem ser substituídos para oferecer suporte a diferentes estratégias de espera.

Você pode modificar as opções de configuração do waiter passando uma matriz associativa de opções do @waiter para o argumento $args dos métodos waitUntil() e getWaiter() de um cliente.

// Providing custom waiter configuration options to a waiter
$s3Client->waitUntil('BucketExists', [
    'Bucket'  => 'my-bucket',
    '@waiter' => [
        'delay'       => 3,
        'maxAttempts' => 10
    ]
]);
delay (int)

Número de segundos de atraso entre tentativas de sondagem. Cada waiter tem um valor de configuração padrão de delay, mas você pode precisar modificar essa configuração para casos de uso específicos.

maxAttempts (int)

O número máximo de tentativas de sondagem a enviar antes do waiter falhar. Essa opção garante que você não espere por um recurso indefinidamente. Cada waiter tem um valor de configuração padrão de maxAttempts, mas você pode precisar modificar essa configuração para casos de uso específicos.

initDelay (int)

Quantidade de tempo em segundos para esperar antes da primeira tentativa de sondagem. Isso pode ser útil ao esperar por um recurso que você sabe que demorará algum tempo para entrar no estado desejado.

before (callable)

Uma função que pode ser chamada do PHP que é invocada antes de cada tentativa. A função que pode ser chamada é invocada com o comando Aws\CommandInterface que está prestes a ser executado e o número de tentativas que foram executadas até agora. Os usos de before callable podem ser para modificar comandos antes que eles sejam executados ou forneçam informações de progresso.

use Aws\CommandInterface;

$s3Client->waitUntil('BucketExists', [
    'Bucket'  => 'my-bucket',
    '@waiter' => [
        'before' => function (CommandInterface $command, $attempts) {
            printf(
                "About to send %s. Attempt %d\n",
                $command->getName(),
                $attempts
            );
        }
    ]
]);

Espera assíncrona

Além da espera de forma síncrona, você pode invocar um waiter para esperar de forma assíncrona enquanto envia outras solicitações ou espera por vários recursos de uma vez.

Você pode acessar uma promessa de waiter recuperando um waiter de um cliente usando o método getWaiter($name, array $args = []) do cliente. Use o método promise() de um waiter para iniciar o waiter. Um promessa de waiter é cumprida com a última Aws\CommandInterface que foi executada no waiter e rejeitada com uma RuntimeException em caso de erro.

use Aws\CommandInterface;

$waiterName = 'BucketExists';
$waiterOptions = ['Bucket' => 'my-bucket'];

// Create a waiter promise
$waiter = $s3Client->getWaiter($waiterName, $waiterOptions);

// Initiate the waiter and retrieve a promise
$promise = $waiter->promise();

// Call methods when the promise is resolved.
$promise
    ->then(function () {
        echo "Waiter completed\n";
    })
    ->otherwise(function (\Exception $e) {
        echo "Waiter failed: " . $e . "\n";
    });

// Block until the waiter completes or fails. Note that this might throw
// a \RuntimeException if the waiter fails.
$promise->wait();

A exposição de uma API de waiters com base em promessa permite alguns casos de uso poderosos e com sobrecarga relativamente baixa. Por exemplo, e se você quisesse esperar por vários recursos, e fazer algo com o primeiro waiter que foi resolvido com êxito?

use Aws\CommandInterface;

// Create an array of waiter promises
$promises = [
    $s3Client->getWaiter('BucketExists', ['Bucket' => 'a'])->promise(),
    $s3Client->getWaiter('BucketExists', ['Bucket' => 'b'])->promise(),
    $s3Client->getWaiter('BucketExists', ['Bucket' => 'c'])->promise()
];

// Initiate a race between the waiters, fulfilling the promise with the
// first waiter to complete (or the first bucket to become available)
$any = Promise\any($promises)
    ->then(function (CommandInterface $command) {
        // This is invoked with the command that succeeded in polling the
        // resource. Here we can know which bucket won the race.
        echo "The {$command['Bucket']} waiter completed first!\n";
    });

// Force the promise to complete
$any->wait();