バケットラベルの使用

このページでは、Cloud Storage のバケットのラベルを追加、変更、削除、表示する方法について説明します。

必要なロール

バケットラベルを追加して管理するために必要な権限を取得するには、バケットに対するストレージ管理者（roles/storage.admin）IAM ロールを付与するよう管理者に依頼してください。

この事前定義ロールには、バケットラベルの追加と管理に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

storage.buckets.get
storage.buckets.list
- この権限は、Google Cloud コンソールを使用してこのページの手順を実施する場合にのみ必要です。
storage.buckets.update

カスタムロールを使用して、これらの権限を取得することもできます。

バケットに対してロールを付与する手順については、バケットで IAM を使用するをご覧ください。

バケットラベルの追加、変更、削除

コンソール

Google Cloud コンソールで、Cloud Storage の [バケット] ページに移動します。
[バケット] に移動
バケットのリストで、ラベルの追加、変更、削除を行うバケットの名前をクリックします。
[バケットの詳細] ページで、[構成] タブをクリックします。
[ラベル] の編集アイコン（）をクリックします。

ラベルエディタウィンドウが表示されます。
1. ラベルを追加するには、[ ラベルの追加] ボタンをクリックして、ラベルの key と value を指定します。
2. 既存のラベルを変更するには、その値をクリックし、新しい値を入力します。
3. ラベルを削除するには、削除するラベルに対応するゴミ箱アイコンをクリックします。
[保存] をクリックします。

失敗した Cloud Storage オペレーションの詳細なエラー情報を Google Cloud コンソールで確認する方法については、トラブルシューティングをご覧ください。

コマンドライン

新しいラベルを追加するか、既存のラベルを更新するには、--update-labels フラグを指定して gcloud storage buckets update コマンドを使用します。次に例を示します。

gcloud storage buckets update gs://BUCKET_NAME --update-labels=KEY_1=VALUE_1

ここで

BUCKET_NAME は、ラベルが適用されるバケットの名前です。例: my-bucket
KEY_1 は、ラベルのキー名です。例: pet
VALUE_1 は、ラベルの値です。例: dog

既存のラベルを削除するには、-remove-labels フラグを使用します。例:

gcloud storage buckets update gs://BUCKET_NAME --remove-labels=KEY_1

上記のコマンドで複数のラベルを変更するには、関連するフラグにラベルをカンマ区切りリストで指定します。例: --update-labels=blue-key=cyan,red-key=ruby

バケットに適用されているすべてのラベルを削除するには、次のコマンドを使用します。

gcloud storage buckets update gs://BUCKET_NAME --clear-labels

クライアントライブラリ

C++

詳細については、Cloud Storage C++ API のリファレンスドキュメントをご覧ください。

Cloud Storage に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

次のサンプルでは、指定されたラベルをバケットに追加します。バケットにすでにラベルがある場合はラベルを変更します。

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& label_key, std::string const& label_value) {
  StatusOr<gcs::BucketMetadata> updated = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetLabel(label_key, label_value));
  if (!updated) throw std::move(updated).status();

  std::cout << "Successfully set label " << label_key << " to " << label_value
            << " on bucket  " << updated->name() << ".";
  std::cout << " The bucket labels are now:";
  for (auto const& kv : updated->labels()) {
    std::cout << "\n  " << kv.first << ": " << kv.second;
  }
  std::cout << "\n";
}

次のサンプルでは、指定されたラベルをバケットから削除します。

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& label_key) {
  StatusOr<gcs::BucketMetadata> updated = client.PatchBucket(
      bucket_name, gcs::BucketMetadataPatchBuilder().ResetLabel(label_key));
  if (!updated) throw std::move(updated).status();

  std::cout << "Successfully reset label " << label_key << " on bucket  "
            << updated->name() << ".";
  if (updated->labels().empty()) {
    std::cout << " The bucket now has no labels.\n";
    return;
  }
  std::cout << " The bucket labels are now:";
  for (auto const& kv : updated->labels()) {
    std::cout << "\n  " << kv.first << ": " << kv.second;
  }
  std::cout << "\n";
}

C#

詳細については、Cloud Storage C# API のリファレンスドキュメントをご覧ください。

次のサンプルでは、指定されたラベルをバケットに追加します。バケットにすでにラベルがある場合はラベルを変更します。


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class BucketAddLabelSample
{
    public Bucket BucketAddLabel(
        string bucketName = "your-bucket-name",
        string labelKey = "label-key-to-add",
        string labelValue = "label-value-to-add")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName);

        if (bucket.Labels == null)
        {
            bucket.Labels = new Dictionary<string, string>();
        }
        bucket.Labels.Add(labelKey, labelValue);

        bucket = storage.UpdateBucket(bucket);
        Console.WriteLine($"Added label {labelKey} with value {labelValue} to bucket {bucketName}.");
        return bucket;
    }
}

次のサンプルでは、指定されたラベルをバケットから削除します。


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class BucketRemoveLabelSample
{
    public Bucket BucketRemoveLabel(string bucketName = "your-bucket-name", string labelKey = "label-key-to-remove")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName);

        if (bucket.Labels != null && bucket.Labels.Keys.Contains(labelKey))
        {
            bucket.Labels.Remove(labelKey);
            bucket = storage.UpdateBucket(bucket);
            Console.WriteLine($"Removed label {labelKey} from bucket {bucketName}.");
        }
        else
        {
            Console.WriteLine($"No such label available on {bucketName}.");
        }
        return bucket;
    }
}

Go

詳細については、Cloud Storage Go API のリファレンスドキュメントをご覧ください。

次のサンプルでは、指定されたラベルをバケットに追加します。バケットにすでにラベルがある場合はラベルを変更します。

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// addBucketLabel adds a label on a bucket.
func addBucketLabel(w io.Writer, bucketName, labelName, labelValue string) error {
	// bucketName := "bucket-name"
	// labelName := "label-name"
	// labelValue := "label-value"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{}
	bucketAttrsToUpdate.SetLabel(labelName, labelValue)
	if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Added label %q with value %q to bucket %v\n", labelName, labelValue, bucketName)
	return nil
}

次のサンプルでは、指定されたラベルをバケットから削除します。

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// removeBucketLabel removes a label on a bucket.
func removeBucketLabel(w io.Writer, bucketName, labelName string) error {
	// bucketName := "bucket-name"
	// labelName := "label-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{}
	bucketAttrsToUpdate.DeleteLabel(labelName)
	if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Removed label %q from bucket %v\n", labelName, bucketName)
	return nil
}

Java

詳細については、Cloud Storage Java API のリファレンスドキュメントをご覧ください。

次のサンプルでは、指定されたラベルをバケットに追加します。バケットにすでにラベルがある場合はラベルを変更します。


import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.HashMap;
import java.util.Map;

public class AddBucketLabel {
  public static void addBucketLabel(
      String projectId, String bucketName, String labelKey, String labelValue) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The key of the label to add
    // String labelKey = "label-key-to-add";

    // The value of the label to add
    // String labelValue = "label-value-to-add";

    Map<String, String> newLabels = new HashMap<>();
    newLabels.put(labelKey, labelValue);

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);
    Map<String, String> labels = bucket.getLabels();
    if (labels != null) {
      newLabels.putAll(labels);
    }
    bucket.toBuilder().setLabels(newLabels).build().update();

    System.out.println(
        "Added label " + labelKey + " with value " + labelValue + " to bucket " + bucketName + ".");
  }
}

次のサンプルでは、指定されたラベルをバケットから削除します。


import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.HashMap;
import java.util.Map;

public class RemoveBucketLabel {
  public static void removeBucketLabel(String projectId, String bucketName, String labelKey) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The key of the label to remove from the bucket
    // String labelKey = "label-key-to-remove";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    Map<String, String> labelsToRemove = new HashMap<>();
    labelsToRemove.put(labelKey, null);

    Bucket bucket = storage.get(bucketName);
    Map<String, String> labels;
    if (bucket.getLabels() == null) {
      labels = new HashMap<>();
    } else {
      labels = new HashMap(bucket.getLabels());
    }
    labels.putAll(labelsToRemove);
    bucket.toBuilder().setLabels(labels).build().update();

    System.out.println("Removed label " + labelKey + " from bucket " + bucketName);
  }
}

Node.js

詳細については、Cloud Storage Node.js API のリファレンスドキュメントをご覧ください。

次のサンプルでは、指定されたラベルをバケットに追加します。バケットにすでにラベルがある場合はラベルを変更します。

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The key of the label to add
// const labelKey = 'label-key-to-add';

// The value of the label to add
// const labelValue = 'label-value-to-add';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

const labels = {
  [labelKey]: labelValue,
};

async function addBucketLabel() {
  await storage.bucket(bucketName).setMetadata({labels});
  console.log(`Added label to bucket ${bucketName}`);
}

addBucketLabel().catch(console.error);

次のサンプルでは、指定されたラベルをバケットから削除します。

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The key of the label to remove from the bucket
// const labelKey = 'label-key-to-remove';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function removeBucketLabel() {
  const labels = {};
  // To remove a label set the value of the key to null.
  labels[labelKey] = null;
  await storage.bucket(bucketName).setMetadata({labels});
  console.log(`Removed labels from bucket ${bucketName}`);
}

removeBucketLabel().catch(console.error);

PHP

詳細については、Cloud Storage PHP API のリファレンスドキュメントをご覧ください。

次のサンプルでは、指定されたラベルをバケットに追加します。バケットにすでにラベルがある場合はラベルを変更します。

use Google\Cloud\Storage\StorageClient;

/**
 * Adds or updates a bucket label.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $labelName The name of the label to add.
 *        (e.g. 'label-key-to-add')
 * @param string $labelValue The value of the label to add.
 *        (e.g. 'label-value-to-add')
 */
function add_bucket_label(string $bucketName, string $labelName, string $labelValue): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $newLabels = [$labelName => $labelValue];
    $bucket->update(['labels' => $newLabels]);
    printf('Added label %s (%s) to %s' . PHP_EOL, $labelName, $labelValue, $bucketName);
}

次のサンプルでは、指定されたラベルをバケットから削除します。

use Google\Cloud\Storage\StorageClient;

/**
 * Removes a label from a bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $labelName The name of the label to remove.
 *        (e.g. 'label-key-to-remove')
 */
function remove_bucket_label(string $bucketName, string $labelName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $labels = [$labelName => null];
    $bucket->update(['labels' => $labels]);
    printf('Removed label %s from %s' . PHP_EOL, $labelName, $bucketName);
}

Python

詳細については、Cloud Storage Python API のリファレンスドキュメントをご覧ください。

次のサンプルでは、指定されたラベルをバケットに追加します。バケットにすでにラベルがある場合はラベルを変更します。

import pprint

from google.cloud import storage


def add_bucket_label(bucket_name):
    """Add a label to a bucket."""
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    labels = bucket.labels
    labels["example"] = "label"
    bucket.labels = labels
    bucket.patch()

    print(f"Updated labels on {bucket.name}.")
    pprint.pprint(bucket.labels)

次のサンプルでは、指定されたラベルをバケットから削除します。

import pprint

from google.cloud import storage


def remove_bucket_label(bucket_name):
    """Remove a label from a bucket."""
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)

    labels = bucket.labels

    if "example" in labels:
        del labels["example"]

    bucket.labels = labels
    bucket.patch()

    print(f"Removed labels on {bucket.name}.")
    pprint.pprint(bucket.labels)

Ruby

詳細については、Cloud Storage Ruby API のリファレンスドキュメントをご覧ください。

次のサンプルでは、指定されたラベルをバケットに追加します。バケットにすでにラベルがある場合はラベルを変更します。

def add_bucket_label bucket_name:, label_key:, label_value:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The key of the label to add
  # label_key = "label-key-to-add"

  # The value of the label to add
  # label_value = "label-value-to-add"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name

  bucket.update do |bucket|
    bucket.labels[label_key] = label_value
  end

  puts "Added label #{label_key} with value #{label_value} to #{bucket_name}"
end

次のサンプルでは、指定されたラベルをバケットから削除します。

def remove_bucket_label bucket_name:, label_key:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The key of the label to remove from the bucket
  # label_key = "label-key-to-remove"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name

  bucket.update do |bucket|
    bucket.labels[label_key] = nil
  end

  puts "Deleted label #{label_key} from #{bucket_name}"
end

REST API

JSON API

OAuth 2.0 Playground から認可アクセストークンを取得します。固有の OAuth 認証情報を使用するように Playground を構成します。手順については、API 認証をご覧ください。
次の情報が含まれる JSON ファイルを作成します。
```
{
  "labels": {
    "KEY_1": "VALUE_1"
  }
}
```
ここで
- KEY_1 は、ラベルのキー名です。例: pet
- VALUE_1 は、ラベルの値です。例: dogキーを削除するには、"<var>VALUE_1</var>" の代わりに null を使用します。
cURL を使用して JSON API を呼び出し、PATCH Bucket リクエストを行います。
```
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"
```
ここで
- JSON_FILE_NAME は、手順 2 で作成した JSON ファイルのパスです。
- OAUTH2_TOKEN は、手順 1 で生成したアクセストークンです。
- BUCKET_NAME は、ラベルが適用されるバケットの名前です。例: my-bucket

1 つのリクエストで複数の key:value ペアを追加、編集、削除できます。

XML API

OAuth 2.0 Playground から認証アクセストークンを取得します。固有の OAuth 認証情報を使用するように Playground を構成します。手順については、API 認証をご覧ください。
次の情報が含まれる XML ファイルを作成します。
```
<Tagging>
  <TagSet>
    <Tag>
      <Key>KEY_1</Key>
      <Value>VALUE_1</Value>
    </Tag>
  </TagSet>
</Tagging>
```
ここで
- KEY_1 は、ラベルのキー名です。例: pet
- VALUE_1 は、ラベルの値です。例: dog
リクエストには複数の <Tag> 要素を追加できることに注意してください。バケット上のすべてのラベルを削除するには、ファイルに単一の空の <Tag> 要素を使用します。
```
<Tagging>
  <TagSet>
    <Tag>
    </Tag>
  </TagSet>
</Tagging>
```
cURL を使用して、PUT Bucket リクエストと tagging クエリ文字列パラメータを含めた XML API を呼び出します。
```
curl -X PUT --data-binary @XML_FILE_NAME \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  "https://storage.googleapis.com/BUCKET_NAME?tagging"
```
ここで
- XML_FILE_NAME は、手順 2 で作成した XML ファイルのパスです。
- OAUTH2_TOKEN は、手順 1 で生成したアクセストークンです。
- BUCKET_NAME は、ラベルが適用されるバケットの名前です。例: my-bucket

バケットラベルを表示する

コンソール

Google Cloud コンソールで、Cloud Storage の [バケット] ページに移動します。
[バケット] に移動
ラベルを表示するバケットの名前をクリックします。
[構成] タブをクリックします。

バケットに設定されたラベルは、[ラベル] フィールドに表示されます。

コマンドライン

gcloud storage buckets describe コマンドを使用し、--format フラグを指定します。

gcloud storage buckets describe gs://BUCKET_NAME --format="default(labels)"

ここで、BUCKET_NAME はラベルを表示するバケットの名前です。例: my-bucket

処理に成功し、バケットにラベルが存在する場合、レスポンスは次のようになります。

labels:
  red-key: ruby
  blue-key: cyan

処理に成功し、バケットにラベルが存在しない場合、レスポンスは次のようになります。

null