Questa pagina mostra come elencare gli oggetti archiviati nei bucket Cloud Storage, che sono ordinati in modo lessicografico per nome nell'elenco.
Prima di iniziare
Per ottenere le autorizzazioni necessarie per elencare gli oggetti, chiedi all'amministratore
di concederti il ruolo IAM Visualizzatore oggetti Storage (roles/storage.objectViewer
)
per il bucket che contiene gli oggetti che vuoi
elencare.
Se prevedi di utilizzare la console Google Cloud per eseguire le attività descritte in questa pagina,
chiedi all'amministratore di concederti il ruolo di base Visualizzatore (roles/viewer
) oltre al ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer
).
Questi ruoli contengono le autorizzazioni necessarie per elencare gli oggetti. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
storage.objects.list
storage.buckets.list
- Questa autorizzazione è necessaria solo se vuoi utilizzare la console Google Cloud per eseguire le attività in questa pagina.
Puoi anche ottenere queste autorizzazioni con altri ruoli predefiniti o ruoli personalizzati.
Per informazioni sulla concessione dei ruoli per i bucket, consulta Utilizzare IAM con i bucket.
Elenca gli oggetti in un bucket
Per elencare gli oggetti in un bucket:
Console
- Nella console Google Cloud , vai alla pagina Bucket in Cloud Storage.
Nell'elenco dei bucket, fai clic sul nome del bucket di cui vuoi visualizzare i contenuti.
(Facoltativo) Utilizza filtri e ordinamenti per limitare e organizzare i risultati nell'elenco.
Riga di comando
Utilizza il comando gcloud storage ls
:
gcloud storage ls gs://BUCKET_NAME
Dove:
BUCKET_NAME
è il nome del bucket che contiene gli oggetti che vuoi elencare. Ad esempio,my-bucket
.
Librerie client
C++
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage C++.
Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Il seguente esempio elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
C#
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage C#.
Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Il seguente esempio elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
Go
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Go.
Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Il seguente esempio elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
Java
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Java.
Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Il seguente esempio elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
Node.js
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Node.js.
Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Il seguente esempio elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
PHP
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage PHP.
Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Il seguente esempio elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
Python
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Python.
Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Il seguente esempio elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
Ruby
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Ruby.
Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Il seguente esempio elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
API REST
API JSON
Avere gcloud CLI installata e inizializzata, il che ti consente di generare un token di accesso per l'intestazione
Authorization
.Utilizza
cURL
per chiamare l'API JSON con una richiesta di elencare gli oggetti:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o"
Dove
BUCKET_NAME
è il nome del bucket di cui vuoi elencare gli oggetti. Ad esempio,my-bucket
.Puoi utilizzare il parametro di query
includeFoldersAsPrefixes=True
per restituire le cartelle gestite come parte dei risultati dell'elenco. Quando utilizzi il parametroincludeFoldersAsPrefixes
, il parametrodelimiter
deve essere impostato su/
.
API XML
Avere gcloud CLI installata e inizializzata, il che ti consente di generare un token di accesso per l'intestazione
Authorization
.Utilizza
cURL
per chiamare l'API XML con una richiestaGET
Bucket:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME?list-type=2"
Dove
BUCKET_NAME
è il nome del bucket di cui vuoi elencare gli oggetti. Ad esempio,my-bucket
.Puoi utilizzare un parametro della stringa di query
prefix=PREFIX
per limitare i risultati agli oggetti che hanno il prefisso specificato.
Filtrare gli oggetti
Quando elenchi gli oggetti, puoi utilizzare prefissi o suffissi nella richiesta di elenco per filtrarli in base al nome.
Console
Per filtrare gli oggetti in base al prefisso del nome utilizzando la console Google Cloud , utilizza il campo Filtra oggetti e cartelle nella pagina Dettagli bucket.
Consulta Filtro e ordinamento per altre opzioni di filtro disponibili utilizzando la console Google Cloud .
Riga di comando
Puoi utilizzare i caratteri jolly nel comando gcloud storage ls
per
filtrare gli oggetti in base al prefisso o al suffisso. Ad esempio, il seguente comando
elenca solo gli oggetti nel bucket my-bucket
il cui nome inizia con
image
e termina con .png
:
gcloud storage ls gs://my-bucket/image*.png
Se la richiesta ha esito positivo, la risposta è simile alla seguente:
gs://my-bucket/image.png gs://my-bucket/image-dog.png gs://my-bucket/image-cat.png ...
Puoi utilizzare i caratteri jolly a doppia stella per trovare corrispondenze con zero o più livelli di directory in un percorso. Ad esempio, il seguente comando elenca solo gli oggetti il cui nome termina con .jpeg
in qualsiasi directory all'interno del bucket my-bucket
:
gcloud storage ls gs://my-bucket/**/*.jpeg
Se la richiesta ha esito positivo, la risposta è simile alla seguente:
gs://my-bucket/puppy.jpeg gs://my-bucket/pug.jpeg gs://my-bucket/pets/dog.jpeg ...
API REST
API JSON
Quando elenchi gli oggetti utilizzando l'API Cloud Storage JSON, puoi
utilizzare i parametri della stringa di query prefix
o matchGlob
per
filtrare i risultati. Per informazioni dettagliate sull'utilizzo di questi parametri
della stringa di query, consulta la
documentazione di riferimento dell'API JSON per l'elenco degli oggetti.
Filtrare per prefisso
Puoi utilizzare il parametro prefix=PREFIX
o della stringa di query
per limitare i risultati a oggetti o cartelle gestite che hanno
il prefisso specificato. Ad esempio, per elencare tutti gli oggetti nel bucket
my-bucket
con il prefisso folder/subfolder/
, crea una richiesta di elenco di oggetti
utilizzando l'URL
"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"
.
L'utilizzo di prefix
per elencare i contenuti di una cartella gestita è utile quando hai solo l'autorizzazione per elencare gli oggetti nella cartella gestita, ma non nell'intero bucket. Ad esempio, supponiamo che tu abbia il ruolo IAM
Visualizzatore oggetti Storage (roles/storage.objectViewer
) per la cartella gestita my-bucket/my-managed-folder-a/
, ma non per
la cartella gestita my-bucket/my-managed-folder-b/
. Per restituire solo gli
oggetti in my-managed-folder-a
, puoi specificare
prefix=my-managed-folder-a/
.
Quando limiti i risultati a una cartella gestita e agli oggetti al suo interno,
devi terminare PREFIX
con /
(ad esempio,
prefix=my-managed-folder/
). In caso contrario, i risultati possono includere anche
oggetti adiacenti alla cartella gestita. In questo esempio,
hai un bucket che contiene i seguenti oggetti:
my-bucket/abc.txt
my-bucket/abc/object.txt
Se specifichi prefix=abc/
, puoi restituire gli oggetti
my-bucket/abc/object.txt
, mentre se specifichi prefix=abc
, puoi restituire
sia my-bucket/abc.txt
che my-bucket/abc/object.txt
.
Filtro per espressione glob
Puoi utilizzare il parametro della stringa di query matchGlob=GLOB_PATTERN
per filtrare i risultati in modo da visualizzare solo gli oggetti che corrispondono a una espressione glob specifica. Ad esempio, matchGlob=**.jpeg
può
essere utilizzato per trovare tutti gli oggetti che terminano con .jpeg
.
Le richieste che utilizzano il parametro matchGlob
non vanno a buon fine se includono anche
un parametro delimiter
impostato su un valore diverso da /
.
Considerazioni sul rendimento durante l'elenco degli oggetti
La struttura sottostante dei bucket con lo spazio dei nomi gerarchico abilitato influisce sulle prestazioni dell'operazione di elenco degli oggetti rispetto ai bucket con spazio dei nomi piatto. Per ulteriori informazioni, vedi Ottimizzare le prestazioni nei bucket con lo spazio dei nomi gerarchico abilitato.
Passaggi successivi
- Scarica un oggetto dal bucket.
- Visualizzare e modificare i metadati degli oggetti.
- Elimina gli oggetti dal bucket.
- Scopri come impaginare i risultati.