Struct ReadObject

Source

pub struct ReadObject<C = Crc32c> { /* 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};
async fn sample(client: &Storage) -> anyhow::Result<()> {
    const MIB: i64 = 1024 * 1024;
    let mut contents = Vec::new();
    let mut reader = client
        .read_object("projects/_/buckets/my-bucket", "my-object")
        .with_read_offset(4 * MIB)
        .with_read_limit(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 ReadObject<Crc32c>

Source

pub fn compute_md5(self) -> ReadObject<Md5<Crc32c>>

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

§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 §

impl<C> ReadObject<C>
where C: Clone + ChecksumEngine + Send,

Source

pub fn with_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 with_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 with_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 with_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 with_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 with_read_offset<T>(self, v: T) -> Self
where T: Into<i64>,

The offset for the first byte to return in the read, relative to the start of the object.

A negative read_offset value will be interpreted as the number of bytes back from the end of the object to be returned.

§Examples

Read starting at 100 bytes to end of file.

let response = client
    .read_object("projects/_/buckets/my-bucket", "my-object")
    .with_read_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")
    .with_read_offset(-100)
    .send()
    .await?;
println!("response details={response:?}");

Read bytes 1000 to 1099.

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

Source

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

The maximum number of data bytes the server is allowed to return.

A read_limit of zero indicates that there is no limit, and a negative read_limit will cause an error.

§Examples:

Read first 100 bytes.

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

Read bytes 1000 to 1099.

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

Source

pub fn with_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")
    .with_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::RecommendedPolicy;
use std::time::Duration;
use gax::retry_policy::RetryPolicyExt;
let response = client
    .read_object("projects/_/buckets/my-bucket", "my-object")
    .with_retry_policy(RecommendedPolicy
        .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_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 response = client
    .read_object("projects/_/buckets/my-bucket", "my-object")
    .with_download_resume_policy(AlwaysResume.with_attempt_limit(3))
    .send()
    .await?;

Source