View and edit object metadata (original) (raw)

Skip to main content

View and edit object metadata

Concepts

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 andCreating and Managing ACLs for guides to accomplishing these tasks.

Required roles

In order to get the required permissions for viewing and editing the metadata of objects, ask your administrator to grant you the Storage Object User (roles/storage.objectUser) role on the bucket.

This role contains the permissions required to view and edit the metadata of objects. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

You might also be able to get these permissions with otherpredefined roles or custom roles.

For instructions on granting roles on buckets, seeUse IAM with buckets.

Complete the following instructions to view the metadata associated with an object:

Console

  1. In the Google Cloud console, go to the Cloud Storage Buckets page.
    Go to Buckets
  2. In the list of buckets, click the name of the bucket that contains the object for which you want to view metadata.
    The Bucket details page opens, with the Objects tab selected.
  3. Navigate to the object, which might 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.
  4. Click the name of the object.
    The Object details page opens, which displays additional object metadata.
  5. Click Edit metadata.
    The overlay window that appears shows the current values for several more object metadata keys, including custom metadata.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

Use the gcloud storage objects describe command:

gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME

Where:

If successful, the response looks similar to the following example:

bucket: my-awesome-bucket content_type: image/png crc32c_hash: pNKjPQ== creation_time: 2024-01-26T21:33:04+0000 custom_fields: Animal: Cat Type: Cute custom_time: 1970-01-01T00:00:00+0000 etag: CMXyydSA/IMDEAE= generation: '1706304784726341' md5_hash: KCbI3PYk1aHfekIvf/osrw== metageneration: 1 name: kitten.png size: 168276 storage_class: STANDARD storage_class_update_time: 2024-01-26T21:33:04+0000 storage_url: gs://my-awesome-bucket/kitten.png#1706304784726341 update_time: 2024-01-26T21:33:04+0000

Client libraries

Terraform

You can use a Terraform resource to view an object's metadata.

REST APIs

JSON API

  1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
  2. Use cURL to call the JSON API with aGET Object request:
    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"
    Where:
    • 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 as pets%2Fdog.png.

XML API

  1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
  2. Use cURL to call the XML API with aHEAD Object request:
    curl -I HEAD \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://storage.googleapis.com/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-bucket.
    • OBJECT_NAME is the URL-encoded name of the object whose metadata you want to view. For example, pets/dog.png, URL-encoded as pets%2Fdog.png.

Edit object metadata

Complete the following steps to edit the metadata associated with an object:

Console

  1. In the Google Cloud console, go to the Cloud Storage Buckets page.
    Go to Buckets
  2. In the list of buckets, click the name of the bucket that contains the object for which you want to edit metadata.
    The Bucket details page opens, with the Objects tab selected.
  3. Navigate to the object, which might be located in a folder.
  4. Click the name of the object.
    The Object details page opens, which displays object metadata.
  5. Click the pencil icon associated with the metadata that you want to edit, if it appears on the page.
  6. Otherwise, click Edit metadata to access additional editable metadata.
    In the overlay window that appears, edit the metadata as needed.
    • For standard metadata fields, edit the Value.
    • Add your own custom metadata by clicking theAdd item button.
    • You can edit both the Key and Value of your custom metadata.
    • Delete your custom metadata by clicking the associated X.
      Once you are finished editing metadata in the overlay window, clickSave.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

Use the gcloud storage objects update command:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME METADATA_FLAG

Where:

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.

Client libraries

REST APIs

JSON API

  1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
  2. Create a JSON file that contains the metadata you want to modify. For more information about metadata associated with an object, see the Cloud Storage Objects resource.
    To add or modify the 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, contentType.
    • 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.
  3. Use cURL to call the JSON API with aPATCH Object request:
    curl -X PATCH --data-binary @JSON_FILE_NAME \
    -H "Authorization: Bearer $(gcloud auth print-access-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.
    • 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 as pets%2Fdog.png.

Note that you can also change an object's metadata with anUPDATE 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 asuploading an object with the following guidelines:

For more information, see Upload an Object for XML.

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-06-12 UTC.