Verwenden der Paginierungsoptionen in der AWS CLI - AWS Command Line Interface
Serverseitige PaginierungClientseitiger Pager

Verwenden der Paginierungsoptionen in der AWS CLI

In diesem Thema werden die verschiedenen Möglichkeiten beschrieben, die Ausgabe von AWS Command Line Interface (AWS CLI) zu paginieren.

Es gibt hauptsächlich zwei Möglichkeiten, die Paginierung vom AWS CLI aus zu steuern.

Serverseitige Paginierungsparameter werden zuerst verarbeitet und jede Ausgabe wird an die clientseitige Paginierung gesendet.

Serverseitige Paginierung

Für die meisten Befehle, die eine umfangreiche Liste mit Elementen zurückgeben, bietet die AWS CLI mehrere serverseitige Optionen, mit denen Sie die Anzahl der Elemente in der Ausgabe steuern können, wenn die AWS CLI die API eines Service aufruft, um die Liste zu füllen. Die serverseitige Paginierung in der AWS CLI wird von der AWS-Service-API aktiviert, daher funktionieren diese Optionen nur, wenn die Service-API sie aktiviert.

Die Optionen für die meisten AWS CLI-Befehle umfassen Folgendes:

Standardmäßig verwendet die AWS CLI eine vom einzelnen Service festgelegte Seitengröße und ruft alle verfügbaren Elemente ab. Amazon S3 hat beispielsweise eine Standardseitengröße von 1 000. Wenn Sie aws s3api list-objects auf einem Amazon-S3-Bucket ausführen, der 3 500 Objekte enthält, ruft die AWS CLI Amazon S3 automatisch vier Mal auf, verarbeitet die servicespezifische Paginierungslogik für Sie im Hintergrund und gibt alle 3 500 Objekte in der endgültigen Ausgabe zurück.

Informationen dazu, ob ein bestimmter Befehl über serverseitige Paginierung verfügt, finden Sie im Referenzhandbuch zu AWS CLI Version 2.

So verwenden Sie den --no-paginate-Parameter

Die --no-paginate-Option deaktiviert folgende Paginierungs-Token auf der Client-Seite. Wenn Sie einen Befehl verwenden, führt AWS CLI standardmäßig automatisch mehrere Aufrufe durch, um alle möglichen Ergebnisse zum Erstellen einer Paginierung zurückzugeben. Ein Aufruf für jede Seite. Beim Deaktivieren der Paginierung wird der AWS CLI-Aufruf nur einmal für die erste Seite der Befehlsergebnisse angezeigt.

Wenn Sie beispielsweise aws s3api list-objects in einem Amazon-S3-Bucket ausführen, der 3 500 Objekte enthält, führt AWS CLI nur den ersten Aufruf an Amazon S3 durch und gibt nur die ersten 1 000 Objekte in der endgültigen Ausgabe zurück.

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

So verwenden Sie den –page-size-Parameter

Wenn beim Ausführen von Listenbefehlen für eine große Anzahl von Ressourcen Probleme auftreten, ist die Standardseitengröße möglicherweise zu hoch. Dies kann dazu führen, dass es bei Aufrufen von AWS-Services zu Zeitüberschreitungen kommt und ein Zeitüberschreitungsfehler generiert wird. Sie können die Option --page-size verwenden, um anzugeben, dass die AWS CLI eine geringere Anzahl an Elementen bei Aufrufen des AWS-Services anfordert. Die AWS CLI wird weiterhin die vollständige Liste abrufen, aber eine größere Anzahl von Service-API-Aufrufen im Hintergrund verarbeiten und bei jedem Aufruf eine geringere Anzahl von Elementen abrufen. Dadurch ist es wahrscheinlicher, dass Aufrufe nicht zu einem Zeitüberschreitungsfehler führen. Das Ändern der Seitengröße hat keine Auswirkungen auf die Ausgabe. Es wirkt sich nur auf die Anzahl der API-Aufrufe aus, die erforderlich sind, um die Ausgabe zu generieren.

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

So verwenden Sie den –max-items-Parameter

Verwenden Sie die Option --max-items, damit bei einem Aufruf weniger Elemente in der AWS CLI-Ausgabe enthalten sind. Die AWS CLI verarbeitet die Paginierung im Service weiterhin wie vorher beschrieben, druckt jedoch jeweils nur die Anzahl der Elemente, die Sie angeben.

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

So verwenden Sie den –starting-token-Parameter

Wenn die Anzahl der ausgegebenen Elemente (--max-items) geringer als die Gesamtanzahl der Elemente ist, die von den zugrunde liegenden API-Aufrufen zurückgeliefert werden, enthält die Ausgabe ein NextToken. Dieses können Sie in einem anschließenden Befehl zum Abrufen der nächsten Gruppe von Elementen übergeben. Im folgenden Beispiel wird gezeigt, wie Sie den Wert NextToken aus dem vorherigen Beispiel verwenden und die zweiten hundert Elemente abrufen.

Anmerkung

Der Parameter --starting-token kann nicht null oder leer sein. Wenn der vorherige Befehl keinen NextToken-Wert zurückgibt, können keine weiteren Elemente zurückgegeben werden und Sie müssen den Befehl nicht erneut aufrufen.

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

Der angegebene AWS-Service gibt Elemente möglicherweise nicht bei jedem Aufruf in der gleichen Reihenfolge zurück. Wenn Sie verschiedene Werte für --page-size und --max-items angeben, können Sie unerwartete Ergebnisse mit fehlenden oder doppelten Elementen bekommen. Um dies zu verhindern, verwenden Sie dieselbe Zahl für --page-size und --max-items, um die Paginierung der AWS CLI mit der Paginierung der zugrunde liegenden Services zu synchronisieren. Sie können auch die gesamte Liste abrufen und erforderliche Paginierungsvorgänge lokal durchführen.

Clientseitiger Pager

AWS CLI Version 2 ermöglicht die Verwendung eines clientseitigen Pager-Programms für die Ausgabe. Standardmäßig gibt diese Funktion alle Ausgaben über das Standard-Pager-Programm Ihres Betriebssystems zurück.

In der Reihenfolge der Rangfolge können Sie den Ausgabe-Pager wie folgt angeben:

  • Verwenden der Einstellung cli_pager in der Datei config im default oder einem benannten Profil.

  • Über die AWS_PAGER Umgebungsvariable.

  • Über die PAGER Umgebungsvariable.

In der Rangfolge können Sie die Verwendung eines externen Paging-Programms auf folgende Weise deaktivieren:

  • Verwenden Sie die --no-cli-pager-Befehlszeilenoption, um den Pager für eine einzelne Befehlsverwendung zu deaktivieren.

  • Setzen Sie die Einstellung cli_pager oder Variable AWS_PAGER auf eine leere Zeichenfolge.

Themen zu clientseitigem Pager:

So verwenden Sie die cli_pager-Einstellung

Sie können Ihre häufig verwendeten Konfigurationseinstellungen und Anmeldeinformationen in Dateien speichern, die von der AWS CLI verwaltet werden. Einstellungen in einem Namensprofil haben Vorrang vor den Einstellungen im default-Profil. Weitere Informationen zu den verschiedenen Konfigurationseinstellungen finden Sie unter Einstellungen der Konfigurations- und Anmeldeinformationsdatei in der AWS CLI.

Im folgenden Beispiel wird der Standard-Ausgabe-Pager auf das less-Programm eingestellt.

[default]
cli_pager=less

Im folgenden Beispiel wird die Standardeinstellung zur Deaktivierung der Verwendung eines Pagers festgelegt.

[default]
cli_pager=

So legen Sie die Umgebungsvariable AWS_PAGER fest

Im folgenden Beispiel wird der Standard-Ausgabe-Pager auf das less-Programm eingestellt. Weitere Informationen zu Umgebungsvariablen finden Sie unter Konfigurieren von Umgebungsvariablen für die AWS CLI.

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

So verwenden Sie die Option --no-cli-pager

Um die Verwendung eines Pagers für einen einzelnen Befehl zu deaktivieren, verwenden Sie die Option --no-cli-pager. Weitere Informationen zu diesen Befehlszeilenoptionen finden Sie unter Befehlszeilenoptionen in der AWS CLI.

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

So verwenden Sie Pager-Flags

Sie können Flags angeben, die automatisch mit Ihrem Paging-Programm verwendet werden sollen. Flags sind abhängig von dem Paging-Programm, das Sie verwenden. Die folgenden Beispiele beziehen sich auf die typischen Standardwerte von less und more.

Linux and macOS

Wenn Sie nichts anderes angeben, verwendet die AWS CLI Pager-Version 2 standardmäßig less. Wenn Sie die Umgebungsvariable LESS nicht festgelegt haben, verwendet die AWS CLI Version 2 die Flags FRX. Sie können Flags kombinieren, indem Sie sie beim Einstellen des Pagers AWS CLI angeben.

Im folgenden Beispiel wird die S-Flag verwendet. Dieses Flag wird dann mit den Standard-Flags FRX kombiniert, um ein endgültiges Flag FRXS zu erstellen.

$ export AWS_PAGER="less -S"

Wenn Sie keines der Flags FRX möchten, können Sie sie negieren. Im folgenden Beispiel wird das F-Flag negiert, um ein endgültiges RX-Flag zu erstellen.

$ export AWS_PAGER="less -+F"

Weitere Informationen zu less-Flags finden Sie unter weniger unter manpages.org.

Windows

Wenn Sie nichts anderes angeben, verwendet die AWS CLI Pager-Version 2 standardmäßig more ohne weitere Flags.

Im folgenden Beispiel wird der Parameter /c genutzt.

C:\> setx AWS_PAGER "more /c"

Weitere Informationen zu more-Flags finden Sie unter more auf Microsoft Docs.