Struct ClientBuilder

pub struct ClientBuilder { /* private fields */ }

A builder for Storage.

let builder = Storage::builder();
let client = builder
    .with_endpoint("https://storage.googleapis.com")
    .build()
    .await?;

Implementations

impl ClientBuilder

pub async fn build(self) -> Result<Storage>

Creates a new client.

Example

let client = Storage::builder().build().await?;

pub fn with_endpoint<V: Into<String>>(self, v: V) -> Self

Sets the endpoint.

Example

let client = Storage::builder()
    .with_endpoint("https://private.googleapis.com")
    .build()
    .await?;

pub fn with_credentials<V: Into<Credentials>>(self, v: V) -> Self

Configures the authentication credentials.

Google Cloud Storage requires authentication for most buckets. Use this method to change the credentials used by the client. More information about valid credentials types can be found in the google-cloud-auth crate documentation.

Example

use auth::credentials::mds;
let client = Storage::builder()
    .with_credentials(
        mds::Builder::default()
            .with_scopes(["https://www.googleapis.com/auth/cloud-platform.read-only"])
            .build()?)
    .build()
    .await?;

pub fn with_retry_policy<V: Into<RetryPolicyArg>>(self, v: V) -> Self

Configure the retry policy.

The client libraries can automatically retry operations that fail. The retry policy controls what errors are considered retryable, sets limits on the number of attempts or the time trying to make attempts.

Example

use gax::retry_policy::{AlwaysRetry, RetryPolicyExt};
let client = Storage::builder()
    .with_retry_policy(AlwaysRetry.with_attempt_limit(3))
    .build()
    .await?;

pub fn with_backoff_policy<V: Into<BackoffPolicyArg>>(self, v: V) -> Self

Configure the retry backoff policy.

The client libraries can automatically retry operations that fail. The backoff policy controls how long to wait in between retry attempts.

Example

use gax::exponential_backoff::ExponentialBackoff;
use std::time::Duration;
let policy = ExponentialBackoff::default();
let client = Storage::builder()
    .with_backoff_policy(policy)
    .build()
    .await?;

pub fn with_retry_throttler<V: Into<RetryThrottlerArg>>(self, v: V) -> Self

Configure the retry throttler.

Advanced applications may want to configure a retry throttler to [Address Cascading Failures] and when Handling Overload conditions. The client libraries throttle their retry loop, using a policy to control the throttling algorithm. Use this method to fine tune or customize the default retry throtler.

Example

use gax::retry_throttler::AdaptiveThrottler;
let client = Storage::builder()
    .with_retry_throttler(AdaptiveThrottler::default())
    .build()
    .await?;

pub fn with_resumable_upload_threshold<V: Into<usize>>(self, v: V) -> Self

Sets the payload size threshold to switch from single-shot to resumable uploads.

Example

let client = Storage::builder()
    .with_resumable_upload_threshold(0_usize) // Forces a resumable upload.
    .build()
    .await?;
let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .send()
    .await?;
println!("response details={response:?}");

The client library can perform uploads using single-shot or resumable uploads. For small objects, single-shot uploads offer better performance, as they require a single HTTP transfer. For larger objects, the additional request latency is not significant, and resumable uploads offer better recovery on errors.

The library automatically selects resumable uploads when the payload is equal to or larger than this option. For smaller uploads the client library uses single-shot uploads.

The exact threshold depends on where the application is deployed and destination bucket location with respect to where the application is running. The library defaults should work well in most cases, but some applications may benefit from fine-tuning.

pub fn with_resumable_upload_buffer_size<V: Into<usize>>(self, v: V) -> Self

Changes the buffer size for some resumable uploads.

Example

let client = Storage::builder()
    .with_resumable_upload_buffer_size(32 * 1024 * 1024_usize)
    .build()
    .await?;
let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .send()
    .await?;
println!("response details={response:?}");

When performing resumable uploads from sources without Seek the client library needs to buffer data in memory until it is persisted by the service. Otherwise the data would be lost if the upload fails. Applications may want to tune this buffer size:

• Use smaller buffer sizes to support more concurrent uploads in the same application.
• Use larger buffer sizes for better throughput. Sending many small buffers stalls the upload until the client receives a successful response from the service.

Keep in mind that there are diminishing returns on using larger buffers.

pub fn with_download_resume_policy<V>(self, v: V) -> Self

where V: DownloadResumePolicy + 'static,

Configure the resume policy for downloads.

The Cloud Storage client library can automatically resume a download that is interrupted by a transient error. Applications may want to limit the number of download attempts, or may wish to expand the type of errors treated as retryable.

Example

use google_cloud_storage::download_resume_policy::{AlwaysResume, DownloadResumePolicyExt};
let client = Storage::builder()
    .with_download_resume_policy(AlwaysResume.with_attempt_limit(3))
    .build()
    .await?;