Working With Object Metadata
Overview Of Metadata
Objects can have associated metadata, which control aspects of how
GET requests are handled, including Content-Type
, Cache-Control
,
Content-Disposition
, and Content-Encoding
. In addition, you can
set custom key:value
metadata for use by your applications. For a
discussion of specific metadata properties, see the metadata concept
page.
There are two ways to set metadata on objects:
At upload time you can specify one or more metadata properties to associate with objects, using the
gsutil -h option
. For example, the following command would cause gsutil to set theContent-Type
andCache-Control
for each of the files being uploaded from a local directory namedimages
:gsutil -h "Content-Type:text/html" \ -h "Cache-Control:public, max-age=3600" cp -r images \ gs://bucket/images
Note that -h is an option on the gsutil command, not the cp sub-command.
You can set or remove metadata fields from already uploaded objects using the
gsutil setmeta
command. See gsutil help setmeta.
Settable Fields; Field Values
You can't set some metadata fields, such as ETag and Content-Length. The fields you can set are:
Cache-Control
Content-Disposition
Content-Encoding
Content-Language
Content-Type
Custom-Time
- Custom metadata
Field names are case-insensitive.
All fields and their values must consist only of ASCII characters, with the
exception of values for x-goog-meta-
fields, which may contain arbitrary
Unicode values. Note that when setting metadata using the XML API, which sends
custom metadata as HTTP headers, Unicode characters are encoded using
UTF-8, then url-encoded to ASCII. For example:
gsutil setmeta -h "x-goog-meta-foo: ã" gs://bucket/object
stores the custom metadata key-value pair of foo
and %C3%A3
.
Subsequently, running ls -L
using the JSON API to list the object's
metadata prints %C3%A3
, while ls -L
using the XML API
url-decodes this value automatically, printing the character ã
.
Viewing Currently Set Metadata
You can see what metadata is currently set on an object by using:
gsutil ls -L gs://the_bucket/the_object