This page describes how to rename folders in a bucket with hierarchical namespace enabled.
The rename operation recursively renames a folder, its child folders, and associated resources including objects and managed folders in a single, atomic action.
The rename operation is atomic. The operation either completes successfully and moves resources to their new path or fails with an error. In case of an error, all resources are restored to their original state.
In a bucket with hierarchical namespace enabled, renaming a folder is a metadata-only operation. It does not involve physically moving or copying the objects within the folder, so no object copy costs are incurred.
However, in a bucket without hierarchical namespace enabled, folders are simulated. Renaming or moving a simulated folder requires copying and deleting each object within it. If your folder contains many objects, the rename process can be inefficient and costly. Renaming or moving a simulated folder is also non-atomic, meaning if the process fails, your bucket might be left in an inconsistent state, with only some objects moved.
During the folder rename process, you can read and list the resources being renamed. However, you cannot run write operations on the affected resources.
The folder rename operation initiates a long-running operation on a bucket.
Required roles
In order to get the required permissions for renaming folders in buckets, ask your administrator to grant you the Storage
Object User (roles/storage.objectUser
) IAM role on the bucket.
For more information about granting roles on projects, see Manage access to projects.
To see the exact permissions that are required, expand the Required permissions section:
Required permissions
storage.folders.rename
- This permission is needed on the source folder.
storage.folders.create
- This permission is needed on the destination folder.
You can also get the preceding permissions with other custom roles or predefined roles. For a more permissive role that lets you manage folders in addition to renaming folders, ask your administrator to grant you one of the following roles:
- Storage Folder Admin (
roles/storage.folderAdmin
) - Storage Object Admin (
roles/storage.objectAdmin
) - Storage Admin (
roles/storage.admin
)
To see which roles are associated with which permissions, see IAM roles for Cloud Storage.
Rename a folder
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
C++
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the
Authorization
header.Use
cURL
to call the JSON API with a request to rename folders: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"
Where:
BUCKET_NAME
is the name of the bucket that contains the folder that you want to rename. For example,my-bucket
.SOURCE_PATH
is the URL-encoded path of the source folder. For example,my-src-folder/
URL-encoded asmy-src-folder%2F
.DESTINATION_PATH
is the URL-encoded path of the destination folder. For example,my-dest-folder/
URL-encoded asmy-dest-folder%2F
.
Next steps
Try it for yourself
If you're new to Google Cloud, create an account to evaluate how Cloud Storage performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
Try Cloud Storage free