Cambia el nombre de las carpetas y moverlas

En esta página, se describe cómo cambiar el nombre de las carpetas y moverlas en un bucket con el espacio de nombres jerárquico habilitado.

La operación de cambio de nombre cambia el nombre de una carpeta, sus carpetas secundarias y los recursos asociados, incluidos objetos y carpetas administradas en una única acción atómica.

La operación de cambio de nombre es atómica. La operación se completa correctamente y mueve los recursos a su nueva ruta de acceso o falla con un error. En caso de error, todos los recursos se restablecen a su estado original.

En un bucket con el espacio de nombres jerárquico habilitado, cambiar el nombre de una carpeta es operación de solo metadatos. No implica mover físicamente o copiar los objetos dentro de ella, por lo que no se generan costos de copia de objetos.

Sin embargo, en un bucket que no tiene habilitado el espacio de nombres jerárquico, las carpetas simulados. Para cambiar el nombre de una carpeta simulada o moverla, debes copiar y borrar cada objeto que contenga. Si la carpeta contiene muchos objetos, el proceso de cambio de nombre puede ser ineficiente y costoso. Cambiar el nombre o mover una carpeta simulada tampoco es atómico, lo que significa que, si el proceso falla, tu bucket podría quedar en un estado de incoherencia y solo se moverán algunos objetos.

Durante el proceso de cambio de nombre de la carpeta, puedes leer y enumerar los recursos a los que se les cambiará el nombre. Sin embargo, no puedes ejecutar operaciones de escritura en los recursos afectados.

La operación para cambiar el nombre de la carpeta inicia una operación de larga duración en un bucket.

Roles obligatorios

Para obtener los permisos necesarios para cambiar el nombre de las carpetas en los buckets o moverlas, pídele a tu administrador que te otorgue el rol de usuario de objeto (roles/storage.objectUser) de IAM en el bucket.

Para obtener información sobre cómo otorgar roles en proyectos, consulta Administra el acceso a los proyectos.

Para ver los permisos exactos que son necesarios, expande la sección Permisos necesarios:

Permisos necesarios

  • storage.folders.rename
    • Este permiso es necesario en la carpeta de origen.
  • storage.folders.create
    • Este permiso es necesario en la carpeta de destino.

También puedes obtener los permisos anteriores con otros roles personalizados o roles predefinidos. Para un rol más permisivo que te permita administrar carpetas además de cambiar el nombre de las carpetas, pídele a tu administrador que te otorgue uno de los siguientes roles:

  • Administrador de carpetas de almacenamiento (roles/storage.folderAdmin)
  • Administrador de objetos de almacenamiento (roles/storage.objectAdmin)
  • Administrador de almacenamiento (roles/storage.admin)

Para ver qué roles están asociados con qué permisos, consulta Roles de IAM para Cloud Storage.

Cambia el nombre de una carpeta y moverla

Console

  1. En la consola de Google Cloud, ve a la página Buckets de Cloud Storage.

    Ir a Buckets

  2. En la lista de buckets, haz clic en el nombre del bucket que contiene la carpeta a la que deseas cambiarle el nombre o moverla.

  3. En la página Detalles del bucket, busca la carpeta que quieres mover o a la que quieres cambiarle el nombre.

  4. Si quieres cambiarle el nombre, haz lo siguiente:

    1. Haz clic en el menú Más acciones de la carpeta.

    2. Haz clic en Cambiar nombre de la carpeta.

    3. En la ventana de superposición que aparece, ingresa un nuevo nombre para la carpeta.

    4. Haga clic en Cambiar nombre.

  5. Si quieres mover la carpeta a otra, haz lo siguiente:

    1. Haz clic en el menú Más acciones de la carpeta.

    2. Haz clic en Mover carpeta.

    3. En la ventana de superposición que aparece, haz clic en Explorar.

    4. Selecciona la carpeta de destino para la carpeta que quieres mover. También puedes hacer clic en para crear una carpeta nueva antes de seleccionarla como carpeta de destino.

    5. Haz clic en Seleccionar.

    6. Haz clic en Mover.

Para obtener información sobre cómo ver detalles de errores acerca de operaciones fallidas de Cloud Storage en la consola de Google Cloud, consulta Solución de problemas.

Línea de comandos

Para cambiar el nombre de las carpetas o moverlas dentro de un bucket con espacio de nombres jerárquico, ejecuta el comando gcloud storage mv:

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

Aquí:

  • BUCKET_NAME es el nombre del bucket que contiene la carpeta a la que deseas cambiarle el nombre o moverla. Por ejemplo, my-bucket
  • FOLDER1 es el nombre de la carpeta original a la que deseas cambiarle el nombre o moverla. Por ejemplo, my-src-folder
  • FOLDER2 es el nombre nuevo de la carpeta de destino. Por ejemplo, my-dest-folder Si una carpeta existente ya usa el nuevo nombre que elegiste, la carpeta original se moverá dentro de la carpeta existente y se convertirá en una carpeta secundaria. Por ejemplo, si cambias el nombre de my-dest-folder a my-dest-folder1 (y my-dest-folder1 ya existe), el resultado es my-dest-folder1/my-dest-folder/. Si el nombre nuevo que eliges aún no existe, se modificará el nombre de la carpeta original para que coincida con el nuevo.

La respuesta se ve como el siguiente ejemplo:

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

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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#

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Go.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Node.js.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Ruby.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

API de REST

API de JSON

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization.

  2. Usa cURL para llamar a la API de JSON con una solicitud para cambiar el nombre de las carpetas:

    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"

    Donde:

    • BUCKET_NAME es el nombre del bucket que contiene la carpeta a la que deseas cambiarle el nombre o moverla. Por ejemplo, my-bucket
    • SOURCE_PATH es la ruta de acceso codificada como URL de la carpeta de origen. Por ejemplo, my-src-folder/, codificado en URL como my-src-folder%2F.
    • DESTINATION_PATH es la ruta de acceso codificada como URL de la carpeta de destino. Por ejemplo, my-dest-folder/, codificado en URL como my-dest-folder%2F.

Próximos pasos

Pruébalo tú mismo

Si es la primera vez que usas Google Cloud, crea una cuenta para evaluar el rendimiento de Cloud Storage en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

Probar Cloud Storage gratis