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 the Content-Type and Cache-Control for each of the files being uploaded from a local directory named images:

    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