Informazioni sulle cartelle nei bucket con spazio dei nomi gerarchico abilitato

Quando crei un bucket con lo spazio dei nomi gerarchico abilitato, il bucket archivia i dati in una vera struttura di file system, anziché in uno spazio dei nomi piatto standard. Le cartelle nei bucket con lo spazio dei nomi gerarchico abilitato consentono di organizzare gli oggetti utilizzando le directory, incluse funzionalità come la ridenominazione atomica delle cartelle. Questo documento descrive i metadati delle cartelle, le operazioni sulle cartelle, il modo in cui le cartelle interagiscono con le cartelle gestite e le considerazioni per l'utilizzo delle cartelle.

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

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

Metadati delle cartelle

I metadati di una cartella contengono informazioni strutturate sulla cartella. Per informazioni dettagliate sui metadati delle cartelle, consulta la risorsa Folder 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 cartelle in modo esplicito utilizzando l'operazione di creazione delle cartelle. Inoltre, quando crei un oggetto e specifichi una cartella inesistente nel suo 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 sulla denominazione delle cartelle, consulta le linee guida per la denominazione delle cartelle.

Elenca cartelle

Puoi recuperare un elenco di cartelle nel tuo 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 reale delle cartelle anziché simularle 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 delimiter su / consente di elencare le cartelle in una modalità simile a quella di una directory, restituendo solo le cartelle che corrispondono al prefisso o che esistono un livello sotto di questo.

L'operazione di elenco delle cartelle restituisce risultati impaginati. 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 le informazioni sulla risorsa 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.

Rinominare o spostare una cartella

La ridenominazione e lo spostamento di una cartella utilizzano la stessa operazione di base. 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 ed evita i costi di copia degli oggetti.

L'operazione di ridenominazione della cartella avvia un'operazione a lunga esecuzione. Il tempo necessario per il completamento dell'operazione dipende dal numero di cartelle rinominate, inclusa la cartella stessa e tutte le relative cartelle secondarie. Per monitorare l'avanzamento di un'operazione di ridenominazione di una cartella, consulta Utilizza operazioni a lunga esecuzione. Durante un'operazione di ridenominazione delle cartelle, 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 console Google Cloud , Rinomina cartella e Sposta cartella sono presentate come due opzioni distinte, ma entrambe 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 eliminarli esplicitamente.

Interazioni tra le cartelle e le cartelle gestite associate

Le cartelle gestite associate vengono utilizzate per controllare l'accesso alle cartelle nei bucket con 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 namespace gerarchico abilitato, tutte le cartelle mancanti nel suo percorso vengono create automaticamente, incluse le cartelle principali e la cartella di destinazione effettiva (nota anche come cartella associata).

    Ad esempio, supponiamo che crei un bucket con 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 le policy IAM associate vengono eliminate. Nei bucket con spazio dei nomi gerarchico abilitato, una cartella gestita non può esistere senza una cartella associata.

    Se non disponi delle autorizzazioni necessarie per eliminare la cartella gestita associata alla cartella, l'operazione di eliminazione della cartella non va a buon fine. Per trovare le autorizzazioni necessarie per eliminare le cartelle gestite, consulta Ottieni i ruoli richiesti per le cartelle gestite.

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

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

Linee guida per la denominazione delle cartelle

Quando crei le cartelle, consulta le seguenti linee guida:

  • La relazione tra i nomi degli oggetti e i nomi delle cartelle: nei bucket con namespace gerarchico abilitato, le cartelle e gli oggetti sono risorse distinte, anche se il nome di un oggetto include il percorso della cartella. Il nome di un oggetto è sempre il percorso completo all'interno del bucket (ad esempio dir1/foo.txt), mentre ogni barra (/) funge da delimitatore che posiziona l'oggetto all'interno di una risorsa cartella (ad esempio dir1/).

    I bucket con spazio dei nomi gerarchico abilitato supportano tutti i nomi degli oggetti validi, inclusi quelli con barre iniziali, finali o consecutive. Quando carichi un oggetto, Cloud Storage crea automaticamente tutte le risorse cartella mancanti nel suo percorso.

    La tabella seguente mostra come i nomi degli oggetti vengono mappati alle risorse cartella:

    Nome oggetto Cartella principale Posizione nella gerarchia delle cartelle
    foo.txt Cartella principale Ogni bucket ha una cartella principale senza nome. Poiché foo.txt non contiene barre, l'oggetto si trova direttamente nella cartella principale.
    dir1/foo.txt dir1/ Il nome completo dell'oggetto è dir1/foo.txt, non foo.txt. Si trova nella cartella di primo livello dir1/, che è distinta dalla cartella principale.
    dir1/ dir1/ Una barra finale non trasforma un oggetto in una cartella. Invece, un oggetto denominato dir1/ è una risorsa oggetto separata che si trova all'interno della cartella dir1/.
    /foo.txt / Una barra iniziale definisce una cartella di primo livello denominata /, che è distinta dalla cartella principale. L'oggetto /foo.txt si trova all'interno della cartella /.
    dir1//foo.txt dir1// Le barre consecutive definiscono le cartelle nidificate. L'oggetto dir1//foo.txt si trova nella cartella di secondo livello dir1//, che è un elemento secondario di dir1/.

  • 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 vengono elencati cartelle o oggetti in un bucket. Non includere informazioni sensibili o PII nei nomi delle cartelle.

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

  • Profondità massima delle cartelle: i bucket con spazio dei nomi gerarchico abilitato supportano una profondità massima delle cartelle di 50. Le cartelle possono essere create con un massimo di 50 cartelle secondarie impilate (ad esempio, folder1/folder2/folder3/.../folder50/my-data.txt). Tuttavia, se a una cartella è associata una cartella gestita, può avere un massimo di 15 cartelle secondarie impilate.

Passaggi successivi