docs(storage): folder and manage folder examples

src/storage/examples/Cargo.toml

@@ -28,6 +28,7 @@ anyhow.workspace               = true
 clap                           = { workspace = true, features = ["derive", "std"] }
 futures.workspace              = true
 google-cloud-gax.workspace     = true
+google-cloud-lro.workspace     = true
 google-cloud-wkt.workspace     = true
 google-cloud-storage.workspace = true
 rand.workspace                 = true

src/storage/examples/src/control.rs

@@ -0,0 +1,23 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+pub mod create_folder;
+pub mod delete_folder;
+pub mod get_folder;
+pub mod list_folders;
+pub mod managed_folder_create;
+pub mod managed_folder_delete;
+pub mod managed_folder_get;
+pub mod managed_folder_list;
+pub mod rename_folder;

src/storage/examples/src/control/create_folder.rs

@@ -0,0 +1,30 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_control_create_folder]
+use google_cloud_storage::{client::StorageControl, model::Folder};
+
+pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    const ID: &str = "example-folder-id";
+    let folder = client
+        .create_folder()
+        .set_parent(format!("projects/_/buckets/{bucket_id}"))
+        .set_folder_id(ID)
+        .set_folder(Folder::new())
+        .send()
+        .await?;
+    println!("folder successfully created {folder:?}");
+    Ok(())
+}
+// [END storage_control_create_folder]

src/storage/examples/src/control/delete_folder.rs

@@ -0,0 +1,28 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_control_delete_folder]
+use google_cloud_storage::client::StorageControl;
+
+pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    const ID: &str = "deleted-folder-id";
+    client
+        .delete_folder()
+        .set_name(format!("projects/_/buckets/{bucket_id}/folders/{ID}"))
+        .send()
+        .await?;
+    println!("folder successfully deleted");
+    Ok(())
+}
+// [END storage_control_delete_folder]

src/storage/examples/src/control/get_folder.rs

@@ -0,0 +1,28 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_control_get_folder]
+use google_cloud_storage::client::StorageControl;
+
+pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    const ID: &str = "example-folder-id";
+    let folder = client
+        .get_folder()
+        .set_name(format!("projects/_/buckets/{bucket_id}/folders/{ID}"))
+        .send()
+        .await?;
+    println!("folder metadata successfully retrieved {folder:?}");
+    Ok(())
+}
+// [END storage_control_get_folder]

src/storage/examples/src/control/list_folders.rs

@@ -0,0 +1,31 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_control_list_folders]
+use google_cloud_gax::paginator::ItemPaginator;
+use google_cloud_storage::client::StorageControl;
+
+pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    let mut items = client
+        .list_folders()
+        .set_parent(format!("projects/_/buckets/{bucket_id}"))
+        .by_item();
+    println!("Listing folders in bucket {bucket_id}");
+    while let Some(folder) = items.next().await.transpose()? {
+        println!("{folder:?}");
+    }
+    println!("DONE");
+    Ok(())
+}
+// [END storage_control_list_folders]

src/storage/examples/src/control/managed_folder_create.rs

@@ -0,0 +1,30 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_control_managed_folder_create]
+use google_cloud_storage::{client::StorageControl, model::ManagedFolder};
+
+pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    const ID: &str = "example001";
+    let folder = client
+        .create_managed_folder()
+        .set_parent(format!("projects/_/buckets/{bucket_id}"))
+        .set_managed_folder_id(ID)
+        .set_managed_folder(ManagedFolder::new())
+        .send()
+        .await?;
+    println!("folder successfully created {folder:?}");
+    Ok(())
+}
+// [END storage_control_managed_folder_create]

src/storage/examples/src/control/managed_folder_delete.rs

@@ -0,0 +1,30 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_control_managed_folder_delete]
+use google_cloud_storage::client::StorageControl;
+
+pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    const ID: &str = "example001";
+    client
+        .delete_managed_folder()
+        .set_name(format!(
+            "projects/_/buckets/{bucket_id}/managedFolders/{ID}"
+        ))
+        .send()
+        .await?;
+    println!("folder successfully deleted");
+    Ok(())
+}
+// [END storage_control_managed_folder_delete]

src/storage/examples/src/control/managed_folder_get.rs

@@ -0,0 +1,30 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_control_managed_folder_get]
+use google_cloud_storage::client::StorageControl;
+
+pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    const ID: &str = "example001";
+    let folder = client
+        .get_managed_folder()
+        .set_name(format!(
+            "projects/_/buckets/{bucket_id}/managedFolders/{ID}"
+        ))
+        .send()
+        .await?;
+    println!("successfully retrieved managed folder metadata: {folder:?}");
+    Ok(())
+}
+// [END storage_control_managed_folder_get]

src/storage/examples/src/control/managed_folder_list.rs

@@ -0,0 +1,31 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_control_managed_folder_list]
+use google_cloud_gax::paginator::ItemPaginator;
+use google_cloud_storage::client::StorageControl;
+
+pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    let mut items = client
+        .list_managed_folders()
+        .set_parent(format!("projects/_/buckets/{bucket_id}"))
+        .by_item();
+    println!("Listing managed folders in bucket {bucket_id}");
+    while let Some(folder) = items.next().await.transpose()? {
+        println!("{folder:?}");
+    }
+    println!("DONE");
+    Ok(())
+}
+// [END storage_control_managed_folder_list]

src/storage/examples/src/control/rename_folder.rs

@@ -0,0 +1,32 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_control_rename_folder]
+use google_cloud_lro::Poller;
+use google_cloud_storage::client::StorageControl;
+
+pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    const ID: &str = "example-folder-id";
+    const NEW_ID: &str = "renamed-folder-id";
+    let folder = client
+        .rename_folder()
+        .set_name(format!("projects/_/buckets/{bucket_id}/folders/{ID}"))
+        .set_destination_folder_id(NEW_ID)
+        .poller()
+        .until_done()
+        .await?;
+    println!("folder successfully renamed {folder:?}");
+    Ok(())
+}
+// [END storage_control_rename_folder]