Informazioni sugli oggetti Cloud Storage

Gli oggetti sono i singoli dati archiviati nei bucket Cloud Storage. Puoi caricare, organizzare e recuperare dati non strutturati in una varietà di formati e dimensioni.

Per una panoramica generale del funzionamento di Cloud Storage, consulta la panoramica del prodotto Cloud Storage.

Oggetti

Gli oggetti sono costituiti da due componenti: dati dell'oggetto e metadati dell'oggetto. I dati degli oggetti sono in genere un file che vuoi archiviare in Cloud Storage e sono completamente opachi per Cloud Storage. I metadati degli oggetti sono una raccolta di coppie nome-valore che descrivono varie qualità degli oggetti.

Due importanti elementi dei metadati degli oggetti comuni a tutti gli oggetti sono il nome e il numero di generazione dell'oggetto. Quando aggiungi un oggetto a un bucket Cloud Storage, specifichi il nome dell'oggetto e Cloud Storage assegna il numero di generazione. Insieme, il nome e la generazione identificano in modo univoco l'oggetto all'interno del bucket.

Non esiste un limite al numero di oggetti che puoi creare in un bucket.

Puoi utilizzare Identity and Access Management (IAM) per controllare l'accesso a tutti gli oggetti all'interno di un bucket o di una cartella gestita. Puoi anche utilizzare gli elenchi di controllo dell'accesso (ACL) per controllare l'accesso ai singoli oggetti.

Considerazioni sulla denominazione

Quando assegni un nome agli oggetti in Cloud Storage, è essenziale rispettare requisiti specifici per garantire la compatibilità ed evitare errori. Questi requisiti si applicano sia ai bucket di spazi dei nomi piatti sia ai bucket abilitati per gli spazi dei nomi gerarchici.

Requisiti generali

  • I nomi degli oggetti possono contenere qualsiasi sequenza di caratteri Unicode validi.
  • I nomi degli oggetti non possono contenere caratteri di ritorno a capo o avanzamento riga.
    • Tieni presente che le barre rovesciate inviate tramite interfacce come gcloud CLI e la console Google Cloud vengono sottoposte a escape in background. Ad esempio, \n diventa \\n. La limitazione relativa al ritorno a capo e all'avanzamento riga si riferisce rigorosamente ai caratteri di escape ANSI.
  • I nomi degli oggetti non possono iniziare con .well-known/acme-challenge/.
  • Gli oggetti non possono essere denominati . o ...

Limiti delle dimensioni degli oggetti specifici per lo spazio dei nomi

La dimensione massima del nome di un oggetto varia a seconda dello spazio dei nomi del bucket:

  • Dimensioni del nome dell'oggetto in un bucket con spazio dei nomi semplice: 1-1024 byte se codificato in UTF-8.

  • Dimensioni dei nomi degli oggetti nei bucket abilitati con spazio dei nomi gerarchico: i nomi degli oggetti nei bucket con spazio dei nomi gerarchico abilitato sono divisi in due parti: il segmento del nome della cartella e il segmento del nome di base.

    • Segmento del nome della cartella: il segmento del percorso di un oggetto che definisce le cartelle in cui si trova l'oggetto. La dimensione massima del segmento del nome della cartella è di 512 byte se codificato in UTF-8.
    • Segmento del nome di base: il segmento del percorso di un oggetto che definisce il file stesso, separato dalle cartelle principali in cui si trova. La dimensione massima del segmento del nome di base è di 512 byte se codificato in UTF-8.

    Ad esempio, nel percorso dell'oggetto my-folder-1/my-folder-2/my-object.txt, il segmento del nome della cartella è my-folder-1/my-folder-2/ e il segmento del nome di base è my-object.txt.

Consigli

Ti consigliamo vivamente di evitare quanto segue nei nomi degli oggetti:

  • Caratteri di controllo non consentiti in XML 1.0 (#x7F–#x84 e #x86–#x9F). Questi caratteri causano problemi di elenco XML quando provi a elencare i tuoi oggetti.
  • Il carattere #. I comandi di Google Cloud CLI interpretano i nomi degli oggetti che terminano con #NUMERIC_STRING come identificatori di versione, pertanto l'inclusione di # nei nomi degli oggetti può rendere difficile o impossibile eseguire operazioni su questi oggetti con versionamento utilizzando gcloud CLI.
  • I caratteri [, ], * o ?. I comandi di Google Cloud CLI interpretano questi caratteri come caratteri jolly, pertanto includerli nei nomi degli oggetti può rendere difficile o impossibile eseguire operazioni con caratteri jolly. Inoltre, * e ? non sono caratteri validi per i nomi file in Windows.
  • I caratteri :, ", <, > o |. Questi non sono caratteri validi per i nomi file in Windows, pertanto i tentativi di scaricare un oggetto che utilizza questi caratteri nel nome in un file Windows non vanno a buon fine, a meno che il metodo di download non includa la ridenominazione del file Windows risultante. Il carattere /, sebbene non sia un carattere valido per i nomi file in Windows, è in genere accettabile per l'utilizzo nei nomi degli oggetti per simulare una struttura di directory; strumenti come Google Cloud CLI convertono automaticamente il carattere in \ durante il download in un ambiente Windows.
  • Le sequenze di caratteri ./ e ../. Queste sequenze di caratteri creano cartelle simulate utilizzando punti singoli o doppi per il nome della cartella, ad esempio folder/./object.txt o folder/../object.txt. Tuttavia, quando scarichi una cartella, le librerie client e gcloud CLI interpretano i segmenti di percorso contenenti solo punti come percorsi file relativi. Questo comportamento significa che gli oggetti potrebbero essere sovrascritti o non essere scaricati.
    • Un singolo punto nel segmento del percorso viene interpretato come la directory corrente. Ad esempio, supponiamo che tu scarichi gli oggetti my-object.txt e ./my-object.txt nella stessa destinazione. Il primo oggetto viene scaricato in /destination-directory/my-object.txt. Il riferimento . sul secondo oggetto viene risolto e il percorso effettivo cambia da /destination-directory/./my-object.txt a /destination-directory/my-object.txt, sovrascrivendo l'altro oggetto che esiste già nello stesso percorso.
    • Un doppio punto nel segmento del percorso viene interpretato come la directory principale. Se il percorso finale di un oggetto scaricato si trova al di fuori della directory di destinazione, l'oggetto non viene scaricato. Gli oggetti che non vengono scaricati vengono restituiti nella risposta a una richiesta di download della directory.
  • Informazioni sensibili o che consentono l'identificazione personale (PII). I nomi degli oggetti sono più visibili dei dati degli oggetti. Ad esempio, i nomi degli oggetti vengono visualizzati negli URL degli oggetti e quando vengono elencati gli oggetti in un bucket.

Gli oggetti esistenti non possono essere rinominati direttamente, ma puoi rinominare un oggetto indirettamente copiando ed eliminando l'oggetto originale.

Spazio dei nomi degli oggetti

Puoi archiviare gli oggetti nei seguenti spazi dei nomi:

Spazio dei nomi piatto

I bucket configurati per archiviare oggetti in uno spazio dei nomi piatto creano sempre oggetti direttamente nel bucket. In questi bucket con spazio dei nomi piatto, non esiste una gerarchia all'interno del bucket e non esistono directory o cartelle in cui si trovano gli oggetti.

Per praticità, esistono diversi modi in cui gli oggetti nei bucket con spazio dei nomi piatto vengono trattati come se fossero archiviati in una gerarchia di cartelle:

  • Le cartelle gestite sono una risorsa di Cloud Storage che fornisce un accesso esteso a gruppi di oggetti con un prefisso del nome condiviso.

  • Strumenti come Google Cloud console e Google Cloud CLI interpretano il carattere barra (/) nel nome di un oggetto come delimitatore, in modo da simulare le cartelle nei bucket che utilizzano uno spazio dei nomi semplice per gli oggetti.

Ad esempio, se crei un oggetto denominato folder1/file.txt nel bucket your-bucket, il percorso dell'oggetto è your-bucket/folder1/file.txt e Cloud Storage non contiene alcuna cartella denominata folder1. Dal punto di vista di Cloud Storage, la stringa folder1/ fa parte del nome dell'oggetto.

Tuttavia, poiché l'oggetto ha un / nel nome, alcuni strumenti implementano l'aspetto delle cartelle. Ad esempio, quando utilizzi la console Google Cloud , devi andare all'oggetto folder1/file1.txt come se fosse un oggetto denominato file1.txt in una cartella denominata folder1. Analogamente, puoi creare una cartella gestita denominata folder1, in modo che file1.txt sia soggetta alla policy di accesso impostata da questa cartella gestita.

Tieni presente che, poiché gli oggetti risiedono in uno spazio dei nomi piatto, le strutture nidificate in profondità, simili a directory, non hanno le prestazioni di un file system nativo quando elencano le sottodirectory nidificate in profondità.

Consulta le best practice per il tasso di richieste per suggerimenti su come ottimizzare le prestazioni evitando nomi sequenziali durante i caricamenti su larga scala. Gli oggetti caricati con nomi sequenziali probabilmente raggiungeranno lo stesso server di backend e limiteranno le prestazioni.

Cartelle simulate

Per aiutarti a organizzare gli oggetti nei bucket Cloud Storage, alcuni strumenti simulano le cartelle ed entrambe le API JSON e API XML dispongono di funzionalità che ti consentono di progettare il tuo schema di denominazione per simulare le cartelle. Fai clic sulle seguenti schede per vedere in che modo i diversi strumenti gestiscono le cartelle simulate.

Console

La console Google Cloud crea una rappresentazione visiva delle cartelle che assomiglia a un browser di file locale.

Nella console Google Cloud puoi creare una cartella vuota in un bucket o caricare una cartella esistente.

Quando carichi una cartella esistente, il nome della cartella diventa parte del percorso di tutti gli oggetti contenuti nella cartella. Nel caricamento sono incluse anche le eventuali sottocartelle e gli oggetti che contengono.

Per creare una cartella:

  1. Nella console Google Cloud , vai alla pagina Bucket in Cloud Storage.

    Vai a Bucket

  2. Vai al bucket.

  3. Fai clic su Crea cartella per creare una nuova cartella vuota o su Carica cartella per caricare una cartella esistente.

Riga di comando

Le CLI di Cloud Storage simulano la tipica esperienza di directory da riga di comando utilizzando una serie di regole.

Per creare l'illusione di un albero di file gerarchico, gcloud CLI applica le seguenti regole per determinare se l'URL di destinazione in un comando deve essere trattato come un nome di oggetto o una cartella:

  1. Se l'URL di destinazione termina con un carattere /, i comandi di gcloud CLI trattano l'URL di destinazione come una cartella. Ad esempio, prendi in considerazione il seguente comando, dove your-file è il nome di un file:

    gcloud storage cp your-file gs://your-bucket/abc/

    Come risultato di questo comando, Cloud Storage crea un oggetto denominato abc/your-file nel bucket your-bucket.

  2. Se copi più file di origine in un URL di destinazione, utilizzando il flag --recursive o un carattere jolly come **, gcloud CLI tratta l'URL di destinazione come una cartella. Ad esempio, considera il seguente comando, dove top-dir è una cartella contenente file come file1 e file2:

    gcloud storage cp top-dir gs://your-bucket/abc --recursive

    Come risultato di questo comando, Cloud Storage crea gli oggetti abc/top-dir/file1 e abc/top-dir/file2 nel bucket your-bucket.

  3. Se nessuna di queste regole è applicabile, gcloud CLI controlla gli oggetti nel bucket per determinare se l'URL di destinazione è un nome di oggetto o una cartella. Ad esempio, considera il seguente comando, dove your-file è il nome di un file:

    gcloud storage cp your-file gs://your-bucket/abc

    gcloud CLI effettua una richiesta di elenco degli oggetti per your-bucket, utilizzando il delimitatore / e prefix=abc, per determinare se sono presenti oggetti in your-bucket il cui percorso inizia con abc/. In questo caso, gcloud CLI tratta abc/ come nome di una cartella e il comando crea l'oggetto abc/your-file nel bucket your-bucket. In caso contrario, gcloud CLI crea l'oggetto abc in your-bucket.

Questo approccio basato su regole è diverso dal modo in cui funzionano molti strumenti, che creano oggetti da 0 byte per contrassegnare l'esistenza delle cartelle. gcloud CLI comprende diverse convenzioni utilizzate da questi strumenti, ad esempio l'aggiunta di _$folder$ alla fine del nome dell'oggetto da 0 byte, ma non richiede che questi oggetti marker implementino un comportamento di denominazione coerente con i comandi UNIX.

Oltre a queste regole, il modo in cui gcloud CLI tratta i file di origine dipende dall'utilizzo o meno del flag --recursive. Se utilizzi il flag, gcloud CLI crea i nomi degli oggetti in modo che rispecchino la struttura della directory di origine, a partire dal punto di elaborazione ricorsiva. Ad esempio, considera il seguente comando, dove home/top-dir è una cartella contenente file come file1 e sub-dir/file2:

gcloud storage cp home/top-dir gs://your-bucket --recursive

Come risultato di questo comando, Cloud Storage crea gli oggetti top-dir/file1 e top-dir/sub-dir/file2 nel bucket your-bucket.

Al contrario, la copia senza il flag --recursive, anche se vengono copiati più file a causa della presenza di un carattere jolly come **, genera oggetti denominati in base al componente del percorso finale dei file di origine. Ad esempio, supponendo di nuovo che home/top-dir sia una cartella che contiene file come file1 e sub-dir/file2, il comando:

gcloud storage cp home/top-dir/** gs://your-bucket

crea un oggetto denominato file1 e un oggetto denominato file2 nel bucket your-bucket.

Tentativi e denominazione

Quando gcloud CLI ritenta una richiesta interrotta, potresti riscontrare un problema per cui il primo tentativo copia un sottoinsieme di file e i tentativi successivi incontrano una cartella di destinazione già esistente, il che causa un nome errato degli oggetti.

Ad esempio, considera il seguente comando, in cui sono presenti sottocartelle in your-dir/, come dir1 e dir2, ed entrambe le sottocartelle contengono il file abc:

gcloud storage cp ./your-dir gs://your-bucket/new --recursive

Se il percorso gs://your-bucket/new non esiste ancora, gcloud CLI crea i seguenti oggetti al primo tentativo riuscito:

new/dir1/abc
new/dir2/abc

Tuttavia, al successivo tentativo riuscito dello stesso comando, gcloud CLI crea i seguenti oggetti:

new/your-dir/dir1/abc
new/your-dir/dir2/abc

Per fare in modo che gcloud CLI funzioni in modo coerente a ogni tentativo, prova quanto segue:

  1. Aggiungi una barra alla fine dell'URL di destinazione in modo che l'gcloud CLI lo tratti sempre come una cartella.

  2. Utilizza gcloud storage rsync. Poiché rsync non utilizza le regole di denominazione delle cartelle definite da cp di Unix, funziona in modo coerente indipendentemente dal fatto che la sottocartella di destinazione esista o meno.

Note aggiuntive

  • Non puoi creare un oggetto da zero byte per simulare una cartella vuota utilizzando gcloud CLI.

  • Durante il download in un file system locale, gcloud CLI ignora gli oggetti il cui nome termina con un carattere /, perché la creazione di un file che termina con / non è consentita su Linux e macOS.

  • Se utilizzi script per creare percorsi file combinando sottopercorsi, tieni presente che, poiché / è solo un carattere che si trova nel nome dell'oggetto, le CLI interpretano gs://your-bucket/folder/ come un oggetto diverso da gs://your-bucket/folder.

API REST

API JSON

Le cartelle non esistono nell'API JSON. Puoi restringere gli oggetti elencati e simulare le cartelle utilizzando i parametri di query prefix e delimiter.

Ad esempio, per elencare tutti gli oggetti nel bucket my-bucket con il prefisso folder/subfolder/, effettua una richiesta di elenco degli oggetti utilizzando questo URL:

"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"

API XML

Le cartelle non esistono nell'API XML. Puoi restringere l'elenco degli oggetti e simulare le cartelle utilizzando i parametri di ricerca prefix e delimiter.

Ad esempio, per elencare tutti gli oggetti nel bucket my-bucket con il prefisso folder/subfolder/, effettua una richiesta di elenco degli oggetti utilizzando questo URL:

"https://storage.googleapis.com/my-bucket?prefix=folder/subfolder/"

Rimozione delle cartelle simulate

Poiché le cartelle simulate non esistono, in genere puoi rimuoverle rinominando gli oggetti in modo che la cartella simulata non faccia più parte del nome dell'oggetto. Ad esempio, se hai un oggetto denominato folder1/file, puoi rimuovere la cartella simulata folder1/ rinominando l'oggetto semplicemente in file.

Tuttavia, se hai utilizzato uno strumento che crea oggetti da zero byte come segnaposto delle cartelle, ad esempio la console Google Cloud , devi eliminare l'oggetto da zero byte per rimuovere la cartella.

Ridenominazione o spostamento di cartelle simulate

La ridenominazione o lo spostamento di una cartella simulata richiede la copia e l'eliminazione di ogni oggetto al suo interno. Se la cartella simulata contiene molti oggetti, il processo di ridenominazione può essere inefficiente e costoso. La ridenominazione o lo spostamento di una cartella simulata non è un'operazione atomica, il che significa che se il processo non va a buon fine, il bucket potrebbe rimanere in uno stato incoerente, con solo alcuni oggetti spostati.

Spazio dei nomi gerarchico

Lo spazio dei nomi gerarchico consente di organizzare gli oggetti all'interno di un bucket Cloud Storage in un file system come una gerarchia di cartelle. Lo spazio dei nomi gerarchico migliora le prestazioni e ti aiuta a gestire i dati in modo efficiente. Per scoprire di più sullo spazio dei nomi gerarchico e su quando utilizzarlo, consulta Spazio dei nomi gerarchico.

Immutabilità degli oggetti

Gli oggetti sono immutabili, il che significa che un oggetto caricato non può essere modificato durante tutta la durata del suo tempo di archiviazione. La durata di archiviazione di un oggetto è il tempo che intercorre tra la creazione corretta dell'oggetto, ad esempio il caricamento, e la sua eliminazione. In pratica, ciò significa che non puoi apportare modifiche incrementali agli oggetti, ad esempio operazioni di aggiunta o troncamento. Tuttavia, è possibile sostituire gli oggetti archiviati in Cloud Storage e questa operazione avviene in modo atomico: fino al completamento del nuovo caricamento, ai lettori viene fornita la versione precedente dell'oggetto, mentre al termine del caricamento viene fornita la nuova versione dell'oggetto. Una singola operazione di sostituzione segna la fine del ciclo di vita di un oggetto immutabile e l'inizio del ciclo di vita di un nuovo oggetto immutabile.

Il numero di generazione di un oggetto cambia ogni volta che sostituisci i dati dell'oggetto. Pertanto, il numero di generazione identifica in modo univoco un oggetto immutabile.

Tieni presente che esiste un limite di una volta al secondo per la sostituzione rapida dello stesso oggetto. La sostituzione dello stesso oggetto con maggiore frequenza potrebbe causare errori 429 Too Many Requests. Devi progettare l'applicazione in modo che carichi i dati per un determinato oggetto non più di una volta al secondo e gestisca gli errori 429 Too Many Requests occasionali utilizzando una strategia di ripetizione con backoff esponenziale.

Passaggi successivi