Struct cloud_storage::Object

pub struct Object {

    pub kind: String,
    pub id: String,
    pub self_link: String,
    pub name: String,
    pub bucket: String,
    pub generation: i64,
    pub metageneration: i64,
    pub content_type: Option<String>,
    pub time_created: DateTime<Utc>,
    pub updated: DateTime<Utc>,
    pub time_deleted: Option<DateTime<Utc>>,
    pub temporary_hold: Option<bool>,
    pub event_based_hold: Option<bool>,
    pub retention_expiration_time: Option<DateTime<Utc>>,
    pub storage_class: String,
    pub time_storage_class_updated: DateTime<Utc>,
    pub size: u64,
    pub md5_hash: Option<String>,
    pub media_link: String,
    pub content_encoding: Option<String>,
    pub content_disposition: Option<String>,
    pub content_language: Option<String>,
    pub cache_control: Option<String>,
    pub metadata: Option<HashMap<String, String>>,
    pub acl: Option<Vec<ObjectAccessControl>>,
    pub owner: Option<Owner>,
    pub crc32c: String,
    pub component_count: Option<i32>,
    pub etag: String,
    pub customer_encryption: Option<CustomerEncrypton>,
    pub kms_key_name: Option<String>,
}

A resource representing a file in Google Cloud Storage.

Fields

kind: String

The kind of item this is. For objects, this is always storage#object.

id: String

The ID of the object, including the bucket name, object name, and generation number.

self_link: String

The link to this object.

name: String

The name of the object. Required if not specified by URL parameter.

bucket: String

The name of the bucket containing this object.

generation: i64

The content generation of this object. Used for object versioning.

metageneration: i64

The version of the metadata for this object at this generation. Used for preconditions and for detecting changes in metadata. A metageneration number is only meaningful in the context of a particular generation of a particular object.

content_type: Option<String>

Content-Type of the object data. If an object is stored without a Content-Type, it is served as application/octet-stream.

time_created: DateTime<Utc>

The creation time of the object in RFC 3339 format.

updated: DateTime<Utc>

The modification time of the object metadata in RFC 3339 format.

time_deleted: Option<DateTime<Utc>>

The deletion time of the object in RFC 3339 format. Returned if and only if this version of the object is no longer a live version, but remains in the bucket as a noncurrent version.

temporary_hold: Option<bool>

Whether or not the object is subject to a temporary hold.

event_based_hold: Option<bool>

Whether or not the object is subject to an event-based hold.

retention_expiration_time: Option<DateTime<Utc>>

The earliest time that the object can be deleted, based on a bucket’s retention policy, in RFC 3339 format.

storage_class: String

Storage class of the object.

time_storage_class_updated: DateTime<Utc>

The time at which the object’s storage class was last changed. When the object is initially created, it will be set to timeCreated.

size: u64

Content-Length of the data in bytes.

md5_hash: Option<String>

MD5 hash of the data; encoded using base64. For more information about using the MD5 hash, see Hashes and ETags: Best Practices.

media_link: String

Media download link.

content_encoding: Option<String>

Content-Encoding of the object data.

content_disposition: Option<String>

Content-Disposition of the object data.

content_language: Option<String>

Content-Language of the object data.

cache_control: Option<String>

Cache-Control directive for the object data. If omitted, and the object is accessible to all anonymous users, the default will be public, max-age=3600.

metadata: Option<HashMap<String, String>>

User-provided metadata, in key/value pairs.

acl: Option<Vec<ObjectAccessControl>>

Access controls on the object, containing one or more objectAccessControls Resources. If iamConfiguration.uniformBucketLevelAccess.enabled is set to true, this field is omitted in responses, and requests that specify this field fail.

owner: Option<Owner>

The owner of the object. This will always be the uploader of the object. If iamConfiguration.uniformBucketLevelAccess.enabled is set to true, this field does not apply, and is omitted in responses.

crc32c: String

CRC32c checksum, as described in RFC 4960, Appendix B; encoded using base64 in big-endian byte order. For more information about using the CRC32c checksum, see Hashes and ETags: Best Practices.

component_count: Option<i32>

Number of underlying components that make up a composite object. Components are accumulated by compose operations, counting 1 for each non-composite source object and componentCount for each composite source object. Note: componentCount is included in the metadata for composite objects only.

etag: String

HTTP 1.1 Entity tag for the object.

customer_encryption: Option<CustomerEncrypton>

Metadata of customer-supplied encryption key, if the object is encrypted by such a key.

kms_key_name: Option<String>

Cloud KMS Key used to encrypt this object, if the object is encrypted by such a key.

Implementations

impl Object

pub async fn create(
    bucket: &str,
    file: Vec<u8>,
    filename: &str,
    mime_type: &str
) -> Result<Self>

Create a new object. Upload a file as that is loaded in memory to google cloud storage, where it will be interpreted according to the mime type you specified.

Example

use cloud_storage::Object;

let file: Vec<u8> = read_cute_cat("cat.png");
Object::create("cat-photos", file, "recently read cat.png", "image/png").await?;

pub fn create_sync(
    bucket: &str,
    file: Vec<u8>,
    filename: &str,
    mime_type: &str
) -> Result<Self>

The synchronous equivalent of Object::create.

Features

This function requires that the feature flag sync is enabled in Cargo.toml.

pub async fn create_streamed<S>(
    bucket: &str,
    stream: S,
    length: impl Into<Option<u64>>,
    filename: &str,
    mime_type: &str
) -> Result<Self> where
    S: TryStream + Send + Sync + 'static,
    S::Error: Into<Box<dyn Error + Send + Sync>>,
    Bytes: From<S::Ok>, 

Create a new object. This works in the same way as Object::create, except it does not need to load the entire file in ram.

Example

use cloud_storage::Object;

let file = reqwest::Client::new()
    .get("https://my_domain.rs/nice_cat_photo.png")
    .send()
    .await?
    .bytes_stream();
Object::create_streamed("cat-photos", file, 10, "recently read cat.png", "image/png").await?;

pub fn create_streamed_sync<R: Read + Send + 'static>(
    bucket: &str,
    file: R,
    length: impl Into<Option<u64>>,
    filename: &str,
    mime_type: &str
) -> Result<Self>

The synchronous equivalent of Object::create_streamed.

Features

This function requires that the feature flag sync is enabled in Cargo.toml.

pub async fn list(
    bucket: &str,
    list_request: ListRequest
) -> Result<impl Stream<Item = Result<ObjectList>> + '_>

Obtain a list of objects within this Bucket. This function will repeatedly query Google and merge the responses into one. Google responds with 1000 Objects at a time, so if you want to make sure only one http call is performed, make sure to set list_request.max_results to 1000.

Example

use cloud_storage::{Object, ListRequest};

let all_objects = Object::list("my_bucket", ListRequest::default()).await?;

pub fn list_sync(
    bucket: &str,
    list_request: ListRequest
) -> Result<Vec<ObjectList>>

The synchronous equivalent of Object::list.

Features

This function requires that the feature flag sync is enabled in Cargo.toml.

pub async fn read(bucket: &str, file_name: &str) -> Result<Self>

Obtains a single object with the specified name in the specified bucket.

Example

use cloud_storage::Object;

let object = Object::read("my_bucket", "path/to/my/file.png").await?;

pub fn read_sync(bucket: &str, file_name: &str) -> Result<Self>

The synchronous equivalent of Object::read.

Features

This function requires that the feature flag sync is enabled in Cargo.toml.

pub async fn download(bucket: &str, file_name: &str) -> Result<Vec<u8>>

Download the content of the object with the specified name in the specified bucket.

Example

use cloud_storage::Object;

let bytes = Object::download("my_bucket", "path/to/my/file.png").await?;

pub fn download_sync(bucket: &str, file_name: &str) -> Result<Vec<u8>>

The synchronous equivalent of Object::download.

Features

This function requires that the feature flag sync is enabled in Cargo.toml.

pub async fn download_streamed(
    bucket: &str,
    file_name: &str
) -> Result<impl Stream<Item = Result<u8>> + Unpin>

Download the content of the object with the specified name in the specified bucket, without allocating the whole file into a vector.

Example

use cloud_storage::Object;
use futures_util::stream::StreamExt;
use std::fs::File;
use std::io::{BufWriter, Write};

let mut stream = Object::download_streamed("my_bucket", "path/to/my/file.png").await?;
let mut file = BufWriter::new(File::create("file.png").unwrap());
while let Some(byte) = stream.next().await {
    file.write_all(&[byte.unwrap()]).unwrap();
}

pub async fn update(&self) -> Result<Self>

Obtains a single object with the specified name in the specified bucket.

Example

use cloud_storage::Object;

let mut object = Object::read("my_bucket", "path/to/my/file.png").await?;
object.content_type = Some("application/xml".to_string());
object.update().await?;

pub fn update_sync(&self) -> Result<Self>

The synchronous equivalent of Object::download.

Features

This function requires that the feature flag sync is enabled in Cargo.toml.

pub async fn delete(bucket: &str, file_name: &str) -> Result<()>

Deletes a single object with the specified name in the specified bucket.

Example

use cloud_storage::Object;

Object::delete("my_bucket", "path/to/my/file.png").await?;

pub fn delete_sync(bucket: &str, file_name: &str) -> Result<()>

The synchronous equivalent of Object::delete.

Features

This function requires that the feature flag sync is enabled in Cargo.toml.

pub async fn compose(
    bucket: &str,
    req: &ComposeRequest,
    destination_object: &str
) -> Result<Self>

Obtains a single object with the specified name in the specified bucket.

Example

use cloud_storage::object::{Object, ComposeRequest, SourceObject};

let obj1 = Object::read("my_bucket", "file1").await?;
let obj2 = Object::read("my_bucket", "file2").await?;
let compose_request = ComposeRequest {
    kind: "storage#composeRequest".to_string(),
    source_objects: vec![
        SourceObject {
            name: obj1.name.clone(),
            generation: None,
            object_preconditions: None,
        },
        SourceObject {
            name: obj2.name.clone(),
            generation: None,
            object_preconditions: None,
        },
    ],
    destination: None,
};
let obj3 = Object::compose("my_bucket", &compose_request, "test-concatted-file").await?;
// obj3 is now a file with the content of obj1 and obj2 concatted together.

pub fn compose_sync(
    bucket: &str,
    req: &ComposeRequest,
    destination_object: &str
) -> Result<Self>

The synchronous equivalent of Object::compose.

Features

This function requires that the feature flag sync is enabled in Cargo.toml.

pub async fn copy(&self, destination_bucket: &str, path: &str) -> Result<Self>

Copy this object to the target bucket and path

Example

use cloud_storage::object::{Object, ComposeRequest};

let obj1 = Object::read("my_bucket", "file1").await?;
let obj2 = obj1.copy("my_other_bucket", "file2").await?;
// obj2 is now a copy of obj1.

pub fn copy_sync(&self, destination_bucket: &str, path: &str) -> Result<Self>

The synchronous equivalent of Object::copy.

Features

This function requires that the feature flag sync is enabled in Cargo.toml.

pub async fn rewrite(
    &self,
    destination_bucket: &str,
    path: &str
) -> Result<Self>

Moves a file from the current location to the target bucket and path.

Limitations

This function does not yet support rewriting objects to another

• Geographical Location,
• Encryption,
• Storage class. These limitations mean that for now, the rewrite and the copy methods do the same thing.

Example

use cloud_storage::object::Object;

let obj1 = Object::read("my_bucket", "file1").await?;
let obj2 = obj1.rewrite("my_other_bucket", "file2").await?;
// obj2 is now a copy of obj1.

pub fn rewrite_sync(&self, destination_bucket: &str, path: &str) -> Result<Self>

The synchronous equivalent of Object::rewrite.

Features

This function requires that the feature flag sync is enabled in Cargo.toml.

pub fn download_url(&self, duration: u32) -> Result<String>

Creates a Signed Url which is valid for duration seconds, and lets the posessor download the file contents without any authentication.

Example

use cloud_storage::{Client, object::{Object, ComposeRequest}};

let client = Client::default();
let obj1 = client.object().read("my_bucket", "file1").await?;
let url = obj1.download_url(50)?;
// url is now a url to which an unauthenticated user can make a request to download a file
// for 50 seconds.

pub fn download_url_with(
    &self,
    duration: u32,
    opts: DownloadOptions
) -> Result<String>

Creates a Signed Url which is valid for duration seconds, and lets the posessor download the file contents without any authentication.

Example

use cloud_storage::{Client, object::{Object, ComposeRequest}};

let client = Client::default();
let obj1 = client.object().read("my_bucket", "file1").await?;
let url = obj1.download_url(50)?;
// url is now a url to which an unauthenticated user can make a request to download a file
// for 50 seconds.

pub fn upload_url(&self, duration: u32) -> Result<String>

Creates a Signed Url which is valid for duration seconds, and lets the posessor upload data to a blob without any authentication.

Example

use cloud_storage::{Client, object::{Object, ComposeRequest}};

let client = Client::default();
let obj1 = client.object().read("my_bucket", "file1").await?;
let url = obj1.upload_url(50)?;
// url is now a url to which an unauthenticated user can make a PUT request to upload a file
// for 50 seconds.

pub fn upload_url_with(
    &self,
    duration: u32,
    custom_metadata: HashMap<String, String>
) -> Result<(String, HashMap<String, String>)>

Creates a Signed Url which is valid for duration seconds, and lets the posessor upload data and custom metadata to a blob without any authentication.

Example

use cloud_storage::{Client, object::{Object, ComposeRequest}};
use std::collections::HashMap;

let client = Client::default();
let obj1 = client.object().read("my_bucket", "file1").await?;
let mut custom_metadata = HashMap::new();
custom_metadata.insert(String::from("field"), String::from("value"));
let (url, headers) = obj1.upload_url_with(50, custom_metadata)?;
// url is now a url to which an unauthenticated user can make a PUT request to upload a file
// for 50 seconds. Note that the user must also include the returned headers in the PUT request

Trait Implementations

impl Debug for Object

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Object

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl PartialEq<Object> for Object

fn eq(&self, other: &Object) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Object) -> bool

This method tests for !=.

impl Serialize for Object

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Object