Questa pagina descrive gli oggetti, una risorsa in 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 di archiviazione ideale in Cloud Storage. Non esiste un limite al numero di oggetti che che puoi creare in un bucket.
Gli oggetti hanno due componenti: dati dell'oggetto e metadati dell'oggetto. Oggetto "dati" è in genere un file che si vuole archiviare in Cloud Storage completamente opaco a Cloud Storage. I metadati dell'oggetto sono una raccolta di coppie nome-valore che descrivono varie qualità dell'oggetto.
Due parti importanti dei metadati dell'oggetto comuni a tutti gli oggetti sono l'oggetto name e il suo numero di generazione. Quando aggiungi un oggetto Bucket Cloud Storage, specifichi il nome dell'oggetto Cloud Storage assegna il numero di generazione. Insieme, il nome identificano in modo univoco l'oggetto all'interno del bucket.
Puoi utilizzare elenchi di controllo dell'accesso (ACL) per controllare l'accesso a singoli utenti di oggetti strutturati. Puoi anche utilizzare Identity and Access Management (IAM) per controllare l'accesso a per tutti gli oggetti in un bucket o in una cartella gestita.
Considerazioni sulla denominazione
Il nome che assegni a un oggetto deve soddisfare i seguenti requisiti:
- I nomi degli oggetti possono contenere qualsiasi sequenza di caratteri Unicode validi, di lunghezza da 1 a 1024 byte con codifica UTF-8.
- I nomi degli oggetti non possono contenere caratteri di ritorno a capo o di a capo.
- I nomi degli oggetti non possono iniziare con
.well-known/acme-challenge/
. - Gli oggetti non possono essere denominati
.
o..
.
È vivamente consigliato evitare quanto segue nei nomi degli oggetti:
- Caratteri di controllo non ammessi in XML 1.0 (#x7F–#x84 e #x86–#x9F): questi caratteri causano l'elenco XML quando provi a elencare gli oggetti.
- Il carattere
#
: i comandi di Google Cloud CLI interpretano i nomi degli oggetti che terminano con #<stringa numerica> come identificatori di versione, pertanto l'inclusione di#
in con nomi di oggetti che possono rendere difficile o impossibile eseguire operazioni con controllo delle versioni usando lgcloud CLId. - I caratteri
[
,]
,*
o?
: i comandi Google Cloud CLI interpretano questi caratteri come caratteri jolly, pertanto la loro inclusione 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|
: non sono caratteri validi per nomi file in Windows, quindi tenta di scaricare un oggetto che utilizza caratteri nel nome di un file Windows non riesce a meno che il metodo di download include la ridenominazione del file di Windows risultante. Il carattere/
, anche se non è un carattere valido per i nomi file in Windows, in genere può essere utilizzato 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. - Informazioni sensibili o che consentono l'identificazione personale (PII): i nomi degli oggetti sono più ampiamente visibili rispetto ai dati dell'oggetto. Ad esempio, i nomi degli oggetti appaiono negli URL e quando vengono elencati gli oggetti in un bucket.
Gli oggetti esistenti non possono essere rinominati direttamente, ma puoi rinominare indirettamente un oggetto copiando ed eliminando l'oggetto originale.
Spazio dei nomi degli oggetti
Puoi archiviare oggetti nei seguenti spazi dei nomi:
Spazio dei nomi piatto
I bucket con uno spazio dei nomi piatto memorizzano gli oggetti in una struttura piatta senza gerarchia, il che significa che non sono presenti directory o cartelle.
Per praticità, ci sono diversi modi in cui gli oggetti vengono trattati come se venissero in una gerarchia di cartelle:
Le cartelle gestite sono una risorsa Cloud Storage che fornisce accesso ampliato a gruppi di oggetti con un prefisso del nome condiviso.
Strumenti come la console Google Cloud e l'interfaccia a riga di comando Google Cloud 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 è your-bucket/folder1/file.txt
e
In Cloud Storage non è archiviata alcuna cartella denominata folder1
. Da
punto di vista di Cloud Storage, la stringa folder1/
fa parte del
il nome dell'oggetto.
Tuttavia, poiché il nome dell'oggetto contiene /
, alcuni strumenti implementano il metodo
l'aspetto delle cartelle. Ad esempio, quando utilizzi la console Google Cloud,
passa all'oggetto folder1/file1.txt
come se fosse un oggetto
denominato file1.txt
in una cartella denominata folder1
. Analogamente, potresti creare
cartella gestita denominata folder1
, mentre file1.txt
sarebbe soggetta a
il criterio di accesso impostato da questa cartella gestita.
Tieni presente che, poiché gli oggetti risiedono in uno spazio dei nomi semplice, strutture simili a directory non hanno le prestazioni che un file system nativo quando elenca le sottodirectory con un alto livello di nidificazione.
Per consigli su come ottimizzare, consulta le best practice relative alle percentuali di richiesta. il rendimento evitando nomi sequenziali durante caricamenti su larga scala. Oggetti caricati con nomi sequenziali probabilmente raggiungono lo stesso server di backend limitare le prestazioni.
Cartelle simulate
Per aiutarti a organizzare gli oggetti nei tuoi bucket Cloud Storage, alcuni strumenti simulano cartelle e le API JSON e XML offrono funzionalità che ti consentono di progettare il tuo schema di denominazione per simulare le cartelle. Fai clic sulle seguenti schede per scoprire in che modo i diversi strumenti gestiscono le cartelle simulate.
Console
La console Google Cloud crea una rappresentazione visiva delle cartelle è simile 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. Nel caricamento sono incluse anche eventuali sottocartelle e gli oggetti che contengono.
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 oppure su Carica per caricare una cartella esistente.
Riga di comando
Le interfacce a riga di comando di Cloud Storage simulano la tipica esperienza con le directory a riga di comando utilizzando una serie di regole.
Per ottenere 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 considerato come un nome di oggetto o cartella:
Se l'URL di destinazione termina con un carattere
/
, gcloud CLI trattano 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 utilizzando il flag
--recursive
o un carattere jolly come**
, l'interfaccia a riga di comando gcloud tratta l'URL di destinazione come una cartella. Per Ad esempio, considera il seguente comando dovetop-dir
è una cartella contenenti file qualifile1
efile2
:gcloud storage cp top-dir gs://your-bucket/abc --recursive
Come risultato di questo comando, Cloud Storage crea gli oggetti
abc/top-dir/file1
eabc/top-dir/file2
nel bucketyour-bucket
.Se nessuna di queste regole si applica, gcloud CLI controlla per determinare se l'URL di destinazione è un oggetto un nome utente 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
L'interfaccia a riga di comando gcloud invia una richiesta di elenco di oggetti per
your-bucket
, utilizzando il delimitatore/
e il prefisso=abc
, per determinare se inyour-bucket
sono presenti oggetti il cui percorso inizia conabc/
. In questo caso, l'interfaccia a riga di comando gcloud trattaabc/
come nome di una cartella e il comando crea l'oggettoabc/your-file
nel bucketyour-bucket
. In caso contrario, gcloud CLI crea l'oggettoabc
ayour-bucket
.
Questo approccio basato su regole è diverso dal funzionamento di molti strumenti, che creano oggetti di 0 byte per contrassegnare l'esistenza di cartelle. L'interfaccia a riga di comando gcloud supporta diverse convenzioni utilizzate da questi strumenti, ad esempio l'aggiunta di _$folder$
alla fine del nome dell'oggetto di 0 byte, ma non richiede che questi oggetti indicatori implementino un comportamento di denominazione coerente con i comandi UNIX.
Oltre a queste regole, il modo in cui l'interfaccia a riga di comando gcloud tratta i file di origine dipende dall'utilizzo o meno del flag --recursive
. Se utilizzi
, la gcloud CLI crea i nomi degli oggetti per eseguire il mirroring dell'origine
struttura di directory, a partire dal punto dell'elaborazione ricorsiva. Ad esempio, considera il seguente comando in cui 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 più file
vengono copiati a causa della presenza di un carattere jolly come **
, determina
gli oggetti denominati dal componente percorso finale dei file di origine. Ad esempio:
supponendo nuovamente che home/top-dir
sia una cartella contenente file come
file1
e sub-dir/file2
, quindi il comando:
gcloud storage cp home/top-dir/** gs://your-bucket
crea un oggetto denominato file1
e un oggetto denominato file2
nel
your-bucket
.
Nuovi tentativi e denominazione
Quando gcloud CLI riprova una richiesta interrotta, potrebbe verificarsi un problema in cui al primo tentativo copia un sottoinsieme di file, e nei tentativi successivi troverà una cartella di destinazione già esistente, il che fa sì che gli oggetti vengano denominati in modo errato.
Ad esempio, considera il comando seguente, in cui sono presenti sottocartelle
in your-dir/
, ad esempio dir1
e dir2
, ed entrambe le sottocartelle contengono
file abc
:
gcloud storage cp ./your-dir gs://your-bucket/new --recursive
Se il percorso gs://your-bucket/new
non esiste ancora, il client CLI gcloud 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:
Aggiungi una barra alla fine dell'URL di destinazione in modo che gcloud CLI la considera sempre come una cartella.
Utilizza
gcloud storage rsync
. Poichérsync
non utilizza le regole di denominazione delle cartelle definite da cp di Unix, funziona in modo coerente indipendentemente dall'esistenza o meno della sottocartella di destinazione.
Note aggiuntive
Non puoi creare un oggetto a zero byte per simulare una cartella vuota utilizzando con gcloud CLI.
Durante il download in un file system locale, gcloud CLI salta gli oggetti il cui nome termina con il 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 interfacce a riga di comando interpretanogs://your-bucket/folder/
come un oggetto diverso dags://your-bucket//folder
.
API REST
API JSON
Le cartelle non esistono nell'API JSON. Puoi restringere il campo
degli oggetti elencati e simulare le cartelle utilizzando prefix
delimiter
parametri di query.
Ad esempio, per elencare tutti gli oggetti nel bucket my-bucket
con il prefisso folder/subfolder/
, invia una richiesta di elenco di oggetti utilizzando questo URL:
"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"
API XML
Nell'API XML non esistono cartelle. Puoi restringere il campo
oggetti elencati e simulare cartelle utilizzando la classe prefix
e delimiter
.
Ad esempio, per elencare tutti gli oggetti nel bucket my-bucket
con il prefisso folder/subfolder/
, invia una richiesta di elenco di oggetti utilizzando questo URL:
"https://storage.googleapis.com/my-bucket?prefix=folder/subfolder/"
Rimuovere le cartelle simulate
Poiché le cartelle simulate non esistono effettivamente, in genere è possibile rimuovere
le cartelle simulate rinominando gli oggetti in modo che la cartella simulata non sia 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 di zero byte come segnaposto per le cartelle, ad esempio la console Google Cloud, devi eliminare l'oggetto di zero byte per rimuovere la cartella.
Spazio dei nomi gerarchico
Lo spazio dei nomi gerarchico ti consente di organizzare gli oggetti all'interno di un bucket Cloud Storage in un file system come la gerarchia delle cartelle. Lo spazio dei nomi gerarchico migliora le prestazioni e ti aiuta a gestire in modo efficiente i tuoi dati. Per scoprire di più sullo spazio dei nomi gerarchico e su quando utilizzarlo, consulta Spazio dei nomi gerarchico.
Immutabilità dell'oggetto
Gli oggetti sono immutabili, il che significa che un oggetto caricato non può cambiare per tutta la durata del suo spazio di archiviazione. La durata di archiviazione di un oggetto è il tempo tra la creazione riuscita dell'oggetto, ad esempio il caricamento, e l'eliminazione riuscita dell'oggetto. In pratica, ciò significa che non puoi apportare modifiche incrementali come aggiungere o troncare operazioni. Tuttavia, è possibile sostituire gli oggetti archiviati in Cloud Storage e questa operazione avviene in modo atomico: fino al completamento del nuovo caricamento, la vecchia versione dell'oggetto viene mostrata ai lettori e, al termine del caricamento, viene mostrata la nuova versione dell'oggetto. Una singola sostituzione segna la fine del ciclo di vita di un oggetto immutabile 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 .
Tieni presente che esiste un limite di una volta al secondo per la sostituzione rapida dello stesso oggetto. La sostituzione dello stesso oggetto più spesso potrebbe comportare errori429 Too Many Requests
. Dovresti progettare l'applicazione affinché carichi
per un determinato oggetto non più di una volta al secondo e gestiscono
429 Too Many Requests
errori che utilizzano un backoff esponenziale
strategia di nuovo tentativo.
Passaggi successivi
- Carica e scarica oggetti.
- Spostare un oggetto esistente.
- Scopri di più sui bucket, che sono contenitori di oggetti.
- Scopri di più sulle cartelle gestite.