Create and manage folders

This page describes how to create, list, upload, delete, and get metadata of folders in buckets with hierarchical namespace enabled.

Before you begin

Ensure that your bucket has hierarchical namespace enabled. For detailed instructions about enabling hierarchical namespace on a bucket, see Create buckets with hierarchical namespace enabled .

Create a folder

This section describes how to create a folder.

Roles required

In order to get the required permissions for creating folders, ask your administrator to grant you the Storage Object User ( roles/storage.objectUser ) IAM role on the bucket. This role contains the storage.folders.create permission, which is required to create a folder.

For instructions on granting roles on buckets, see Use IAM with buckets.

You might also be able to get this permission with other custom roles or predefined roles . For a more permissive role that lets you manage folders in addition to creating folders, ask your administrator to grant you any 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, refer to IAM roles for Cloud Storage.

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the bucket list, click the name of the bucket you want to create the folder in.
In the Bucket details page, click Create folder to create an empty folder.
In the Name field, enter a name for your folder. For naming considerations, see Considerations .
Click Create .
Your newly created folder appears in the Folder browser pane.

Command line

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
In your development environment, run the gcloud storage folders create command:
```
gcloud storage folders create --recursive gs:// BUCKET_NAME 
/ FOLDER_NAME 
```
Where:
- BUCKET_NAME is the name of your bucket. For example, my-bucket .
- FOLDER_NAME is the name of the folder you want to create. For example, my-folder/ . For information about folder names, see the folders overview documentation .
- --recursive is a flag that automatically creates all non-existent parent folders along with the folder. This setting is optional when parent folders already exist.
If the request is successful, the command returns the following message:
```
Completed 1/1
```

Client Libraries

C++

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 client libraries .

  namespace 
  
 storagecontrol 
  
 = 
  
 google 
 :: 
 cloud 
 :: 
 storagecontrol_v2 
 ; 
 []( 
 storagecontrol 
 :: 
 StorageControlClient 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 bucket_name 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 folder_id 
 ) 
  
 { 
  
 auto 
  
 const 
  
 parent 
  
 = 
  
 std 
 :: 
 string 
 { 
 "projects/_/buckets/" 
 } 
  
 + 
  
 bucket_name 
 ; 
  
 auto 
  
 folder 
  
 = 
  
 client 
 . 
 CreateFolder 
 ( 
  
 parent 
 , 
  
 google 
 :: 
 storage 
 :: 
 control 
 :: 
 v2 
 :: 
 Folder 
 {}, 
  
 folder_id 
 ); 
  
 if 
  
 ( 
 ! 
 folder 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 folder 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 "Created folder: " 
 << 
 folder 
 - 
> name 
 () 
 << 
 " 
 \n 
 " 
 ; 
 }

C#

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 client libraries .

  using 
  
  Google.Cloud.Storage.Control.V2 
 
 ; 
 using 
  
 System 
 ; 
 public 
  
 class 
  
 StorageControlCreateFolderSample 
 { 
  
 public 
  
 Folder 
  
 StorageControlCreateFolder 
 ( 
 string 
  
 bucketName 
  
 = 
  
 "your-unique-bucket-name" 
 , 
  
 string 
  
 folderName 
  
 = 
  
 "your_folder_name" 
 ) 
  
 { 
  
  StorageControlClient 
 
  
 storageControl 
  
 = 
  
  StorageControlClient 
 
 . 
  Create 
 
 (); 
  
 var 
  
 request 
  
 = 
  
 new 
  
  CreateFolderRequest 
 
  
 { 
  
 // Set project to "_" to signify globally scoped bucket 
  
 Parent 
  
 = 
  
  BucketName 
 
 . 
  FormatProjectBucket 
 
 ( 
 "_" 
 , 
  
 bucketName 
 ), 
  
 FolderId 
  
 = 
  
 folderName 
  
 }; 
  
  Folder 
 
  
 folder 
  
 = 
  
 storageControl 
 . 
  CreateFolder 
 
 ( 
 request 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Folder {folderName} created in bucket {bucketName}" 
 ); 
  
 return 
  
 folder 
 ; 
  
 } 
 }

Go

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 client libraries .

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 control 
  
 "cloud.google.com/go/storage/control/apiv2" 
  
 "cloud.google.com/go/storage/control/apiv2/controlpb" 
 ) 
 // createFolder creates a folder in the bucket with the given name. 
 func 
  
 createFolder 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 bucket 
 , 
  
 folder 
  
 string 
 ) 
  
 error 
  
 { 
  
 // bucket := "bucket-name" 
  
 // folder := "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 
 () 
  
 req 
  
 := 
  
& controlpb 
 . 
 CreateFolderRequest 
 { 
  
 Parent 
 : 
  
 fmt 
 . 
 Sprintf 
 ( 
 "projects/_/buckets/%v" 
 , 
  
 bucket 
 ), 
  
 FolderId 
 : 
  
 folder 
 , 
  
 } 
  
 f 
 , 
  
 err 
  
 := 
  
 client 
 . 
 CreateFolder 
 ( 
 ctx 
 , 
  
 req 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "CreateFolder(%q): %w" 
 , 
  
 folder 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "created folder with path %q" 
 , 
  
 f 
 . 
  Name 
 
 ) 
  
 return 
  
 nil 
 }

Java

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 client libraries .

  import 
  
 com.google.storage.control.v2. BucketName 
 
 ; 
 import 
  
 com.google.storage.control.v2. CreateFolderRequest 
 
 ; 
 import 
  
 com.google.storage.control.v2. Folder 
 
 ; 
 import 
  
 com.google.storage.control.v2. StorageControlClient 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 public 
  
 final 
  
 class 
 CreateFolder 
  
 { 
  
 public 
  
 static 
  
 void 
  
 createFolder 
 ( 
 String 
  
 bucketName 
 , 
  
 String 
  
 folderName 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // The name of the bucket 
  
 // String bucketName = "your-unique-bucket-name"; 
  
 // The name of the folder within the bucket 
  
 // String folderName = "your-unique-folder-name"; 
  
 try 
  
 ( 
  StorageControlClient 
 
  
 storageControl 
  
 = 
  
  StorageControlClient 
 
 . 
 create 
 ()) 
  
 { 
  
  CreateFolderRequest 
 
  
 request 
  
 = 
  
  CreateFolderRequest 
 
 . 
 newBuilder 
 () 
  
 // Set project to "_" to signify globally scoped bucket 
  
 . 
 setParent 
 ( 
  BucketName 
 
 . 
 format 
 ( 
 "_" 
 , 
  
 bucketName 
 )) 
  
 . 
  setFolderId 
 
 ( 
 folderName 
 ) 
  
 . 
 build 
 (); 
  
  Folder 
 
  
 newFolder 
  
 = 
  
 storageControl 
 . 
 createFolder 
 ( 
 request 
 ); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Created folder: %s%n" 
 , 
  
 newFolder 
 . 
  getName 
 
 ()); 
  
 } 
  
 } 
 }

Node.js

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 client libraries .

  /** 
 * TODO(developer): Uncomment these variables before running the sample. 
 */ 
 // The name of your GCS bucket 
 // const bucketName = 'bucketName'; 
 // The name of the folder to be created 
 // const folderName = 'folderName'; 
 // Imports the Control library 
 const 
  
 { 
 StorageControlClient 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage-control 
' 
 ). 
 v2 
 ; 
 // Instantiates a client 
 const 
  
 controlClient 
  
 = 
  
 new 
  
  StorageControlClient 
 
 (); 
 async 
  
 function 
  
 callCreateFolder 
 () 
  
 { 
  
 const 
  
 bucketPath 
  
 = 
  
 controlClient 
 . 
  bucketPath 
 
 ( 
 '_' 
 , 
  
 bucketName 
 ); 
  
 // Create the request 
  
 const 
  
 request 
  
 = 
  
 { 
  
 parent 
 : 
  
 bucketPath 
 , 
  
 folderId 
 : 
  
 folderName 
 , 
  
 }; 
  
 // Run request 
  
 const 
  
 [ 
 response 
 ] 
  
 = 
  
 await 
  
 controlClient 
 . 
 createFolder 
 ( 
 request 
 ); 
  
 console 
 . 
 log 
 ( 
 `Created folder: 
 ${ 
 response 
 . 
 name 
 } 
 .` 
 ); 
 } 
 callCreateFolder 
 ();

PHP

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 client libraries .

  use Google\Cloud\Storage\Control\V2\Client\StorageControlClient; 
 use Google\Cloud\Storage\Control\V2\CreateFolderRequest; 
 /** 
 * Create a new folder in an existing bucket. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 * @param string $folderName The name of your folder inside the bucket. 
 *        (e.g. 'my-folder') 
 */ 
 function create_folder(string $bucketName, string $folderName): void 
 { 
 $storageControlClient = new StorageControlClient(); 
 // Set project to "_" to signify global bucket 
 $formattedName = $storageControlClient->bucketName('_', $bucketName); 
 $request = new CreateFolderRequest([ 
 'parent' => $formattedName, 
 'folder_id' => $folderName, 
 ]); 
 $folder = $storageControlClient->createFolder($request); 
 printf('Created folder: %s', $folder->getName()); 
 }

Python

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 client libraries .

  from 
  
 google.cloud 
  
 import 
  storage_control_v2 
 
 def 
  
 create_folder 
 ( 
 bucket_name 
 : 
 str 
 , 
 folder_name 
 : 
 str 
 ) 
 - 
> None 
 : 
 # The ID of your GCS bucket 
 # bucket_name = "your-unique-bucket-name" 
 # The name of the folder to be created 
 # folder_name = "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. 
 project_path 
 = 
 storage_control_client 
 . 
  common_project_path 
 
 ( 
 "_" 
 ) 
 bucket_path 
 = 
 f 
 " 
 { 
 project_path 
 } 
 /buckets/ 
 { 
 bucket_name 
 } 
 " 
 request 
 = 
  storage_control_v2 
 
 . 
  CreateFolderRequest 
 
 ( 
 parent 
 = 
 bucket_path 
 , 
 folder_id 
 = 
 folder_name 
 , 
 ) 
 response 
 = 
 storage_control_client 
 . 
  create_folder 
 
 ( 
 request 
 = 
 request 
 ) 
 print 
 ( 
 f 
 "Created folder: 
 { 
 response 
 . 
 name 
 } 
 " 
 )

Ruby

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 client libraries .

  def 
  
 create_folder 
  
 bucket_name 
 :, 
  
 folder_name 
 : 
  
 # The ID of your GCS bucket 
  
 # bucket_name = "your-unique-bucket-name" 
  
 # The name of the folder to be created 
  
 # folder_name = "folder-name" 
  
 require 
  
 "google/cloud/storage/control" 
  
 storage_control 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
 Storage 
 :: 
 Control 
 . 
 storage_control 
  
 # The storage bucket path uses the global access pattern, in which the "_" 
  
 # denotes this bucket exists in the global namespace. 
  
 bucket_path 
  
 = 
  
 storage_control 
 . 
 bucket_path 
  
 project 
 : 
  
 "_" 
 , 
  
 bucket 
 : 
  
 bucket_name 
  
 request 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
 Storage 
 :: 
 Control 
 :: 
 V2 
 :: 
 CreateFolderRequest 
 . 
 new 
  
 parent 
 : 
  
 bucket_path 
 , 
  
 folder_id 
 : 
  
 folder_name 
  
 response 
  
 = 
  
 storage_control 
 . 
 create_folder 
  
 request 
  
 puts 
  
 "Created folder: 
 #{ 
 response 
 . 
 name 
 } 
 " 
 end

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.
Create a JSON file that contains the settings for the folder, which must include a name for the folder. See the Folders: Insert documentation for a complete list of settings. The following are required settings to include:
```
 { 
  
 "name" 
 : 
  
 " FOLDER_NAME 
" 
 , 
 } 
```
Where FOLDER_NAME is the name of the folder you want to create. For example, my-folder/ . For information about folder names, see the folders overview documentation .
Use cURL to call the JSON API :
```
curl -X POST --data-binary @ JSON_FILE_NAME 
\
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME 
/folders?recursive=true"
```
Where:
- JSON_FILE_NAME is the name of the JSON file that contains the settings for the folder.
- BUCKET_NAME is the name of the bucket where you want to create the folder.
- recursive is set to true to automatically create all the non-existent parent folders along with the folder. This setting is optional when parent folders already exist.

List folders

This section describes how to list folders.

Roles required

In order to get the required permissions for listing folders, ask your administrator to grant you the Storage Object Viewer ( roles/storage.objectViewer ) IAM role on the bucket. This role contains the storage.folders.list permission, which is required to list folders.

For instructions on granting roles on buckets, see Use IAM with buckets.

You might also be able to get this permission with other custom roles or predefined roles . For a more permissive role that lets you manage folders in addition to listing folders, ask your administrator to grant you any one of the following roles:

Storage Folder Admin ( roles/storage.folderAdmin )
Storage Object Admin ( roles/storage.objectAdmin )
Storage Object User ( roles/storage.objectUser )
Storage Admin ( roles/storage.admin )

To see which roles are associated with which permissions, refer to IAM roles for Cloud Storage.

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the bucket list, click the name of the bucket whose folders you want to list.
From the Folder browserpane, use the expander arrow to expand the list of folders within your bucket.

A list displays the folders, simulated folders, and managed folders in your bucket.

Command line

To list all folders in a bucket, run the gcloud storage folders list command:

gcloud storage folders list gs:// BUCKET_NAME 
/

Where:

BUCKET_NAME is the name of the bucket that contains the folders you want to list. For example, my-bucket .

A successful response looks like the following example:

bucket: hns-bucket
id: hns-bucket/A/
kind: storage#folder
name: A/
selfLink: https://www.googleapis.com/storage/v1/b/hns-bucket/f/A
timeCreated: '2023-05-05T16:32:08.878000+00:00'
updated: '2023-05-05T16:32:08.878000+00:00'
---
bucket: hns-bucket
id: hns-bucket/B/
kind: storage#folder
name: B/
selfLink: https://www.googleapis.com/storage/v1/b/hns-bucket/f/B
timeCreated: '2023-05-05T16:32:08.878000+00:00'
updated: '2023-05-05T16:32:08.878000+00:00'
---
bucket: hns-bucket
id: hns-bucket/B/D/
kind: storage#folder
name: D/
selfLink: https://www.googleapis.com/storage/v1/b/hns-bucket/f/B/D
timeCreated: '2023-05-05T16:32:08.878000+00:00'
updated: '2023-05-05T16:32:08.878000+00:00'
---
bucket: hns-bucket
id: hns-bucket/C/
kind: storage#folder
name: C/
selfLink: https://www.googleapis.com/storage/v1/b/hns-bucket/f/C
timeCreated: '2023-05-05T16:32:08.878000+00:00'
updated: '2023-05-05T16:32:08.878000+00:00'
---
bucket: hns-bucket
id: hns-bucket/C/E/
kind: storage#folder
name: E/
selfLink: https://www.googleapis.com/storage/v1/b/hns-bucket/f/C/E
timeCreated: '2023-05-05T16:32:08.878000+00:00'
updated: '2023-05-05T16:32:08.878000+00:00'
...

Client libraries

C++

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 client libraries .

  namespace 
  
 storagecontrol 
  
 = 
  
 google 
 :: 
 cloud 
 :: 
 storagecontrol_v2 
 ; 
 []( 
 storagecontrol 
 :: 
 StorageControlClient 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 bucket_name 
 ) 
  
 { 
  
 auto 
  
 const 
  
 parent 
  
 = 
  
 std 
 :: 
 string 
 { 
 "projects/_/buckets/" 
 } 
  
 + 
  
 bucket_name 
 ; 
  
 for 
  
 ( 
 auto 
  
 folder 
  
 : 
  
 client 
 . 
 ListFolders 
 ( 
 parent 
 )) 
  
 { 
  
 if 
  
 ( 
 ! 
 folder 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 folder 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 folder 
 - 
> name 
 () 
 << 
 " 
 \n 
 " 
 ; 
  
 } 
  
 std 
 :: 
 cout 
 << 
 bucket_name 
 << 
 std 
 :: 
 endl 
 ; 
 }

C#

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 client libraries .

  using 
  
  Google.Cloud.Storage.Control.V2 
 
 ; 
 using 
  
 System 
 ; 
 using 
  
 System.Collections.Generic 
 ; 
 public 
  
 class 
  
 StorageControlListFoldersSample 
 { 
  
 public 
  
 IEnumerable<Folder> 
  
 StorageControlListFolders 
 ( 
 string 
  
 bucketName 
  
 = 
  
 "your-unique-bucket-name" 
 ) 
  
 { 
  
  StorageControlClient 
 
  
 storageControl 
  
 = 
  
  StorageControlClient 
 
 . 
  Create 
 
 (); 
  
 // Use "_" for project ID to signify globally scoped bucket 
  
 string 
  
 bucketResourceName 
  
 = 
  
  BucketName 
 
 . 
  FormatProjectBucket 
 
 ( 
 "_" 
 , 
  
 bucketName 
 ); 
  
 var 
  
 folders 
  
 = 
  
 storageControl 
 . 
  ListFolders 
 
 ( 
 bucketResourceName 
 ); 
  
 foreach 
  
 ( 
 var 
  
 folder 
  
 in 
  
 folders 
 ) 
  
 { 
  
 Console 
 . 
 Write 
 ( 
 folder 
 . 
 Name 
 ); 
  
 } 
  
 return 
  
 folders 
 ; 
  
 } 
 }

Go

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 client libraries .

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 control 
  
 "cloud.google.com/go/storage/control/apiv2" 
  
 "cloud.google.com/go/storage/control/apiv2/controlpb" 
  
 "google.golang.org/api/iterator" 
 ) 
 // listFolders lists all folders present in the bucket. 
 func 
  
 listFolders 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 bucket 
  
 string 
 ) 
  
 error 
  
 { 
  
 // bucket := "bucket-name" 
  
 // folder := "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 bucket path for a bucket containing folders. 
  
 bucketPath 
  
 := 
  
 fmt 
 . 
 Sprintf 
 ( 
 "projects/_/buckets/%v" 
 , 
  
 bucket 
 ) 
  
 // List all folders present. 
  
 req 
  
 := 
  
& controlpb 
 . 
 ListFoldersRequest 
 { 
  
 Parent 
 : 
  
 bucketPath 
 , 
  
 } 
  
 it 
  
 := 
  
 client 
 . 
 ListFolders 
 ( 
 ctx 
 , 
  
 req 
 ) 
  
 for 
  
 { 
  
 f 
 , 
  
 err 
  
 := 
  
 it 
 . 
 Next 
 () 
  
 if 
  
 err 
  
 == 
  
 iterator 
 . 
  Done 
 
  
 { 
  
 break 
  
 } 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "ListFolders(%q): %w" 
 , 
  
 bucketPath 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "got folder %v\n" 
 , 
  
 f 
 . 
  Name 
 
 ) 
  
 } 
  
 return 
  
 nil 
 }

Java

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 client libraries .

  import 
  
 com.google.storage.control.v2. BucketName 
 
 ; 
 import 
  
 com.google.storage.control.v2. Folder 
 
 ; 
 import 
  
 com.google.storage.control.v2. ListFoldersRequest 
 
 ; 
 import 
  
 com.google.storage.control.v2. StorageControlClient 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 public 
  
 final 
  
 class 
 ListFolders 
  
 { 
  
 public 
  
 static 
  
 void 
  
 listFolders 
 ( 
 String 
  
 bucketName 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // The name of the bucket 
  
 // String bucketName = "your-unique-bucket-name"; 
  
 try 
  
 ( 
  StorageControlClient 
 
  
 storageControl 
  
 = 
  
  StorageControlClient 
 
 . 
 create 
 ()) 
  
 { 
  
  ListFoldersRequest 
 
  
 request 
  
 = 
  
  ListFoldersRequest 
 
 . 
 newBuilder 
 () 
  
 // Set project to "_" to signify globally scoped bucket 
  
 . 
 setParent 
 ( 
  BucketName 
 
 . 
 format 
 ( 
 "_" 
 , 
  
 bucketName 
 )) 
  
 . 
 build 
 (); 
  
 Iterable<Folder> 
  
 folders 
  
 = 
  
 storageControl 
 . 
 listFolders 
 ( 
 request 
 ). 
 iterateAll 
 (); 
  
 for 
  
 ( 
  Folder 
 
  
 folder 
  
 : 
  
 folders 
 ) 
  
 { 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Found folder: %s%n" 
 , 
  
 folder 
 . 
 getName 
 ()); 
  
 } 
  
 } 
  
 } 
 }

Node.js

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 client libraries .

  /** 
 * TODO(developer): Uncomment these variables before running the sample. 
 */ 
 // The name of your GCS bucket 
 // const bucketName = 'bucketName'; 
 // Imports the Control library 
 const 
  
 { 
 StorageControlClient 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage-control 
' 
 ). 
 v2 
 ; 
 // Instantiates a client 
 const 
  
 controlClient 
  
 = 
  
 new 
  
  StorageControlClient 
 
 (); 
 async 
  
 function 
  
 callListFolders 
 () 
  
 { 
  
 const 
  
 bucketPath 
  
 = 
  
 controlClient 
 . 
  bucketPath 
 
 ( 
 '_' 
 , 
  
 bucketName 
 ); 
  
 // Create the request 
  
 const 
  
 request 
  
 = 
  
 { 
  
 parent 
 : 
  
 bucketPath 
 , 
  
 }; 
  
 // Run request 
  
 const 
  
 [ 
 folders 
 ] 
  
 = 
  
 await 
  
 controlClient 
 . 
 listFolders 
 ( 
 request 
 ); 
  
 for 
  
 ( 
 const 
  
 curFolder 
  
 of 
  
 folders 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 curFolder 
 . 
 name 
 ); 
  
 } 
 } 
 callListFolders 
 ();

PHP

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 client libraries .

  use Google\Cloud\Storage\Control\V2\Client\StorageControlClient; 
 use Google\Cloud\Storage\Control\V2\ListFoldersRequest; 
 /** 
 * List folders in an existing bucket. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 */ 
 function list_folders(string $bucketName): void 
 { 
 $storageControlClient = new StorageControlClient(); 
 // Set project to "_" to signify global bucket 
 $formattedName = $storageControlClient->bucketName('_', $bucketName); 
 $request = new ListFoldersRequest([ 
 'parent' => $formattedName, 
 ]); 
 $folders = $storageControlClient->listFolders($request); 
 foreach ($folders as $folder) { 
 printf('Folder name: %s' . PHP_EOL, $folder->getName()); 
 } 
 }

Python

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 client libraries .

  from 
  
 google.cloud 
  
 import 
  storage_control_v2 
 
 def 
  
 list_folders 
 ( 
 bucket_name 
 : 
 str 
 ) 
 - 
> None 
 : 
 # The ID of your GCS bucket 
 # bucket_name = "your-unique-bucket-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. 
 project_path 
 = 
 storage_control_client 
 . 
  common_project_path 
 
 ( 
 "_" 
 ) 
 bucket_path 
 = 
 f 
 " 
 { 
 project_path 
 } 
 /buckets/ 
 { 
 bucket_name 
 } 
 " 
 request 
 = 
  storage_control_v2 
 
 . 
  ListFoldersRequest 
 
 ( 
 parent 
 = 
 bucket_path 
 , 
 ) 
 page_result 
 = 
 storage_control_client 
 . 
  list_folders 
 
 ( 
 request 
 = 
 request 
 ) 
 for 
 folder 
 in 
 page_result 
 : 
 print 
 ( 
 folder 
 ) 
 print 
 ( 
 f 
 "Listed folders in bucket 
 { 
 bucket_name 
 } 
 " 
 )

Ruby

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 client libraries .

  def 
  
 list_folders 
  
 bucket_name 
 : 
  
 # The ID of your GCS bucket 
  
 # bucket_name = "your-unique-bucket-name" 
  
 require 
  
 "google/cloud/storage/control" 
  
 storage_control 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
 Storage 
 :: 
 Control 
 . 
 storage_control 
  
 # The storage bucket path uses the global access pattern, in which the "_" 
  
 # denotes this bucket exists in the global namespace. 
  
 bucket_path 
  
 = 
  
 storage_control 
 . 
 bucket_path 
  
 project 
 : 
  
 "_" 
 , 
  
 bucket 
 : 
  
 bucket_name 
  
 request 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
 Storage 
 :: 
 Control 
 :: 
 V2 
 :: 
 ListFoldersRequest 
 . 
 new 
  
 parent 
 : 
  
 bucket_path 
  
 response 
  
 = 
  
 storage_control 
 . 
 list_folders 
  
 request 
  
 puts 
  
 response 
 . 
 response 
 . 
 folders 
 end

Create and manage folders Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Create a folder

Roles required

Console

Command line

Client Libraries

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

REST APIs

JSON API

List folders

Roles required

Console

Command line

Client libraries

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

REST APIs

JSON API

Upload a folder

Roles required

Console

Command line

Delete a folder

Roles required

Console

Command line

Client libraries

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

REST APIs

JSON API

Get the metadata of a folder

Roles required

Command line

Client libraries

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

REST APIs

JSON API

Manage access on a folder

What's next

Try it for yourself

Create and manage folders