This page shows you how to modify and view the labels set on a bucket in Cloud Storage.
Required permissions
Console
In order to complete this guide using the Google Cloud console, you must have the proper IAM permissions. If the bucket 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 bucket 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 bucket 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 bucket 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.
Modify a bucket's labels
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the bucket list, find the bucket whose labels you want to change, and click its Bucket overflow menu (
).
Click Edit labels.
The label editor panel appears.
To add a label, click the + Add label button, and specify a
key
and avalue
for your label.To modify an existing label, click on its Value and a enter a new value.
To remove a label, click the Trash icon associated with the label you want to remove.
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
To add a new label or update an existing label, use the
gcloud storage buckets update
command with the --update-labels
flag. For example:
gcloud storage buckets update gs://BUCKET_NAME --update-labels=KEY_1=VALUE_1
Where
BUCKET_NAME
is the name of the bucket that the label applies to. For example,my-bucket
.KEY_1
is the key name for your label. For example,pet
.VALUE_1
is the value for your label. For example,dog
.
To delete an existing label, use the -remove-labels
flag. For example:
gcloud storage buckets update gs://BUCKET_NAME --remove-labels=KEY_1
You can change multiple labels in the above commands by including them
in a comma-separated list within the relevant flag. For example,
--update-labels=blue-key=cyan,red-key=ruby
.
To remove all labels attached to a bucket, use the following command:
gcloud storage buckets update gs://BUCKET_NAME --clear-labels
gsutil
To add a new label or update an existing label, use the -l
flag in the
label ch
command. For example:
gsutil label ch -l KEY_1:VALUE_1 gs://BUCKET_NAME
Where
KEY_1
is the key name for your label. For example,pet
.VALUE_1
is the value for your label. For example,dog
.BUCKET_NAME
is the name of the bucket that the label applies to. For example,my-bucket
.
To delete an existing label, use the -d
flag. For example:
gsutil label ch -d KEY_1 gs://BUCKET_NAME
You can use multiple -l
and -d
flags to modify multiple key:value
pairs for a bucket in a single command. Use the label set
command
to replace all existing labels with new ones.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage C# API
reference documentation.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage Go API
reference documentation.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage Java API
reference documentation.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage Node.js API
reference documentation.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage PHP API
reference documentation.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage Python API
reference documentation.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage Ruby API
reference documentation.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket: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. For instructions, see API authentication.
Create a JSON file that contains the following information:
{ "labels": { "KEY_1": "VALUE_1" } }
Where
KEY_1
is the key name for your label. For example,pet
.VALUE_1
is the value for your label. For example,dog
. If you want to remove a key, usenull
in place of"<var>VALUE_1</var>"
.
Use
cURL
to call the JSON API with aPATCH
Bucket 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?fields=labels"
Where:
JSON_FILE_NAME
is the path for the JSON file that you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the bucket that the label applies to. For example,my-bucket
.
You can add, edit, or remove multiple key:value
pairs in a request.
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.
Create an XML file that contains the following information:
<Tagging> <TagSet> <Tag> <Key>KEY_1</Key> <Value>VALUE_1</Value> </Tag> </TagSet> </Tagging>
Where:
KEY_1
is the key name for your label. For example,pet
.VALUE_1
is the value for your label. For example,dog
.
Note that you can add multiple
<Tag>
elements in a request. If you want to remove all labels on a bucket, use a single, empty<Tag>
element in the file:<Tagging> <TagSet> <Tag> </Tag> </TagSet> </Tagging>
Use
cURL
to call the XML API with aPUT
Bucket request andtagging
query string parameter:curl -X PUT --data-binary @XML_FILE_NAME \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?tagging"
Where:
XML_FILE_NAME
is the path for the XML file that you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the bucket that the label applies to. For example,my-bucket
.
View bucket labels
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
(Optional): You can limit the columns displayed in the Google Cloud console bucket list by clicking the Column display options menu (
).
In the bucket list, find the bucket you want to verify, and check the entry for Label. You may need to scroll horizontally to view the Label column.
If your bucket has multiple labels, some may be hidden. When labels are hidden, an expandable button appears. Clicking the button displays all labels for a bucket.
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 buckets describe
command with the
--format
flag:
gcloud storage buckets describe gs://BUCKET_NAME --format="default(labels)"
Where BUCKET_NAME
is the name of the bucket
whose labels you want to view. For example, my-bucket
.
If successful and labels exist for the bucket, the response is similar to the following:
labels: red-key: ruby blue-key: cyan
If successful and labels to not exist for the bucket, the response is similar to the following:
null
gsutil
Use the following gsutil ls
command:
gsutil ls -L -b gs://BUCKET_NAME
Where:
BUCKET_NAME
is the bucket whose labels you want to view. For example,my-bucket
.
The response looks like the following example:
gs://my-bucket/ : Storage class: STANDARD ... ... Labels: { "your_label_key": "your_label_value" } ...
Client libraries
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. For instructions, see API authentication.
Use
cURL
to call the JSON API with aGET
Bucket request that includes thefields=labels
query string parameter:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=labels"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the bucket whose labels you want to view. For example,my-bucket
.
The response looks like the following example:
{ "labels" : { (your_label_key): your_label_value }, }
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 aGET
Bucket request andtagging
query string parameter:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?tagging"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the bucket whose labels you want to view. For example,my-bucket
.
The response looks like the following example:
<Tagging> <TagSet> <Tag> <Key>your_label_key</Key> <Value>your_label_value</Value> </Tag> </TagSet> </Tagging>
What's next
- Learn about bucket tags.
- Get information about a bucket.