建立及管理代管資料夾

您可以使用受管理資料夾，控管 Cloud Storage 值區中物件的存取權。受管理資料夾可讓您管理物件群組的 IAM 權限，這些物件在物件名稱路徑中具有共同前置字元。這種做法有助於您符合資料安全性與法規遵循規定。本文說明如何建立、列出及刪除受管理資料夾。

事前準備

如要建立及管理代管資料夾，請先啟用統一的值區層級存取權，並取得必要的 IAM 角色。

啟用統一值區層級存取權

如果尚未啟用統一值區層級存取權，請先完成這項作業。

取得必要角色

如要取得建立及管理代管資料夾所需的權限，請要求管理員授予您 bucket 的「Storage 資料夾管理員 」(roles/storage.folderAdmin) IAM 角色。

這個預先定義的角色具備建立及管理受管理資料夾所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立及管理代管資料夾，必須具備下列權限：

  • 如何建立受管理的資料夾： storage.managedFolders.create
  • 如要列出新建立的代管資料夾，藉此驗證： storage.objects.list
  • 如要列出代管資料夾，請執行下列指令： storage.managedFolders.list
  • 如何取得代管資料夾： storage.managedFolders.get
  • 如何移動代管資料夾：
    • storage.managedFolders.delete (來源 bucket)
    • storage.managedFolders.create (用於目的地值區)
  • 如要刪除代管資料夾： storage.managedFolders.delete

如要瞭解如何授予值區角色，請參閱「設定及管理值區的 IAM 政策」。

建立代管資料夾

控制台

使用 Google Cloud 控制台時，您可以對資料夾或模擬資料夾啟用管理功能，藉此建立受管理資料夾。下列步驟說明如何建立資料夾或模擬資料夾，然後啟用資料夾管理功能：

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

    前往「Buckets」(值區) 頁面

  2. 在 bucket 清單中，點選要建立受管理資料夾的 bucket 名稱。

  3. 在「Bucket details」(值區詳細資料) 頁面中，按一下「Create folder」(建立資料夾) 建立新資料夾。如果要轉換為受管理資料夾的資料夾已存在，請跳至說明如何存取「More options」(更多選項) 選單的步驟。

  4. 在「名稱」欄位中，輸入資料夾名稱。如需命名注意事項，請參閱「受管理資料夾名稱」。

  5. 點選「建立」。

    新建立的資料夾會顯示在「資料夾瀏覽器」窗格中。

  6. 在「資料夾瀏覽器」窗格中，按一下要轉換為代管資料夾的資料夾旁邊的「更多選項」 選單，然後按一下「編輯權限」。

    系統會顯示「要啟用資料夾管理機制嗎？」對話方塊。

  7. 按一下「啟用」。

    資料夾會轉換為代管資料夾。畫面上會顯示「Permissions for MANAGED_FOLDER_NAME」(權限) 窗格，其中會列出資料夾的 IAM 政策 (依主體和角色)。如要建立新的 IAM 政策，請參閱「在代管資料夾中設定 IAM 政策」。

指令列

如要建立受管理資料夾，請執行 gcloud storage managed-folders create 指令：

gcloud storage managed-folders create gs://BUCKET_NAME/MANAGED_FOLDER_NAME

其中：

  • BUCKET_NAME 是您要建立受管理資料夾的值區名稱。例如：my-bucket。

  • MANAGED_FOLDER_NAME 是要建立的受管理資料夾名稱。例如：my-managed-folder/。

如要確認受管理資料夾是否已建立，請執行 gcloud storage managed-folders describe 指令：

gcloud storage managed-folders describe gs://BUCKET_NAME/MANAGED_FOLDER_NAME

其中：

  • BUCKET_NAME 是您建立受管理資料夾的值區名稱。

  • MANAGED_FOLDER_NAME 是您建立的受管理資料夾名稱。

用戶端程式庫

C++

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

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

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& bucket_name, std::string const& managed_folder_id) {
  auto const parent = std::string{"projects/_/buckets/"} + bucket_name;
  auto managed_folder = client.CreateManagedFolder(
      parent, google::storage::control::v2::ManagedFolder{},
      managed_folder_id);
  if (!managed_folder) throw std::move(managed_folder).status();

  std::cout << "Created managed folder: " << managed_folder->name() << "\n";
}

C#

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

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

using Google.Cloud.Storage.Control.V2;
using System;

public class StorageControlCreateManagedFolderSample
{
    public ManagedFolder StorageControlCreateManagedFolder(string bucketId = "your-unique-bucket-name",
        string managedFolderId = "your_managed_folder_id")
    {
        StorageControlClient storageControl = StorageControlClient.Create();

        ManagedFolder managedFolder = storageControl.CreateManagedFolder(
            // Set project to "_" to signify globally scoped bucket
            new BucketName("_", bucketId),
            new ManagedFolder(),
            managedFolderId
        );

        Console.WriteLine($"Managed Folder {managedFolderId} created in bucket {bucketId}");
        return managedFolder;
    }
}

Go

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

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

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

	control "cloud.google.com/go/storage/control/apiv2"
	"cloud.google.com/go/storage/control/apiv2/controlpb"
)

// createManagedFolder creates a managed folder in the bucket with the given name.
func createManagedFolder(w io.Writer, bucket, folder string) error {
	// bucket := "bucket-name"
	// folder := "managed-folder-name"

	ctx := context.Background()
	client, err := control.NewStorageControlClient(ctx)
	if err != nil {
		return fmt.Errorf("NewStorageControlClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*30)
	defer cancel()
	mf := &controlpb.ManagedFolder{}

	req := &controlpb.CreateManagedFolderRequest{
		Parent:          fmt.Sprintf("projects/_/buckets/%v", bucket),
		ManagedFolder:   mf,
		ManagedFolderId: folder,
	}
	f, err := client.CreateManagedFolder(ctx, req)
	if err != nil {
		return fmt.Errorf("CreateManagedFolder(%q): %w", folder, err)
	}

	fmt.Fprintf(w, "created Managed Folder with path %q", f.Name)
	return nil
}

Java

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

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


import com.google.storage.control.v2.BucketName;
import com.google.storage.control.v2.CreateManagedFolderRequest;
import com.google.storage.control.v2.ManagedFolder;
import com.google.storage.control.v2.StorageControlClient;

public class CreateManagedFolder {
  public static void managedFolderCreate(String bucketName, String managedFolderId)
      throws Exception {

    // Instantiates a client in a try-with-resource to automatically cleanup underlying resources
    try (StorageControlClient storageControlClient = StorageControlClient.create()) {
      CreateManagedFolderRequest request =
          CreateManagedFolderRequest.newBuilder()
              // Set project to "_" to signify global bucket
              .setParent(BucketName.format("_", bucketName))
              .setManagedFolder(ManagedFolder.newBuilder().build())
              .setManagedFolderId(managedFolderId)
              .build();
      String response = storageControlClient.createManagedFolder(request).getName();
      System.out.printf("Performed createManagedFolder request for %s%n", response);
    }
  }
}

Node.js

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

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */

// The name of your GCS bucket
// const bucketName = 'bucketName';

// The name of the managed folder to be created
// const managedFolderName = 'managedFolderName';

// Imports the Control library
const {StorageControlClient} = require('@google-cloud/storage-control').v2;

// Instantiates a client
const controlClient = new StorageControlClient();

async function callCreateManagedFolder() {
  const bucketPath = controlClient.bucketPath('_', bucketName);

  // Create the request
  const request = {
    parent: bucketPath,
    managedFolderId: managedFolderName,
  };

  // Run request
  const [response] = await controlClient.createManagedFolder(request);
  console.log(`Created managed folder: ${response.name}.`);
}

callCreateManagedFolder();

PHP

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

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

use Google\Cloud\Storage\Control\V2\Client\StorageControlClient;
use Google\Cloud\Storage\Control\V2\CreateManagedFolderRequest;
use Google\Cloud\Storage\Control\V2\ManagedFolder;

/**
 * Create a new folder in an existing bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $managedFolderId The name of your folder inside the bucket.
 *        (e.g. 'my-folder')
 */
function managed_folder_create(string $bucketName, string $managedFolderId): void
{
    $storageControlClient = new StorageControlClient();

    // Set project to "_" to signify global bucket
    $formattedName = $storageControlClient->bucketName('_', $bucketName);

    // $request = new CreateManagedFolderRequest([
    //     'parent' => $formattedName,
    //     'managedFolder' => new ManagedFolder(),
    //     'managedFolderId' => $managedFolderId,
    // ]);
    $request = CreateManagedFolderRequest::build($formattedName, new ManagedFolder(), $managedFolderId);

    $managedFolder = $storageControlClient->createManagedFolder($request);

    printf('Performed createManagedFolder request for %s', $managedFolder->getName());
}

Python

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

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

from google.cloud import storage_control_v2


def create_managed_folder(bucket_name: str, managed_folder_id: str) -> None:
    # The ID of your GCS bucket
    # bucket_name = "your-unique-bucket-name"

    # The name of the managed folder to be created
    # managed_folder_id = "managed-folder-name"

    storage_control_client = storage_control_v2.StorageControlClient()
    # The storage bucket path uses the global access pattern, in which the "_"
    # denotes this bucket exists in the global namespace.
    project_path = storage_control_client.common_project_path("_")
    bucket_path = f"{project_path}/buckets/{bucket_name}"

    request = storage_control_v2.CreateManagedFolderRequest(
        parent=bucket_path,
        managed_folder_id=managed_folder_id,
    )
    response = storage_control_client.create_managed_folder(request=request)

    print(f"Created managed folder: {response.name}")

Ruby

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

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

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

  # The name of the managed folder to be created
  # managed_folder_id = "managed-folder-name"

  require "google/cloud/storage/control"

  storage_control = Google::Cloud::Storage::Control.storage_control

  # The storage bucket path uses the global access pattern, in which the "_"
  # denotes this bucket exists in the global namespace.
  bucket_path = storage_control.bucket_path project: "_", bucket: bucket_name

  request = Google::Cloud::Storage::Control::V2::CreateManagedFolderRequest.new parent: bucket_path,
                                                                                managed_folder_id: managed_folder_id

  response = storage_control.create_managed_folder request

  puts "Created managed folder: #{response.name}"
end

Rust

use google_cloud_storage::{client::StorageControl, model::ManagedFolder};

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const ID: &str = "example001";
    let folder = client
        .create_managed_folder()
        .set_parent(format!("projects/_/buckets/{bucket_id}"))
        .set_managed_folder_id(ID)
        .set_managed_folder(ManagedFolder::new())
        .send()
        .await?;
    println!("folder successfully created {folder:?}");
    Ok(())
}

REST API

JSON API

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

  2. 使用 cURL 透過 POST ManagedFolder 要求呼叫 JSON API：

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-d '{ "name": "MANAGED_FOLDER_NAME" }' \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/managedFolders"

    其中：

    • BUCKET_NAME 是您要建立受管理資料夾的值區名稱。例如：my-bucket。

    • MANAGED_FOLDER_NAME 是您要建立的受管理資料夾名稱。例如：my-managed-folder/。

列出代管資料夾

控制台

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

    前往「Buckets」(值區) 頁面

  2. 在「資料夾瀏覽器」窗格中，使用「切換節點」 展開值區中的資料夾清單。

清單會顯示 bucket 中的資料夾、模擬資料夾和受管理資料夾。

指令列

如要列出受管理資料夾，請執行 gcloud storage managed-folders list 指令：

gcloud storage managed-folders list gs://BUCKET_NAME

其中：

  • BUCKET_NAME 是包含要列出代管資料夾的值區名稱。例如：my-bucket。

請注意，您也可以指定資料夾路徑，而非值區名稱。 例如：

gcloud storage managed-folders list gs://my-bucket/folder/

用戶端程式庫

C++

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

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

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& bucket_name) {
  auto const parent = std::string{"projects/_/buckets/"} + bucket_name;
  for (auto managed_folder : client.ListManagedFolders(parent)) {
    if (!managed_folder) throw std::move(managed_folder).status();
    std::cout << managed_folder->name() << "\n";
  }

  std::cout << bucket_name << std::endl;
}

C#

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

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

using Google.Cloud.Storage.Control.V2;
using System;
using System.Collections.Generic;

public class StorageControlListManagedFoldersSample
{
    public IEnumerable<ManagedFolder> StorageControlListManagedFolders(string bucketId = "your-unique-bucket-name")
    {
        StorageControlClient storageControl = StorageControlClient.Create();

        // Use "_" for project ID to signify globally scoped bucket
        BucketName bucketResourceName = new BucketName("_", bucketId);
        var managedFolders = storageControl.ListManagedFolders(bucketResourceName);

        foreach (var managedFolder in managedFolders)
        {
            Console.Write(managedFolder.Name);
        }
        return managedFolders;
    }
}

Go

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

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

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

	control "cloud.google.com/go/storage/control/apiv2"
	"cloud.google.com/go/storage/control/apiv2/controlpb"
	"google.golang.org/api/iterator"
)

// listManagedFolders lists all managed folders present in the bucket.
func listManagedFolders(w io.Writer, bucket string) error {
	// bucket := "bucket-name"
	// folder := "managed-folder-name"

	ctx := context.Background()
	client, err := control.NewStorageControlClient(ctx)
	if err != nil {
		return fmt.Errorf("NewStorageControlClient: %w", err)
	}
	defer client.Close()

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

	// Construct bucket path for a bucket containing folders.
	bucketPath := fmt.Sprintf("projects/_/buckets/%v", bucket)

	// List all folders present.
	req := &controlpb.ListManagedFoldersRequest{
		Parent: bucketPath,
	}
	it := client.ListManagedFolders(ctx, req)
	for {
		f, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("ListManagedFolders(%q): %w", bucketPath, err)
		}
		fmt.Fprintf(w, "got managed folder %v\n", f.Name)
	}

	return nil
}

Java

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

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


import com.google.storage.control.v2.BucketName;
import com.google.storage.control.v2.ListManagedFoldersRequest;
import com.google.storage.control.v2.ManagedFolder;
import com.google.storage.control.v2.StorageControlClient;

class ListManagedFolders {

  public static void managedFolderList(String bucketName) throws Exception {
    // Instantiates a client in a try-with-resource to automatically cleanup underlying resources
    try (StorageControlClient storageControlClient = StorageControlClient.create()) {
      ListManagedFoldersRequest listManagedFoldersRequest =
          ListManagedFoldersRequest.newBuilder()
              // Set project to "_" to signify global bucket
              .setParent(BucketName.format("_", bucketName))
              .build();
      Iterable<ManagedFolder> managedFolders =
          storageControlClient.listManagedFolders(listManagedFoldersRequest).iterateAll();
      for (ManagedFolder folder : managedFolders) {
        System.out.printf("%s bucket has managed folder %s%n", bucketName, folder.getName());
      }
    }
  }
}

Node.js

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

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */

// The name of your GCS bucket
// const bucketName = 'bucketName';

// Imports the Control library
const {StorageControlClient} = require('@google-cloud/storage-control').v2;

// Instantiates a client
const controlClient = new StorageControlClient();

async function callListManagedFolders() {
  const bucketPath = controlClient.bucketPath('_', bucketName);

  // Create the request
  const request = {
    parent: bucketPath,
  };

  // Run request
  const [folders] = await controlClient.listManagedFolders(request);
  for (const curManagedFolder of folders) {
    console.log(curManagedFolder.name);
  }
}

callListManagedFolders();

PHP

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

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

use Google\Cloud\Storage\Control\V2\Client\StorageControlClient;
use Google\Cloud\Storage\Control\V2\ListManagedFoldersRequest;

/**
 * List folders in an existing bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function managed_folders_list(string $bucketName): void
{
    $storageControlClient = new StorageControlClient();

    // Set project to "_" to signify global bucket
    $formattedName = $storageControlClient->bucketName('_', $bucketName);

    $request = new ListManagedFoldersRequest([
        'parent' => $formattedName,
    ]);

    $folders = $storageControlClient->listManagedFolders($request);

    foreach ($folders as $folder) {
        printf('%s bucket has managed folder %s' . PHP_EOL, $bucketName, $folder->getName());
    }
}

Python

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

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

from google.cloud import storage_control_v2


def list_managed_folders(bucket_name: str = "your-bucket-name") -> None:
    """Lists all managed folders in a Google Cloud Storage bucket.

    Args:
        bucket_name: The name of the Google Cloud Storage bucket.

    Returns:
        None. The function prints the name of each managed folder to the
        console.

    Example:
        >>> list_managed_folders(bucket_name="my-test-bucket")
        Managed folders in bucket projects/_/buckets/my-test-bucket:
            projects/_/buckets/my-test-bucket/managedFolders/folder-one
            projects/_/buckets/my-test-bucket/managedFolders/folder-two
    """
    client = storage_control_v2.StorageControlClient()

    # The storage bucket path uses the global access pattern,
    # in which the "_" denotes this bucket exists in the global namespace.
    GLOBAL_NAMESPACE_PATTERN = "_"
    bucket_resource_name = f"projects/{GLOBAL_NAMESPACE_PATTERN}/buckets/{bucket_name}"

    managed_folders = client.list_managed_folders(parent=bucket_resource_name)

    print(f"Managed folders in bucket {bucket_resource_name}:")
    for managed_folder in managed_folders:
        print(f"\t{managed_folder.name}")

Ruby

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

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

def list_managed_folders bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage/control"

  storage_control = Google::Cloud::Storage::Control.storage_control

  # The storage bucket path uses the global access pattern, in which the "_"
  # denotes this bucket exists in the global namespace.
  bucket_path = storage_control.bucket_path project: "_", bucket: bucket_name

  request = Google::Cloud::Storage::Control::V2::ListManagedFoldersRequest.new parent: bucket_path

  managed_folders = storage_control.list_managed_folders request
  managed_folders.each do |managed_folder|
    puts managed_folder
  end

  puts "Listed managed folders in bucket #{bucket_name}"
end

Rust

use google_cloud_gax::paginator::ItemPaginator;
use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    let mut items = client
        .list_managed_folders()
        .set_parent(format!("projects/_/buckets/{bucket_id}"))
        .by_item();
    println!("Listing managed folders in bucket {bucket_id}");
    while let Some(folder) = items.next().await.transpose()? {
        println!("{folder:?}");
    }
    println!("DONE");
    Ok(())
}

REST API

JSON API

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

  2. 使用 cURL 透過要求列出受管理資料夾呼叫 JSON API：

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/managedFolders"

    其中 BUCKET_NAME 是包含您要列出代管資料夾的值區名稱。例如：my-bucket。

取得代管資料夾的中繼資料

指令列

如要取得受管理資料夾的中繼資料，請執行 gcloud storage managed-folders describe 指令：

  gcloud storage managed-folders describe gs://BUCKET_NAME/MANAGED_FOLDER_NAME

其中：

  • BUCKET_NAME 是包含要列出代管資料夾的值區名稱。例如：my-bucket。

  • MANAGED_FOLDER_NAME 是要擷取中繼資料的受管理資料夾名稱。

用戶端程式庫

C++

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

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

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& bucket_name, std::string const& managed_folder_id) {
  auto const name = std::string{"projects/_/buckets/"} + bucket_name +
                    "/managedFolders/" + managed_folder_id;
  auto managed_folder = client.GetManagedFolder(name);
  if (!managed_folder) throw std::move(managed_folder).status();

  std::cout << "Got managed folder: " << managed_folder->name() << "\n";
}

C#

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

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

using Google.Cloud.Storage.Control.V2;
using System;

public class StorageControlGetManagedFolderSample
{
    public ManagedFolder StorageControlGetManagedFolder(string bucketId = "your-unique-bucket-name",
        string managedFolderId = "your_managed_folder_Id")
    {
        StorageControlClient storageControl = StorageControlClient.Create();

        ManagedFolderName managedFolderResourceName =
            // Set project to "_" to signify globally scoped bucket
            new ManagedFolderName("_", bucketId, managedFolderId);

        ManagedFolder managedFolder = storageControl.GetManagedFolder(managedFolderResourceName);

        Console.WriteLine($"Got managed folder: {managedFolder.Name}");
        return managedFolder;
    }
}

Go

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

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

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

	control "cloud.google.com/go/storage/control/apiv2"
	"cloud.google.com/go/storage/control/apiv2/controlpb"
)

// getManagedFolder gets metadata for the managed folder with the given name.
func getManagedFolder(w io.Writer, bucket, folder string) error {
	// bucket := "bucket-name"
	// folder := "managed-folder-name"

	ctx := context.Background()
	client, err := control.NewStorageControlClient(ctx)
	if err != nil {
		return fmt.Errorf("NewStorageControlClient: %w", err)
	}
	defer client.Close()

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

	// Construct folder path including the bucket name.
	folderPath := fmt.Sprintf("projects/_/buckets/%v/managedFolders/%v/", bucket, folder)

	req := &controlpb.GetManagedFolderRequest{
		Name: folderPath,
	}
	f, err := client.GetManagedFolder(ctx, req)
	if err != nil {
		return fmt.Errorf("GetManagedFolder(%q): %w", folderPath, err)
	}

	fmt.Fprintf(w, "got managed folder metadata: %+v", f)
	return nil
}

Java

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

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


import com.google.storage.control.v2.BucketName;
import com.google.storage.control.v2.GetManagedFolderRequest;
import com.google.storage.control.v2.ManagedFolder;
import com.google.storage.control.v2.ManagedFolderName;
import com.google.storage.control.v2.StorageControlClient;

class GetManagedFolder {

  public static void managedFolderGet(String bucketName, String managedFolderId) throws Exception {
    // Instantiates a client in a try-with-resource to automatically cleanup underlying resources
    try (StorageControlClient storageControlClient = StorageControlClient.create()) {
      // Set project to "_" to signify global bucket
      BucketName resourceBucketName = BucketName.of("_", bucketName);
      GetManagedFolderRequest getManagedFolderRequest =
          GetManagedFolderRequest.newBuilder()
              .setName(
                  ManagedFolderName.format(
                      resourceBucketName.getProject(),
                      resourceBucketName.getBucket(),
                      managedFolderId))
              .build();
      ManagedFolder managedFolder = storageControlClient.getManagedFolder(getManagedFolderRequest);
      System.out.printf("Got Managed Folder %s%n", managedFolder.getName());
    }
  }
}

Node.js

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

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */

// The name of your GCS bucket
// const bucketName = 'bucketName';

// The name of the managed folder to get
// const managedFolderName = 'managedFolderName';

// Imports the Control library
const {StorageControlClient} = require('@google-cloud/storage-control').v2;

// Instantiates a client
const controlClient = new StorageControlClient();

async function callGetManagedFolder() {
  const managedFolderPath = controlClient.managedFolderPath(
    '_',
    bucketName,
    managedFolderName
  );

  // Create the request
  const request = {
    name: managedFolderPath,
  };

  // Run request
  const [response] = await controlClient.getManagedFolder(request);
  console.log(`Got managed folder: ${response.name}.`);
}

callGetManagedFolder();

PHP

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

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

use Google\Cloud\Storage\Control\V2\Client\StorageControlClient;
use Google\Cloud\Storage\Control\V2\GetManagedFolderRequest;

/**
 * Get a folder in an existing bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $managedFolderId The name of your folder inside the bucket.
 *        (e.g. 'my-folder')
 */
function managed_folder_get(string $bucketName, string $managedFolderId): void
{
    $storageControlClient = new StorageControlClient();

    // Set project to "_" to signify global bucket
    $formattedName = $storageControlClient->managedFolderName('_', $bucketName, $managedFolderId);

    $request = new GetManagedFolderRequest([
        'name' => $formattedName,
    ]);

    $managedFolder = $storageControlClient->getManagedFolder($request);

    printf('Got Managed Folder %s', $managedFolder->getName());
}

Python

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

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

from google.cloud import storage_control_v2


def get_managed_folder(bucket_name: str, managed_folder_id: str) -> None:
    # The ID of your GCS bucket
    # bucket_name = "your-unique-bucket-name"

    # The name of the managed folder
    # managed_folder_id = "managed-folder-name"

    storage_control_client = storage_control_v2.StorageControlClient()
    # The storage bucket path uses the global access pattern, in which the "_"
    # denotes this bucket exists in the global namespace.
    folder_path = storage_control_client.managed_folder_path(
        "_", bucket_name, managed_folder_id
    )

    request = storage_control_v2.GetManagedFolderRequest(
        name=folder_path,
    )
    response = storage_control_client.get_managed_folder(request=request)

    print(f"Got managed folder: {response.name}")

Ruby

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

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

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

  # The name of the managed folder to be created
  # managed_folder_id = "managed-folder-name"

  require "google/cloud/storage/control"

  storage_control = Google::Cloud::Storage::Control.storage_control

  # The storage bucket path uses the global access pattern, in which the "_"
  # denotes this bucket exists in the global namespace.
  folder_path = storage_control.managed_folder_path project: "_",
                                                    bucket: bucket_name,
                                                    managed_folder: managed_folder_id

  request = Google::Cloud::Storage::Control::V2::GetManagedFolderRequest.new name: folder_path

  response = storage_control.get_managed_folder request

  puts "Got managed folder: #{response.name}"
end

Rust

use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const ID: &str = "example001";
    let folder = client
        .get_managed_folder()
        .set_name(format!(
            "projects/_/buckets/{bucket_id}/managedFolders/{ID}"
        ))
        .send()
        .await?;
    println!("successfully retrieved managed folder metadata: {folder:?}");
    Ok(())
}

REST API

JSON API

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

  2. 使用 cURL 透過要求取得受管理資料夾，呼叫 JSON API：

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/managedFolders/MANAGED_FOLDER_NAME"

    其中：

    • BUCKET_NAME 是包含要取得的受管理資料夾的值區名稱。例如：my-bucket。

    • MANAGED_FOLDER_NAME 是以路徑表示的受管理資料夾名稱，例如 example-dir/。如果受管理資料夾是巢狀結構，受管理資料夾路徑中的斜線 (/) 字元必須逸出，例如 example-dir1%2Fexample-dir2。

移動代管資料夾

控制台

  1. 在目標值區中建立新的代管資料夾。

  2. 將 IAM 政策從來源 bucket 中的原始代管資料夾，複製到目的地 bucket 中的新代管資料夾。

  3. 將物件從來源值區的原始代管資料夾複製到目的地值區的新代管資料夾。

  4. 從來源 bucket 刪除原始受管理資料夾。

指令列

如要移動受管理資料夾和其中的物件，請執行 gcloud storage mv 指令，並使用 --include-managed-folders 選項：

gcloud storage mv --include-managed-folders gs://SOURCE_BUCKET_NAME/MANAGED_FOLDER_NAME gs://DESTINATION_BUCKET_NAME/MANAGED_FOLDER_NAME

其中：

  • SOURCE_BUCKET 是原始值區的名稱。例如：my-source-bucket`。

  • DESTINATION_BUCKET 是您要將受管理資料夾移至的值區名稱。例如：my-destination-bucket。

  • MANAGED_FOLDER_NAME 是您要移動的受管理資料夾名稱。例如：my-managed-folder/。

REST API

JSON API

如要將受管理資料夾從一個值區移至另一個值區，請完成下列步驟：

  1. 在目標值區中建立新的代管資料夾。

  2. 從來源 bucket 中原始代管資料夾複製 IAM 政策，然後貼到目的地 bucket 中的新代管資料夾。

  3. 將物件從來源值區的原始代管資料夾複製到目的地值區的新代管資料夾。

  4. 從來源 bucket 刪除原始受管理資料夾。

刪除代管資料夾

控制台

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

    前往「Buckets」(值區) 頁面

  2. 在 bucket 清單中，點選含有要刪除受管理資料夾的 bucket 名稱。

  3. 前往「Bucket details」(值區詳細資料) 頁面，找出要刪除的受管理資料夾，然後按一下旁邊的「更多選項」圖示 。

  4. 按一下「刪除資料夾」。

  5. 如要確認刪除受管理資料夾，請在「刪除」欄位中輸入 DELETE。

  6. 點選「刪除」。

    系統會從 Cloud Storage bucket 刪除受管理資料夾及其內容，包括儲存的物件和其他受管理資料夾。

指令列

如要刪除代管資料夾和其中的物件，請執行 gcloud storage rm 指令：

gcloud storage rm -r gs://BUCKET_NAME/MANAGED_FOLDER_NAME

其中：

  • BUCKET_NAME 是包含要刪除之受管理資料夾的值區名稱。例如：my-bucket。

  • MANAGED_FOLDER_NAME 是要刪除的受管理資料夾名稱。例如：my-managed-folder/。

用戶端程式庫

C++

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

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

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& bucket_name, std::string const& managed_folder_id) {
  auto const name = std::string{"projects/_/buckets/"} + bucket_name +
                    "/managedFolders/" + managed_folder_id;
  auto status = client.DeleteManagedFolder(name);
  if (!status.ok()) throw std::move(status);

  std::cout << "Deleted managed folder: " << managed_folder_id << "\n";
}

C#

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

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

using Google.Cloud.Storage.Control.V2;
using System;

public class StorageControlDeleteManagedFolderSample
{
    public void StorageControlDeleteManagedFolder(string bucketId = "your-unique-bucket-name",
        string managedFolderId = "your_managed_folder_id")
    {
        StorageControlClient storageControl = StorageControlClient.Create();

        ManagedFolderName managedFolderResourceName =
            // Set project to "_" to signify globally scoped bucket
            new ManagedFolderName("_", bucketId, managedFolderId);

        storageControl.DeleteManagedFolder(managedFolderResourceName);

        Console.WriteLine($"Deleted managed folder {managedFolderId} from bucket {bucketId}");
    }
}

Go

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

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

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

	control "cloud.google.com/go/storage/control/apiv2"
	"cloud.google.com/go/storage/control/apiv2/controlpb"
)

// deleteManagedFolder deletes the managed folder with the given name.
func deleteManagedFolder(w io.Writer, bucket, folder string) error {
	// bucket := "bucket-name"
	// folder := "managed-folder-name"

	ctx := context.Background()
	client, err := control.NewStorageControlClient(ctx)
	if err != nil {
		return fmt.Errorf("NewStorageControlClient: %w", err)
	}
	defer client.Close()

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

	// Construct folder path including the bucket name.
	folderPath := fmt.Sprintf("projects/_/buckets/%v/managedFolders/%v/", bucket, folder)

	req := &controlpb.DeleteManagedFolderRequest{
		Name: folderPath,
	}
	if err := client.DeleteManagedFolder(ctx, req); err != nil {
		return fmt.Errorf("DeleteManagedFolder(%q): %w", folderPath, err)
	}

	fmt.Fprintf(w, "deleted managed folder %q", folderPath)
	return nil
}

Java

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

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

import com.google.storage.control.v2.BucketName;
import com.google.storage.control.v2.DeleteManagedFolderRequest;
import com.google.storage.control.v2.ManagedFolderName;
import com.google.storage.control.v2.StorageControlClient;

class DeleteManagedFolder {
  public static void managedFolderDelete(String bucketName, String managedFolderId)
      throws Exception {
    // Instantiates a client in a try-with-resource to automatically cleanup underlying resources
    try (StorageControlClient storageControlClient = StorageControlClient.create()) {
      // Set project to "_" to signify global bucket
      BucketName resourceBucketName = BucketName.of("_", bucketName);
      DeleteManagedFolderRequest deleteManagedFolderRequest =
          DeleteManagedFolderRequest.newBuilder()
              .setName(
                  ManagedFolderName.format(
                      resourceBucketName.getProject(),
                      resourceBucketName.getBucket(),
                      managedFolderId))
              .build();
      storageControlClient.deleteManagedFolder(deleteManagedFolderRequest);
      System.out.printf("Deleted Managed Folder %s%n", managedFolderId);
    }
  }
}

Node.js

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

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */

// The name of your GCS bucket
// const bucketName = 'bucketName';

// The name of the folder to be deleted
// const managedFolderName = 'managedFolderName';

// Imports the Control library
const {StorageControlClient} = require('@google-cloud/storage-control').v2;

// Instantiates a client
const controlClient = new StorageControlClient();

async function callDeleteManagedFolder() {
  const managedFolderPath = controlClient.managedFolderPath(
    '_',
    bucketName,
    managedFolderName
  );

  // Create the request
  const request = {
    name: managedFolderPath,
  };

  // Run request
  await controlClient.deleteManagedFolder(request);
  console.log(`Deleted managed folder: ${managedFolderName}.`);
}

callDeleteManagedFolder();

PHP

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

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

use Google\Cloud\Storage\Control\V2\Client\StorageControlClient;
use Google\Cloud\Storage\Control\V2\DeleteManagedFolderRequest;

/**
 * Delete a folder in an existing bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $managedFolderId The id of your folder inside the bucket.
 *        (e.g. 'my-folder')
 */
function managed_folder_delete(string $bucketName, string $managedFolderId): void
{
    $storageControlClient = new StorageControlClient();

    // Set project to "_" to signify global bucket
    $formattedName = $storageControlClient->managedFolderName('_', $bucketName, $managedFolderId);

    $request = DeleteManagedFolderRequest::build($formattedName);

    $storageControlClient->deleteManagedFolder($request);

    printf('Deleted Managed Folder %s', $managedFolderId);
}

Python

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

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

from google.cloud import storage_control_v2


def delete_managed_folder(bucket_name: str, managed_folder_id: str) -> None:
    # The ID of your GCS bucket
    # bucket_name = "your-unique-bucket-name"

    # The name of the managed folder to be deleted
    # managed_folder_id = "managed-folder-name"

    storage_control_client = storage_control_v2.StorageControlClient()
    # The storage bucket path uses the global access pattern, in which the "_"
    # denotes this bucket exists in the global namespace.
    folder_path = storage_control_client.managed_folder_path(
        "_", bucket_name, managed_folder_id
    )

    request = storage_control_v2.DeleteManagedFolderRequest(
        name=folder_path,
    )
    storage_control_client.delete_managed_folder(request=request)

    print(f"Deleted managed folder: {managed_folder_id}")

Ruby

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

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

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

  # The name of the managed folder to be created
  # managed_folder_id = "managed-folder-name"

  require "google/cloud/storage/control"

  storage_control = Google::Cloud::Storage::Control.storage_control

  # The storage bucket path uses the global access pattern, in which the "_"
  # denotes this bucket exists in the global namespace.
  folder_path = storage_control.managed_folder_path project: "_",
                                                    bucket: bucket_name,
                                                    managed_folder: managed_folder_id

  request = Google::Cloud::Storage::Control::V2::DeleteManagedFolderRequest.new name: folder_path

  storage_control.delete_managed_folder request

  puts "Deleted managed folder: #{managed_folder_id}"
end

Rust

use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const ID: &str = "example001";
    client
        .delete_managed_folder()
        .set_name(format!(
            "projects/_/buckets/{bucket_id}/managedFolders/{ID}"
        ))
        .send()
        .await?;
    println!("folder successfully deleted");
    Ok(())
}

REST API

JSON API

如要刪除受管理資料夾，請先刪除受管理資料夾中的物件。

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

  2. 使用 cURL 透過 DELETE ManagedFolder 要求呼叫 JSON API：

    curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/managedFolders/MANAGED_FOLDER_NAME"

    其中：

    • BUCKET_NAME 是包含要刪除之受管理資料夾的值區名稱。例如：my-bucket。

    • MANAGED_FOLDER_NAME 是要刪除的受管理資料夾名稱。例如：my-managed-folder/。

    根據預設，受管理資料夾必須是空的才能刪除。如要刪除非空白的受管理資料夾，請在要求中加入 allowNonEmpty=true 做為查詢參數。

疑難排解

如需建立及管理受管理資料夾的相關說明，請參閱「疑難排解頁面」。

後續步驟