Mengganti nama dan memindahkan folder

Halaman ini menjelaskan cara mengganti nama dan memindahkan folder di bucket dengan namespace hierarkis yang diaktifkan.

Operasi ganti nama secara rekursif mengganti nama folder, folder turunannya, dan resource terkait, termasuk objek dan folder terkelola dalam satu tindakan atomik.

Operasi penggantian nama bersifat atomik. Operasi berhasil diselesaikan dan memindahkan resource ke jalur barunya atau gagal dengan error. Jika terjadi error, semua resource akan dipulihkan ke status aslinya.

Di bucket dengan namespace hierarkis yang diaktifkan, mengganti nama folder adalah operasi khusus metadata. Tindakan ini tidak melibatkan pemindahan atau penyalinan objek secara fisik dalam folder, sehingga tidak ada biaya penyalinan objek yang akan dikenakan.

Namun, di bucket tanpa namespace hierarkis yang diaktifkan, folder akan disimulasikan. Mengganti nama atau memindahkan folder simulasi memerlukan penyalinan dan penghapusan setiap objek di dalamnya. Jika folder Anda berisi banyak objek, proses penggantian nama dapat menjadi tidak efisien dan mahal. Mengganti nama atau memindahkan folder simulasi juga bersifat non-atomik, yang berarti jika proses gagal, bucket Anda mungkin akan dibiarkan dalam status yang tidak konsisten, dengan hanya beberapa objek yang dipindahkan.

Selama proses penggantian nama folder, Anda dapat membaca dan mencantumkan resource yang diganti namanya. Namun, Anda tidak dapat menjalankan operasi tulis pada resource yang terpengaruh.

Operasi penggantian nama folder memulai operasi yang berjalan lama di bucket.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna mengganti nama atau memindahkan folder di bucket, minta administrator untuk memberi Anda peran IAM Storage Object User (roles/storage.objectUser) di bucket.

Untuk mengetahui informasi selengkapnya tentang cara memberikan peran pada project, lihat Mengelola akses ke project.

Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

• storage.folders.rename
• Izin ini diperlukan di folder sumber.
• storage.folders.create
• Izin ini diperlukan di folder tujuan.

Anda juga bisa mendapatkan izin sebelumnya dengan peran khusus atau peran standar lainnya. Untuk peran yang lebih permisif yang memungkinkan Anda mengelola folder selain mengganti nama folder, minta administrator untuk memberi Anda salah satu peran berikut:

• Storage Folder Admin (roles/storage.folderAdmin)
• Storage Object Admin (roles/storage.objectAdmin)
• Storage Admin (roles/storage.admin)

Untuk melihat peran mana yang terkait dengan izin apa, lihat Peran IAM untuk Cloud Storage.

Mengganti nama dan memindahkan folder

Konsol

1. Di Konsol Google Cloud, buka halaman Bucket Cloud Storage.
   

   Buka Bucket

2. Dalam daftar bucket, klik nama bucket yang berisi folder yang ingin dipindahkan atau diganti namanya.

3. Di halaman Bucket details, temukan folder yang ingin dipindahkan atau diganti namanya.

4. Jika Anda ingin mengganti nama folder, lakukan hal berikut:

   1. Klik menu Tindakan lainnya folder.

   2. Klik Ganti nama folder.

   3. Di jendela overlay yang muncul, masukkan nama baru untuk folder.

   4. Klik Ganti nama.

5. Jika Anda ingin memindahkan folder ke folder lain, lakukan tindakan berikut:

   1. Klik menu Tindakan lainnya folder.

   2. Klik Pindahkan folder.

   3. Di jendela overlay yang muncul, klik Jelajahi.

   4. Pilih folder tujuan untuk folder yang Anda pindahkan. Anda juga dapat mengklik untuk membuat folder baru sebelum memilihnya sebagai folder tujuan.

   5. Klik Pilih.

   6. Klik Pindahkan.

Untuk mempelajari cara mendapatkan informasi error mendetail tentang operasi Cloud Storage yang gagal di Konsol Google Cloud, lihat Pemecahan masalah.

Command line

Untuk mengganti nama atau memindahkan folder dalam bucket dengan namespace hierarkis, jalankan perintah gcloud storage mv:

gcloud storage mv gs://BUCKET_NAME/FOLDER1 gs://BUCKET_NAME/FOLDER2

Dengan keterangan:

• BUCKET_NAME adalah nama bucket yang berisi folder yang ingin diganti namanya atau dipindahkan. Contoh, my-bucket.
• FOLDER1 adalah nama folder asli yang ingin Anda ganti namanya atau pindahkan. Contoh, my-src-folder.
• FOLDER2 adalah nama baru folder tujuan. Contoh, my-dest-folder. Jika nama baru yang Anda pilih sudah digunakan oleh folder yang ada, folder asli akan dipindahkan ke dalam folder yang ada, menjadi folder turunan. Misalnya, jika Anda mengganti nama my-dest-folder menjadi my-dest-folder1 (dan my-dest-folder1 sudah ada), hasilnya adalah my-dest-folder1/my-dest-folder/. Jika nama baru yang Anda pilih belum ada, folder asli akan diganti namanya agar cocok dengan nama baru.

Responsnya akan terlihat seperti contoh berikut:

Copying gs://my-bucket/my-src-folder to gs://hns-bucket/my-dest-folder...

Library klien

C++

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage C++ API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& bucket_name, std::string const& source_folder_id,
   std::string const& dest_folder_id) {
  auto name = std::string{"projects/_/buckets/"} + bucket_name + "/folders/" +
              source_folder_id;
  // Start a rename operation and block until it completes. Real applications
  // may want to setup a callback, wait on a coroutine, or poll until it
  // completes.
  auto renamed = client.RenameFolder(name, dest_folder_id).get();
  if (!renamed) throw std::move(renamed).status();

  std::cout << "Renamed: " << source_folder_id << " to: " << dest_folder_id
            << "\n";
}

C#

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage C# API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

public class StorageControlRenameFolderSample
{
    public Folder StorageControlRenameFolder(string bucketName = "your-unique-bucket-name",
        string sourceFolderName = "your_folder_name", string targetFolderName = "target_folder_name")
    {
        StorageControlClient storageControl = StorageControlClient.Create();

        string folderResourceName =
            // Set project to "_" to signify globally scoped bucket
            FolderName.FormatProjectBucketFolder("_", bucketName, sourceFolderName);

        var operation = storageControl.RenameFolder(folderResourceName, targetFolderName);
        var folder = operation.PollUntilCompleted().Result;

        Console.WriteLine($"Renamed folder {sourceFolderName} to {targetFolderName}");
        return folder;
    }
}

Go

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Go API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

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

// renameFolder changes the name of an existing folder.
func renameFolder(w io.Writer, bucket, src, dst string) error {
	// bucket := "bucket-name"
	// src := "original-folder-name"
	// dst := "new-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 source folder path including the bucket name.
	srcPath := fmt.Sprintf("projects/_/buckets/%v/folders/%v", bucket, src)

	req := &controlpb.RenameFolderRequest{
		Name:                srcPath,
		DestinationFolderId: dst,
	}
	op, err := client.RenameFolder(ctx, req)
	if err != nil {
		return fmt.Errorf("RenameFolder(%q): %w", srcPath, err)
	}

	// Wait for long-running operation to complete.
	f, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("waiting for RenameFolder: %w", err)
	}

	fmt.Fprintf(w, "folder %v moved to new path %v", srcPath, f.Name)
	return nil
}

Java

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Java API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import com.google.api.gax.longrunning.OperationFuture;
import com.google.storage.control.v2.Folder;
import com.google.storage.control.v2.FolderName;
import com.google.storage.control.v2.RenameFolderMetadata;
import com.google.storage.control.v2.RenameFolderRequest;
import com.google.storage.control.v2.StorageControlClient;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public final class RenameFolder {

  public static void renameFolder(
      String bucketName, String sourceFolderName, String destinationFolderName)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // The name of the bucket
    // String bucketName = "your-unique-bucket-name";

    // The name of the folder within the bucket
    // String sourceFolderName = "your-unique-source-folder-name";

    // The new name of the folder within the bucket
    // String destinationFolderName = "your-unique-destination-folder-name";

    try (StorageControlClient storageControl = StorageControlClient.create()) {

      // Set project to "_" to signify globally scoped bucket
      String sourceFolderResourceName = FolderName.format("_", bucketName, sourceFolderName);
      RenameFolderRequest request =
          RenameFolderRequest.newBuilder()
              .setName(sourceFolderResourceName)
              .setDestinationFolderId(destinationFolderName)
              .build();

      OperationFuture<Folder, RenameFolderMetadata> renameOperation =
          storageControl.renameFolderAsync(request);

      Folder destinationFolder = renameOperation.get(30, TimeUnit.SECONDS);

      System.out.printf(
          "Renamed folder from %s to %s%n", sourceFolderResourceName, destinationFolder.getName());
    }
  }
}

Node.js

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Node.js API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

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

// The source folder name
// const sourceFolderName = 'currentFolderName';

// The destination folder ID
// const destinationFolderName = 'destinationFolderName';

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

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

async function callRenameFolder() {
  const folderPath = controlClient.folderPath(
    '_',
    bucketName,
    sourceFolderName
  );

  // Create the request
  const request = {
    name: folderPath,
    destinationFolderId: destinationFolderName,
  };

  // Run request
  await controlClient.renameFolder(request);
  console.log(
    `Renamed folder ${sourceFolderName} to ${destinationFolderName}.`
  );
}

callRenameFolder();

PHP

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage PHP API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

/**
 * Rename a folder in an existing bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $sourceFolder The source folder ID.
 *        (e.g. 'my-folder')
 * @param string $destinationFolder The destination folder ID.
 *        (e.g. 'my-folder')
 */
function rename_folder(string $bucketName, string $sourceFolder, string $destinationFolder): void
{
    $storageControlClient = new StorageControlClient();

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

    $request = new RenameFolderRequest([
        'name' => $formattedName,
        'destination_folder_id' => $destinationFolder,
    ]);

    $storageControlClient->renameFolder($request);

    printf('Renamed folder %s to %s', $sourceFolder, $destinationFolder);
}

Python

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Python API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

from google.cloud import storage_control_v2


def rename_folder(
    bucket_name: str, source_folder_name: str, destination_folder_name: str
) -> None:
    # The ID of your GCS bucket
    # bucket_name = "your-unique-bucket-name"
    #
    # The source folder ID
    # source_folder_name = "current-folder-name"
    #
    # The destination folder ID
    # destination_folder_name = "new-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.
    source_folder_path = storage_control_client.folder_path(
        project="_", bucket=bucket_name, folder=source_folder_name
    )

    request = storage_control_v2.RenameFolderRequest(
        name=source_folder_path,
        destination_folder_id=destination_folder_name,
    )

    operation = storage_control_client.rename_folder(request=request)
    operation.result(60)

    print(f"Renamed folder {source_folder_name} to {destination_folder_name}")

Ruby

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Ruby API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

def rename_folder bucket_name:, source_folder_id:, destination_folder_id:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"
  #
  # The source folder ID
  # source_folder_id = "current-folder-id"
  #
  # The destination folder ID, e.g. foo/bar/
  # destination_folder_id = "destination-folder-id"

  require "google/cloud/storage/control"

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

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

  request = Google::Cloud::Storage::Control::V2::RenameFolderRequest.new name: folder_path,
                                                                         destination_folder_id: destination_folder_id

  storage_control.rename_folder request

  puts "Renamed folder #{source_folder_id} to #{destination_folder_id}"
end

REST API

JSON API

1. Menginstal dan melakukan inisialisasi gcloud CLI , yang memungkinkan Anda membuat token akses untuk header Authorization.

2. Gunakan cURL untuk memanggil JSON API dengan permintaan untuk mengganti nama folder:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/folders/SOURCE_PATH/renameTo/folders/DESTINATION_PATH"

   Dengan keterangan:

   • BUCKET_NAME adalah nama bucket yang berisi folder yang ingin Anda ganti namanya atau pindahkan. Contoh, my-bucket.
   • SOURCE_PATH adalah jalur folder sumber yang dienkode ke URL. Misalnya, URL my-src-folder/ dienkode sebagai my-src-folder%2F.
   • DESTINATION_PATH adalah jalur folder tujuan yang dienkode URL. Misalnya, URL my-dest-folder/ dienkode sebagai my-dest-folder%2F.

Langkah berikutnya

• Membuat dan mengelola folder.
• Gunakan namespace hierarkis untuk workload Hadoop.

Coba sendiri

Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa Cloud Storage dalam skenario dunia nyata. Pelanggan baru mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

Coba Cloud Storage gratis