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

# Usar resultados paginados no AWS SDK para PHP versão 3
<a name="guide_paginators"></a>

Algumas operações de serviços da AWS 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 para PHP que atuam como uma abstração sobre esse processo para facilitar o uso de APIs paginadas aos desenvolvedores. 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
<a name="paginator-objects"></a>

O objeto retornado pelo método `getPaginator()` é uma instância da classe `Aws\ResultPaginator`. Essa classe implementa a interface `iterator` nativa do PHP, e é por isso que ela funciona com `foreach`. Ela também pode ser usada com funções de iterador, como `iterator_to_array`, e integra-se bem com [iteradores do SPL](http://www.php.net/manual/en/spl.iterators.php), 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
<a name="enumerating-data-from-results"></a>

Os objetos do paginador têm um método chamado `search()`, que permite criar iteradores para dados em um conjunto de resultados. Ao chamar `search()`, forneça uma [expressão JMESPath](guide_jmespath.md) 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";
}
```

As expressões de JMESPath 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
<a name="async-paginators"></a>

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

**nota**  
O uso do método `each()` permite paginar sobre os resultados da operação de uma API enquanto simultaneamente envia outras solicitações de forma assíncrona.

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