Struct s3::bucket::Bucket

pub struct Bucket {
    pub name: String,
    pub region: Region,
    pub credentials: Credentials,
    pub extra_headers: Headers,
    pub extra_query: Query,
}

Example

use s3::bucket::Bucket;
use s3::credentials::Credentials;

let bucket_name = "rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();

let bucket = Bucket::new(bucket_name, region, credentials);

Fields

name: String

region: Region

credentials: Credentials

extra_headers: Headers

extra_query: Query

Methods

impl Bucket

pub fn new(
    name: &str,
    region: Region,
    credentials: Credentials
) -> S3Result<Bucket>

Instantiate a new Bucket.

Example

use s3::bucket::Bucket;
use s3::credentials::Credentials;

let bucket_name = "rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();

let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

pub fn get_object(&self, path: &str) -> S3Result<(Vec<u8>, u16)>

Gets file from an S3 path.

Example:

use s3::bucket::Bucket;
use s3::credentials::Credentials;

let bucket_name = "rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let (data, code) = bucket.get_object("/test.file").unwrap();
println!("Code: {}\nData: {:?}", code, data);

pub fn get_object_async(&self, path: &str) -> impl Future<Item = (Vec<u8>, u16)>

Gets file from an S3 path.

Example:

extern crate futures;

use s3::bucket::Bucket;
use s3::credentials::Credentials;
use futures::Future;

let bucket_name = "rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

bucket.get_object_async("/test.file")
    .map(|(data, code)| {
        println!("Code: {}", code);
        println!("{:?}", data);
});

pub fn get_object_stream<T: Write>(
    &self,
    path: &str,
    writer: &mut T
) -> S3Result<u16>

Stream file from S3 path to a local file, generic over T: Write.

Example:

use s3::bucket::Bucket;
use s3::credentials::Credentials;
use std::fs::File;

let bucket_name = "rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();
let mut output_file = File::create("output_file").expect("Unable to create file");

let code = bucket.get_object_stream("/test.file", &mut output_file).unwrap();
println!("Code: {}", code);

pub fn get_object_stream_async<'b, T: Write>(
    &self,
    path: &str,
    writer: &'b mut T
) -> impl Future<Item = u16> + 'b

Stream file from S3 path to a local file, generic over T: Write.

Example:

extern crate futures;

use s3::bucket::Bucket;
use s3::credentials::Credentials;
use std::fs::File;
use futures::Future;

let bucket_name = "rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();
let mut output_file = File::create("output_file").expect("Unable to create file");

bucket.get_object_stream_async("/test.file", &mut output_file)
    .map(|status_code| println!("Code: {}", status_code));

pub fn location(&self) -> S3Result<(Region, u16)>

Example

use s3::bucket::Bucket;
use s3::credentials::Credentials;

let bucket_name = "rust-s3-test";
let region = "eu-central-1".parse().unwrap();
let credentials = Credentials::default();

let bucket = Bucket::new(bucket_name, region, credentials).unwrap();
println!("{}", bucket.location().unwrap().0)

pub fn delete_object(&self, path: &str) -> S3Result<(Vec<u8>, u16)>

Delete file from an S3 path.

Example:

use s3::bucket::Bucket;
use s3::credentials::Credentials;

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let (_, code) = bucket.delete_object("/test.file").unwrap();
assert_eq!(204, code);

pub fn put_object(
    &self,
    path: &str,
    content: &[u8],
    content_type: &str
) -> S3Result<(Vec<u8>, u16)>

Put into an S3 bucket.

Example

use s3::bucket::Bucket;
use s3::credentials::Credentials;

let bucket_name = &"rust-s3-test";
let aws_access = &"access_key";
let aws_secret = &"secret_key";

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let content = "I want to go to S3".as_bytes();
let (_, code) = bucket.put_object("/test.file", content, "text/plain").unwrap();
assert_eq!(201, code);

pub fn put_object_tagging(
    &self,
    path: &str,
    tags: &[(&str, &str)]
) -> S3Result<(Vec<u8>, u16)>

Tag an S3 object.

Example

use s3::bucket::Bucket;
use s3::credentials::Credentials;

let bucket_name = &"rust-s3-test";
let aws_access = &"access_key";
let aws_secret = &"secret_key";

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let (_, code) = bucket.put_object_tagging("/test.file", &[("Tag1", "Value1"), ("Tag2", "Value2")]).unwrap();
assert_eq!(201, code);

pub fn delete_object_tagging(&self, path: &str) -> S3Result<(Vec<u8>, u16)>

Delete tags from an S3 object.

Example

use s3::bucket::Bucket;
use s3::credentials::Credentials;

let bucket_name = &"rust-s3-test";
let aws_access = &"access_key";
let aws_secret = &"secret_key";

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let (_, code) = bucket.delete_object_tagging("/test.file").unwrap();
assert_eq!(201, code);

pub fn get_object_tagging(&self, path: &str) -> S3Result<(Option<Tagging>, u16)>

Retrieve an S3 object list of tags.

Example

use s3::bucket::Bucket;
use s3::credentials::Credentials;

let bucket_name = &"rust-s3-test";
let aws_access = &"access_key";
let aws_secret = &"secret_key";

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let (tags, code) = bucket.get_object_tagging("/test.file").unwrap();
if code == 200 {
    for tag in tags.expect("No tags found").tag_set {
        println!("{}={}", tag.key(), tag.value());
    }
}

pub fn list_page(
    &self,
    prefix: String,
    delimiter: Option<String>,
    continuation_token: Option<String>
) -> S3Result<(ListBucketResult, u16)>

pub fn list_page_async(
    &self,
    prefix: String,
    delimiter: Option<String>,
    continuation_token: Option<String>
) -> impl Future<Item = (ListBucketResult, u16), Error = S3Error> + Send

pub fn list_all(
    &self,
    prefix: String,
    delimiter: Option<String>
) -> S3Result<Vec<(ListBucketResult, u16)>>

List the contents of an S3 bucket.

Example

use std::str;
use s3::bucket::Bucket;
use s3::credentials::Credentials;
let bucket_name = &"rust-s3-test";
let aws_access = &"access_key";
let aws_secret = &"secret_key";

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let results = bucket.list_all("/".to_string(), Some("/".to_string())).unwrap();
for (list, code) in results {
    assert_eq!(200, code);
    println!("{:?}", list);
}

pub fn list_all_async(
    &self,
    prefix: String,
    delimiter: Option<String>
) -> impl Future<Item = Vec<ListBucketResult>, Error = S3Error> + Send

List the contents of an S3 bucket.

Example

extern crate futures;
use std::str;
use s3::bucket::Bucket;
use s3::credentials::Credentials;
use futures::future::Future;
let bucket_name = &"rust-s3-test";
let aws_access = &"access_key";
let aws_secret = &"secret_key";

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let results = bucket.list_all_async("/".to_string(), Some("/".to_string())).and_then(|list| {
    println!("{:?}", list);
    Ok(())
});

pub fn name(&self) -> String

Get a reference to the name of the S3 bucket.

pub fn host(&self) -> String

Get a reference to the hostname of the S3 API endpoint.

pub fn self_host(&self) -> String

pub fn scheme(&self) -> String

pub fn region(&self) -> Region

Get the region this object will connect to.

pub fn access_key(&self) -> String

Get a reference to the AWS access key.

pub fn secret_key(&self) -> String

Get a reference to the AWS secret key.

pub fn token(&self) -> Option<&str>

Get a reference to the AWS token.

pub fn credentials(&self) -> &Credentials

Get a reference to the full Credentials object used by this Bucket.

pub fn set_credentials(&mut self, credentials: Credentials) -> Credentials

Change the credentials used by the Bucket, returning the existing credentials.

pub fn add_header(&mut self, key: &str, value: &str)

Add an extra header to send with requests to S3.

Add an extra header to send with requests. Note that the library already sets a number of headers - headers set with this method will be overridden by the library headers:

• Host
• Content-Type
• Date
• Content-Length
• Authorization
• X-Amz-Content-Sha256
• X-Amz-Date

pub fn extra_headers(&self) -> &Headers

Get a reference to the extra headers to be passed to the S3 API.

pub fn extra_headers_mut(&mut self) -> &mut Headers

Get a mutable reference to the extra headers to be passed to the S3 API.

pub fn add_query(&mut self, key: &str, value: &str)

Add an extra query pair to the URL used for S3 API access.

pub fn extra_query(&self) -> &Query

Get a reference to the extra query pairs to be passed to the S3 API.

pub fn extra_query_mut(&mut self) -> &mut Query

Get a mutable reference to the extra query pairs to be passed to the S3 API.

Trait Implementations

impl Clone for Bucket

fn clone(&self) -> Bucket

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Bucket

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

Formats the value using the given formatter.

impl Eq for Bucket

impl PartialEq<Bucket> for Bucket

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

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

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

This method tests for !=.

impl StructuralEq for Bucket

impl StructuralPartialEq for Bucket