폴더 이름 바꾸기 및 이동

이 페이지에서는 계층적 네임스페이스가 사용 설정된 버킷에서 폴더의 이름을 바꾸고 이동하는 방법을 설명합니다.

이름 바꾸기 작업은 폴더, 하위 폴더, 객체 및 관리 폴더를 포함한 관련 리소스의 이름을 단일 원자 작업으로 재귀적으로 바꿉니다.

이름 변경 작업은 원자적입니다. 작업이 성공적으로 완료되어 리소스를 새 경로로 이동하거나 오류와 함께 실패합니다. 오류가 발생하면 모든 리소스가 원래 상태로 복원됩니다.

계층적 네임스페이스가 사용 설정된 버킷에서 폴더의 이름을 바꾸는 작업은 메타데이터 전용 작업입니다. 폴더 내 객체를 물리적으로 이동하거나 복사하지 않으므로 객체 복사 비용이 발생하지 않습니다.

그러나 계층적 네임스페이스가 사용 설정되지 않은 버킷에서는 폴더가 시뮬레이션됩니다. 시뮬레이션된 폴더의 이름을 바꾸거나 이동하려면 폴더 내의 각 객체를 복사하고 삭제해야 합니다. 폴더에 객체가 많으면 이름을 바꾸는 프로세스가 비효율적이고 비용이 많이 들 수 있습니다. 시뮬레이션된 폴더의 이름을 변경하거나 이동하는 것도 비원자적입니다. 즉, 프로세스가 실패하면 일부 객체만 이동된 상태로 버킷이 일치하지 않는 상태로 남아 있을 수 있습니다.

폴더 이름을 바꾸는 동안 이름이 바뀌는 리소스를 읽고 나열할 수 있습니다. 그러나 영향을 받는 리소스에서는 쓰기 작업을 실행할 수 없습니다.

폴더 이름 변경 작업은 버킷에서 장기 실행 작업을 시작합니다.

필요한 역할

버킷의 폴더 이름을 바꾸거나 이동하는 데 필요한 권한을 얻으려면 관리자에게 버킷에 대한 스토리지 객체 사용자(roles/storage.objectUser) IAM 역할을 부여해 달라고 요청하세요.

프로젝트에 대해 역할을 부여하는 방법에 대한 자세한 내용은 프로젝트에 대한 액세스 관리를 참조하세요.

필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

  • storage.folders.rename
    • 소스 폴더에 이 권한이 필요합니다.
  • storage.folders.create
    • 대상 폴더에 이 권한이 필요합니다.

다른 커스텀 역할이나 사전 정의된 역할을 사용하여 위의 권한을 얻을 수도 있습니다. 폴더 이름을 바꾸는 것 외에도 폴더를 관리할 수 있는 더 관대한 역할을 부여받으려면 관리자에게 다음 역할 중 하나를 부여해 달라고 요청하세요.

  • 스토리지 폴더 관리자(roles/storage.folderAdmin)
  • 스토리지 객체 관리자(roles/storage.objectAdmin)
  • 스토리지 관리자(roles/storage.admin)

어떤 역할이 어떤 권한과 연결되어 있는지 확인하려면 Cloud Storage에 대한 IAM 역할을 참조하세요.

폴더 이름 바꾸기 및 이동

콘솔

  1. Google Cloud 콘솔에서 Cloud Storage 버킷 페이지로 이동합니다.

    버킷으로 이동

  2. 버킷 목록에서 이동하거나 이름을 바꿀 폴더가 포함된 버킷의 이름을 클릭합니다.

  3. 버킷 세부정보 페이지에서 이동하거나 이름을 바꾸려는 폴더를 찾습니다.

  4. 폴더 이름을 변경하려면 다음 단계를 따르세요.

    1. 폴더의 추가 작업 메뉴를 클릭합니다.

    2. 폴더 이름 바꾸기를 클릭합니다.

    3. 나타나는 오버레이 창에서 폴더의 새 이름을 입력합니다.

    4. 이름 바꾸기를 클릭합니다.

  5. 폴더를 다른 폴더로 이동하려면 다음 단계를 따르세요.

    1. 폴더의 추가 작업 메뉴를 클릭합니다.

    2. 폴더 이동을 클릭합니다.

    3. 오버레이 창이 나타나면 찾아보기를 클릭합니다.

    4. 이동할 폴더의 대상 폴더를 선택합니다. 를을 클릭하여 새 폴더를 만든 후 대상 폴더로 선택할 수도 있습니다.

    5. 선택을 클릭합니다.

    6. 이동을 클릭합니다.

Google Cloud 콘솔에서 실패한 Cloud Storage 작업에 대한 자세한 오류 정보를 가져오는 방법은 문제 해결을 참조하세요.

명령줄

계층적 네임스페이스가 있는 버킷 내에서 폴더의 이름을 바꾸거나 폴더를 이동하려면 gcloud storage mv 명령어를 실행합니다.

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

각 항목의 의미는 다음과 같습니다.

  • BUCKET_NAME은 이름을 바꾸거나 이동하려는 폴더가 포함된 버킷의 이름입니다. 예를 들면 my-bucket입니다.
  • FOLDER1은 이름을 바꾸거나 이동하려는 원본 폴더의 이름입니다. 예를 들면 my-src-folder입니다.
  • FOLDER2는 대상 폴더의 새 이름입니다. 예를 들면 my-dest-folder입니다. 선택한 새 이름이 기존 폴더에서 이미 사용 중인 경우 원래 폴더가 기존 폴더 내로 이동하여 하위 폴더가 됩니다. 예를 들어 my-dest-folder의 이름을 my-dest-folder1로 바꾸고 my-dest-folder1이 이미 있으면 결과는 my-dest-folder1/my-dest-folder/입니다. 선택한 새 이름이 아직 없는 경우 원래 폴더의 이름이 새 이름과 일치하도록 변경됩니다.

응답은 다음 예시와 같습니다.

Copying gs://my-bucket/my-src-folder to gs://hns-bucket/my-dest-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& 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#

자세한 내용은 Cloud Storage C# API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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

자세한 내용은 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"
)

// 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

자세한 내용은 Cloud Storage Java API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.


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

자세한 내용은 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 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

자세한 내용은 Cloud Storage PHP API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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

자세한 내용은 Cloud Storage Python API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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

자세한 내용은 Cloud Storage Ruby API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

  2. cURL를 사용하여 폴더 이름 변경 요청으로 JSON API를 호출합니다.

    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"

    각 항목의 의미는 다음과 같습니다.

    • BUCKET_NAME은 이름을 바꾸거나 이동하려는 폴더가 포함된 버킷의 이름입니다. 예를 들면 my-bucket입니다.
    • SOURCE_PATH는 소스 폴더의 URL 인코딩 경로입니다. 예를 들어 my-src-folder/my-src-folder%2F로 URL 인코딩됩니다.
    • DESTINATION_PATH는 대상 폴더의 URL 인코딩 경로입니다. 예를 들어 my-dest-folder/my-dest-folder%2F로 URL 인코딩됩니다.

다음 단계

직접 사용해 보기

Google Cloud를 처음 사용하는 경우 계정을 만들어 실제 시나리오에서 Cloud Storage의 성능을 평가할 수 있습니다. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

Cloud Storage 무료로 사용해 보기