Utilisation des options de pagination dans l’AWS CLI - AWS Command Line Interface
Pagination côté serveurPager côté client

Utilisation des options de pagination dans l’AWS CLI

Cette rubrique décrit les différentes façons de paginer la sortie de l’AWS Command Line Interface (AWS CLI).

Il existe principalement deux manières de contrôler la pagination à partir de l’AWS CLI.

Les paramètres de pagination côté serveur traitent en premier et toute sortie est envoyée à la pagination côté client.

Pagination côté serveur

Pour la plupart des commandes qui peuvent renvoyer une longue liste d’éléments, l’AWS CLI ajoute plusieurs options côté serveur pour contrôler le nombre d’éléments inclus dans la sortie lorsque l’AWS CLI appelle une API de service pour remplir la liste. La pagination côté serveur dans l’AWS CLI est activée par l’API de service AWS. Par conséquent, ces options ne fonctionnent que si l’API de service les active.

Les options pour la plupart des commandes de l’AWS CLI sont les suivantes :

Par défaut, l’AWS CLI utilise une taille de page déterminée par le service individuel et extrait tous les éléments disponibles. Par exemple, Amazon S3 a une taille de page par défaut de 1 000. Si vous exécutez le code aws s3api list-objects sur un compartiment S3 qui contient 3 500 objets, l’AWS CLI effectue quatre appels à Amazon S3, en gérant la logique de pagination spécifique à un service en arrière-plan et en envoyant tous les 3 500 objets dans la sortie finale.

Pour savoir si une commande spécifique possède une pagination côté serveur, consultez le guide de référence de l’AWS CLI version 2.

Utilisation du paramètre --no-paginate

L’option --no-paginate désactive les jetons de pagination suivants côté client. Lorsque de l’utilisation d’une commande, par défaut, l’AWS CLI effectue automatiquement plusieurs appels pour renvoyer tous les résultats possibles afin de créer la pagination. Un appel par page. La désactivation de la pagination fait en sorte que l’AWS CLI n’appelle qu’une seule fois pour obtenir la première page des résultats de la commande.

Par exemple, si vous exécutez aws s3api list-objects sur un compartiment Amazon S3 qui contient 3 500 objets, l’AWS CLI n’effectue que le premier appel à Amazon S3, renvoyant uniquement les 1 000 premiers objets dans la sortie finale.

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

Utilisation du paramètre --page-size

Si vous constatez des problèmes lors de l’exécution de commandes de liste sur un grand nombre de ressources, la taille de page par défaut peut être trop élevée. Cela peut entraîner des appels aux services AWS dépassant le délai maximum autorisé et générer une erreur « expirée ». Vous pouvez utiliser l’option --page-size pour spécifier que l’AWS CLI demande un plus petit nombre d’éléments de chaque appel au service AWS. L’AWS CLI extrait toujours la liste complète, mais elle effectue un plus grand nombre d’appels d’API de service en arrière-plan, et extraie un plus petit nombre d’éléments à chaque appel. Cela donne aux appels individuels une plus grande chance de réussite sans délai d’expiration. Modifier la taille de la page n’affecte pas la sortie ; cela affecte uniquement le nombre d’appels d’API qui doivent être effectués pour générer la sortie.

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

Utilisation du paramètre --max-items

Pour inclure moins d’éléments à la fois dans la sortie de l’AWS CLI, utilisez l’option --max-items. L’AWS CLI gère toujours la pagination avec le service comme décrite ci-dessus, mais imprime uniquement le nombre d’éléments à un instant que vous spécifiez.

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

Utilisation du paramètre --starting-token

Si le nombre d’éléments en sortie (--max-items) est inférieur au nombre total d’éléments renvoyés par les appels d’API sous-jacents, la sortie inclut un code NextToken que vous pouvez transmettre dans une commande suivante pour récupérer le prochain ensemble d’éléments. L’exemple suivant montre comment utiliser la valeur NextToken renvoyée par l’exemple précédent et vous permet de récupérer la deuxième centaine d’éléments.

Note

Le paramètre --starting-token ne peut pas être nul ni vide. Si la commande précédente ne renvoie pas de valeur NextToken, il n’y a plus aucun élément à renvoyer et vous ne devez plus rappeler la commande.

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

Le service AWS spécifié peut renvoyer des éléments dans un ordre différent à chaque fois que vous appelez. Si vous spécifiez des valeurs différentes pour les codes --page-size et --max-items, vous pouvez obtenir des résultats inattendus avec des éléments manquants ou des doublons. Pour empêcher que cela ne se produise, utilisez le même nombre pour les codes --page-size et --max-items, afin de synchroniser la pagination de l’AWS CLI et celle du service sous-jacent. Vous pouvez également extraire la liste complète et exécuter les opérations de pagination nécessaires localement.

Pager côté client

La version 2 de l’AWS CLI intègre l’utilisation d’un programme de pager côté client pour la sortie. Par défaut, cette fonctionnalité renvoie toutes les sorties via le programme de pager par défaut de votre système d’exploitation.

Par ordre de priorité, vous pouvez spécifier le pager de sortie de deux manières :

  • En utilisant le paramètre cli_pager du fichier config dans le profil default ou nommé.

  • À l’aide de la variable d’environnement AWS_PAGER.

  • À l’aide de la variable d’environnement PAGER.

Par ordre de priorité, vous pouvez désactiver toute utilisation d’un programme de pagination externe de la manière suivante :

  • Utilisez l’option de ligne de commande --no-cli-pager pour désactiver le pager pour l’utilisation d’une commande unique.

  • Définissez le paramètre cli_pager ou la variable AWS_PAGER sur une chaîne vide.

Rubriques relatives au pager côté client :

Utilisation du paramètre cli_pager

Vous pouvez enregistrer vos paramètres de configuration utilisés fréquemment et vos informations d’identification dans des fichiers qui sont gérés par l’AWS CLI. Les paramètres d’un profil de nom ont priorité sur les paramètres du profil default. Pour plus d’informations sur les paramètres de configuration, consultez Paramètres des fichiers de configuration et d’informations d’identification dans l’AWS CLI.

L’exemple suivant définit le pager de sortie par défaut sur le programme less.

[default]
cli_pager=less

L’exemple suivant définit la valeur par défaut pour désactiver l’utilisation d’un pager.

[default]
cli_pager=

Définition de la variable d’environnement AWS_PAGER

L’exemple suivant définit le pager de sortie par défaut sur le programme less. Pour plus d’informations sur les variables d’environnement, consultez Configuration des variables d’environnement pour l’AWS CLI.

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

Utilisation de l’option --no-cli-pager

Pour désactiver l’utilisation d’un pager sur une commande unique, utilisez l’option --no-cli-pager. Pour plus d’informations sur les options de ligne de commande, consultez Option de ligne de commande dans l’AWS CLI.

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

Utilisation des indicateurs de pager

Vous pouvez définir des indicateurs à utiliser automatiquement avec votre programme de pagination. Les indicateurs dépendent du programme de pagination que vous utilisez. Les exemples ci-dessous concernent les valeurs par défaut typiques de less et more.

Linux and macOS

Si vous n’en spécifiez pas d’autres, le pager utilisé par défaut par la version 2 de l’AWS CLI est less. Si la variable d’environnement LESS n’est pas définie, la version 2 de l’AWS CLI utilise les indicateurs FRX. Vous pouvez combiner des indicateurs en les spécifiant lors de la configuration du pager de l’AWS CLI.

L’exemple suivant utilise l’indicateur S. Cet indicateur se combine ensuite avec les indicateurs FRX par défaut pour créer un indicateur FRXS final.

$ export AWS_PAGER="less -S"

Si vous ne voulez aucun des indicateurs FRX, vous pouvez les supprimer. L’exemple suivant refuse l’indicateur F afin de créer un indicateur RX final.

$ export AWS_PAGER="less -+F"

Pour plus d’informations sur les indicateurs less, consultez less sur manpages.org.

Windows

Si vous n’en spécifiez pas d’autres, le pager utilisé par défaut par la version 2 de l’AWS CLI est more sans indicateurs supplémentaires.

L’exemple suivant utilise le paramètre /c.

C:\> setx AWS_PAGER "more /c"

Pour plus d’informations sur les indicateurs more, consultez more sur Microsoft Docs.