Renomear e mover pastas

Nesta página, descrevemos como renomear e mover pastas em um bucket com namespace hierárquico ativado.

A operação renomeia recursivamente uma pasta, suas pastas filhas e recursos associados, como objetos e pastas gerenciadas, em um único local ação.

A operação de renomeação é atômica. A operação é concluída com êxito e move os recursos para o novo caminho ou falha com um erro. Em caso de erro, todos os recursos sejam restaurados ao estado original.

Em um bucket com namespace hierárquico ativado, renomear uma pasta operação somente de metadados. Não envolve mover fisicamente ou copiar objetos na pasta. Portanto, não haverá custo de cópia de objetos.

Mas, em um bucket sem namespace hierárquico ativado, as pastas simulados. Para renomear ou mover uma pasta simulada, é preciso copiar e excluir todos os objetos contidos nela. Se a pasta contiver muitos objetos, o processo de renomeação poderá ser ineficiente e poderá ser dispendioso. A renomeação ou a movimentação de uma pasta simulada também não são atômicas. Isso significa que, se o processo falhar, o bucket poderá ficar em um estado inconsistente, com apenas alguns objetos movidos.

Durante o processo de renomeação de pastas, é possível ler e listar os recursos que estão sendo renomeados. No entanto, não é possível executar operações de gravação nos recursos afetados.

A operação de renomeação de pasta inicia uma operação de longa duração. em um bucket.

Funções exigidas

Para ter as permissões necessárias para renomear ou mover pastas em buckets, peça ao administrador para conceder a você o papel do IAM de Usuário do objeto do Storage (roles/storage.objectUser) no bucket.

Para mais informações sobre como conceder papéis em projetos, consulte Gerenciar acesso a projetos.

Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

• storage.folders.rename
• Essa permissão é necessária na pasta de origem.
• storage.folders.create
• Essa permissão é necessária na pasta de destino.

Também é possível receber as permissões anteriores com outros papéis personalizados ou Papéis predefinidos. Para um papel mais abrangente, que permite gerenciar pastas além de renomear pastas, peça para o administrador conceder a você uma das papéis a seguir:

• Administrador de pastas de armazenamento (roles/storage.folderAdmin)
• Administrador de objetos do Storage (roles/storage.objectAdmin)
• Administrador do Storage (roles/storage.admin)

Para saber quais papéis estão associados a quais permissões, consulte Papéis do IAM para o Cloud Storage.

Renomear e mover uma pasta

Console

1. No Console do Google Cloud, acesse a página Buckets do Cloud Storage.
   

   Acessar buckets

2. Na lista de buckets, clique no nome do bucket que contém a pasta que você quer mover ou renomear.

3. Na página Detalhes do bucket, encontre a pasta que você quer mover ou renomear.

4. Se você quiser renomear a pasta, faça o seguinte:

   1. Clique no menu Mais ações da pasta.

   2. Clique em Renomear pasta.

   3. Na janela de sobreposição que aparece, insira um novo nome para a pasta.

   4. Clique em Renomear.

5. Se você quiser mover a pasta para outra pasta, faça o seguinte:

   1. Clique no menu Mais ações da pasta.

   2. Clique em Mover pasta.

   3. Na janela de sobreposição que aparece, clique em Procurar.

   4. Selecione a pasta de destino para a pasta que você está movendo. Também é possível clicar em para criar uma nova pasta antes de selecioná-la como a pasta de destino.

   5. Clique em Selecionar.

   6. Clique em Mover.

Para saber como acessar informações detalhadas de erro sobre operações do Cloud Storage com falha no console do Google Cloud, consulte Solução de problemas.

Linha de comando

Para renomear ou mover pastas em um bucket com namespace hierárquico, execute o comando gcloud storage mv:

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

Em que:

• BUCKET_NAME é o nome do bucket que contém a pasta que você quer renomear ou mover. Por exemplo, my-bucket.
• FOLDER1 é o nome da pasta original que você quer renomear ou mover. Por exemplo, my-src-folder.
• FOLDER2 é o novo nome da pasta de destino. Por exemplo, my-dest-folder. Se o novo nome escolhido já estiver sendo usado por uma pasta existente, a pasta original será movida para dentro da pasta existente, tornando-se uma pasta filha. Por exemplo, se você renomear my-dest-folder como my-dest-folder1 (e my-dest-folder1 já existir), o resultado será my-dest-folder1/my-dest-folder/. Se o novo nome escolhido ainda não existir, a pasta original será renomeada para corresponder ao novo nome.

A resposta terá esta aparência:

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

Bibliotecas de cliente

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage C++.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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#

Para mais informações, consulte a documentação de referência da API Cloud Storage C#.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para mais informações, consulte a documentação de referência da API Cloud Storage Go.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para mais informações, consulte a documentação de referência da API Cloud Storage Node.js.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para mais informações, consulte a documentação de referência da API Cloud Storage PHP.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para mais informações, consulte a documentação de referência da API Cloud Storage Python.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

Para mais informações, consulte a documentação de referência da API Cloud Storage Ruby.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

APIs REST

API JSON

1. Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

2. Use cURL para chamar a API JSON com uma solicitação para renomear pastas:

   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"

   Em que:

   • BUCKET_NAME é o nome do bucket que contém a pasta que você quer renomear ou mover. Por exemplo, my-bucket.
   • SOURCE_PATH é o caminho codificado pelo URL da pasta de origem. Por exemplo, my-src-folder/, codificado em URL como my-src-folder%2F.
   • DESTINATION_PATH é o caminho codificado de URL da pasta de destino. Por exemplo, my-dest-folder/, codificado em URL como my-dest-folder%2F.

Próximas etapas

• Crie e gerencie pastas.
• Use o namespace hierárquico para cargas de trabalho do Hadoop.

Faça um teste

Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho do Cloud Storage em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Faça uma avaliação gratuita do Cloud Storage