Struct Gcs 

pub struct Gcs { /* private fields */ }

Google Cloud Storage services support.

Capabilities

This service can be used to:

• stat
• read
• write
• create_dir
• delete
• copy
• rename
• list
• presign
• blocking

Configuration

• root: Set the work directory for backend
• bucket: Set the container name for backend
• endpoint: Customizable endpoint setting
• credential: Service Account or External Account JSON, in base64
• credential_path: local path to Service Account or External Account JSON file
• service_account: name of Service Account
• predefined_acl: Predefined ACL for GCS
• default_storage_class: Default storage class for GCS

Refer to public API docs for more information. For authentication related options, read on.

Options to authenticate to GCS

OpenDAL supports the following authentication options:

1. Provide a base64-ed JSON key string with credential
2. Provide a JSON key file at explicit path with credential_path
3. Provide a JSON key file at implicit path
   • GcsBackend will attempt to load Service Account key from ADC well-known places.
4. Fetch access token from VM metadata
   • Only works when running inside Google Cloud.
   • If a non-default Service Account name is required, set with service_account. Otherwise, nothing need to be set.
5. A custom TokenLoader via GcsBuilder.customized_token_loader()

Notes:

• When a Service Account key is provided, it will be used to create access tokens (VM metadata will not be used).
• Explicit Service Account key, in json or path, always take precedence over ADC-defined key paths.
• Due to limitation in GCS, a private key is required to create Pre-signed URL. Currently, OpenDAL only supports Service Account key.

Example

Via Builder

use anyhow::Result;
use opendal::services::Gcs;
use opendal::Operator;

#[tokio::main]
async fn main() -> Result<()> {
    // create backend builder
    let mut builder = Gcs::default()
       // set the storage bucket for OpenDAL
       .bucket("test")
       // set the working directory root for GCS
       // all operations will happen within it
       .root("/path/to/dir")
       // set the credentials with service account
       .credential("service account JSON in base64")
       // set the predefined ACL for GCS
       .predefined_acl("publicRead")
       // set the default storage class for GCS
       .default_storage_class("STANDARD");

    let op: Operator = Operator::new(builder)?.finish();
    Ok(())
}

Implementations

impl GcsBuilder

pub fn root(self, root: &str) -> Self

Available on crate feature services-gcs only.

set the working directory root of backend

pub fn bucket(self, bucket: &str) -> Self

Available on crate feature services-gcs only.

set the container’s name

pub fn scope(self, scope: &str) -> Self

Available on crate feature services-gcs only.

set the GCS service scope

If not set, we will use https://www.googleapis.com/auth/devstorage.read_write.

Valid scope examples

• read-only: https://www.googleapis.com/auth/devstorage.read_only
• read-write: https://www.googleapis.com/auth/devstorage.read_write
• full-control: https://www.googleapis.com/auth/devstorage.full_control

Reference: Cloud Storage authentication

pub fn service_account(self, service_account: &str) -> Self

Available on crate feature services-gcs only.

Set the GCS service account.

service account will be used for fetch token from vm metadata. If not set, we will try to fetch with default service account.

pub fn endpoint(self, endpoint: &str) -> Self

Available on crate feature services-gcs only.

set the endpoint GCS service uses

pub fn credential(self, credential: &str) -> Self

Available on crate feature services-gcs only.

set the base64 hashed credentials string used for OAuth2 authentication.

this method allows to specify the credentials directly as a base64 hashed string. alternatively, you can use credential_path() to provide the local path to a credentials file. we will use one of credential and credential_path to complete the OAuth2 authentication.

Reference: Google Cloud Storage Authentication.

pub fn credential_path(self, path: &str) -> Self

Available on crate feature services-gcs only.

set the local path to credentials file which is used for OAuth2 authentication.

credentials file contains the original credentials that have not been base64 hashed. we will use one of credential and credential_path to complete the OAuth2 authentication.

Reference: Google Cloud Storage Authentication.

pub fn http_client(self, client: HttpClient) -> Self

👎Deprecated since 0.53.0: Use Operator::update_http_client instead

Available on crate feature services-gcs only.

Specify the http client that used by this service.

Notes

This API is part of OpenDAL’s Raw API. HttpClient could be changed during minor updates.

pub fn customized_token_loader( self, token_load: Box<dyn GoogleTokenLoad>, ) -> Self

Available on crate feature services-gcs only.

Specify the customized token loader used by this service.

pub fn token(self, token: String) -> Self

Available on crate feature services-gcs only.

Provide the OAuth2 token to use.

pub fn disable_vm_metadata(self) -> Self

Available on crate feature services-gcs only.

Disable attempting to load credentials from the GCE metadata server.

pub fn disable_config_load(self) -> Self

Available on crate feature services-gcs only.

Disable loading configuration from the environment.

pub fn predefined_acl(self, acl: &str) -> Self

Available on crate feature services-gcs only.

Set the predefined acl for GCS.

Available values are:

• authenticatedRead
• bucketOwnerFullControl
• bucketOwnerRead
• private
• projectPrivate
• publicRead

pub fn default_storage_class(self, class: &str) -> Self

Available on crate feature services-gcs only.

Set the default storage class for GCS.

Available values are:

• STANDARD
• NEARLINE
• COLDLINE
• ARCHIVE

pub fn allow_anonymous(self) -> Self

Available on crate feature services-gcs only.

Allow anonymous requests.

This is typically used for buckets which are open to the public or GCS storage emulators.

Trait Implementations

impl Builder for GcsBuilder

Available on crate feature services-gcs only.

type Config = GcsConfig

Associated configuration for this builder.

fn build(self) -> Result<impl Access>

Consume the accessor builder to build a service.

impl Debug for GcsBuilder

Available on crate feature services-gcs only.

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

Formats the value using the given formatter.

impl Default for GcsBuilder

Available on crate feature services-gcs only.

fn default() -> GcsBuilder

Returns the “default value” for a type.