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

pub fn with_automatic_decompression(self, v: bool) -> Self

Enables automatic decompression.

The Cloud Storage service [automatically decompresses] objects with content_encoding == "gzip" during reads. The client library disables this behavior by default, as it is not possible to perform ranged reads or to resume interrupted downloads if automatic decompression is enabled.

Use this option to enable automatic decompression.

§Example

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

Source