Renommer et déplacer des dossiers

Cette page explique comment renommer et déplacer des dossiers dans un bucket avec l'espace de noms hiérarchique activé.

L'opération de renommage renomme de manière récursive un dossier, ses dossiers enfants et les ressources associées, y compris les objets et les dossiers gérés, en une seule action atomique.

L'opération de renommage est atomique. L'opération aboutit et déplace les ressources vers leur nouveau chemin d'accès, ou échoue avec une erreur. En cas d'erreur, toutes les ressources sont restaurées à leur état d'origine.

Dans un bucket avec espace de noms hiérarchique activé, le renommage d'un dossier est une opération de métadonnées uniquement. Il ne nécessite pas de déplacer ni de copier physiquement les objets dans le dossier. Par conséquent, aucun coût de copie d'objets n'est généré.

Toutefois, dans un bucket sans espace de noms hiérarchique activé, les dossiers sont simulés. Pour renommer ou déplacer un dossier simulé, vous devez copier et supprimer chaque objet qu'il contient. Si votre dossier contient de nombreux objets, le processus de renommage peut être inefficace et coûteux. Le renommage ou le déplacement d'un dossier simulé n'est pas non plus atomique. Autrement dit, si le processus échoue, votre bucket peut rester dans un état incohérent, avec seulement certains objets déplacés.

Pendant le processus de renommage de dossier, vous pouvez lire et lister les ressources en cours de renommage. Toutefois, vous ne pouvez pas exécuter d'opérations d'écriture sur les ressources concernées.

L'opération de modification du nom du dossier lance une opération de longue durée sur un bucket.

Rôles requis

Pour obtenir les autorisations requises pour renommer ou déplacer des dossiers dans des buckets, demandez à votre administrateur de vous accorder le rôle IAM "Utilisateur d'objets Storage" (roles/storage.objectUser) sur le bucket.

Pour en savoir plus sur l'attribution de rôles aux projets, consultez la page Gérer l'accès aux projets.

Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

  • storage.folders.rename
    • Cette autorisation est requise pour le dossier source.
  • storage.folders.create
    • Cette autorisation est requise pour le dossier de destination.

Vous pouvez également obtenir les autorisations précédentes avec d'autres rôles personnalisés ou des rôles prédéfinis. Pour un rôle plus permissif qui vous permet de gérer des dossiers en plus de les renommer, demandez à votre administrateur de vous attribuer l'un des rôles suivants :

  • Administrateur de dossier de l'espace de stockage (roles/storage.folderAdmin)
  • Administrateur des objets de l'espace de stockage (roles/storage.objectAdmin)
  • Administrateur de l'espace de stockage (roles/storage.admin)

Pour connaître les rôles et les autorisations associées, consultez la page Rôles IAM pour Cloud Storage.

Renommer et déplacer un dossier

Console

  1. Dans la console Google Cloud, accédez à la page Buckets Cloud Storage.

    Accéder à la page "Buckets"

  2. Dans la liste des buckets, cliquez sur le nom du bucket qui contient le dossier que vous souhaitez déplacer ou renommer.

  3. Sur la page Informations sur le bucket, recherchez le dossier que vous souhaitez déplacer ou renommer.

  4. Si vous souhaitez renommer le dossier, procédez comme suit:

    1. Cliquez sur le menu Autres actions du dossier.

    2. Cliquez sur Renommer le dossier.

    3. Dans la fenêtre qui apparaît en superposition, saisissez un nouveau nom pour le dossier.

    4. Cliquez sur Renommer.

  5. Si vous souhaitez déplacer le dossier dans un autre dossier, procédez comme suit :

    1. Cliquez sur le menu Autres actions du dossier.

    2. Cliquez sur Déplacer le dossier.

    3. Dans la fenêtre qui apparaît en superposition, cliquez sur Parcourir.

    4. Sélectionnez le dossier de destination du dossier que vous déplacez. Vous pouvez également cliquer sur  pour créer un dossier avant de le sélectionner comme dossier de destination.

    5. Cliquez sur Sélectionner.

    6. Cliquez sur Déplacer.

Pour savoir comment obtenir des informations détaillées sur les erreurs liées aux opérations Cloud Storage ayant échoué dans la console Google Cloud, consultez la section Dépannage.

Ligne de commande

Pour renommer ou déplacer des dossiers dans un bucket doté d'un espace de noms hiérarchique, exécutez la commande gcloud storage mv:

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

Où :

  • BUCKET_NAME correspond au nom du bucket contenant le dossier que vous souhaitez renommer ou déplacer. Exemple :my-bucket
  • FOLDER1 correspond au nom du dossier d'origine que vous souhaitez renommer ou déplacer. Exemple :my-src-folder
  • FOLDER2 est le nouveau nom du dossier de destination. Exemple :my-dest-folder Si le nouveau nom que vous choisissez est déjà utilisé par un dossier existant, le dossier d'origine est déplacé dans le dossier existant et devient un dossier enfant. Par exemple, si vous renommez my-dest-folder en my-dest-folder1 (et que my-dest-folder1 existe déjà), le résultat est my-dest-folder1/my-dest-folder/. Si le nouveau nom que vous choisissez n'existe pas déjà, le dossier d'origine est renommé en conséquence.

La réponse est semblable à ceci :

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

Bibliothèques clientes

C++

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C++.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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#

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C#.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Go.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.


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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Node.js.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage PHP.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Python.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Ruby.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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 REST

API JSON

  1. Vous devez installer et initialiser gcloud CLI, ce qui vous permet de générer un jeton d'accès pour l'en-tête Authorization.

  2. Utilisez cURL pour appeler l'API JSON avec une requête permettant de renommer des dossiers:

    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"

    Où :

    • BUCKET_NAME correspond au nom du bucket contenant le dossier que vous souhaitez renommer ou déplacer. Exemple :my-bucket
    • SOURCE_PATH est le chemin d'accès au format URL du dossier source. Par exemple, my-src-folder/, encodé au format URL : my-src-folder%2F.
    • DESTINATION_PATH correspond au chemin d'accès au dossier de destination encodé au format URL. Par exemple, my-dest-folder/, encodé au format URL : my-dest-folder%2F.

Étapes suivantes

Faites l'essai

Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de Cloud Storage en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

Profiter d'un essai gratuit de Cloud Storage