gcloud_storage/lib.rs
1#![allow(clippy::result_large_err)]
2//! # google-cloud-storage
3//!
4//! Google Cloud Platform Storage Client library.
5//!
6//! * [About Cloud Storage](https://cloud.google.com/storage/)
7//! * [JSON API Documentation](https://cloud.google.com/storage/docs/json_api/v1)
8//!
9//! ## Quick Start
10//!
11//! ### Authentication
12//! There are two ways to create a client that is authenticated against the google cloud.
13//!
14//! #### Automatically
15//!
16//! The function `with_auth()` will try and read the credentials from a file specified in the environment variable `GOOGLE_APPLICATION_CREDENTIALS`, `GOOGLE_APPLICATION_CREDENTIALS_JSON` or
17//! from a metadata server.
18//!
19//! This is also described in [google-cloud-auth](https://github.com/yoshidan/google-cloud-rust/blob/main/foundation/auth/README.md)
20//!
21//! ```
22//! use google_cloud_storage::client::{ClientConfig, Client};
23//!
24//! async fn run() {
25//! let config = ClientConfig::default().with_auth().await.unwrap();
26//! let client = Client::new(config);
27//! }
28//! ```
29//!
30//! #### Manually
31//!
32//! When you cant use the `gcloud` authentication but you have a different way to get your credentials (e.g a different environment variable)
33//! you can parse your own version of the 'credentials-file' and use it like that:
34//!
35//! ```
36//! use google_cloud_auth::credentials::CredentialsFile;
37//! // or google_cloud_storage::client::google_cloud_auth::credentials::CredentialsFile
38//! use google_cloud_storage::client::{ClientConfig, Client};
39//!
40//! async fn run(cred: CredentialsFile) {
41//! let config = ClientConfig::default().with_credentials(cred).await.unwrap();
42//! let client = Client::new(config);
43//! }
44//! ```
45//!
46//! ### Anonymous Access
47//!
48//! To provide [anonymous access without authentication](https://cloud.google.com/storage/docs/authentication), do the following.
49//!
50//! ```rust
51//! use google_cloud_storage::client::{ClientConfig, Client};
52//!
53//! async fn run() {
54//! let config = ClientConfig::default().anonymous();
55//! let client = Client::new(config);
56//! }
57//! ```
58//!
59//! ### Usage
60//!
61//! ```
62//! use google_cloud_storage::client::Client;
63//! use google_cloud_storage::client::ClientConfig;
64//! use google_cloud_storage::sign::SignedURLOptions;
65//! use google_cloud_storage::sign::SignedURLMethod;
66//! use google_cloud_storage::http::Error;
67//! use google_cloud_storage::http::objects::download::Range;
68//! use google_cloud_storage::http::objects::get::GetObjectRequest;
69//! use google_cloud_storage::http::objects::upload::{Media, UploadObjectRequest, UploadType};
70//! use tokio::task::JoinHandle;
71//! use std::fs::File;
72//! use std::io::BufReader;
73//! use std::io::Read;
74//!
75//! async fn run(config: ClientConfig) -> Result<(), Error> {
76//!
77//! // Create client.
78//! let mut client = Client::new(config);
79//!
80//! // Upload the file
81//! let upload_type = UploadType::Simple(Media::new("file.png"));
82//! let uploaded = client.upload_object(&UploadObjectRequest {
83//! bucket: "bucket".to_string(),
84//! ..Default::default()
85//! }, "hello world".as_bytes(), &upload_type).await;
86//!
87//! // Download the file
88//! let data = client.download_object(&GetObjectRequest {
89//! bucket: "bucket".to_string(),
90//! object: "file.png".to_string(),
91//! ..Default::default()
92//! }, &Range::default()).await;
93//!
94//! // Create signed url with the default key and google-access-id of the client
95//! let url_for_download = client.signed_url("bucket", "foo.txt", None, None, SignedURLOptions::default());
96//! let url_for_upload = client.signed_url("bucket", "foo.txt", None, None, SignedURLOptions {
97//! method: SignedURLMethod::PUT,
98//! ..Default::default()
99//! });
100//!
101//! Ok(())
102//! }
103//! ```
104
105extern crate core;
106
107pub mod client;
108pub mod http;
109pub mod sign;