Struct ReadObject

Source

pub struct ReadObject<S = Storage>where
    S: Storage + 'static,
{ /* private fields */ }

Expand description

The request builder for Storage::read_object calls.

§Example: accumulate the contents of an object into a vector

use google_cloud_storage::{client::Storage, builder::storage::ReadObject};
async fn sample(client: &Storage) -> anyhow::Result<()> {
    let builder: ReadObject = client.read_object("projects/_/buckets/my-bucket", "my-object");
    let mut reader = builder.send().await?;
    let mut contents = Vec::new();
    while let Some(chunk) = reader.next().await.transpose()? {
        contents.extend_from_slice(&chunk);
    }
    println!("object contents={:?}", contents);
    Ok(())
}

§Example: read part of an object

use google_cloud_storage::{client::Storage, builder::storage::ReadObject};
use google_cloud_storage::model_ext::ReadRange;
async fn sample(client: &Storage) -> anyhow::Result<()> {
    const MIB: u64 = 1024 * 1024;
    let mut contents = Vec::new();
    let mut reader = client
        .read_object("projects/_/buckets/my-bucket", "my-object")
        .set_read_range(ReadRange::segment(4 * MIB, 2 * MIB))
        .send()
        .await?;
    while let Some(chunk) = reader.next().await.transpose()? {
        contents.extend_from_slice(&chunk);
    }
    println!("range contents={:?}", contents);
    Ok(())
}

Implementations§

Source §

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

Source

pub fn compute_md5(self) -> Self

Enables computation of MD5 hashes.

Crc32c hashes are checked by default.

Checksum validation is supported iff:

The full content is requested.
All of the content is returned (status != PartialContent).
The server sent a checksum header.
The http stack did not uncompress the file.
The server did not uncompress data on read.

§Example

let builder =  client
    .read_object("projects/_/buckets/my-bucket", "my-object")
    .compute_md5();
let mut reader = builder
    .send()
    .await?;
let mut contents = Vec::new();
while let Some(chunk) = reader.next().await.transpose()? {
    contents.extend_from_slice(&chunk);
}
println!("object contents={:?}", contents);

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).

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. Setting to 0 makes the operation succeed only if there are no live versions of the object.

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. Setting to 0 makes the operation succeed only if there is a live version of the object.

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.

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.

Source

pub fn set_read_range(self, range: ReadRange) -> Self

The range of bytes to return in the read.

This can be all the bytes starting at a given offset (ReadRange::offset()), all the bytes in an explicit range (Range::segment), or the last N bytes of the object (ReadRange::tail).

§Examples

Read starting at 100 bytes to end of file.

let response = client
    .read_object("projects/_/buckets/my-bucket", "my-object")
    .set_read_range(ReadRange::offset(100))
    .send()
    .await?;
println!("response details={response:?}");

Read last 100 bytes of file:

let response = client
    .read_object("projects/_/buckets/my-bucket", "my-object")
    .set_read_range(ReadRange::tail(100))
    .send()
    .await?;
println!("response details={response:?}");

Read bytes 1000 to 1099.

let response = client
    .read_object("projects/_/buckets/my-bucket", "my-object")
    .set_read_range(ReadRange::segment(1000, 100))
    .send()
    .await?;
println!("response details={response:?}");

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
    .read_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
    .read_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
    .read_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
    .read_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
    .read_object("projects/_/buckets/my-bucket", "my-object")
    .with_read_resume_policy(AlwaysResume.with_attempt_limit(3))
    .send()
    .await?;

Source