Esta documentación es para la versión 1 de AWS CLI. Para obtener documentación relacionada con la versión 2 de AWS CLI, consulte la Guía del usuario de la versión 2.

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

En este tema se describen las diferentes formas de paginar la salida de AWS Command Line Interface (AWS CLI).

Paginación del lado del servidor

Para la mayoría de los comandos que pueden devolver una amplia lista de elementos, la AWS CLI tiene múltiples opciones del servidor 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. La API de servicio de AWS habilita la paginación del servidor en la AWS CLI, por lo que estas opciones solo funcionan si la API de servicio las habilita.

De forma predeterminada, AWS CLI utiliza un tamaño de página determinado por el servicio individual y recupera todos los elementos disponibles. Por ejemplo, Simple Storage Service (Amazon S3) tiene un tamaño de página predeterminado de 1000. Si ejecuta aws s3api list-objects en un bucket de Simple Storage Service (Amazon S3) que contiene 3500 objetos, AWS CLI realiza cuatro llamadas a Simple Storage Service (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.

‎Para obtener información acerca de si un comando específico tiene paginación del servidor, consulte la Guía de referencia de la AWS CLI.

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

La opción --no-paginate desactiva los siguientes tokens de paginación en el lado del cliente. 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 amzn-s3-demo-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 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 amzn-s3-demo-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 amzn-s3-demo-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.

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