Use object contexts

Object contexts are custom key-value pairs that you can attach to Cloud Storage objects. You can use object contexts to classify data, track processing workflows, and help enrich your objects with metadata. These contexts persist when you copy, compose, or restore objects.

This page describes how to attach and manage contexts on Cloud Storage objects.

Get the required roles

To get the permissions that you need to create and manage object contexts, ask your administrator to grant you the following IAM roles on the object:

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to create and manage object contexts. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create and manage object contexts:

  • Create an object with object contexts:
    • storage.objects.create
    • storage.objects.createContext
  • Attach, update, and delete object contexts:
    • storage.objects.update
    • storage.objects.createContext
    • storage.objects.updateContext
    • storage.objects.deleteContext
  • Drop object contexts: storage.objects.dropContexts
  • View object contexts:
    • storage.objects.get
    • storage.objects.list

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

Naming requirements for key-value pairs

Both keys and values for custom contexts must meet the following requirements:

  • Must be between 1 and 256 characters, inclusive.

  • Must begin with an alphanumeric character.

  • Must be a valid UTF-8 character. Most UTF-8 characters are supported, except for the following characters:

    • Single quote (')

    • Double quote (")

    • Backslash (\)

    • Forward slash (/)

Attach contexts to new objects

Attach contexts to objects when you upload new objects to Cloud Storage buckets. Each context consists of a key and a value.

Console

  1. In the Google Cloud console, go to the Cloud Storage Buckets page.

    Go to Buckets

  2. Upload the object.

  3. Follow the steps to attach contexts to the object.

Command line

To attach contexts when you upload objects with the gcloud storage cp command, use the --custom-contexts flag:

gcloud storage cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME --custom-contexts=KEY=VALUE,...

Where:

  • OBJECT_LOCATION is the local path to your object. For example, Desktop/employees.txt.
  • DESTINATION_BUCKET_NAME is the name of the bucket to which you are uploading your object. For example, my-bucket.
  • KEY is the context key to attach to an object. For example, Department. You can specify multiple key-value pairs separated by commas.
  • VALUE is the value to associate with the context key. For example, Human resources.

Alternatively, create a JSON file that contains the contexts you want to attach to the objects, and use the --custom-contexts-file flag:

  {
    "KEY": {
      "value": "VALUE"
    },
    ...
  }

Where:

  • KEY is the context key to attach to an object. For example, Department. You can specify multiple key-value pairs.
  • VALUE is the value to associate with the context key. For example, Human resources.

To attach contexts when you upload directories with the gcloud storage rsync command, use the