Struct UploadObject

pub struct UploadObject<T> { /* private fields */ }

A request builder for uploads without rewind.

Implementations

impl<T> UploadObject<T>

where T: StreamingSource + Send + Sync + 'static, T::Error: Error + Send + Sync + 'static,

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

Upload an object from a streaming source without rewinds.

Example

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

impl<T> UploadObject<T>

where T: StreamingSource + Seek + Send + Sync + 'static, <T as StreamingSource>::Error: Error + Send + Sync + 'static, <T as Seek>::Error: Error + Send + Sync + 'static,

pub async fn send_unbuffered(self) -> Result<Object>

A simple upload from a buffer.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .send_unbuffered()
    .await?;
println!("response details={response:?}");

impl<T> UploadObject<T>

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

where V: Into<i64>,

Set a request precondition on the object generation to match.

With this precondition the request fails if the current object generation matches the provided value. A common value is 0, which prevents uploads from succeeding if the object already exists.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_if_generation_match(0)
    .send()
    .await?;
println!("response details={response:?}");

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

where V: Into<i64>,

Set a request precondition on the object generation to match.

With this precondition the request fails if the current object generation does not match the provided value.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_if_generation_not_match(0)
    .send()
    .await?;
println!("response details={response:?}");

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

where V: Into<i64>,

Set a request precondition on the object meta generation.

With this precondition the request fails if the current object metadata generation does not match the provided value. This may be useful to prevent changes when the metageneration is known.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_if_metageneration_match(1234)
    .send()
    .await?;
println!("response details={response:?}");

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

where V: Into<i64>,

Set a request precondition on the object meta-generation.

With this precondition the request fails if the current object metadata generation matches the provided value. This is rarely useful in uploads, it is more commonly used on downloads to prevent downloads if the value is already cached.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_if_metageneration_not_match(1234)
    .send()
    .await?;
println!("response details={response:?}");

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

where I: IntoIterator<Item = V>, V: Into<ObjectAccessControl>,

Sets the ACL for the new object.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_acl([ObjectAccessControl::new().set_entity("allAuthenticatedUsers").set_role("READER")])
    .send()
    .await?;
println!("response details={response:?}");

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

Sets the cache control for the new object.

This can be used to control caching in public objects.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_cache_control("public; max-age=7200")
    .send()
    .await?;
println!("response details={response:?}");

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

Sets the content disposition for the new object.

Google Cloud Storage can serve content directly to web browsers. This attribute sets the Content-Disposition header, which may change how the browser displays the contents.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_content_disposition("inline")
    .send()
    .await?;
println!("response details={response:?}");

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

Sets the content encoding for the object data.

This can be used to upload compressed data and enable transcoding of the data during downloads.

Example

use flate2::write::GzEncoder;
use std::io::Write;
let mut e = GzEncoder::new(Vec::new(), flate2::Compression::default());
e.write_all(b"hello world");
let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", bytes::Bytes::from_owner(e.finish()?))
    .with_content_encoding("gzip")
    .send()
    .await?;
println!("response details={response:?}");

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

Sets the content language for the new object.

Google Cloud Storage can serve content directly to web browsers. This attribute sets the Content-Language header, which may change how the browser displays the contents.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_content_language("en")
    .send()
    .await?;
println!("response details={response:?}");

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

Sets the content type for the new object.

Google Cloud Storage can serve content directly to web browsers. This attribute sets the Content-Type header, which may change how the browser interprets the contents.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_content_type("text/plain")
    .send()
    .await?;
println!("response details={response:?}");

pub fn with_custom_time<V: Into<Timestamp>>(self, v: V) -> Self

Sets the custom time for the new object.

This field is typically set in order to use the DaysSinceCustomTime condition in Object Lifecycle Management.

Example

let time = wkt::Timestamp::try_from("2025-07-07T18:30:00Z")?;
let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_custom_time(time)
    .send()
    .await?;
println!("response details={response:?}");

pub fn with_event_based_hold<V: Into<bool>>(self, v: V) -> Self

Sets the event based hold flag for the new object.

This field is typically set in order to prevent objects from being deleted or modified.

Example

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

pub fn with_metadata<I, K, V>(self, i: I) -> Self

where I: IntoIterator<Item = (K, V)>, K: Into<String>, V: Into<String>,

Sets the custom metadata for the new object.

This field is typically set to annotate the object with application-specific metadata.

Example

let time = wkt::Timestamp::try_from("2025-07-07T18:30:00Z")?;
let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_metadata([("test-only", "true"), ("environment", "qa")])
    .send()
    .await?;
println!("response details={response:?}");

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

where V: Into<Retention>,

Sets the retention configuration for the new object.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_retention(
        Retention::new()
            .set_mode(retention::Mode::Locked)
            .set_retain_until_time(wkt::Timestamp::try_from("2035-01-01T00:00:00Z")?))
    .send()
    .await?;
println!("response details={response:?}");

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

where V: Into<String>,

Sets the storage class for the new object.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_storage_class("ARCHIVE")
    .send()
    .await?;
println!("response details={response:?}");

pub fn with_temporary_hold<V: Into<bool>>(self, v: V) -> Self

Sets the temporary hold flag for the new object.

This field is typically set in order to prevent objects from being deleted or modified.

Example

let time = wkt::Timestamp::try_from("2025-07-07T18:30:00Z")?;
let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_temporary_hold(true)
    .send()
    .await?;
println!("response details={response:?}");

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

where V: Into<String>,

Sets the resource name of the Customer-managed encryption key for this object.

The service imposes a number of restrictions on the keys used to encrypt Google Cloud Storage objects. Read the documentation in full before trying to use customer-managed encryption keys. In particular, verify the service has the necessary permissions, and the key is in a compatible location.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_kms_key("projects/test-project/locations/us-central1/keyRings/test-ring/cryptoKeys/test-key")
    .send()
    .await?;
println!("response details={response:?}");

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

where V: Into<String>,

Configure this object to use one of the predefined ACLs.

Example

let response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_predefined_acl("private")
    .send()
    .await?;
println!("response details={response:?}");

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
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_key(KeyAes256::new(key)?)
    .send()
    .await?;
println!("response details={response:?}");

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

The retry policy used for this request.

Example

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

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
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_backoff_policy(ExponentialBackoff::default())
    .send()
    .await?;
println!("response details={response:?}");

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 maybe be necessary to use an ad-hoc throttler for some subset of the requests.

Example

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

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 response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_resumable_upload_threshold(0_usize) // Forces a resumable upload.
    .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 response = client
    .upload_object("projects/_/buckets/my-bucket", "my-object", "hello world")
    .with_resumable_upload_buffer_size(32 * 1024 * 1024_usize)
    .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.