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 vuoi elencare gli oggetti all'interno delle cartelle gestite, puoi concedere
roles/storage.objectViewer alla cartella gestita che contiene gli oggetti
che vuoi visualizzare anziché al bucket.
Se prevedi di utilizzare la console Cloud de Confiance 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.liststorage.buckets.list- Questa autorizzazione è necessaria solo se vuoi utilizzare la console Cloud de Confiance 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 Impostare e gestire le policy IAM sui bucket.
Elenca gli oggetti in un bucket
Console
- Nella console Cloud de Confiance , vai alla pagina Bucket in Cloud Storage.
Nell'elenco dei bucket, fai clic sul nome del bucket di cui vuoi visualizzare i contenuti.
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 saperne di più, 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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.
L'esempio seguente elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
C#
Per saperne di più, 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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.
L'esempio seguente elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
Go
Per saperne di più, 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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.
L'esempio seguente elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
Java
Per saperne di più, 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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.
L'esempio seguente elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
Node.js
Per saperne di più, 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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.
L'esempio seguente elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
PHP
Per saperne di più, 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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.
L'esempio seguente elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
Python
Per saperne di più, 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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.
L'esempio seguente elenca tutti gli oggetti in un bucket:
Il seguente esempio elenca gli oggetti con un determinato prefisso:
Ruby
Per saperne di più, 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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.
L'esempio seguente 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
cURLper chiamare l'API JSON con una richiesta di elencare gli oggetti:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o"
dove
BUCKET_NAMEè il nome del bucket di cui vuoi elencare gli oggetti. Ad esempio,my-bucket.
API XML
Avere gcloud CLI installata e inizializzata, il che ti consente di generare un token di accesso per l'intestazione
Authorization.Utilizza
cURLper chiamare l'API XML con una richiesta bucketGET:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.s3nsapis.fr/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=PREFIXper limitare i risultati agli oggetti che hanno il prefisso specificato.
Elenca gli oggetti in una cartella
Console
- Nella console Cloud de Confiance , vai alla pagina Bucket in Cloud Storage.
Nell'elenco dei bucket, fai clic sul nome del bucket che contiene la cartella.
Nella scheda Oggetti della pagina Dettagli bucket, fai clic sul nome della cartella di cui vuoi visualizzare i contenuti.
Riga di comando
Utilizza il comando gcloud storage ls per elencare gli oggetti in una cartella:
gcloud storage ls gs://BUCKET_NAME/FOLDER_NAME
Dove:
BUCKET_NAMEè il nome del bucket che contiene la cartella. Ad esempio,my-bucket.FOLDER_NAMEè il nome della cartella che contiene gli oggetti che vuoi elencare. Ad esempio,my-folder.
API REST
API JSON
Per elencare gli oggetti in una cartella, utilizza una richiesta di elenco degli oggetti
con i parametri prefix e delimiter. Quando è impostato il parametro prefix, l'operazione di elenco è limitata alla restituzione solo di oggetti
e cartelle con il prefisso. Quando il parametro delimiter è impostato,
l'elenco prefixes[] nella risposta viene compilato con i nomi
delle cartelle con il prefisso specificato.
Ad esempio:
Per elencare tutti gli oggetti nella cartella
image/all'interno del bucketmy-bucket, utilizza il seguente URL:"https://storage.s3nsapis.fr/storage/v1/b/my-bucket/o?prefix=image&delimiter=/".In questo caso, potrebbero essere restituiti gli oggetti
my-bucket/image/cat.jpegemy-bucket/image/dog.jpeg.Per includere gli oggetti nelle sottocartelle all'interno di
image/, rimuovi il parametrodelimiter:"https://storage.s3nsapis.fr/storage/v1/b/my-bucket/o?prefix=image".In questo modo potrebbero essere restituiti gli oggetti
my-bucket/image/cat.jpeg,my-bucket/image/dog.jpegemy-bucket/image/dog/shiba.jpeg.
Per utilizzare i caratteri jolly nella richiesta di oggetti elenco e trovare corrispondenze tra gli oggetti in base all'espressione glob, utilizza il parametro matchGlob. Ad esempio, matchGlob=**.jpeg corrisponde a tutti
gli oggetti che terminano con .jpeg. Quando utilizzi matchGlob, devi impostare
delimiter su /.
Ad esempio, utilizza il seguente URL per trovare la corrispondenza di tutti gli oggetti all'interno della
cartella image che terminano con .jpeg:
"https://storage.s3nsapis.fr/storage/v1/b/my-bucket/o?prefix=image&delimiter=/&matchGlob=**.jpeg"
Per ulteriori dettagli sull'utilizzo dei parametri per filtrare gli oggetti, consulta la documentazione di riferimento dell'API JSON per l'elenco degli oggetti.
Caso d'uso
L'utilizzo di prefix per elencare i contenuti di una cartella può essere utile
quando hai solo l'autorizzazione per elencare gli oggetti nella cartella, ma non
l'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/.
Filtrare gli oggetti
Quando elenchi gli oggetti, puoi utilizzare prefissi o suffissi nella richiesta di elenco per filtrare gli oggetti per nome.
Console
Consulta Filtro e ordinamento per informazioni su come filtrare e ordinare gli oggetti in bucket o cartelle.
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 cartelle in un percorso. Ad esempio, il seguente comando elenca solo gli oggetti il cui nome
termina con .jpeg in qualsiasi cartella o sottocartella 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
Consulta Elencare gli oggetti nelle cartelle per informazioni su come filtrare gli oggetti in base al prefisso del nome della cartella o dell'oggetto.
Filtrare gli oggetti per contesti
Puoi utilizzare un filtro per mostrare solo gli oggetti che hanno i contesti specificati (anteprima) nella risposta dell'elenco.
Riga di comando
Utilizza il comando gcloud alpha storage objects list:
gcloud alpha storage objects list gs://BUCKET_NAME --metadata-filter='contexts."KEY"="VALUE"'
Dove:
BUCKET_NAMEè il nome del bucket contenente l'oggetto in base al quale vuoi filtrare il contesto. Ad esempio,my-bucket.KEYè la chiave di contesto collegata all'oggetto.VALUEè il valore associato alla chiave di contesto.
Se l'operazione ha esito positivo, la risposta è simile al seguente esempio:
---
bucket: my-bucket
contexts:
Department:
createTime: '2023-01-01T00:00:00.000000+00:00'
type: CUSTOM
updateTime: '2023-01-01T00:00:00.000000+00:00'
value: HR
DataClassification:
createTime: '2023-01-01T00:00:00.000000+00:00'
type: CUSTOM
updateTime: '2023-01-01T00:00:00.000000+00:00'
value: Confidential
name: employees.txt
...
Librerie client
Java
Per saperne di più, 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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN su s3nsapis.fr.
API REST
API JSON
La richiesta Object: list mostra un esempio di come utilizzare il parametro di query filter:
curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o/?filter=contexts.%22KEY%22%3D%22VALUE%22"
Dove:
BUCKET_NAMEè il nome del bucket contenente l'oggetto in base al cui contesto vuoi filtrare. Ad esempio,my-bucket.KEYè la chiave di contesto collegata all'oggetto.VALUEè il valore associato alla chiave di contesto.
Sintassi
Cloud Storage supporta la seguente sintassi per il filtro.
| Sintassi | Descrizione |
|---|---|
contexts."KEY":* |
Corrisponde a qualsiasi oggetto a cui è associato un contesto con la chiave specificata. |
contexts."KEY"="VALUE" |
Corrisponde a qualsiasi oggetto che abbia un contesto con la chiave e il valore specificati allegati. |
|
OR
|
Corrisponde a qualsiasi oggetto che non ha un contesto con la chiave specificata allegata. |
|
OR
|
Corrisponde a qualsiasi oggetto che non ha un contesto con la chiave e il valore specificati allegati. |
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 dello spazio dei nomi piatto. Per saperne di più, consulta 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.