建立已啟用階層命名空間的 bucket

本頁說明如何建立啟用階層式命名空間的 bucket。

必要的角色

如要取得建立啟用階層式命名空間的 bucket 所需的權限，請要求管理員授予您專案的「Storage 管理員 」(roles/storage.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備 storage.buckets.create 權限，可建立啟用階層式命名空間的值區。

您或許還可透過自訂角色或其他預先定義的角色取得這項權限。

建立已啟用階層命名空間的 bucket

控制台

1. 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
   

   前往「Buckets」(值區) 頁面

2. 按一下 「建立」。

3. 在「建立 bucket」頁面中，輸入 bucket 資訊。完成下列每個步驟後，請點選「繼續」前往下一個步驟：

   1. 在「開始使用」部分，執行下列操作：

      • 輸入符合bucket 名稱要求的全域不重複名稱。

   2. 在「Choose where to store your data」(選擇資料的儲存位置) 部分，執行下列操作：

      1. 選取「位置類型」。

      2. 使用位置類型下拉式選單，選取要永久儲存 bucket 中物件資料的位置。

         • 如果您選取「雙區域」位置類型，也可以勾選相關核取方塊，啟用強化型複製功能。

   3. 在「選擇資料儲存方式」部分，執行下列操作：

      1. 為 bucket 選取預設儲存空間級別，或選取「Autoclass」，讓系統自動管理 bucket 資料的儲存空間級別。

      2. 在「為資料密集型工作負載提供最理想的儲存空間」部分，執行下列操作：

         • 如要啟用階層命名空間，請選取「為這個 bucket 啟用階層命名空間」。

           注意：只有在建立 bucket 時，才能啟用階層式命名空間。 建立水桶後，您就無法變更這項設定。

   4. 在「Choose how to control access to objects」(選取如何控制物件的存取權) 部分，執行下列操作：

      1. 選取 bucket 是否要強制執行禁止公開存取。

         注意：如果專案的機構政策已強制禁止公開存取， 「禁止公開存取」核取方塊會遭到鎖定。

      2. 選取「統一」，即可在 bucket 上啟用統一 bucket 層級存取權。

   5. 在「選擇保護物件資料的方式」部分，執行下列操作：

      • 選取「資料保護」下方的任何選項，為 bucket 設定保護措施。

      • 如要變更虛刪除功能在刪除物件後保留物件的時間長度，請選取「虛刪除政策」核取方塊，然後選取「設定自訂保留期限」選項。然後指定要保留已刪除物件的時間長度。

        如要停用虛刪除功能 (例如值區主要包含短期暫存資料)，請取消勾選「虛刪除政策」核取方塊。

      • 如要選擇如何加密物件資料，請按一下標示為「資料加密」的 展開箭頭，然後執行下列操作：

        • 在「預設加密金鑰類型」部分，選取 bucket 的預設加密金鑰。如果選取「Cloud KMS key」(Cloud KMS 金鑰)，請提供 Cloud Key Management Service 金鑰。
        • 在「加密機制強制執行規則」部分的「金鑰類型」，選取要允許或限制 bucket 中新物件使用的加密類型。

4. 點選「建立」。

如要瞭解如何在 Google Cloud 控制台中取得 Cloud Storage 作業失敗的詳細錯誤資訊，請參閱「疑難排解」一文。

指令列

1. 在 Google Cloud 控制台中啟用 Cloud Shell。

   啟用 Cloud Shell

   Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

2. 在開發環境中執行 gcloud storage buckets create 指令：

   gcloud storage buckets create gs://BUCKET_NAME --location=BUCKET_LOCATION --uniform-bucket-level-access --enable-hierarchical-namespace

   其中：

   • BUCKET_NAME 是您要為 bucket 指定的名稱，但須符合命名規定。例如：my-bucket。
   • BUCKET_LOCATION 是 bucket 的位置。例如：us-east1。
   • --uniform-bucket-level-access：為 bucket 啟用統一 bucket 層級存取權。
     
     注意：如要建立啟用階層命名空間的 bucket，必須先在 bucket 上啟用統一 bucket 層級存取權。
   • --enable-hierarchical-namespace：為 bucket 啟用階層命名空間。您無法在現有 bucket 中啟用階層命名空間。

   如果要求成功，指令會傳回下列訊息：

   Creating gs://BUCKET_NAME/...

   設定下列標記，進一步控管值區的建立作業：

   • --project：指定要與 bucket 建立關聯的專案 ID 或專案編號。例如：my-project。
   • --default-storage-class：指定 bucket 的預設儲存空間級別。例如：STANDARD。如要自動管理物件的儲存空間級別，請改用 --enable-autoclass 旗標。詳情請參閱「Autoclass」。

   如要查看使用 Google Cloud CLI 建立水桶的完整選項清單，請參閱 buckets create 選項。

   例如：

   gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_ID --default-storage-class=STORAGE_CLASS --location=BUCKET_LOCATION --uniform-bucket-level-access --enable-hierarchical-namespace

用戶端程式庫

C++

詳情請參閱「Cloud Storage C++ API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  auto metadata = client.CreateBucket(
      bucket_name,
      gcs::BucketMetadata()
          .set_hierarchical_namespace(gcs::BucketHierarchicalNamespace{true})
          .set_iam_configuration(gcs::BucketIamConfiguration{
              gcs::UniformBucketLevelAccess{true, {}}, std::nullopt}));
  if (!metadata) throw std::move(metadata).status();

  std::cout << "Bucket " << metadata->name() << " created."
            << "\nFull Metadata: " << *metadata << "\n";
}

C#

詳情請參閱「Cloud Storage C# API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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

public class CreateBucketWithHierarchicalNamespaceEnabledSample
{
    public Bucket CreateBucketWithHierarchicalNamespace(
        string projectId = "your-project-id",
        string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.CreateBucket(projectId,
            new Bucket
            {
                Name = bucketName,
                IamConfiguration = new Bucket.IamConfigurationData
                {
                    UniformBucketLevelAccess = new Bucket.IamConfigurationData.UniformBucketLevelAccessData { Enabled = true }
                },
                HierarchicalNamespace = new Bucket.HierarchicalNamespaceData { Enabled = true }
            });
        Console.WriteLine($"Created {bucketName} with Hierarchical Namespace enabled.");
        return bucket;
    }
}

Go

詳情請參閱「Cloud Storage Go API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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

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

// createBucketHierarchicalNamespace creates a new bucket with hierarchical
// namespace features enabled.
func createBucketHierarchicalNamespace(w io.Writer, projectID, bucketName string) error {
	// projectID := "my-project-id"
	// bucketName := "bucket-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*30)
	defer cancel()

	attrs := &storage.BucketAttrs{
		HierarchicalNamespace: &storage.HierarchicalNamespace{
			Enabled: true,
		},
		// Hierarchical namespace buckets must use uniform bucket-level access.
		UniformBucketLevelAccess: storage.UniformBucketLevelAccess{
			Enabled: true,
		},
	}
	bucket := client.Bucket(bucketName)
	if err := bucket.Create(ctx, projectID, attrs); err != nil {
		return fmt.Errorf("Bucket(%q).Create: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Created bucket %v with hierarchical namespace enabled\n", bucketName)
	return nil
}

Java

詳情請參閱「Cloud Storage Java API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.BucketInfo.HierarchicalNamespace;
import com.google.cloud.storage.BucketInfo.IamConfiguration;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public final class CreateHierarchicalNamespaceBucket {

  public static void createHierarchicalNamespaceBucket(String projectId, String bucketName)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID to give your GCS bucket
    // String bucketName = "your-unique-bucket-name";
    StorageOptions storageOptions = StorageOptions.newBuilder().setProjectId(projectId).build();
    try (Storage storage = storageOptions.getService()) {

      BucketInfo bucketInfo =
          BucketInfo.newBuilder(bucketName)
              .setIamConfiguration(
                  // Hierarchical namespace buckets must use uniform bucket-level access.
                  IamConfiguration.newBuilder().setIsUniformBucketLevelAccessEnabled(true).build())
              .setHierarchicalNamespace(HierarchicalNamespace.newBuilder().setEnabled(true).build())
              .build();

      Bucket bucket = storage.create(bucketInfo);

      System.out.printf(
          "Created bucket %s with Hierarchical Namespace enabled.%n", bucket.getName());
    }
  }
}

Node.js

詳情請參閱「Cloud Storage Node.js API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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

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

// Creates a client
// The bucket in the sample below will be created in the project associated with this client.
// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
const storage = new Storage();

async function createBucketWithHierarchicalNamespace() {
  const [bucket] = await storage.createBucket(bucketName, {
    iamConfiguration: {
      uniformBucketLevelAccess: {
        enabled: true,
      },
    },
    hierarchicalNamespace: {
      enabled: true,
    },
  });

  console.log(
    `Created '${bucket.name}' with hierarchical namespace enabled.`
  );
}

createBucketWithHierarchicalNamespace().catch(console.error);

PHP

詳情請參閱「Cloud Storage PHP API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

use Google\Cloud\Storage\StorageClient;

/**
 * Create a new bucket with Hierarchical Namespace enabled.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function create_bucket_hierarchical_namespace(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->createBucket($bucketName, [
        'hierarchicalNamespace' => ['enabled' => true],
        'iamConfiguration' => ['uniformBucketLevelAccess' => ['enabled' => true]]
    ]);

    printf('Created bucket %s with Hierarchical Namespace enabled.', $bucket->name());
}

Python

詳情請參閱「Cloud Storage Python API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

from google.cloud import storage


def create_bucket_hierarchical_namespace(bucket_name):
    """Creates a bucket with hierarchical namespace enabled."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    bucket.iam_configuration.uniform_bucket_level_access_enabled = True
    bucket.hierarchical_namespace_enabled = True
    bucket.create()

    print(f"Created bucket {bucket_name} with hierarchical namespace enabled.")

Ruby

詳情請參閱「Cloud Storage Ruby API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

def create_bucket_hierarchical_namespace bucket_name:
  # The ID to give your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new

  hierarchical_namespace = Google::Apis::StorageV1::Bucket::HierarchicalNamespace.new enabled: true

  storage.create_bucket bucket_name do |b|
    b.uniform_bucket_level_access = true
    b.hierarchical_namespace = hierarchical_namespace
  end

  puts "Created bucket #{bucket_name} with Hierarchical Namespace enabled."
end

Rust

use google_cloud_storage::{
    client::StorageControl,
    model::Bucket,
    model::bucket::iam_config::UniformBucketLevelAccess,
    model::bucket::{HierarchicalNamespace, IamConfig},
};

pub async fn sample(
    client: &StorageControl,
    project_id: &str,
    bucket_id: &str,
) -> anyhow::Result<()> {
    let bucket = client
        .create_bucket()
        .set_parent("projects/_")
        .set_bucket_id(bucket_id)
        .set_bucket(
            Bucket::new()
                .set_project(format!("projects/{project_id}"))
                .set_hierarchical_namespace(HierarchicalNamespace::new().set_enabled(true))
                .set_iam_config(IamConfig::new().set_uniform_bucket_level_access(
                    UniformBucketLevelAccess::new().set_enabled(true),
                )),
        )
        .send()
        .await?;
    println!("successfully created bucket {bucket:?}");
    Ok(())
}

REST API

JSON API

1. 安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

2. 建立包含 bucket 設定的 JSON 檔案，其中必須包含 bucket 的 name。如需完整的設定清單，請參閱「Buckets: Insert」說明文件。以下是常見的設定：

{
  "name": "BUCKET_NAME",
  "location": "BUCKET_LOCATION",
  "storageClass": "STORAGE_CLASS",
  "hierarchicalNamespace": {
    "enabled": "BOOLEAN"
  },
  "iamConfiguration": {
    "uniformBucketLevelAccess": {
      "enabled": true
  },
},
}

其中：

• BUCKET_NAME 是您要授予值區的名稱，必須遵守命名要求。例如：my-bucket。
• BUCKET_LOCATION 是您希望儲存值區物件資料的位置。例如：US-EAST1。
• STORAGE_CLASS 是值區的預設儲存空間級別。例如：STANDARD。
• hierarchicalNamespace.enabled設為 TRUE，即可為 bucket 啟用階層命名空間。您無法在現有 bucket 中啟用階層命名空間。
3. uniformBucketLevelAccess.enabled 設為 TRUE，即可為 bucket 啟用統一 bucket 層級存取權。
   
   注意：如要建立啟用階層命名空間的 bucket，必須先在 bucket 上啟用統一 bucket 層級存取權。
4. 使用 cURL 呼叫 JSON API：

   curl -X POST --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?project=PROJECT_IDENTIFIER"

   其中：

   • JSON_FILE_NAME 是包含 bucket 設定的 JSON 檔案名稱。
   • PROJECT_IDENTIFIER 是 bucket 關聯的專案 ID 或編號。例如：my-project。

後續步驟

• 瞭解資料夾。
• 建立及管理資料夾。
• 取得 bucket 的中繼資料。
• 取得 bucket 的儲存空間配置。
• 列出及刪除 bucket。

歡迎試用

如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用 Cloud Storage 平台的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

免費試用 Cloud Storage