Informazioni sulle cartelle nei bucket con spazio dei nomi gerarchico abilitato

Questa pagina fornisce informazioni sulle cartelle nei bucket con lo spazio dei nomi gerarchico abilitato.

Panoramica

Quando crei un bucket con lo spazio dei nomi gerarchico abilitato, il bucket utilizza una vera struttura di file system anziché uno spazio dei nomi semplice standard. Le cartelle esistono come risorsa nei bucket con lo spazio dei nomi gerarchico abilitato. Utilizzando le cartelle, puoi organizzare gli oggetti in modo più efficace e accedere a funzionalità di directory reali, come la ridenominazione atomica delle cartelle e operazioni di metadati efficienti.

Le cartelle nei bucket con lo spazio dei nomi gerarchico abilitato sono diverse dalle cartelle simulate e dalle cartelle gestite. Le cartelle simulate esistono nei bucket di spazi dei nomi semplici e le cartelle gestite possono essere applicate sia nei bucket di spazi dei nomi semplici sia nei bucket con lo spazio dei nomi gerarchico abilitato. Le cartelle gestite vengono utilizzate principalmente per concedere le autorizzazioni IAM a gruppi di oggetti. Per saperne di più su questi altri tipi di cartelle, consulta Tipi di cartelle.

Puoi gestire le cartelle eseguendo operazioni sulle cartelle. Per scoprire come creare, elencare ed eliminare le cartelle, nonché recuperare i metadati delle cartelle , consulta Creare e gestire le cartelle. Per scoprire come rinominare o spostare una cartella, consulta Rinominare una cartella.

Metadati delle cartelle

I metadati di una cartella contengono informazioni strutturate sulla cartella. Per informazioni dettagliate sui metadati delle cartelle, consulta la Folder risorsa nella documentazione di riferimento dell'API JSON di Cloud Storage.

I componenti chiave dei metadati di una cartella sono i seguenti:

  • bucket: il nome del bucket in cui si trova la cartella. Ad esempio, my-bucket.
  • id: un identificatore univoco per la cartella all'interno del bucket. Ad esempio, hns-bucket/dir1/.
  • kind: il tipo di risorsa. Per una cartella, questo valore è sempre storage#folder.
  • name: il nome della cartella. Ad esempio, dir1/.
  • selfLink: un URL che fa riferimento alla cartella nell'API Cloud Storage.
  • timeCreated: il timestamp della creazione della cartella. Ad esempio, 2023-05-05T16:32:08.878000+00:00.
  • updated: il timestamp dell'ultimo aggiornamento della cartella. Ad esempio, 2024-05-06T16:32:08.878000+00:00.

Operazioni sulle cartelle

Questa sezione descrive le operazioni che puoi eseguire sulle cartelle. Alcune operazioni avviano un'operazione a lunga esecuzione che puoi monitorare per tenere traccia dell'avanzamento e dello stato dell'operazione.

Crea una cartella

Puoi creare esplicitamente le cartelle utilizzando l'operazione di creazione delle cartelle. Inoltre, quando crei un oggetto e specifichi una cartella inesistente nel relativo percorso, la cartella principale mancante viene creata automaticamente. Ad esempio, la creazione di un oggetto denominato dir1/foo.txt crea automaticamente la cartella dir1/ se non esiste già.

Per informazioni sull'assegnazione dei nomi alle cartelle, consulta Considerazioni.

Elenca cartelle

Puoi recuperare un elenco di cartelle nel bucket utilizzando l'operazione di elenco delle cartelle. Poiché le cartelle sono risorse distinte nei bucket con lo spazio dei nomi gerarchico abilitato, questa operazione valuta la struttura delle cartelle effettiva anziché simulare le cartelle dai percorsi degli oggetti.

Quando elenchi le cartelle, puoi filtrare i risultati utilizzando parametri come prefix, delimiter, lexicographicStart e lexicographicEnd. Ad esempio, l'impostazione del parametro delimitatore su / consente di elencare le cartelle in modalità simile a una directory, restituendo solo le cartelle che corrispondono al prefisso o che esistono un livello sotto.

L'operazione di elenco delle cartelle restituisce risultati paginati. Una singola pagina di risposta può contenere un massimo di 1000 cartelle.

Recupera i metadati di una cartella

Puoi recuperare le proprietà di una cartella utilizzando l'operazione di recupero dei metadati della cartella. Questa operazione recupera informazioni sulla risorsa della cartella stessa, anziché sugli oggetti che contiene.

Questa operazione restituisce i metadati di una cartella, che forniscono informazioni strutturate come il timestamp di creazione, l'identificatore univoco e il bucket in cui si trova. Per un elenco dettagliato delle proprietà restituite da questa operazione, consulta Metadati delle cartelle.

Rinomina o sposta una cartella

La ridenominazione e lo spostamento di una cartella utilizzano la stessa operazione sottostante. L'operazione è una modifica atomica solo dei metadati che aggiorna il percorso della cartella senza copiare o eliminare fisicamente gli oggetti sottostanti. La ridenominazione di una cartella aggiorna anche il percorso della cartella per le risorse al suo interno, come cartelle secondarie, oggetti e cartelle gestite. In questo modo l'operazione è rapida e si evitano i costi di copia degli oggetti.

L'operazione di ridenominazione della cartella avvia un'operazione a lunga esecuzione.

Durante un'operazione di ridenominazione della cartella, puoi leggere ed elencare le cartelle che vengono rinominate, ma non puoi eseguire operazioni di scrittura su di esse.

Nell'API JSON e in Google Cloud CLI, le operazioni di ridenominazione e spostamento utilizzano lo stesso endpoint URL o comando. Nella Google Cloud console, Rinomina cartella e Sposta cartella vengono presentate come due opzioni distinte, ma entrambe le opzioni eseguono la stessa operazione di backend.

Elimina una cartella

Puoi eliminare definitivamente una cartella utilizzando l'operazione di eliminazione della cartella. Sebbene le cartelle possano essere create automaticamente durante le operazioni sugli oggetti, non vengono rimosse automaticamente quando diventano vuote. Devi eliminarle esplicitamente.

Interazioni tra cartelle e cartelle gestite associate

Le cartelle gestite associate vengono utilizzate per controllare l'accesso alle cartelle nei bucket con lo spazio dei nomi gerarchico abilitato. Le cartelle e le cartelle gestite associate interagiscono nei seguenti modi:

  • Creazione di cartelle: quando crei una cartella gestita in un bucket con lo spazio dei nomi gerarchico abilitato, le cartelle mancanti nel relativo percorso vengono create automaticamente, incluse le cartelle principali e la cartella di destinazione effettiva (nota anche come cartella associata).

    Ad esempio, supponiamo che tu crei un bucket con lo spazio dei nomi gerarchico abilitato denominato my-bucket. Se crei una cartella gestita denominata 2025/training-data/ nel bucket, Cloud Storage crea automaticamente la cartella principale 2025/ e la cartella associata di destinazione training-data/ nel bucket.

  • Eliminazione di cartelle: quando elimini una cartella con una cartella gestita associata, Cloud Storage elimina anche la cartella gestita associata. Questo perché quando elimini una cartella, elimini l'intero percorso. Poiché il percorso non esiste più, la cartella gestita associata e tutti i criteri IAM ad essa collegati vengono eliminati. Nei bucket con lo spazio dei nomi gerarchico abilitato, una cartella gestita non può esistere senza una cartella associata.

    Se non disponi delle autorizzazioni richieste per eliminare la cartella gestita associata alla cartella, l'operazione di eliminazione della cartella non riesce. Per trovare le autorizzazioni richieste per l'eliminazione delle cartelle gestite, consulta Ottenere i ruoli richiesti per le cartelle gestite.

  • Ridenominazione di cartelle: quando rinomini una cartella con una cartella gestita associata, Cloud Storage rinomina anche la cartella gestita associata.

Per informazioni sui requisiti di denominazione per le cartelle con una cartella gestita associata, consulta Denominazione delle cartelle.

Considerazioni

Quando crei le cartelle, tieni presente quanto segue:

  • Nomi di oggetti e cartelle: i bucket con lo spazio dei nomi gerarchico abilitato, supportano tutti i nomi di oggetti validi, inclusi quelli con barre (/) iniziali, finali o consecutive. Ogni barra (/) nel nome di un oggetto rappresenta una cartella. La seguente tabella mostra esempi della relazione tra i nomi degli oggetti e la relativa posizione nella gerarchia delle cartelle:

    Nome oggetto Posizione nella gerarchia delle cartelle
    foo.txt Ogni bucket include una cartella principale. L'oggetto foo.txt si trova nella cartella principale del bucket.
    dir1/foo.txt L'oggetto foo.txt si trova in una cartella di primo livello denominata dir1/. La cartella di primo livello è diversa dalla cartella principale.
    dir1/ La barra finale nei nomi degli oggetti come dir1/ indica che l'oggetto si trova all'interno della cartella. In questo esempio, il nome dell'oggetto dir1/ è uguale al nome della cartella principale dir1/.
    dir1//foo.txt L'oggetto foo.txt si trova in una cartella di secondo livello denominata dir1//, una cartella secondaria di dir1/.

  • Profondità massima della cartella: i bucket con lo spazio dei nomi gerarchico abilitato supportano una profondità massima della cartella di 50. È possibile creare cartelle con un massimo di 50 cartelle secondarie impilate (ad esempio, folder1/folder2/folder3/.../folder50/my-data.txt). Tuttavia, se una cartella ha una cartella gestita associata, può avere solo fino a 15 cartelle secondarie impilate.

  • Dimensione massima del nome della cartella: 512 byte (codificati in UTF-8).

  • Informazioni sensibili o che consentono l'identificazione personale (PII): i nomi delle cartelle sono più visibili dei metadati delle cartelle. Ad esempio, i nomi delle cartelle vengono visualizzati negli URL e quando elenchi le cartelle o gli oggetti in un bucket. Non includere informazioni sensibili o PII nei nomi delle cartelle.

Passaggi successivi

Provalo

Se non conosci Google Cloud, crea un account per valutare le prestazioni di Cloud Storage in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

Prova Cloud Storage senza costi