Struct OpenObject

Source

pub struct OpenObject<S = Storage> { /* private fields */ }

Expand description

A request builder for Storage::open_object.

§Example

use google_cloud_storage::client::Storage;
async fn sample(client: &Storage) -> anyhow::Result<()> {
    let builder: OpenObject = client
        .open_object("projects/_/buckets/my-bucket", "my-object");
    let descriptor = builder
        .set_generation(123)
        .send()
        .await?;
    println!("object metadata={:?}", descriptor.object());
    // Use `descriptor` to read data from `my-object`.
    Ok(())
}

Implementations§

Source §

impl<S> OpenObject<S>
where S: Storage + 'static,

Source

pub async fn send(self) -> Result<ObjectDescriptor>

Sends the request, returning a new object descriptor.

Example:

let open = client
    .open_object("projects/_/buckets/my-bucket", "my-object")
    .send()
    .await?;
println!("object metadata={:?}", open.object());

Source

pub async fn send_and_read( self, range: ReadRange, ) -> Result<(ObjectDescriptor, ReadObjectResponse)>

Sends the request, returning a new object descriptor and reader.

Example:

use google_cloud_storage::model_ext::ReadRange;
let (descriptor, mut reader) = client
    .open_object("projects/_/buckets/my-bucket", "my-object.parquet")
    .send_and_read(ReadRange::tail(32))
    .await?;
println!("object metadata={:?}", descriptor.object());
let data = reader.next().await.transpose()?;

This method allows applications to open an object and issue a read request in the same RPC, which is typically faster than opening an object and then issuing a read_range() call. This may be useful when opening objects that have metadata information in a footer or header.

Source §

impl<S> OpenObject<S>

Source

pub fn set_generation<T: Into<i64>>(self, v: T) -> Self

If present, selects a specific revision of this object (as opposed to the latest version, the default).

§Example

use google_cloud_storage::read_resume_policy::{AlwaysResume, ReadResumePolicyExt};
let response = client
    .open_object("projects/_/buckets/my-bucket", "my-object")
    .set_generation(123456)
    .send()
    .await?;

Source

pub fn set_if_generation_match<T>(self, v: T) -> Self
where T: Into<i64>,

Makes the operation conditional on whether the object’s current generation matches the given value.

§Example

use google_cloud_storage::read_resume_policy::{AlwaysResume, ReadResumePolicyExt};
let response = client
    .open_object("projects/_/buckets/my-bucket", "my-object")
    .set_if_generation_match(123456)
    .send()
    .await?;

Source

pub fn set_if_generation_not_match<T>(self, v: T) -> Self
where T: Into<i64>,

Makes the operation conditional on whether the object’s live generation does not match the given value. If no live object exists, the precondition fails.

§Example

use google_cloud_storage::read_resume_policy::{AlwaysResume, ReadResumePolicyExt};
let response = client
    .open_object("projects/_/buckets/my-bucket", "my-object")
    .set_if_generation_not_match(123456)
    .send()
    .await?;

Source

pub fn set_if_metageneration_match<T>(self, v: T) -> Self
where T: Into<i64>,

Makes the operation conditional on whether the object’s current metageneration matches the given value.

§Example

use google_cloud_storage::read_resume_policy::{AlwaysResume, ReadResumePolicyExt};
let response = client
    .open_object("projects/_/buckets/my-bucket", "my-object")
    .set_if_metageneration_match(123456)
    .send()
    .await?;

Source

pub fn set_if_metageneration_not_match<T>(self, v: T) -> Self
where T: Into<i64>,

Makes the operation conditional on whether the object’s current metageneration does not match the given value.

§Example

use google_cloud_storage::read_resume_policy::{AlwaysResume, ReadResumePolicyExt};
let response = client
    .open_object("projects/_/buckets/my-bucket", "my-object")
    .set_if_metageneration_not_match(123456)
    .send()
    .await?;

Source

pub fn set_key(self, v: KeyAes256) -> Self

The encryption key used with the Customer-Supplied Encryption Keys feature. In raw bytes format (not base64-encoded).

Example:

let key: &[u8] = &[97; 32];
let response = client
    .open_object("projects/_/buckets/my-bucket", "my-object")
    .set_key(KeyAes256::new(key)?)
    .send()
    .await?;
println!("response details={response:?}");

Source

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

The retry policy used for this request.

§Example

use google_cloud_storage::retry_policy::RetryableErrors;
use std::time::Duration;
use gax::retry_policy::RetryPolicyExt;
let response = client
    .open_object("projects/_/buckets/my-bucket", "my-object")
    .with_retry_policy(
        RetryableErrors
            .with_attempt_limit(5)
            .with_time_limit(Duration::from_secs(10)),
    )
    .send()
    .await?;
println!("response details={response:?}");

Source

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

The backoff policy used for this request.

§Example

use std::time::Duration;
use gax::exponential_backoff::ExponentialBackoff;
let response = client
    .open_object("projects/_/buckets/my-bucket", "my-object")
    .with_backoff_policy(ExponentialBackoff::default())
    .send()
    .await?;
println!("response details={response:?}");

Source

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

The retry throttler used for this request.

Most of the time you want to use the same throttler for all the requests in a client, and even the same throttler for many clients. Rarely it may be necessary to use an custom throttler for some subset of the requests.

§Example

let response = client
    .open_object("projects/_/buckets/my-bucket", "my-object")
    .with_retry_throttler(adhoc_throttler())
    .send()
    .await?;
println!("response details={response:?}");
fn adhoc_throttler() -> gax::retry_throttler::SharedRetryThrottler {
}

Source

pub fn with_read_resume_policy<V>(self, v: V) -> Self
where V: ReadResumePolicy + 'static,

Configure the resume policy for read requests.

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

§Example

use google_cloud_storage::read_resume_policy::{AlwaysResume, ReadResumePolicyExt};
let response = client
    .open_object("projects/_/buckets/my-bucket", "my-object")
    .with_read_resume_policy(AlwaysResume.with_attempt_limit(3))
    .send()
    .await?;

Source

pub fn with_attempt_timeout(self, v: Duration) -> Self

Configure per-attempt timeout.

§Example

use std::time::Duration;
let response = client
    .open_object("projects/_/buckets/my-bucket", "my-object")
    .with_attempt_timeout(Duration::from_secs(120))
    .send()
    .await?;

The Cloud Storage client library times out open_object() attempts by default (with a 60s timeout). Applications may want to set a different value depending on how they are deployed.

Note that the per-attempt timeout is subject to the overall retry loop time limits (if any). The effective timeout for each attempt is the smallest of (a) the per-attempt timeout, and (b) the remaining time in the retry loop.