Questa pagina descrive gli oggetti, una risorsa di Cloud Storage. Per una panoramica generale del funzionamento di Cloud Storage, consulta la panoramica del prodotto Cloud Storage.
Oggetti
Gli oggetti sono i singoli dati archiviati in Cloud Storage. Non esiste un limite al numero di oggetti che puoi creare in un bucket.
Gli oggetti hanno due componenti: dati degli oggetti e metadati degli oggetti. I dati degli oggetti sono in genere un file che vuoi archiviare in Cloud Storage ed è completamente opaco per Cloud Storage. I metadati degli oggetti sono una raccolta di coppie nome-valore che descrivono varie qualità degli oggetti.
Due parti importanti dei metadati degli oggetti comuni a tutti gli oggetti sono il nome dell'oggetto e il suo numero di generazione. Quando aggiungi un oggetto a un bucket Cloud Storage, specifichi il nome dell'oggetto e Cloud Storage assegna il numero di generazione. Insieme, nome e generazione identificano in modo univoco l'oggetto all'interno del bucket.
Puoi utilizzare gli elenchi di controllo dell'accesso (ACL) per controllare l'accesso ai singoli oggetti. Puoi anche utilizzare Identity and Access Management (IAM) per controllare l'accesso a tutti gli oggetti all'interno di un bucket o di una cartella gestita.
Considerazioni sull'assegnazione dei nomi
Il nome assegnato a un oggetto deve soddisfare i seguenti requisiti:
- I nomi degli oggetti possono contenere qualsiasi sequenza di caratteri Unicode validi con una lunghezza compresa tra 1 e 1024 byte con codifica UTF-8.
- I nomi degli oggetti non possono contenere caratteri di ritorno a capo o avanzamento riga.
- I nomi degli oggetti non possono iniziare con
.well-known/acme-challenge/
. - Gli oggetti non possono essere denominati
.
o..
.
Ti consigliamo vivamente di evitare quanto segue nei nomi degli oggetti:
- Caratteri di controllo non ammessi in XML 1.0 (#x7F–#x84 e #x86–#x9F): questi caratteri causano problemi relativi all'elenco XML quando provi a elencare gli oggetti.
- Il carattere
#
: i comandi dell'interfaccia a riga di comando di Google Cloud interpretano i nomi degli oggetti che terminano con #<stringa numerica> come identificatori di versione, pertanto l'inclusione di#
nei nomi degli oggetti può rendere difficile o impossibile eseguire operazioni su questi oggetti utilizzando gcloud CLI. - I caratteri
[
,]
,*
o?
: i comandi dell'interfaccia a riga di comando di Google Cloud 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 dei file in Windows. - I caratteri
:
,"
,<
,>
o|
non sono caratteri validi per i nomi dei file in Windows, pertanto i tentativi di scaricare in un file Windows un oggetto che utilizza questi caratteri nel nome non riescono a meno che il metodo di download non includa la ridenominazione del file di Windows risultante. Il carattere/
, sebbene non sia un carattere valido per i nomi dei file in Windows, in genere può essere utilizzato nei nomi degli oggetti per imitare una struttura di directory; strumenti come Google Cloud CLI lo convertono automaticamente in\
durante il download in un ambiente Windows. - Informazioni sensibili o che consentono l'identificazione personale (PII): i nomi degli oggetti sono più ampiamente visibili rispetto ai dati degli oggetti. Ad esempio, i nomi degli oggetti appaiono negli URL dell'oggetto e quando si elencano 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 oggetto
I nomi degli oggetti risiedono in uno spazio dei nomi semplice all'interno di un bucket. Ciò significa che:
- Diversi bucket possono avere oggetti con lo stesso nome.
- Gli oggetti non risiedono nelle sottodirectory di un bucket.
Per comodità, esistono diversi modi in cui gli oggetti vengono trattati come se fossero archiviati in una gerarchia di cartelle:
Le cartelle gestite sono una risorsa di Cloud Storage che fornisce l'accesso esteso a gruppi di oggetti con un prefisso del nome condiviso.
Strumenti come la console Google Cloud e Google Cloud CLI utilizzano il carattere barra (
/
) come delimitatore per simulare le cartelle in un bucket.
Ad esempio, se crei un oggetto denominato folder1/file.txt
nel bucket your-bucket
, il percorso dell'oggetto sarà your-bucket/folder1/file.txt
e Cloud Storage non avrà alcuna cartella denominata folder1
archiviata al suo interno. 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 accedere 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
, quindi file1.txt
sarà soggetta al criterio di accesso impostato da questa cartella gestita.
Tieni presente che, poiché gli oggetti risiedono in uno spazio dei nomi semplice, le strutture simili a directory profondamente nidificate non avranno le prestazioni di un file system nativo quando vengono elencate sottodirectory con molti livelli di nidificazione.
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. È probabile che gli oggetti caricati con nomi sequenziali raggiungano lo stesso server di backend e limitino le prestazioni.
Cartelle simulate
Per aiutarti a organizzare gli oggetti nei bucket Cloud Storage, alcuni strumenti simulano cartelle. Sia le API JSON che le API XML dispongono di funzionalità che consentono di progettare uno schema di denominazione personalizzato per simulare le cartelle. Fai clic sulle schede seguenti per vedere in che modo 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 al suo interno. Anche le eventuali sottocartelle e gli oggetti al loro interno sono inclusi nel caricamento.
Per creare una cartella:
- Nella console Google Cloud, vai alla pagina Bucket di Cloud Storage.
Vai al bucket.
Fai clic su Crea cartella per creare una nuova cartella vuota o su Carica cartella per caricarne una esistente.
Riga di comando
Le interfacce a riga di comando di Cloud Storage simulano la tipica esperienza della directory a riga di comando utilizzando una serie di regole.
Per creare l'illusione di una struttura di file gerarchica, 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:
Se l'URL di destinazione termina con un carattere
/
, i comandi dell'interfaccia a riga della gcloud CLI considerano l'URL di destinazione come una cartella. Ad esempio, considera il comando seguente, doveyour-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 bucketyour-bucket
.Se copi più file di origine in un URL di destinazione, l'gcloud CLI considera l'URL di destinazione come una cartella. Ad esempio, considera il comando seguente in cui
your-dir
è una cartella contenente file comefile1
efile2
:gcloud storage cp your-dir gs://your-bucket/abc --recursive
Come risultato di questo comando, Cloud Storage crea gli oggetti
abc/your-dir/file1
eabc/your-dir/file2
nel bucketyour-bucket
.Se nessuna di queste regole si applica, gcloud CLI controlla gli oggetti nel bucket per determinare se l'URL di destinazione è un nome oggetto o una cartella. Ad esempio, considera il comando seguente in cui
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 il prefisso=abc
per determinare se sono presenti oggetti inyour-bucket
il cui percorso inizia conabc/
. Se è così, l'interfaccia alla gcloud CLI consideraabc/
come nome di cartella e il comando crea l'oggettoabc/your-file
nel bucketyour-bucket
. In caso contrario, gcloud CLI crea l'oggettoabc
inyour-bucket
.
Questo approccio basato su regole è diverso dal funzionamento di molti strumenti, che creano oggetti a 0 byte per contrassegnare l'esistenza di cartelle. Gcloud CLI comprende diverse convenzioni utilizzate da questi strumenti, ad esempio la convenzione di aggiungere _$folder$
alla fine del nome dell'oggetto a 0 byte, ma non richiede questi oggetti indicatore per implementare un comportamento di denominazione coerente con i comandi UNIX.
Nuovi tentativi e denominazione
Quando gcloud CLI riprova una richiesta interrotta, potresti riscontrare un problema in cui al primo tentativo viene copiato un sottoinsieme di file, mentre i tentativi successivi incontrano una cartella di destinazione già esistente, il che causa un nome errato degli oggetti.
Ad esempio, considera il comando seguente, 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, l'gcloud CLI crea i seguenti oggetti al primo tentativo riuscito:
new/dir1/abc new/dir2/abc
Tuttavia, al successivo tentativo riuscito dello stesso comando, l'gcloud CLI crea i seguenti oggetti:
new/your-dir/dir1/abc new/your-dir/dir2/abc
Affinché gcloud CLI funzioni in modo coerente a ogni tentativo, prova quanto segue:
Aggiungi una barra alla fine dell'URL di destinazione in modo che gcloud CLI la consideri sempre come una cartella.
Utilizza
gcloud storage rsync
. Poichérsync
non utilizza le regole di denominazione delle cartelle Unix definite da cp, funziona in modo coerente indipendentemente dal fatto che la sottocartella di destinazione esista o meno.
Per ulteriori informazioni su come vengono creati i nomi, consulta
la creazione dei nomi utilizzando cp
.
Note aggiuntive
Non puoi creare un oggetto a zero byte per simulare una cartella vuota utilizzando gcloud CLI.
Se utilizzi gli script per creare percorsi di file combinando i percorsi secondari, tieni presente che, poiché
/
è solo un carattere presente nel nome dell'oggetto, le interfacce a riga di comando interpretanogs://my-bucket/folder/
come un oggetto diverso dags://my-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/
, crea 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 gli oggetti elencati 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/
, crea 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 effettivamente non esistono, in genere puoi rimuoverle
rinominando gli oggetti rinominando gli oggetti in modo che la cartella simulata non faccia più
parte del nome dell'oggetto. Ad esempio, se disponi di un oggetto denominato
folder1/file
, puoi rimuovere la cartella simulata folder1/
rinominando
l'oggetto in file
.
Tuttavia, se hai utilizzato uno strumento che crea oggetti a zero byte come segnaposto delle cartelle, come la console Google Cloud, devi eliminare l'oggetto a zero byte per rimuovere la cartella.
Immutabilità dell'oggetto
Gli oggetti sono immutabili, il che significa che un oggetto caricato non può cambiare durante la sua durata di archiviazione. La durata di archiviazione di un oggetto è il tempo che intercorre tra la creazione corretta dell'oggetto, ad esempio il caricamento, e l'eliminazione corretta dell'oggetto. In pratica, questo significa che non puoi apportare modifiche incrementali agli oggetti, come operazioni di accodamento o troncamento. Tuttavia, è possibile sostituire gli oggetti archiviati in Cloud Storage, con modalità a livello atomico: fino al completamento del nuovo caricamento, la versione precedente dell'oggetto viene fornita ai lettori e, al termine del caricamento, la nuova versione dell'oggetto viene fornita ai lettori. Una singola operazione di sostituzione contrassegna la fine del ciclo di vita di un oggetto immutabile e l'inizio della durata 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 più frequente dello stesso oggetto potrebbe causare errori 429 Too Many Requests
. Dovresti progettare l'applicazione in modo che carichi i dati per un determinato oggetto non più di una volta al secondo e gestisci gli errori 429 Too Many Requests
occasionali utilizzando una strategia di nuovo tentativo di backoff esponenziale.
Passaggi successivi
- Carica e scarica oggetti.
- Sposta un oggetto esistente.
- Scopri di più sui bucket, che sono container per gli oggetti.
- Scopri di più sulle cartelle gestite.