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

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

• Usando os parâmetros de paginação do lado do servidor.

• Usando o programa de paginação do lado do cliente de saída padrão.

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 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 versão 2.

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.

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

Paginação do lado do cliente

A AWS CLI versão 2 fornece um programa de paginação do lado do cliente para uso na saída. Por padrão, o atributo 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:

• cli_pager

• AWS_PAGER

• --no-cli-pager

• Sinalizadores de paginação

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 do arquivo de configuração e credenciais na 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 ambiente AWS_PAGER

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 Configurar variáveis de ambiente para a AWS CLI.

Linux and macOS

$ export AWS_PAGER="less"

Windows

C:\> setx AWS_PAGER "less"

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

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 da linha de comando na 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 paginador que a AWS CLI versão 2 usará por padrão é less. Se você não tiver a variável de ambiente LESS definida, a AWS CLI versão 2 usará os sinalizadores FRX. Você pode combinar sinalizadores especificando-os ao definir a paginação AWS CLI.

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 paginador que a AWS CLI versão 2 usará 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 sinalizadores more, consulte more nos Documentos da Microsoft.