docs(storage): retention policy examples

src/storage/examples/src/get_retention_policy.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_get_retention_policy]
+use google_cloud_storage::client::StorageControl;
+
+pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    let bucket = client
+        .get_bucket()
+        .set_name(format!("projects/_/buckets/{bucket_id}"))
+        .send()
+        .await?;
+    println!(
+        "Retention policy for bucket {bucket_id}: {:?}",
+        bucket.retention_policy
+    );
+    Ok(())
+}
+// [END storage_get_retention_policy]

src/storage/examples/src/lib.rs

@@ -28,17 +28,21 @@ mod enable_default_event_based_hold;
 mod get_bucket_metadata;
 mod get_default_event_based_hold;
 mod get_public_access_prevention;
+mod get_retention_policy;
 mod list_buckets;
+mod lock_retention_policy;
 mod objects;
 mod print_bucket_acl;
 mod print_bucket_acl_for_user;
 mod print_bucket_website_configuration;
 mod quickstart;
 mod remove_bucket_owner;
+mod remove_retention_policy;
 mod set_lifecycle_abort_multipart_upload;
 mod set_public_access_prevention_enforced;
 mod set_public_access_prevention_inherited;
 mod set_public_access_prevention_unspecified;
+mod set_retention_policy;
 mod view_lifecycle_management_configuration;
 
 use google_cloud_gax::throttle_result::ThrottleResult;
@@ -96,6 +100,8 @@ pub async fn run_bucket_examples(buckets: &mut Vec<String>) -> anyhow::Result<()
     let project_id = std::env::var("GOOGLE_CLOUD_PROJECT").unwrap();
     let service_account = std::env::var("GOOGLE_CLOUD_RUST_TEST_SERVICE_ACCOUNT")?;
 
+    // We create multiple buckets because there is a rate limit on bucket
+    // changes.
     let id = random_bucket_id();
     buckets.push(id.clone());
     tracing::info!("running create_bucket example");
@@ -120,7 +126,6 @@ pub async fn run_bucket_examples(buckets: &mut Vec<String>) -> anyhow::Result<()
     enable_default_event_based_hold::sample(&client, &id).await?;
     tracing::info!("running disable_default_event_based_hold example");
     disable_default_event_based_hold::sample(&client, &id).await?;
-
     tracing::info!("running set_public_access_prevention_unspecified example");
     set_public_access_prevention_unspecified::sample(&client, &id).await?;
     tracing::info!("running set_public_access_prevention_inherited example");
@@ -131,7 +136,6 @@ pub async fn run_bucket_examples(buckets: &mut Vec<String>) -> anyhow::Result<()
     set_public_access_prevention_enforced::sample(&client, &id).await?;
     tracing::info!("running get_public_access_prevention example");
     get_public_access_prevention::sample(&client, &id).await?;
-
     tracing::info!("running view_lifecycle_management_configuration example");
     view_lifecycle_management_configuration::sample(&client, &id).await?;
     tracing::info!("running enable_bucket_lifecycle_management example");
@@ -144,6 +148,14 @@ pub async fn run_bucket_examples(buckets: &mut Vec<String>) -> anyhow::Result<()
     print_bucket_website_configuration::sample(&client, &id).await?;
     tracing::info!("running define_bucket_website_configuration example");
     define_bucket_website_configuration::sample(&client, &id, "index.html", "404.html").await?;
+    tracing::info!("running remove_retention_policy example");
+    remove_retention_policy::sample(&client, &id).await?;
+    tracing::info!("running set_retention_policy example");
+    set_retention_policy::sample(&client, &id, 60).await?;
+    tracing::info!("running get_retention_policy example");
+    get_retention_policy::sample(&client, &id).await?;
+    tracing::info!("running lock_retention_policy example");
+    lock_retention_policy::sample(&client, &id).await?;
     tracing::info!("running print_bucket_acl example");
     print_bucket_acl::sample(&client, &id).await?;
     tracing::info!("running add_bucket_owner example");

src/storage/examples/src/lock_retention_policy.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_lock_retention_policy]
+use google_cloud_storage::client::StorageControl;
+
+pub async fn sample(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
+        .lock_bucket_retention_policy()
+        .set_if_metageneration_match(metageneration)
+        .set_bucket(bucket.name)
+        .send()
+        .await?;
+    println!(
+        "Retention policy for bucket {bucket_id} locked: {:?}",
+        bucket.retention_policy
+    );
+    Ok(())
+}
+// [END storage_lock_retention_policy]

src/storage/examples/src/remove_retention_policy.rs

@@ -0,0 +1,40 @@
+// 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_remove_retention_policy]
+use google_cloud_storage::client::StorageControl;
+use google_cloud_storage::model::bucket::RetentionPolicy;
+use google_cloud_wkt::FieldMask;
+
+pub async fn sample(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_retention_policy(RetentionPolicy::new()))
+        .set_if_metageneration_match(metageneration)
+        .set_update_mask(FieldMask::default().set_paths(["retention_policy"]))
+        .send()
+        .await?;
+    println!(
+        "Retention policy for bucket {bucket_id} removed: {:?}",
+        bucket.retention_policy
+    );
+    Ok(())
+}
+// [END storage_remove_retention_policy]

src/storage/examples/src/set_retention_policy.rs

@@ -0,0 +1,46 @@
+// 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_set_retention_policy]
+use google_cloud_storage::client::StorageControl;
+use google_cloud_storage::model::bucket::RetentionPolicy;
+use google_cloud_wkt::{Duration, FieldMask};
+
+pub async fn sample(
+    client: &StorageControl,
+    bucket_id: &str,
+    retention_period: i64,
+) -> anyhow::Result<()> {
+    let bucket = client
+        .get_bucket()
+        .set_name(format!("projects/_/buckets/{bucket_id}"))
+        .send()
+        .await?;
+    let metageneration = bucket.metageneration;
+    let retention_policy =
+        RetentionPolicy::new().set_retention_duration(Duration::new(retention_period, 0)?);
+    let bucket = client
+        .update_bucket()
+        .set_bucket(bucket.set_retention_policy(retention_policy))
+        .set_if_metageneration_match(metageneration)
+        .set_update_mask(FieldMask::default().set_paths(["retention_policy"]))
+        .send()
+        .await?;
+    println!(
+        "Retention policy for bucket {bucket_id} set to: {:?}",
+        bucket.retention_policy
+    );
+    Ok(())
+}
+// [END storage_set_retention_policy]