Usando as opções de paginação no AWS CLI - AWS Command Line Interface
Paginação do lado do servidorPaginação do lado do cliente

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

Usando as opções de paginação no AWS CLI

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

Há duas formas principais de controlar a paginação a partir da AWS CLI.

Os parâmetros de paginação do lado do servidor são processados primeiro, e qualquer saída é enviada para a paginação do lado do cliente.

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 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 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 amzn-s3-demo-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 amzn-s3-demo-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.

nota

O parâmetro --starting-token não pode ser nulo nem vazio. Se o comando anterior não retornar um valor NextToken, não haverá mais itens a serem retornados e você não precisará chamar o comando novamente.

$ aws s3api list-objects \
    --bucket amzn-s3-demo-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.

Paginação do lado do cliente

AWS CLI a versão 2 fornece o uso de um programa de pager do lado do cliente para saída. Por padrão, o recurso retorna toda a saída pelo programa de paginação padrão do sistema operacional.

Em ordem de precedência, você pode especificar a paginação de saída destas duas formas:

  • Usando a configuração cli_pager no arquivo config no perfil default ou nomeado.

  • Usando a variável de ambiente AWS_PAGER.

  • Usando a variável de ambiente PAGER.

Por ordem de precedência, você pode desabilitar todo o uso de um programa de paginação externo das seguintes maneiras:

  • Usar opção de linha de comando --no-cli-pager para desabilitar a paginação para o uso de um único comando.

  • Definir a configuração cli_pager ou a variável AWS_PAGER como uma string vazia.

Tópicos de paginação do lado do cliente:

Como usar a configuração cli_pager

Você pode salvar as definições de configuração usadas com frequência e credenciais em arquivos que são mantidos pela AWS CLI. As configurações em um perfil de nome têm precedência sobre as configurações no perfil default. Para obter mais informações sobre as opções de configuração, consulte Configurações e configurações do arquivo de credenciais no AWS CLI.

O exemplo a seguir define a paginação de saída padrão para o programa less.

[default]
cli_pager=less

O exemplo abaixo define o padrão para desativar o uso de um paginador.

[default]
cli_pager=

Como definir a variável de AWS_PAGER ambiente

O exemplo a seguir define a paginação de saída padrão para o programa less. Para obter mais informações sobre variáveis de ambiente, consulte Configurando variáveis de ambiente para o AWS CLI.

Linux and macOS
$ export AWS_PAGER="less"
Windows
C:\> setx AWS_PAGER "less"

Como usar a no-cli-pager opção --

Para desabilitar o uso de uma paginação em um único comando, use a opção --no-cli-pager. Para obter mais informações sobre as opções de linha de comando, consulte Opções de linha de comando no AWS CLI.

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

Como usar sinalizadores de paginação

Você pode especificar sinalizadores para usar automaticamente com seu programa de paginação. Os sinalizadores dependem do programa de paginação utilizado. Os exemplos abaixo são referem-se aos padrões típicos de less e more.

Linux and macOS

Se você não especificar o contrário, o pager que a AWS CLI versão 2 usa por padrão éless. Se você não tiver a variável de LESS ambiente definida, a AWS CLI versão 2 usa os FRX sinalizadores. Você pode combinar sinalizadores especificando-os ao definir o AWS CLI pager.

O exemplo a seguir usa o sinalizador S. Esse sinalizador então se combina aos sinalizadores FRX padrão para criar um sinalizador FRXS.

$ export AWS_PAGER="less -S"

Caso não queira usar nenhum dos sinalizadores FRX, você poderá negá-los. O exemplo a seguir nega o sinalizador F para criar um sinalizador RX final.

$ export AWS_PAGER="less -+F"

Para obter mais informações sobre sinalizadores less, consulte less em manpages.org.

Windows

Se você não especificar o contrário, o pager que a AWS CLI versão 2 usa por padrão é more sem sinalizadores adicionais.

O exemplo a seguir usa o parâmetro /c.

C:\> setx AWS_PAGER "more /c"

Para obter mais informações sobre more sinalizadores, consulte more no Microsoft Docs.