Questa pagina descrive i campi di metadati utilizzati di frequente che vengono archiviati insieme agli oggetti in Cloud Storage.
Introduzione
Gli oggetti archiviati in Cloud Storage hanno metadati associati.
I metadati identificano le proprietà dell'oggetto e specificano come deve essere gestito l'oggetto quando viene eseguito l'accesso. I metadati esistono come coppie chiave-valore. Ad esempio, la classe di archiviazione di un oggetto è rappresentata
dalla voce di metadati storageClass:STANDARD
. storageClass
è la chiave
per i metadati e tutti gli oggetti hanno una chiave associata.
STANDARD
specifica il valore di questo oggetto specifico e il valore varia
da oggetto a oggetto.
La modificabilità dei metadati varia: alcuni possono essere modificati in qualsiasi momento, altri
possono essere impostati solo al momento della creazione dell'oggetto e altri
possono essere solo visualizzati. Ad esempio, puoi modificare il valore dei metadati Cache-Control
in qualsiasi momento, ma puoi assegnare i metadati storageClass
solo quando l'oggetto viene creato o riscritto e non puoi modificare direttamente il valore dei metadati generation
, anche se il valore generation
cambia quando l'oggetto viene sostituito.
Metadati modificabili
Esistono due categorie di metadati che gli utenti possono modificare per gli oggetti:
Metadati a chiave fissa: metadati le cui chiavi sono impostate, ma per i quali puoi specificare un valore.
Metadati personalizzati: metadati che aggiungi specificando sia una chiave sia un valore associato alla chiave.
Quando modifichi i metadati, in genere devi evitare i caratteri non ASCII, perché non sono consentiti nelle intestazioni HTTP, che utilizza l'API XML.
Metadati a chiave fissa
Puoi modificare i seguenti metadati per gli oggetti, ma devi disporre di autorizzazioni sufficienti per farlo:
- Metadati del controllo dell'accesso
- Cache-Control
- Content-Disposition
- Content-Encoding
- Content-Language
- Content-Type
- Custom-Time
- Blocco di oggetti
- Configurazione della conservazione
Metadati del controllo dell'accesso
Cloud Storage utilizza Identity and Access Management (IAM) e elenchi di controllo dell'accesso (ACL) per controllare l'accesso agli oggetti. Utilizza questi link per scoprire di più su questi metodicontrollo dell'accesso'accesso e sui metadati associati.
Cache-Control
I metadati Cache-Control
possono specificare due aspetti diversi
di come vengono pubblicati i dati da Cloud Storage: se i dati possono essere
memorizzati nella cache e se possono essere trasformati.
Memorizzazione nella cache dei dati
I metadati Cache-Control
ti consentono di controllare se e per quanto tempo le cache
possono memorizzare nella cache i tuoi oggetti, che possono poi essere utilizzati per soddisfare le richieste future. Le cache possono includere cache del browser e di internet, nonché la
memorizzazione nella cache integrata di Cloud Storage.
Se un oggetto applicabile non ha una voce di metadati Cache-Control
,
Cloud Storage utilizza il valore predefinito:
public, max-age=3600
, se l'oggetto non è criptato utilizzando una chiave di crittografia gestita dal cliente o archiviato all'interno di un perimetro di servizio Virtual Private Cloud.no-cache, no-store, max-age=0
, se l'oggetto è criptato utilizzando una chiave di crittografia gestita dal cliente.private, max-age=0
, se l'oggetto è archiviato all'interno di un perimetro di servizio Virtual Private Cloud.no-cache, no-store, max-age=0, must-revalidate
, se l'oggetto è archiviato all'interno di un perimetro di servizio Virtual Private Cloud e criptato utilizzando una chiave di crittografia gestita dal cliente.
Se consenti la memorizzazione nella cache, i download potrebbero continuare a ricevere versioni precedenti di un oggetto, anche dopo il caricamento di una versione più recente. Questo perché le versioni precedenti
rimangono "fresche" nelle cache per un periodo di tempo determinato da
max-age
. Inoltre, poiché gli oggetti possono essere memorizzati nella cache in varie posizioni su Internet, non è possibile forzare la scadenza di un oggetto memorizzato nella cache a livello globale. Ciò
significa che se revochi l'accesso pubblico a un oggetto, l'oggetto può comunque essere
servito da una cache, a seconda dell'ultima volta che è stato eseguito l'accesso e della sua
impostazione Cache-Control
. Ad esempio, se il tuo oggetto è stato pubblicato con un
Cache-Control
di public, max-age=3600
, può rimanere in una cache per un'ora. Se vuoi impedire la pubblicazione di versioni memorizzate nella cache di oggetti leggibili pubblicamente, imposta Cache-Control: no-store
sull'oggetto.
Trasformazione dei dati
I metadati Cache-Control
ti consentono anche di pubblicare gli oggetti così come sono archiviati,
senza applicare trasformazioni ai dati, ad esempio rimuovendo la codifica dei contenuti gzip
per i client incompatibili. Per pubblicare un oggetto così com'è, imposta
Cache-Control:no-transform
.
Content-Disposition
I metadati Content-Disposition
specificano le informazioni di presentazione
sui dati trasmessi. L'impostazione Content-Disposition
ti consente di controllare lo stile di presentazione dei contenuti, ad esempio
determinare se un allegato deve essere visualizzato automaticamente o se
è necessaria un'azione da parte dell'utente per aprirlo. Consulta
https://datatracker.ietf.org/doc/html/rfc6266 per la
specifica Content-Disposition
.
Content-Encoding
I metadati Content-Encoding
possono essere utilizzati per indicare che un oggetto è compresso, mantenendo comunque il Content-Type
sottostante dell'oggetto.
Ad esempio, un file di testo compresso con gzip può avere l'indicazione che
si tratta di un file di testo in Content-Type
e che è
compresso con gzip in Content-Encoding
. Prima di caricare i file, devi assicurarti che siano effettivamente compressi utilizzando il formato Content-Encoding
specificato, altrimenti si potrebbe verificare un comportamento imprevisto quando tenti di scaricare gli oggetti. Per ulteriori informazioni, consulta la pagina Transcodifica.
Per i contenuti comprimibili, come il testo, l'utilizzo di Content-Encoding: gzip
consente di risparmiare
sui costi di rete e di archiviazione e migliora le prestazioni di pubblicazione dei contenuti. Tuttavia, per i contenuti già compressi, come gli archivi e molti formati multimediali, l'applicazione di un altro livello di compressione e la relativa indicazione nei metadati Content-Encoding
è in genere dannosa sia per le dimensioni che per il rendimento dell'oggetto e deve essere evitata.
Content-Language
I metadati Content-Language
indicano la lingua o le lingue
a cui è destinato l'oggetto. Fai riferimento ai codici lingua ISO 639-1
per i valori tipici di questi metadati.
Cloud Storage supporta valori Content-Language
fino a 100 caratteri.
Content-Type
I metadati impostati più di frequente sono Content-Type
(noto anche come tipo di media),
che consente ai browser di eseguire il rendering corretto dell'oggetto. Tutti gli oggetti hanno un valore specificato nei metadati Content-Type
, ma questo valore non deve corrispondere al tipo sottostante dell'oggetto. Ad esempio, se Content-Type
non è specificato dal caricatore e non può essere determinato, viene impostato su
application/octet-stream
o application/x-www-form-urlencoded
, a seconda di
come hai caricato l'oggetto. Per un elenco dei tipi di contenuti validi, consulta la pagina
IANA Media Types.
Custom-Time
I metadati Custom-Time
sono una data e un'ora specificate dall'utente rappresentate nel formato RFC 3339 YYYY-MM-DD'T'HH:MM:SS.SS'Z'
o YYYY-MM-DD'T'HH:MM:SS'Z'
quando i millisecondi sono zero. Questi metadati vengono
in genere impostati per utilizzare la condizione DaysSinceCustomTime
nella
gestione del ciclo di vita degli oggetti.
Non puoi rimuovere Custom-Time
una volta impostato su un oggetto. Inoltre,
il valore di Custom-Time
non può diminuire. ovvero non puoi impostare
Custom-Time
su una data/ora precedente rispetto a Custom-Time
esistente. Tuttavia, puoi rimuovere o reimpostare in modo efficace il Custom-Time
riscrivendo l'oggetto.
Blocchi degli oggetti
Utilizza i flag dei metadati per inserire blocchi sugli oggetti, che impediscono che vengano eliminati o sostituiti. Per ulteriori informazioni, consulta la pagina Archiviazione a fini legali degli oggetti.
Configurazione della conservazione
Se presente, la configurazione della conservazione di un oggetto definisce una data e un'ora precedenti alle quali l'oggetto non può essere eliminato o sostituito. Per ulteriori informazioni, vedi Blocco della conservazione degli oggetti.
Metadati personalizzati
I metadati personalizzati sono metadati per i quali definisci sia la chiave che il valore. Per
creare metadati personalizzati, devi specificare sia una chiave che un valore. Dopo aver creato una coppia di metadati personalizzati key:value
, puoi eliminare la chiave o modificare il valore.
I metadati personalizzati sono soggetti a un limite di dimensioni.
La pagina Visualizzazione e modifica dei metadati include informazioni sull'impostazione di metadati personalizzati.
Il prefisso x-goog-meta-
L'API XML imposta e recupera i metadati degli oggetti utilizzando le intestazioni delle richieste, mentre
l'API JSON consente di impostare metadati personalizzati nella richiesta finale di un
caricamento ripristinabile utilizzando le intestazioni delle richieste. Per distinguere chiaramente
le intestazioni dei metadati personalizzati dalle intestazioni delle richieste standard, entrambe le API antepongono x-goog-meta-
a queste intestazioni.
Metadati non modificabili
Alcuni metadati non possono essere modificati direttamente. Questi metadati vengono impostati al momento della creazione o della riscrittura dell'oggetto. Nell'ambito della creazione o della riscrittura dell'oggetto, puoi impostare alcuni metadati, come la classe di archiviazione dell'oggetto o le chiavi di crittografia gestite dal cliente. Altri metadati vengono aggiunti automaticamente e possono essere solo visualizzati, ad esempio il numero di generazione dell'oggetto o l'ora di creazione.
Numeri di generazione e metagenerazione
Come parte dei metadati, ogni oggetto Cloud Storage ha una proprietà numerica generation
e una proprietà numerica metageneration
che identificano in modo univoco l'oggetto:
Proprietà | Descrizione |
---|---|
generation |
Identifica la versione di un oggetto ed è presente per ogni oggetto, indipendentemente dal fatto che un bucket utilizzi il controllo delle versioni degli oggetti.
|
metageneration |
Identifica la versione dei metadati e aumenta ogni volta che i metadati di un determinato generation vengono aggiornati.
|
Le proprietà generation
e metageneration
vengono utilizzate nelle seguenti circostanze:
Quando utilizzi le condizioni preliminari nelle richieste: le condizioni preliminari causano l'esito negativo della richiesta se la condizione preliminare non è soddisfatta. In questo modo, la richiesta non viene applicata a una versione imprevista di un oggetto, ad esempio non vengono recuperati i dati dell'oggetto sbagliato o non viene modificato lo stato errato dei metadati di un oggetto.
Quando elenco, accesso, ripristino ed eliminazione di versioni non correnti degli oggetti: Le versioni non correnti degli oggetti sono particolarmente pertinenti nei bucket che utilizzano o hanno utilizzato in precedenza il controllo delle versioni degli oggetti.
Checksum
I checksum sono metadati calcolati a partire dai dati dell'oggetto associato. I checksum vengono utilizzati per verificare che i dati degli oggetti non siano danneggiati. Gli oggetti Cloud Storage hanno diversi campi di metadati del checksum.
CRC32C
Tutti gli oggetti Cloud Storage hanno un hash CRC32C. Le librerie per il calcolo di CRC32C includono:
- CRC32C di Google per C++
- hash/crc32 per Go
- GoogleAPIs Guava per Java
- google-crc32c per Python
- digest-crc in Ruby
Il CRC32C con codifica Base64 è in ordine dei byte big-endian.
MD5
Gli oggetti Cloud Storage hanno un hash MD5 se soddisfano i seguenti criteri:
- L'oggetto non è un oggetto composito
- L'oggetto non è stato caricato utilizzando un caricamento multiparte dell'API XML
Questo hash si applica solo a un oggetto completo, quindi non può essere utilizzato per verificare l'integrità dei download parziali causati dall'esecuzione di un GET di intervallo.
ETags
Tutti gli oggetti Cloud Storage hanno un ETag. Tuttavia, lo stesso oggetto può avere un valore ETag diverso quando viene richiesto dall'API XML rispetto all'API JSON. Nella maggior parte dei casi, gli utenti non devono fare ipotesi sul valore utilizzato in un ETag, tranne che cambia ogni volta che i dati o i metadati sottostanti cambiano, come indicato nella specifica.
L'intestazione ETag di un oggetto restituisce il valore MD5 dell'oggetto se tutte le seguenti condizioni sono vere:
- La richiesta viene effettuata tramite l'API XML
- L'oggetto utilizza solo Google Cloud-powered encryption keys per la crittografia lato server
- L'oggetto non è un oggetto composito e non è stato caricato utilizzando un caricamento multiparte dell'API XML
Ora di modifica
Come parte dei metadati, ogni oggetto Cloud Storage ha una proprietà updated
che indica l'ultima volta che i metadati dell'oggetto sono stati modificati. L'ora
updated
viene inizialmente impostata sull'ora di creazione dell'oggetto e poi cambia
ogni volta che vengono modificati i metadati dell'oggetto. Ciò include le modifiche apportate da un richiedente, ad esempio la modifica dei metadati personalizzati, nonché le modifiche apportate da Cloud Storage per conto di un richiedente, ad esempio la modifica della classe di archiviazione in base a una configurazione del ciclo di vita degli oggetti.
Passaggi successivi
- Visualizzare e modificare i metadati degli oggetti.
- Scopri di più sulle classi di archiviazione disponibili.
- Per una descrizione dettagliata di tutti i campi dei metadati degli oggetti disponibili nell'API JSON, consulta la documentazione di riferimento sugli oggetti per JSON.