Esta documentação é somente para a versão 1 da AWS CLI. Para obter a documentação relacionada à AWS CLI versão 2, consulte o Guia do usuário da versão 2.

Usar as opções de paginação na AWS CLI

Este tópico descreve as diferentes maneiras de paginar a saída da AWS Command Line Interface (AWS CLI).

Paginação do lado do servidor

Para a maioria dos comandos que retornam uma extensa lista de itens, a AWS CLI oferece várias opções do lado do servidor para controlar o número de itens incluídos na saída quando a AWS CLI chama a API de um serviço para preencher a lista. A paginação do lado do servidor na AWS CLI é habilitada pela API do serviço da AWS; portanto, essas opções só funcionarão se a API de serviço as habilitar.

Por padrão, a AWS CLI usa um tamanho de página determinado pelo serviço específico e recupera todos os itens disponíveis. Por exemplo, o Amazon S3 tem um tamanho de página padrão de mil. Se você executar aws s3api list-objects em um bucket do Amazon S3 que contém 3,5 mil objetos, a AWS CLI fará automaticamente quatro chamadas para o Amazon S3, lidando com a lógica de paginação específica do serviço para você em segundo plano e retornando todos os 3,5 mil objetos na saída final.

Consulte informações sobre se um comando específico oferece paginação do lado do servidor no Guia de referência da AWS CLI.

Como usar o parâmetro –no-paginate

A opção --no-paginate desabilita os seguintes tokens de paginação no lado do cliente. Ao usar um comando, por padrão a AWS CLI faz várias chamadas automaticamente para retornar todos os resultados possíveis para criar a paginação. Uma chamada para cada página. Desabilitar a paginação faz com que a AWS CLI chame apenas uma vez pela primeira página de resultados do comando.

Por exemplo, se você executar oaws s3api list-objects em um bucket do Amazon S3 que contém 3500 objetos, o AWS CLI fará apenas a primeira chamada para o Amazon S3, retornando apenas os primeiros 1000 objetos na saída final.

$ aws s3api list-objects \
    --bucket amzn-s3-demo-bucket \
    --no-paginate
{
    "Contents": [
...

Como usar o parâmetro --page-size

Caso haja problemas ao executar os comandos da lista em um grande número de recursos, o tamanho da página padrão poderá ser muito alto. Isso pode fazer com que as chamadas para os serviços do AWS excedam o tempo máximo permitido e gerar um erro de “expiração”. Você pode usar a opção --page-size para especificar que a AWS CLI solicite um número menor de itens de cada chamada para o serviço da AWS. A AWS CLI ainda recuperará a lista completa, mas executará um número maior de chamadas de API de serviço em segundo plano e recuperará um número menor de itens em cada chamada. Isso fornece às chamadas individuais chances melhores de sucesso sem um tempo limite. Alterar o tamanho da página não afeta a saída, afeta somente o número de chamadas da API que precisam ser feitas para gerar a saída.

$ aws s3api list-objects \
    --bucket amzn-s3-demo-bucket \
    --page-size 100
{
    "Contents": [
...

Como usar o parâmetro --max-items

Para incluir menos itens por vez na saída da AWS CLI, use a opção --max-items. A AWS CLI ainda lida com paginação com o serviço conforme descrito anteriormente, mas imprime apenas o número de itens que você especificar de cada vez.

$ aws s3api list-objects \
    --bucket amzn-s3-demo-bucket \
    --max-items 100
{
    "NextToken": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==",
    "Contents": [
...

Como usar o parâmetro --starting-token

Se o número de saída de itens (--max-items) for menor do que o número total de itens retornados pelas chamadas de API subjacentes, a saída incluirá um NextToken que pode ser passado para um comando subsequente para recuperar o próximo conjunto de itens. O exemplo a seguir mostra como usar o valor NextToken retornado pelo exemplo anterior e permite que você recupere os segundos 100 itens.

$ aws s3api list-objects \
    --bucket amzn-s3-demo-bucket \
    --max-items 100 \
    --starting-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==
{
    "Contents": [
...

O serviço da AWS especificado pode não retornar itens na mesma ordem cada vez que você chamá-lo. Se você especificar valores diferentes para --page-size e --max-items, poderá obter resultados inesperados com itens ausentes ou duplicados. Para evitar que isso aconteça, use o mesmo número para --page-size e --max-items para sincronizar a paginação da AWS CLI com a paginação do serviço subjacente. Também é possível recuperar a lista completa e executar quaisquer operações necessárias de paginação localmente.