Uso de las opciones de paginación de la AWS CLI - AWS Command Line Interface

Python 2.7, 3.4 y 3.5 están obsoletas para la versión 1 de AWS CLI. Para obtener más información, consulte la sección de la versión 1 de AWS CLI de Acerca de las versiones de AWS CLI.

Uso de las opciones de paginación de la AWS CLI

En este tema se describen las diferentes formas de paginar la salida de AWS Command Line Interface (AWS CLI). Hay principalmente dos formas de controlar la paginación desde laAWS CLI.

Los parámetros de paginación del lado del servidor procesan primero y cualquier salida se envía a la paginación del lado del cliente.

Paginación del lado del servidor

En el caso de los comandos que pueden devolver una amplia lista de elementos, AWS Command Line Interface (AWS CLI) añade múltiples opciones para controlar el número de elementos que se incluyen en la salida cuando la AWS CLI llame a la API de un servicio para rellenar la lista.

  • --no-paginate

  • --page-size

  • --max-items

  • --starting-token

De forma predeterminada, la AWS CLI utiliza un tamaño de página de 1000 y recupera todos los elementos disponibles. Por ejemplo, si ejecuta aws s3api list-objects en un bucket de Amazon S3 que contiene 3500 objetos, la AWS CLI hace cuatro llamadas a Amazon S3, y se encarga de administrar por usted la lógica de paginación específica del servicio en segundo plano y de devolver los 3500 objetos en la salida final.

Cómo usar el parámetro —no-paginate

Para deshabilitar la paginación y devolver solo la primera página de resultados, utilice la opción --no-paginate. Cuando se utiliza un comando, de forma predeterminada, la AWS CLI realiza automáticamente varias llamadas para devolver todos los resultados posibles para crear paginación. Una llamada por cada página. La desactivación de la paginación hace la única llamada de la AWS CLI una vez para la primera página de resultados de comandos.

Por ejemplo, si ejecuta aws s3api list-objects en un bucket de Amazon S3 que contiene 3500 objetos, la AWS CLI solo realiza la primera llamada a Amazon S3, devolviendo solo los primeros 1000 objetos de la salida final.

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

Cómo usar el parámetro —page-size

Si observa algún problema al ejecutar los comandos de la lista en un gran número de recursos, el tamaño de página predeterminado de 1000 puede ser demasiado grande. Esto puede provocar las llamadas a los servicios de AWS para superar el tiempo máximo permitido y generar un error de "tiempo de espera agotado". Puede utilizar la opción --page-size para especificar que la AWS CLI solicite un número menor de elementos de cada llamada al servicio de AWS. La AWS CLI recupera aun así la lista completa, pero realiza un mayor número de llamadas a la API en segundo plano y recupera un menor número de elementos con cada llamada. Esto ofrece a las llamadas individuales una mayor posibilidad de que tengan éxito sin que se agote el tiempo de espera. El cambio del tamaño de página no afecta a la salida; solo afecta a la cantidad de llamadas a la API que hay que realizar para generar la salida.

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

Cómo usar el parámetro —max-items

Para incluir menos elementos a la vez en la salida de la AWS CLI, utilice la opción --max-items. La AWS CLI sigue administrando la paginación con el servicio tal y como se indicó anteriormente, pero solamente muestra a la vez el número de elementos especificado.

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

Cómo usar el parámetro —starting-token

Si el número de elementos de salida (--max-items) es inferior al número total de elementos devueltos por las llamadas básicas a la API, la salida incluirá un NextToken que podrá pasar a un comando posterior para recuperar el siguiente conjunto de elementos. En el siguiente ejemplo se muestra cómo usar el valor NextToken devuelto por el ejemplo anterior y le permite recuperar los segundos 100 elementos.

nota

El parámetro --starting-token no puede ser nulo ni está vacío. Si el comando anterior no devuelve un valor NextToken, no hay más elementos para devolver y no es necesario llamar al comando de nuevo.

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

Puede que el servicio de AWS especificado no devuelva los elementos en el mismo orden cada vez que lo llame. Si especifica diferentes valores para --page-size y --max-items, puede obtener resultados inesperados en el que faltan elementos o están duplicados. Para evitar esto, utilice el mismo número con --page-size y --max-items para sincronizar la paginación de la AWS CLI con la del servicio subyacente. También puede recuperar la lista completa y realizar las operaciones de paginación necesarias de forma local.

Paginación del lado del cliente

Esta característica solo está disponible con la versión 2 de la AWS CLI.

La siguiente característica está disponible solo si usa la versión 2 de la AWS CLI. No está disponible si ejecuta la versión 1 de la AWS CLI. Para obtener información sobre cómo instalar la versión 2, consulte Instalación, actualización y desinstalación de la versión 2 de la AWS CLI.

La versión 2 de la AWS CLI proporciona el uso de un programa de paginación del lado del cliente para la salida. De forma predeterminada, esta función devuelve todas las salidas a través del programa de paginación predeterminado del sistema operativo.

En orden de prioridad, puede especificar la paginación de salida de estas dos maneras:

  • Uso de la configuración cli_pager en el archivo config en un perfil con nombre.

  • Uso de la variable de entorno AWS_PAGER.

  • Uso de la configuración cli_pager en el archivo config en el perfil default.

  • Uso de la variable de entorno PAGER.

En orden de prioridad, puede deshabilitar todo el uso de un programa de paginación externo de las siguientes maneras:

  • Use la opción de línea de comandos --no-cli-pager para desactivar la paginación para un solo uso de comando.

  • Establezca la configuración cli_pager o la variable AWS_PAGER en una cadena vacía.

Cómo utilizar la configuración cli_pager

Puede guardar las opciones de configuración y las credenciales que utiliza con frecuencia en archivos que son mantenidos por la AWS CLI. La configuración de un perfil de nombre tiene prioridad sobre la configuración en el perfil default. Para obtener más información sobre los valores de configuración, consulte Opciones de los archivos de configuración y credenciales.

El siguiente ejemplo establece la paginación de salida predeterminada en el programa less.

[default] cli_pager=less

En el ejemplo siguiente se establece el valor predeterminado para deshabilitar el uso de un paginador.

[default] cli_pager=

Cómo usar la variable de entorno AWS_PAGER

El siguiente ejemplo establece la paginación de salida predeterminada en el programa less. Para obtener más información sobre las variables de entorno, consulte Variables de entorno para configurar la AWS CLI.

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

En el ejemplo siguiente se deshabilita el uso de un paginador.

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

Cómo usar la opción —no-cli-pager

Para deshabilitar el uso de un paginador en un único comando, utilice la opción --no-cli-pager. Para obtener más información acerca de las opciones de línea de comandos, consulte Opciones de línea de comandos.

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

Cómo usar marcadores de paginación

Puede especificar marcadores que se usarán automáticamente con el programa de paginación. Los marcadores dependen del programa de paginación que utilice. Los siguientes ejemplos son para los valores predeterminados típicos de less y more.

Linux and macOS

Si no especifica lo contrario, la versión 2 de AWS CLI que usa el paginador por defecto es less. Si no tiene el conjunto de variables de entorno LESS, la versión 2 de la AWS CLI utiliza los marcadores FRX. Puede combinar marcadores especificándolos al establecer el paginador AWS CLI.

En este ejemplo se usa el marcador S. Este marcador se combina con los marcadores predeterminados FRX para crear un marcador FRXS.

$ export AWS_PAGER="less -S"

Si no quiere utilizar ninguno de los marcadores FRX, puede negarlos. En el siguiente ejemplo se niega el marcador F para crear un marcador RX final.

$ export AWS_PAGER="less -+F"

Para obtener más información sobre los marcadores less, consulte menos en manpages.org.

Windows

Si no especifica lo contrario, la versión 2 de la AWS CLI del paginador utiliza por defecto more sin marcadores adicionales.

En el siguiente ejemplo se usa el parámetro /c.

C:\> setx AWS_PAGER "more /c"

Para obtener más información sobre los marcadores more, consulte más en Documentos de Microsoft.