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.
Required permissions
Console
In order to complete this guide using the Google Cloud console, you must have the proper IAM permissions. If the object you want to access exists in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.
For a list of permissions required for specific actions, see IAM permissions for the Google Cloud console.
For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.
Command line
In order to complete this guide using a command-line utility, you must have the proper IAM permissions. If the object you want to access exists in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.
For a list of permissions required for specific actions, see IAM permissions for gsutil commands.
For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.
Client libraries
In order to complete this guide using the Cloud Storage client libraries, you must have the proper IAM permissions. If the object you want to access exists in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.
Unless otherwise noted, client library requests are made through the JSON API and require permissions as listed in IAM permissions for JSON methods. To see which JSON API methods are invoked when you make requests using a client library, log the raw requests.
For a list of relevant IAM roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.
REST APIs
JSON API
In order to complete this guide using the JSON API, you must have the proper IAM permissions. If the object you want to access exists in a project that you did not create, you might need the project owner to give you a role that contains the necessary permissions.
For a list of permissions required for specific actions, see IAM permissions for JSON methods.
For a list of relevant roles, see Cloud Storage roles. Alternatively, you can create a custom role that has specific, limited permissions.
View object metadata
Complete the following instructions to view the metadata associated with an object:
Console
- In the Google Cloud console, go to the Cloud Storage Buckets 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 Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
gcloud
Use the gcloud storage objects describe
command:
gcloud storage objects describe 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:
bucket: my-awesome-bucket crc32c: pNKjPQ== etag: CN2c0uXT6uICEAk= generation: '1584387380410716' id: my-awesome-bucket/cat.jpeg/1584387380410716 kind: storage#object md5Hash: KCbI3PYk1aHfekIvf/osrw== mediaLink: https://storage.googleapis.com/download/storage/v1/b/my-awesome-bucket/o/cat.jpeg?generation=1584387380410716&alt=media metadata: Animal: Cat Type: Cute metageneration: '5' name: cat.jpeg selfLink: https://www.googleapis.com/storage/v1/b/my-awesome-bucket/o/cat.jpeg size: '168276' storageClass: STANDARD timeCreated: '2022-03-16T19:36:20.410000+00:00' timeStorageClassUpdated: '2022-03-16T19:36:20.410000+00:00' updated: '2022-05-12T22:16:58.455000+00:00'
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
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Terraform
You can use a Terraform resource to view an object's metadata.
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
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 URL-encoded name of the object whose metadata you want to view. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
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 URL-encoded name of the object whose metadata you want to view. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.
Edit object metadata
Complete the following steps to edit the metadata associated with an object:
Console
- In the Google Cloud console, go to the Cloud Storage Buckets 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 Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
gcloud
Use the gcloud storage objects update
command:
gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME METADATA_FLAG
Where:
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
.METADATA_FLAG
is the flag for the metadata you want to edit. For example--content-type=image/png
.
If successful, the response looks like the following example:
Patching gs://my-bucket/pets/dog.png#1560574162144861... Completed 1
For a complete list of metadata that you can update with this command, see the command reference page.
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"
.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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. For instructions, see API authentication.
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 \ -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 path for the file that 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 URL-encoded name of the object whose metadata you want to edit. For example,pets/dog.png
, URL-encoded aspets%2Fdog.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.
- Get bucket metadata.
- Change an object's storage class.
- Add a hold to an object.
- Learn how to use request preconditions to ensure object metadata doesn't change in between requests.