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

Paginadores na versão 3 AWS SDK for PHP

Algumas operações AWS de serviço são paginadas e respondem com resultados truncados. Por exemplo, a operação ListObjects do Amazon S3 retorna só até 1.000 objetos por vez. Operações como essas (normalmente prefixadas com "list" ou "describe") exigem solicitações subsequentes com parâmetros de token (ou marcador) para recuperar todo o conjunto de resultados.

Os paginadores são um recurso do AWS SDK for PHP que atua como uma abstração desse processo para facilitar o uso do paginado pelos desenvolvedores. APIs Um paginador é essencialmente um iterador de resultados. Eles são criados por meio do método getPaginator() do cliente. Quando chama getPaginator(), você deve fornecer o nome da operação e os argumentos da operação (da mesma forma como faz quando ao executar uma operação). Você pode iterar por um objeto paginador usando foreach para obter objetos Aws\Result individuais.

$results = $s3Client->getPaginator('ListObjects', [
    'Bucket' => 'amzn-s3-demo-bucket'
]);

foreach ($results as $result) {
    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
}

Objetos de paginador

O objeto retornado pelo método getPaginator() é uma instância da classe Aws\ResultPaginator. Essa classe implementa PHP a iterator interface nativa do, e é por isso que ela funciona comforeach. Ele também pode ser usado com funções iteradoras, comoiterator_to_array, e se integra bem com SPLiteradores como o objeto. LimitIterator

Os objetos de paginador mantêm apenas uma "página" de resultados de cada vez e são executados lentamente. Isso significa que eles fazem apenas o número de solicitações que precisarem para gerar a página atual de resultados. Por exemplo, a operação ListObjects do Amazon S3 retorna apenas até 1.000 objetos por vez, portanto, se o bucket tiver aproximadamente 10.000 objetos, o paginador precisará fazer um total de 10 solicitações. Quando você percorre os resultados, a primeira solicitação é executada quando você inicia a iteração, a segunda na segunda iteração do loop e assim por diante.

Enumeração de dados dos resultados

Os objetos do paginador têm um método chamado search(), que permite criar iteradores para dados em um conjunto de resultados. Ao chamarsearch(), forneça uma JMESPathexpressão para especificar quais dados extrair. Chamar search() retorna um iterador que produz os resultados da expressão em cada página de resultados. Isso é avaliado lentamente, conforme você percorre o iterador retornado.

O exemplo a seguir é equivalente ao exemplo de código anterior, mas usa o método ResultPaginator::search() para ser mais conciso.

$results = $s3Client->getPaginator('ListObjects', [
    'Bucket' => 'amzn-s3-demo-bucket'
]);

foreach ($results->search('Contents[].Key') as $key) {
    echo $key . "\n";
}

JMESPathexpressões permitem que você faça coisas bastante complexas. Por exemplo, se você desejar imprimir todas as chaves de objeto e prefixos comuns (ou seja, fazer um ls de um bucket), você pode fazer o seguinte.

// List all prefixes ("directories") and objects ("files") in the bucket
$results = $s3Client->getPaginator('ListObjects', [
    'Bucket'    => 'amzn-s3-demo-bucket',
    'Delimiter' => '/'
]);

$expression = '[CommonPrefixes[].Prefix, Contents[].Key][]';
foreach ($results->search($expression) as $item) {
    echo $item . "\n";
}

Paginação assíncrona

Você pode iterar sobre os resultados de um paginador de forma assíncrona fornecendo um retorno de chamada para o método each() de um Aws\ResultPaginator. O retorno de chamada é invocado para cada valor gerado pelo paginador.

$results = $s3Client->getPaginator('ListObjects', [
    'Bucket' => 'amzn-s3-demo-bucket'
]);

$promise = $results->each(function ($result) {
    echo 'Got ' . var_export($result, true) . "\n";
});

Um valor de retorno não nulo do retorno de chamada será gerado por uma promessa com base na corrotina subjacente. Isso significa que você pode retornar promessas do retorno de chamada que devem ser resolvidas antes de continuar a iteração nos itens restantes, essencialmente mesclando outras promessas com a iteração. O último valor não nulo retornado pelo retorno de chamada é o resultado que cumpre a promessa para qualquer promessa downstream. Se o último valor de retorno for uma promessa, a resolução dessa promessa será o resultado que cumpre ou rejeita as promessas downstream.

// Delete all keys that end with "Foo"
$promise = $results->each(function ($result) use ($s3Client) {
    if (substr($result['Key'], -3) === 'Foo') {
        // Merge this promise into the iterator
        return $s3Client->deleteAsync([
            'Bucket' => 'amzn-s3-demo-bucket',
            'Key'    => 'Foo'
        ]);
    }
});

$promise
    ->then(function ($result) {
        // Result would be the last result to the deleteAsync operation
    })
    ->otherwise(function ($reason) {
        // Reason would be an exception that was encountered either in the
        // call to deleteAsync or calls performed while iterating
    });

// Forcing a synchronous wait will also wait on all of the deleteAsync calls
$promise->wait();