Questa documentazione è valida AWS CLI solo per la versione 1. Per la documentazione relativa alla versione 2 di AWS CLI, consulta la Guida per l'utente della versione 2.

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Utilizzo delle opzioni di paginazione della AWS CLI

In questo argomento vengono descritti i diversi modi per paginare l’output dall’AWS Command Line Interface (AWS CLI).

Paginazione lato server

Per i comandi che possono restituire un elenco di voci di grandi dimensioni, AWS CLI aggiunge diverse opzioni lato server opzioni che consentono di controllare il numero di voci incluse nell’output quando la AWS CLI chiama un’API del servizio per compilare l’elenco. La paginazione lato server in AWS CLI è abilitata dall’API del servizio AWS, pertanto queste opzioni funzionano solo se l’API del servizio le abilita.

Per impostazione predefinita, AWS CLI utilizza una dimensione di pagina determinata dal singolo servizio e recupera tutti gli elementi disponibili. Ad esempio, Amazon S3 ha una dimensione di pagina predefinita di 1000. Se esegui aws s3api list-objects in un bucket che contiene 3500 oggetti, la AWS CLI effettua automaticamente quattro chiamate a Amazon S3, gestendo la logica di paginazione specifica del servizio in background e restituendo tutti i 3500 oggetti nell’output finale.

Per informazioni sulla paginazione lato server di uno specifico comando, consulta la AWS CLI reference guide.

Come utilizzare il parametro --no-paginate

L’opzione --no-paginate disabilita i token di paginazione seguenti sul lato client. Quando si utilizza un comando, per impostazione predefinita la AWS CLI effettua automaticamente più chiamate per restituire tutti i risultati possibili per creare la paginazione. Una chiamata per ogni pagina. Disabilitando la paginazione, la AWS CLI effettua una sola chiamata per la prima pagina dei risultati del comando.

Ad esempio, se esegui aws s3api list-objects su un bucket Amazon S3 che contiene 3.500 oggetti, la AWS CLI effettua solo la prima chiamata ad Amazon S3, restituendo solo i primi 1.000 oggetti nell’output finale.

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

Come utilizzare il parametro --page-size

Se vengono rilevati errori quando esegui i comandi dell’elenco per un numero elevato di risorse, le dimensioni di pagina predefinite potrebbero essere eccessive. Questo può causare il superamento del tempo massimo consentito per le chiamate ai servizi AWS e la generazione di un errore di tipo "timeout". Puoi utilizzare l'opzione --page-size per specificare che AWS CLI richieda un numero minore di elementi da ciascuna chiamata al servizio AWS. La AWS CLI recupera comunque l’elenco completo, ma esegue un maggior numero di chiamate API in background e recupera un numero di elementi inferiore per ogni chiamata. In questo modo, le chiamate individuali hanno una migliore possibilità di completamento prima della scadenza. La modifica delle dimensioni della pagina non pregiudica l'output, ma solo il numero di chiamate API che deve essere effettuato per generare l'output.

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

Come utilizzare il parametro --max-items

Per includere un numero minore di elementi alla volta nell'output di AWS CLI, utilizza l'opzione --max-items. L'AWS CLI gestisce ancora la paginazione con il servizio come descritto in precedenza, ma stampa solo il numero di voci al momento specificato.

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

Come utilizzare il parametro --starting-token

Se l'output del numero di elementi (--max-items) è inferiore rispetto al numero totale di elementi restituito dalle chiamate API sottostanti, l'output include NextToken, che può essere trasferito a un comando successivo per recuperare il set di elementi successivo. L'esempio seguente mostra come usare il valore NextToken restituito dall'esempio precedente e consente di recuperare il secondo centinaio di elementi.

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

Il servizio AWS specificato potrebbe non restituire gli elementi nello stesso ordine ogni volta che effettui la chiamata. Se si specificano valori diversi per --page-size e --max-items, puoi ottenere risultati imprevisti con elementi mancanti o duplicati. Per evitarlo, utilizza lo stesso numero per --page-size e --max-items per sincronizzare la paginazione della AWS CLI con quella del servizio sottostante. Puoi anche recuperare l'intero elenco ed eseguire tutte le operazioni di paginazione necessarie in locale.