This page describes how to view and edit the metadata associated with objects stored in Cloud Storage.
This page does not cover viewing or editing Identity and Access Management (IAM) policies or object Access Control Lists (ACLs), both of which control who is allowed to access your data. See Using IAM Permissions and Creating and Managing ACLs for guides to accomplishing these tasks.
Viewing object metadata
To view the metadata associated with an object:
Console
- In the Google Cloud Console, go to the Cloud Storage Browser page.
In the list of buckets, click on the name of the bucket that contains the desired object.
The Bucket details page opens, with the Objects tab selected.
Navigate to the object, which may be located in a folder.
Certain object metadata values, such as the object's size and storage class, are displayed along with the object's name.
Click the more actions menu (
) associated with the object.
Click Edit metadata.
The overlay window that appears shows the current values for the object's editable metadata.
To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.
gsutil
Use the gsutil stat
command:
gsutil stat gs://BUCKET_NAME/OBJECT_NAME
Where:
BUCKET_NAME
is the name of the bucket containing the object whose metadata you want to view. For example,my-awesome-bucket
.OBJECT_NAME
is the name of the object whose metadata you want to view. For example,cat.jpeg
.
If successful, the response looks similar to the following example:
gs://my-awesome-bucket/cat.jpeg: Creation time: Fri, 03 Feb 2017 22:43:31 GMT Update time: Wed, 10 May 2017 18:33:07 GMT Storage class: STANDARD Content-Length: 11012 Content-Type: image/jpeg Metadata: Breed: Tabby Hash (crc32c): HQbzrB== Hash (md5): OBydg25+pPG1Cwawjsl7DA== ETag: CJCh9apA9dECAEs= Generation: 1486161811706000 Metageneration: 11
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aGET
Object request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the bucket containing the object whose metadata you want to view. For example,my-bucket
.OBJECT_NAME
is the name of the object whose metadata you want to view. For example,pets/dog.png
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the XML API with aHEAD
Object request:curl -I HEAD \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the bucket containing the object whose metadata you want to view. For example,my-bucket
.OBJECT_NAME
is the name of the object whose metadata you want to view. For example,pets/dog.png
.
Editing object metadata
To edit the metadata associated with an object:
Console
- In the Google Cloud Console, go to the Cloud Storage Browser page.
In the list of buckets, click on the name of the bucket that contains the desired object.
The Bucket details page opens, with the Objects tab selected.
Navigate to the object, which may be located in a folder.
Click the more actions menu (
) associated with the object.
Click Edit metadata.
In the overlay window that appears, make the desired edits to the metadata.
For standard metadata fields, edit the Value.
Add your own custom metadata by clicking the + Add item button.
You can edit both the Key and Value of your custom metadata.
Delete your custom metadata by clicking the associated X.
Click Save.
To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.
gsutil
Use the gsutil setmeta -h
command:
gsutil setmeta -h "METADATA_KEY:METADATA_VALUE" gs://BUCKET_NAME/OBJECT_NAME
Where:
METADATA_KEY
is the key for the metadata you want to set. For example,Content-Type
.METADATA_VALUE
is the value for the metadata you want to set. For example,image/png
.BUCKET_NAME
is the name of the bucket containing the object whose metadata you want to edit. For example,my-bucket
.OBJECT_NAME
is the name of the object whose metadata you want to edit. For example,pets/dog.png
.
If successful, the response looks like the following example:
Operation completed over 1 objects.
Note that if you are adding custom metadata with gsutil, you must prefix
your metadata key with x-goog-meta-
for gsutil to recognize that this is a
custom metadata attribute, rather than a standard HTTP header. The metadata
key itself is not stored with the x-goog-meta-
prefix. An example of
custom "METADATA_KEY:METADATA_VALUE"
is
"x-goog-meta-dogbreed:shibainu"
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
C++
C#
Go
Node.js
PHP
Python
Ruby
Java
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a .json file that contains the metadata you wish to modify.
To add or modify fixed-key metadata such as
contentType
, use the following format:{ "STANDARD_METADATA_KEY": "STANDARD_METADATA_VALUE" }
Where:
STANDARD_METADATA_KEY
is the key for the metadata you want to add or modify. For example,Content-Type
.STANDARD_METADATA_VALUE
is the value for the metadata you want to add or modify. For example,image/png
.
To add or modify custom metadata, use the following format:
{ "metadata": { "CUSTOM_METADATA_KEY": "CUSTOM_METADATA_VALUE" } }
Where:
CUSTOM_METADATA_KEY
is the custom metadata key that you want to add or modify. For example,dogbreed
.CUSTOM_METADATA_VALUE
is the value you want associated with the custom metadata key. For example,shibainu
.
To delete a custom metadata entry, use the following format:
{ "metadata": { "CUSTOM_METADATA_KEY": null } }
Where:
CUSTOM_METADATA_KEY
is the key for the custom metadata that you want to delete. For example,dogbreed
.
Use
cURL
to call the JSON API with aPATCH
Object request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"
Where:
JSON_FILE_NAME
is the name of the JSON file you created in Step 2.OAUTH2_TOKEN
is the name of the access token you generated in Step 1.BUCKET_NAME
is the name of the bucket containing the object whose metadata you want to edit. For example,my-bucket
.OBJECT_NAME
is the name of the object whose metadata you want to edit. For example,pets/dog.png
.
Note that you can also change an object's metadata with an
UPDATE
Object request. When using this method, any metadata
that is not explicitly specified in the request is removed from the
object's metadata.
XML API
When working with the XML API, metadata can only be set at the time the object is written, such as when uploading, moving, or replacing the object. Follow instructions such as uploading an object with the following guidelines:
Add
-H "METADATA_KEY:METADATA_VALUE"
to the request header for each metadata value you are setting. For example,-H "Content-Type:image/png"
.Prefix
x-goog-meta-
to any custom metadata values. An example of custom"METADATA_KEY:METADATA_VALUE"
is"x-goog-meta-dogbreed:shibainu"
.
For more information, see Upload an Object for XML.
What's next
- Learn more about metadata associated with an object.
- Change the storage class associated with an object.
- Add a hold to an object.