Informazioni sugli oggetti Cloud Storage

Questa pagina descrive gli oggetti, una risorsa in Cloud Storage. Per un uso generico per una panoramica del funzionamento di Cloud Storage, consulta 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 puoi creare in un bucket.

Gli oggetti hanno due componenti: i dati dell'oggetto e i metadati dell'oggetto. I dati oggetto sono in genere un file che vuoi archiviare in Cloud Storage ed è completamente opaco per 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 e la generazione 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 tutti gli oggetti all'interno di un bucket o di una cartella gestita.

Considerazioni sulla denominazione

Quando assegni un nome agli oggetti in Cloud Storage, è essenziale rispettare requisiti specifici per garantire la compatibilità ed evitare errori. Questi I requisiti si applicano sia ai bucket di spazi dei nomi fissi che bucket abilitati per lo spazio dei nomi gerarchico.

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 di a capo.
  • I nomi degli oggetti non possono iniziare con .well-known/acme-challenge/.
  • Gli oggetti non possono essere denominati . o ...

Limiti di dimensioni degli oggetti specifici per lo spazio dei nomi

La dimensione massima di un nome di oggetto varia in base allo spazio dei nomi del bucket:

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

  • Dimensioni del nome dell'oggetto nei bucket abilitati con lo spazio dei nomi gerarchico: i nomi degli oggetti possono essere suddivisi in due parti:

    • Nome cartella: il nome della cartella in cui si trova l'oggetto. La dimensione massima per il nome della cartella è di 512 byte con codifica UTF-8.
    • Nome base: il nome dell'oggetto che si trova nella cartella. La dimensione massima del nome base è 512 byte se codificato in UTF-8.

    Ad esempio, il percorso my-folder/my-object.txt rappresenta un oggetto con nome base come my-object.txt archiviata in una cartella denominata my-folder/.

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 con le schede XML quando provi a elencare i tuoi oggetti.
  • Il carattere #: i comandi dell'interfaccia a riga di comando 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 con versione utilizzando l'interfaccia a riga di comando gcloud.
  • 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 i nomi dei 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 /, 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ù visibili dei dati dell'oggetto. Ad esempio, i nomi degli oggetti vengono visualizzati negli URL per l'oggetto 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 memorizzare gli oggetti nei seguenti spazi dei nomi:

Spazio dei nomi piatto

I bucket con spazio dei nomi semplice archiviano gli oggetti in una struttura semplice senza gerarchia, il che significa che non esistono directory o cartelle.

Per comodità, esistono diversi modi per trattare gli oggetti come se fossero memorizzati in una gerarchia di cartelle:

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 una 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 accedere all'oggetto folder1/file1.txt come se fosse un oggetto chiamato file1.txt in una cartella denominata folder1. Analogamente, puoi creare una cartella gestita denominata folder1, in modo che file1.txt sia soggetta al criterio di accesso impostato da questa cartella gestita.

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

Per consigli su come ottimizzare, consulta le best practice relative alle percentuali di richiesta. il rendimento evitando nomi sequenziali durante caricamenti su larga scala. Gli oggetti caricati con nomi sequenziali hanno maggiori probabilità di raggiungere lo stesso server di backend e limitare il rendimento.

Cartelle simulate

Per aiutarti a organizzare gli oggetti nei tuoi bucket Cloud Storage, alcuni strumenti simulano cartelle e le API JSON e XML dispongono di 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 suo nome diventa parte di il percorso di tutti gli oggetti contenuti nella cartella. Nel caricamento sono incluse anche 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 oppure su Carica per caricare una cartella esistente.

Riga di comando

Le interfacce a riga di comando di Cloud Storage simulano la tipica directory a riga di comando esperienza usando una serie di regole.

Per creare l'illusione di una struttura ad albero di file, l'interfaccia a riga di comando gcloud applica le seguenti regole per determinare se l'URL di destinazione in un comando deve essere considerato come un nome di oggetto o una cartella:

  1. Se l'URL di destinazione termina con un carattere /, gcloud CLI trattano l'URL di destinazione come 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/

    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 **, l'interfaccia a riga di comando gcloud tratta l'URL di destinazione come una cartella. Ad esempio, considera il seguente comando in cui top-dir è una cartella contenente file come file1 e file2:

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

    In seguito a 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, l'interfaccia a riga di comando gcloud 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

    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 in your-bucket sono presenti oggetti il cui percorso inizia con abc/. In questo caso, gcloud CLI considera abc/ come un nome di cartella, e il comando crea l'oggetto abc/your-file nel bucket your-bucket. In caso contrario, gcloud CLI crea l'oggetto abc a your-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 gcloud CLI tratta i file di origine dipende dall'uso o meno del flag --recursive. Se utilizzi il flag, gcloud CLI crea i nomi degli oggetti in modo da rispecchiare la struttura della directory di origine, a partire dal punto di elaborazione ricorsiva. Per Ad esempio, considera il seguente comando dove home/top-dir è una cartella contenenti file quali file1 e sub-dir/file2:

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

In seguito a 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 dal componente del percorso finale dei file di origine. Ad esempio, supponendo ancora che home/top-dir sia una cartella contenente 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 altro denominato file2 nel bucket your-bucket.

Nuovi tentativi e denominazione

Quando la CLI gcloud fa un nuovo tentativo con una richiesta interrotta, potresti riscontrare un problema in cui il primo tentativo copia un sottoinsieme di file e i tentativi successivi rilevano una cartella di destinazione già esistente, il che causa la denominazione errata degli oggetti.

Ad esempio, considera il seguente comando, in cui sono presenti sottodirectory sotto your-dir/ come dir1 e dir2 ed entrambe le sottodirectory contengono il 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:

  1. Aggiungi una barra alla fine dell'URL di destinazione in modo che gcloud CLI la considera 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 dall'esistenza o meno della sottocartella di destinazione.

Note aggiuntive

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

  • Durante il download su un file system locale, gcloud CLI salta 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 gli script per creare percorsi dei file combinando percorsi secondari, tieni presente che perché / è solo un carattere che si trova nel nome del le interfacce a riga di comando 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 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 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

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 prefisso folder/subfolder/, effettua una richiesta di elenco degli oggetti utilizzando questo URL:

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

Rimuovere le 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 la cartella appena 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 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 in modo efficiente i tuoi dati. Per scoprire di più sullo spazio dei nomi gerarchico e su quando utilizzarlo, consulta la sezione Spazio dei nomi gerarchico.

Immutabilità dell'oggetto

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 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. Un'unica 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 .

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 utilizzando un backoff esponenziale strategia di nuovo tentativo.

Passaggi successivi