Rust: Per request configuration examples (awsdocs#5985)

Rust: Add per-operation examples for setting region, retries, and credentials

rustv1/examples/sdk-config/src/bin/per-request-credentials.rs

@@ -0,0 +1,51 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+#![allow(clippy::result_large_err)]
+
+use std::time::{Duration, SystemTime};
+
+use aws_config::BehaviorVersion;
+use aws_credential_types::{credential_fn::provide_credentials_fn, Credentials};
+use aws_sdk_s3::{Client, Config, Error};
+
+/// Displays how many Amazon S3 buckets you have.
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    tracing_subscriber::fmt::init();
+
+    let shared_config = aws_config::defaults(BehaviorVersion::latest()).load().await;
+    let client = Client::new(&shared_config);
+
+    // snippet-start:[rust.per_operation_credentials]
+    let resp = client
+        .list_buckets()
+        .customize()
+        .config_override(
+            Config::builder().credentials_provider(provide_credentials_fn(move || {
+                // This snippet is for example purposes only. Production applications are responsible
+                // for developing secure methods to provide Credentials at this point.
+                let access_key_id = "access_key_id".to_string();
+                let secret_access_key = "secret_access_key".to_string();
+                let session_token = "session_token".to_string();
+                let expires_after = SystemTime::now() + Duration::from_secs(60);
+                async move {
+                    Ok(Credentials::new(
+                        access_key_id,
+                        secret_access_key,
+                        Some(session_token),
+                        Some(expires_after),
+                        "example_provider",
+                    ))
+                }
+            })),
+        )
+        .send()
+        .await?;
+    // snippet-end:[rust.per_operation_credentials]
+    let buckets = resp.buckets();
+
+    println!("Found {} buckets in all regions.", buckets.len());
+
+    Ok(())
+}

rustv1/examples/sdk-config/src/bin/per-request-retries.rs

@@ -0,0 +1,61 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+#![allow(clippy::result_large_err)]
+
+use aws_config::BehaviorVersion;
+use aws_sdk_s3::config::retry::RetryConfig;
+use aws_sdk_s3::{meta::PKG_VERSION, Client, Config, Error};
+use clap::Parser;
+
+#[derive(Debug, Parser)]
+struct Opt {
+    /// The number of (re)tries.
+    #[structopt(short, long, default_value = "2")]
+    tries: u32,
+
+    /// Whether to display additional information.
+    #[structopt(short, long)]
+    verbose: bool,
+}
+
+/// Displays how many Amazon S3 buckets you have.
+/// # Arguments
+///
+/// * `[-t TRIES]` - The number of times to (re)try the request.
+/// * `[-v]` - Whether to display additional information.
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    tracing_subscriber::fmt::init();
+
+    let Opt { tries, verbose } = Opt::parse();
+
+    if verbose {
+        println!("S3 client version: {}", PKG_VERSION);
+        println!("Max retries:       {}", &tries);
+        println!();
+    }
+
+    assert_ne!(tries, 0, "You cannot set zero retries.");
+
+    let shared_config = aws_config::defaults(BehaviorVersion::latest()).load().await;
+
+    // Construct an S3 client with customized retry configuration.
+    let client = Client::new(&shared_config);
+
+    // snippet-start:[rust.per_operation_retry]
+    let resp = client
+        .list_buckets()
+        .customize()
+        .config_override(
+            Config::builder().retry_config(RetryConfig::standard().with_max_attempts(tries)),
+        )
+        .send()
+        .await?;
+    // snippet-end:[rust.per_operation_retry]
+    let buckets = resp.buckets();
+
+    println!("Found {} buckets in all regions.", buckets.len());
+
+    Ok(())
+}

rustv1/examples/sdk-config/src/bin/pre-request-region.rs

@@ -0,0 +1,70 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+#![allow(clippy::result_large_err)]
+
+use aws_config::meta::region::RegionProviderChain;
+use aws_config::{BehaviorVersion, Region};
+use aws_sdk_s3::{meta::PKG_VERSION, Client, Config, Error};
+use clap::Parser;
+
+#[derive(Debug, Parser)]
+struct Opt {
+    /// The AWS Region.
+    #[structopt(short, long)]
+    region: Option<String>,
+
+    /// Whether to display additional information.
+    #[structopt(short, long)]
+    verbose: bool,
+}
+
+/// Displays how many Amazon S3 buckets you have.
+/// # Arguments
+///
+/// * `[-r REGION]` - The Region in which the client is created.
+///   If not supplied, uses the value of the **AWS_REGION** environment variable.
+///   If the environment variable is not set, defaults to **us-west-2**.
+/// * `[-v]` - Whether to display additional information.
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    tracing_subscriber::fmt::init();
+
+    let Opt { region, verbose } = Opt::parse();
+
+    if verbose {
+        println!("S3 client version: {}", PKG_VERSION);
+        println!(
+            "Region:            {}",
+            region.as_deref().unwrap_or("not provided"),
+        );
+        println!();
+    }
+
+    let shared_config = aws_config::defaults(BehaviorVersion::latest()).load().await;
+
+    // Construct an S3 client with customized retry configuration.
+    let client = Client::new(&shared_config);
+
+    // snippet-start:[rust.per_operation_region]
+    let resp = client
+        .list_buckets()
+        .customize()
+        .config_override(
+            Config::builder().region(
+                RegionProviderChain::first_try(region.map(Region::new))
+                    .or_default_provider()
+                    .or_else(Region::new("us-west-2"))
+                    .region()
+                    .await,
+            ),
+        )
+        .send()
+        .await?;
+    // snippet-end:[rust.per_operation_region]
+    let buckets = resp.buckets();
+
+    println!("Found {} buckets in all regions.", buckets.len());
+
+    Ok(())
+}