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

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

Use as AWS CLI opções de paginação

Este tópico descreve as diferentes maneiras de paginar a saída pela AWS CLI.

Paginação do lado do servidor

Para comandos que podem retornar uma grande lista de itens, o AWS Command Line Interface (AWS CLI) tem várias opções para controlar o número de itens incluídos na saída quando AWS CLI chama um serviço API para preencher a lista.

Por padrão, o AWS CLI usa um tamanho de página determinado pelo serviço individual 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.

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, ele faz AWS CLI automaticamente várias chamadas para retornar todos os resultados possíveis para criar paginação. Uma chamada para cada página. A desativação da paginação tem a AWS CLI única chamada uma vez para a primeira página dos resultados do comando.

Por exemplo, se você executa aws s3api list-objects em um bucket do Amazon S3 que contém 3.500 objetos, ele AWS CLI só faz a primeira chamada para o Amazon S3, retornando somente os primeiros 1.000 objetos na saída final.

$ aws s3api list-objects \
    --bucket my-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 AWS serviços excedam o tempo máximo permitido e gerem um erro de “tempo limite”. Você pode usar a --page-size opção para especificar que AWS CLI solicite um número menor de itens de cada chamada para o AWS serviço. O AWS CLI ainda recupera a lista completa, mas executa um número maior de API chamadas de serviço em segundo plano e recupera um número menor de itens com 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 API chamadas que precisam ser feitas para gerar a saída.

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

Como usar o parâmetro --max-items

Para incluir menos itens por vez na AWS CLI saída, use a --max-items opção. O AWS CLI Still processa a paginação com o serviço conforme descrito anteriormente, mas imprime somente o número de itens por vez que você especifica.

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

Como usar o parâmetro --starting-token

Se o número de itens output (--max-items) for menor que o número total de itens retornados pelas API chamadas subjacentes, a saída incluirá um NextToken que você pode passar 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 my-bucket \
    --max-items 100 \
    --starting-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==
{
    "Contents": [
...

O AWS serviço especificado pode não devolver itens no mesmo pedido sempre que você ligar. 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.