docs(storage): more examples for buckets

src/storage/examples/Cargo.toml

@@ -28,9 +28,12 @@ anyhow.workspace               = true
 clap                           = { workspace = true, features = ["derive", "std"] }
 futures.workspace              = true
 google-cloud-gax.workspace     = true
+google-cloud-wkt.workspace     = true
 google-cloud-storage.workspace = true
 rand.workspace                 = true
 tokio                          = { workspace = true, features = ["macros"] }
+tracing.workspace              = true
+tracing-subscriber             = { workspace = true, features = ["fmt", "std"] }
 
 [features]
 run-integration-tests = []

src/storage/examples/src/change_default_storage_class.rs

@@ -0,0 +1,39 @@
+// 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_change_default_storage_class]
+use google_cloud_storage::client::StorageControl;
+use google_cloud_wkt::FieldMask;
+
+pub async fn change_default_storage_class(
+    client: &StorageControl,
+    bucket_id: &str,
+) -> anyhow::Result<()> {
+    let bucket = client
+        .get_bucket()
+        .set_name(format!("projects/_/buckets/{bucket_id}"))
+        .send()
+        .await?;
+    let metageneration = bucket.metageneration;
+    let bucket = client
+        .update_bucket()
+        .set_bucket(bucket.set_storage_class("NEARLINE"))
+        .set_if_metageneration_match(metageneration)
+        .set_update_mask(FieldMask::default().set_paths(["storage_class"]))
+        .send()
+        .await?;
+    println!("successfully updated bucket {bucket:?}");
+    Ok(())
+}
+// [END storage_change_default_storage_class]

src/storage/examples/src/create_bucket.rs

@@ -0,0 +1,33 @@
+// 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_create_bucket]
+use google_cloud_storage::{client::StorageControl, model::Bucket};
+
+pub async fn create_bucket(
+    client: &StorageControl,
+    project_id: &str,
+    bucket_id: &str,
+) -> anyhow::Result<()> {
+    let bucket = client
+        .create_bucket()
+        .set_parent("projects/_")
+        .set_bucket_id(bucket_id)
+        .set_bucket(Bucket::new().set_project(format!("projects/{project_id}")))
+        .send()
+        .await?;
+    println!("successfully created bucket {bucket:?}");
+    Ok(())
+}
+// [END storage_create_bucket]

src/storage/examples/src/create_bucket_class_location.rs

@@ -0,0 +1,38 @@
+// 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_create_bucket_class_and_location]
+use google_cloud_storage::{client::StorageControl, model::Bucket};
+
+pub async fn create_bucket_class_and_location(
+    client: &StorageControl,
+    project_id: &str,
+    bucket_id: &str,
+) -> anyhow::Result<()> {
+    let bucket = client
+        .create_bucket()
+        .set_parent("projects/_")
+        .set_bucket_id(bucket_id)
+        .set_bucket(
+            Bucket::new()
+                .set_project(format!("projects/{project_id}"))
+                .set_storage_class("NEARLINE")
+                .set_location("US-CENTRAL1"),
+        )
+        .send()
+        .await?;
+    println!("successfully created bucket {bucket:?}");
+    Ok(())
+}
+// [END storage_create_bucket_class_and_location]

src/storage/examples/src/create_bucket_dual_region.rs

@@ -0,0 +1,41 @@
+// 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_create_bucket_dual_region]
+use google_cloud_storage::{
+    client::StorageControl, model::Bucket, model::bucket::CustomPlacementConfig,
+};
+
+pub async fn create_bucket_dual_region(
+    client: &StorageControl,
+    project_id: &str,
+    bucket_id: &str,
+) -> anyhow::Result<()> {
+    let bucket = client
+        .create_bucket()
+        .set_parent("projects/_")
+        .set_bucket_id(bucket_id)
+        .set_bucket(
+            Bucket::new()
+                .set_project(format!("projects/{project_id}"))
+                .set_custom_placement_config(
+                    CustomPlacementConfig::new().set_data_locations(["US-EAST4", "US-CENTRAL1"]),
+                ),
+        )
+        .send()
+        .await?;
+    println!("successfully created bucket {bucket:?}");
+    Ok(())
+}
+// [END storage_create_bucket_dual_region]

src/storage/examples/src/create_bucket_hierarchical_namespace.rs

@@ -0,0 +1,45 @@
+// 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_create_bucket_hierarchical_namespace]
+use google_cloud_storage::{
+    client::StorageControl,
+    model::Bucket,
+    model::bucket::iam_config::UniformBucketLevelAccess,
+    model::bucket::{HierarchicalNamespace, IamConfig},
+};
+
+pub async fn create_bucket_hierarchical_namespace(
+    client: &StorageControl,
+    project_id: &str,
+    bucket_id: &str,
+) -> anyhow::Result<()> {
+    let bucket = client
+        .create_bucket()
+        .set_parent("projects/_")
+        .set_bucket_id(bucket_id)
+        .set_bucket(
+            Bucket::new()
+                .set_project(format!("projects/{project_id}"))
+                .set_hierarchical_namespace(HierarchicalNamespace::new().set_enabled(true))
+                .set_iam_config(IamConfig::new().set_uniform_bucket_level_access(
+                    UniformBucketLevelAccess::new().set_enabled(true),
+                )),
+        )
+        .send()
+        .await?;
+    println!("successfully created bucket {bucket:?}");
+    Ok(())
+}
+// [END storage_create_bucket_hierarchical_namespace]

src/storage/examples/src/delete_bucket.rs

@@ -0,0 +1,27 @@
+// 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_delete_bucket]
+use google_cloud_storage::client::StorageControl;
+
+pub async fn delete_bucket(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    client
+        .delete_bucket()
+        .set_name(format!("projects/_/buckets/{bucket_id}"))
+        .send()
+        .await?;
+    println!("successfully deleted bucket {bucket_id}");
+    Ok(())
+}
+// [END storage_delete_bucket]

src/storage/examples/src/get_bucket_metadata.rs

@@ -0,0 +1,37 @@
+// 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_get_bucket_class_and_location]
+// [START storage_get_bucket_labels]
+// [START storage_get_bucket_metadata]
+// [START storage_get_public_access_prevention]
+// [START storage_get_rpo]
+// [START storage_get_uniform_bucket_level_access]
+use google_cloud_storage::client::StorageControl;
+
+pub async fn get_bucket_metadata(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    let bucket = client
+        .get_bucket()
+        .set_name(format!("projects/_/buckets/{bucket_id}"))
+        .send()
+        .await?;
+    println!("successfully obtained bucket metadata {bucket:?}");
+    Ok(())
+}
+// [END storage_get_uniform_bucket_level_access]
+// [END storage_get_rpo]
+// [END storage_get_public_access_prevention]
+// [END storage_get_bucket_metadata]
+// [END storage_get_bucket_labels]
+// [END storage_get_bucket_class_and_location]

src/storage/examples/src/lib.rs

@@ -12,16 +12,69 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+pub mod change_default_storage_class;
+pub mod create_bucket;
+pub mod create_bucket_class_location;
+pub mod create_bucket_dual_region;
+pub mod create_bucket_hierarchical_namespace;
+pub mod delete_bucket;
+pub mod get_bucket_metadata;
 pub mod list_buckets;
 use google_cloud_storage::client::StorageControl;
 use rand::{Rng, distr::Distribution};
 
 pub const BUCKET_ID_LENGTH: usize = 63;
 
-pub async fn run_bucket_examples(_bucket_id: &str) -> anyhow::Result<()> {
+pub async fn run_bucket_examples(buckets: &mut Vec<String>) -> anyhow::Result<()> {
+    let _guard = {
+        use tracing_subscriber::fmt::format::FmtSpan;
+        let subscriber = tracing_subscriber::fmt()
+            .with_level(true)
+            .with_thread_ids(true)
+            .with_span_events(FmtSpan::NEW | FmtSpan::CLOSE)
+            .finish();
+
+        tracing::subscriber::set_default(subscriber)
+    };
+
     let client = StorageControl::builder().build().await?;
     let project_id = std::env::var("GOOGLE_CLOUD_PROJECT").unwrap();
-    list_buckets::list_buckets(&client, &project_id).await
+
+    let id = random_bucket_id();
+    buckets.push(id.clone());
+    tracing::info!("running create_bucket example");
+    create_bucket::create_bucket(&client, &project_id, &id).await?;
+    tracing::info!("running change_default_storage_class example");
+    change_default_storage_class::change_default_storage_class(&client, &id).await?;
+    tracing::info!("running get_bucket_metadata example");
+    get_bucket_metadata::get_bucket_metadata(&client, &id).await?;
+    tracing::info!("running delete_bucket example");
+    delete_bucket::delete_bucket(&client, &id).await?;
+
+    let id = random_bucket_id();
+    buckets.push(id.clone());
+    tracing::info!("running create_bucket_class_and_location example");
+    create_bucket_class_location::create_bucket_class_and_location(&client, &project_id, &id)
+        .await?;
+
+    let id = random_bucket_id();
+    buckets.push(id.clone());
+    tracing::info!("running create_bucket_dual_region example");
+    create_bucket_dual_region::create_bucket_dual_region(&client, &project_id, &id).await?;
+
+    let id = random_bucket_id();
+    buckets.push(id.clone());
+    tracing::info!("running create_bucket_hierarchical_namespace example");
+    create_bucket_hierarchical_namespace::create_bucket_hierarchical_namespace(
+        &client,
+        &project_id,
+        &id,
+    )
+    .await?;
+
+    tracing::info!("running list_buckets example");
+    list_buckets::list_buckets(&client, &project_id).await?;
+    Ok(())
 }
 
 pub async fn cleanup_bucket(client: StorageControl, name: String) -> anyhow::Result<()> {

src/storage/examples/tests/integration.rs

@@ -15,16 +15,18 @@
 #[cfg(all(test, feature = "run-integration-tests"))]
 mod tests {
     use google_cloud_storage::client::StorageControl;
-    use storage_samples::{cleanup_bucket, random_bucket_id, run_bucket_examples};
+    use storage_samples::{cleanup_bucket, run_bucket_examples};
 
     #[tokio::test]
     async fn run_all_examples() -> anyhow::Result<()> {
         let client = StorageControl::builder().build().await?;
 
-        let bucket_id = random_bucket_id();
-        let result = run_bucket_examples(&bucket_id).await;
+        let mut buckets = Vec::new();
+        let result = run_bucket_examples(&mut buckets).await;
         // Ignore cleanup errors.
-        let _ = cleanup_bucket(client, format!("projects/_/buckets/{bucket_id}")).await;
+        for id in buckets.into_iter() {
+            let _ = cleanup_bucket(client.clone(), format!("projects/_/buckets/{id}")).await;
+        }
         result
     }
 }