Struct opendal::services::Gcs

pub struct Gcs { /* private fields */ }

Available on crate feature services-gcs only.

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

set the working directory root of backend

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

set the container’s name

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

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

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

set the endpoint GCS service uses

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

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

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

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

Specify the customized token loader used by this service.

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

Provide the OAuth2 token to use.

pub fn disable_vm_metadata(self) -> Self

Disable attempting to load credentials from the GCE metadata server.

pub fn disable_config_load(self) -> Self

Disable loading configuration from the environment.

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

Set the predefined acl for GCS.

Available values are:

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

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

Set the default storage class for GCS.

Available values are:

• STANDARD
• NEARLINE
• COLDLINE
• ARCHIVE

pub fn allow_anonymous(self) -> Self

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

const SCHEME: Scheme = Scheme::Gcs

Associated scheme for this builder. It indicates what underlying service is.

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

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

Formats the value using the given formatter.

impl Default for GcsBuilder

fn default() -> GcsBuilder

Returns the “default value” for a type.