Questa pagina mostra come elencare gli oggetti archiviati nei bucket Cloud Storage, ordinati nell'elenco lessicograficamente per nome.
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 vuoi restituire ACL degli oggetti come parte della richiesta o utilizzare la console Google Cloud per eseguire le attività in questa pagina, avrai bisogno di ruoli alternativi:
Se vuoi restituire ACL degli oggetti come parte della richiesta, chiedi all'amministratore di concederti il ruolo Amministratore oggetti Storage (
roles/storage.objectAdmin
) anziché il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer
).Se prevedi di utilizzare la console Google Cloud per eseguire le attività indicate in questa pagina, chiedi all'amministratore di concederti il ruolo Amministratore Storage (
roles/storage.admin
) anziché il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer
).In alternativa, puoi chiedere 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 visualizzare le autorizzazioni esatte necessarie, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
storage.objects.list
storage.objects.getIamPolicy
- Questa autorizzazione è necessaria solo se vuoi restituire ACL degli oggetti
storage.buckets.list
- Questa autorizzazione è necessaria solo se vuoi utilizzare la console Google Cloud per eseguire le attività in questa pagina.
Puoi ottenere queste autorizzazioni anche con altri ruoli predefiniti o ruoli personalizzati.
Per informazioni sulla concessione dei ruoli per i bucket, consulta Utilizzare IAM con i bucket.
Elenco degli oggetti in un bucket
Completa i seguenti passaggi per elencare gli oggetti in un bucket:
Console
- Nella console Google Cloud, vai alla pagina Bucket di Cloud Storage.
Nell'elenco dei bucket, fai clic sul nome del bucket di cui vuoi visualizzare il contenuto.
(Facoltativo) Utilizza i filtri per restringere i risultati nell'elenco.
Riga di comando
Utilizza il comando gcloud storage ls
con il flag --recursive
:
gcloud storage ls --recursive gs://BUCKET_NAME/**
Dove:
BUCKET_NAME
è il nome del bucket di cui vuoi elencare gli oggetti. Ad esempio,my-bucket
.
La risposta è simile al seguente esempio:
gs://my-bucket/cats.jpeg gs://my-bucket/dogs.jpeg gs://my-bucket/thesis.txt ...
Librerie client
C++
Per maggiori informazioni, consulta la documentazione di riferimento dell'API C++ di Cloud Storage.
Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Nell'esempio seguente sono elencati tutti gli oggetti in un bucket:
Nel seguente esempio sono elencati gli oggetti con un determinato prefisso:
C#
Per maggiori informazioni, consulta la documentazione di riferimento dell'API C# di Cloud Storage.
Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Nell'esempio seguente sono elencati tutti gli oggetti in un bucket:
Nel seguente esempio sono elencati gli oggetti con un determinato prefisso:
Go
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go di Cloud Storage.
Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Nell'esempio seguente sono elencati tutti gli oggetti in un bucket:
Nel seguente esempio sono elencati gli oggetti con un determinato prefisso:
Java
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di Cloud Storage.
Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Nell'esempio seguente sono elencati tutti gli oggetti in un bucket:
Nel seguente esempio sono elencati gli oggetti con un determinato prefisso:
Node.js
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Node.js di Cloud Storage.
Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Nell'esempio seguente sono elencati tutti gli oggetti in un bucket:
Nel seguente esempio sono elencati gli oggetti con un determinato prefisso:
PHP
Per maggiori informazioni, consulta la documentazione di riferimento dell'API PHP di Cloud Storage.
Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Nell'esempio seguente sono elencati tutti gli oggetti in un bucket:
Nel seguente esempio sono elencati gli oggetti con un determinato prefisso:
Python
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python di Cloud Storage.
Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Nell'esempio seguente sono elencati tutti gli oggetti in un bucket:
Nel seguente esempio sono elencati gli oggetti con un determinato prefisso:
Ruby
Per maggiori informazioni, consulta la documentazione di riferimento dell'API Ruby di Cloud Storage.
Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Nell'esempio seguente sono elencati tutti gli oggetti in un bucket:
Nel seguente esempio sono elencati gli oggetti con un determinato prefisso:
API REST
API JSON
- Richiedi un token di accesso all'autorizzazione da OAuth 2.0 Playground. Configura il parco giochi in modo che utilizzi le tue credenziali OAuth. Per le istruzioni, consulta Autenticazione API.
Utilizza
cURL
per chiamare l'API JSON con una richiesta di elencare gli oggetti:curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o"
Dove:
OAUTH2_TOKEN
è il token di accesso generato nel passaggio 1.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 cartelle gestite come parte dei risultati dell'elenco. Quando utilizzi il parametroincludeFoldersAsPrefixes
, il parametrodelimiter
deve essere impostato su/
.Per restituire gli ACL degli oggetti, aggiungi alla richiesta il parametro di query
projection
con il valorefull
. Tieni presente che gli ACL sono disabilitati e non possono essere restituiti se l'accesso uniforme a livello di bucket è abilitato nel bucket.
API XML
- Richiedi un token di accesso all'autorizzazione da OAuth 2.0 Playground. Configura il parco giochi in modo che utilizzi le tue credenziali OAuth. Per le istruzioni, consulta Autenticazione API.
Utilizza
cURL
per chiamare l'API XML con una richiesta bucketGET
:curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?list-type=2"
Dove:
OAUTH2_TOKEN
è il token di accesso generato nel passaggio 1.BUCKET_NAME
è il nome del bucket di cui vuoi elencare gli oggetti. Ad esempio,my-bucket
.
Puoi utilizzare un parametro di stringa di query
prefix=PREFIX
per limitare i risultati agli oggetti che hanno il prefisso specificato.
Filtro degli oggetti
Console
Per filtrare gli oggetti utilizzando la console Google Cloud, utilizza il campo Filtro nella pagina Dettagli bucket.
Riga di comando
Quando elenchi oggetti utilizzando Google Cloud CLI, puoi utilizzare i caratteri jolly per filtrare gli oggetti che iniziano con un prefisso specificato o terminano con un suffisso specificato. Ad esempio, il seguente comando corrisponde a .png
oggetti che iniziano con image
:
gcloud storage ls gs://my-bucket/image*.png
Per ulteriori informazioni sull'applicazione di filtri mediante Google Cloud CLI, consulta la documentazione di gcloud storage ls
.
API REST
API JSON
Quando elenchi gli oggetti utilizzando l'API JSON di Cloud Storage, puoi utilizzare i parametri della stringa di query prefix
o matchGlob
per filtrare i risultati. Per maggiori dettagli sull'utilizzo di questi parametri delle stringhe di query, consulta la documentazione di riferimento dell'API JSON per l'elenco degli oggetti.
Filtro per prefisso
Puoi utilizzare il parametro prefix=PREFIX
o della stringa di query per limitare i risultati agli oggetti o alle 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 degli oggetti utilizzando l'URL "https://storage.googleapis.com/storage/v1/b/my-bucket?prefix=folder/subfolder/"
.
L'utilizzo di prefix
per elencare i contenuti di una cartella gestita è utile quando hai l'autorizzazione per elencare solo gli oggetti nella cartella gestita, ma non l'intero bucket. Ad esempio, supponiamo che tu disponga del 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 gli 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 solo per gli oggetti che corrispondono a una specifica espressione glob. Ad esempio, matchGlob=**.jpeg
può
essere utilizzato per trovare corrispondenze di tutti gli oggetti i cui nomi 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 /
.
Passaggi successivi
- Scarica un oggetto dal bucket.
- Visualizzare e modificare i metadati degli oggetti.
- Elimina gli oggetti dal bucket.
- Scopri come suddividere in pagine i risultati.