Struct S3Config

#[non_exhaustive]
pub struct S3Config {

    pub root: Option<String>,
    pub bucket: String,
    pub enable_versioning: bool,
    pub endpoint: Option<String>,
    pub region: Option<String>,
    pub access_key_id: Option<String>,
    pub secret_access_key: Option<String>,
    pub session_token: Option<String>,
    pub role_arn: Option<String>,
    pub external_id: Option<String>,
    pub role_session_name: Option<String>,
    pub disable_config_load: bool,
    pub disable_ec2_metadata: bool,
    pub allow_anonymous: bool,
    pub server_side_encryption: Option<String>,
    pub server_side_encryption_aws_kms_key_id: Option<String>,
    pub server_side_encryption_customer_algorithm: Option<String>,
    pub server_side_encryption_customer_key: Option<String>,
    pub server_side_encryption_customer_key_md5: Option<String>,
    pub default_storage_class: Option<String>,
    pub enable_virtual_host_style: bool,
    pub batch_max_operations: Option<usize>,
    pub delete_max_size: Option<usize>,
    pub disable_stat_with_override: bool,
    pub checksum_algorithm: Option<String>,
    pub disable_write_with_if_match: bool,
}

Config for Aws S3 and compatible services (including minio, digitalocean space, Tencent Cloud Object Storage(COS) and so on) support.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

root: Option<String>

root of this backend.

All operations will happen under this root.

default to / if not set.

bucket: String

bucket name of this backend.

required.

enable_versioning: bool

is bucket versioning enabled for this bucket

endpoint: Option<String>

endpoint of this backend.

Endpoint must be full uri, e.g.

• AWS S3: https://s3.amazonaws.com or https://s3.{region}.amazonaws.com
• Cloudflare R2: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
• Aliyun OSS: https://{region}.aliyuncs.com
• Tencent COS: https://cos.{region}.myqcloud.com
• Minio: http://127.0.0.1:9000

If user inputs endpoint without scheme like “s3.amazonaws.com”, we will prepend “https://” before it.

• If endpoint is set, we will take user’s input first.
• If not, we will try to load it from environment.
• If still not set, default to https://s3.amazonaws.com.

region: Option<String>

Region represent the signing region of this endpoint. This is required if you are using the default AWS S3 endpoint.

If using a custom endpoint,

• If region is set, we will take user’s input first.
• If not, we will try to load it from environment.

access_key_id: Option<String>

access_key_id of this backend.

• If access_key_id is set, we will take user’s input first.
• If not, we will try to load it from environment.

secret_access_key: Option<String>

secret_access_key of this backend.

• If secret_access_key is set, we will take user’s input first.
• If not, we will try to load it from environment.

session_token: Option<String>

session_token (aka, security token) of this backend.

This token will expire after sometime, it’s recommended to set session_token by hand.

role_arn: Option<String>

role_arn for this backend.

If role_arn is set, we will use already known config as source credential to assume role with role_arn.

external_id: Option<String>

external_id for this backend.

role_session_name: Option<String>

role_session_name for this backend.

disable_config_load: bool

Disable config load so that opendal will not load config from environment.

For examples:

• envs like AWS_ACCESS_KEY_ID
• files like ~/.aws/config

disable_ec2_metadata: bool

Disable load credential from ec2 metadata.

This option is used to disable the default behavior of opendal to load credential from ec2 metadata, a.k.a, IMDSv2

allow_anonymous: bool

Allow anonymous will allow opendal to send request without signing when credential is not loaded.

server_side_encryption: Option<String>

server_side_encryption for this backend.

Available values: AES256, aws:kms.

server_side_encryption_aws_kms_key_id: Option<String>

server_side_encryption_aws_kms_key_id for this backend

• If server_side_encryption set to aws:kms, and server_side_encryption_aws_kms_key_id is not set, S3 will use aws managed kms key to encrypt data.
• If server_side_encryption set to aws:kms, and server_side_encryption_aws_kms_key_id is a valid kms key id, S3 will use the provided kms key to encrypt data.
• If the server_side_encryption_aws_kms_key_id is invalid or not found, an error will be returned.
• If server_side_encryption is not aws:kms, setting server_side_encryption_aws_kms_key_id is a noop.

server_side_encryption_customer_algorithm: Option<String>

server_side_encryption_customer_algorithm for this backend.

Available values: AES256.

server_side_encryption_customer_key: Option<String>

server_side_encryption_customer_key for this backend.

Value

base64 encoded key that matches algorithm specified in server_side_encryption_customer_algorithm.

server_side_encryption_customer_key_md5: Option<String>

Set server_side_encryption_customer_key_md5 for this backend.

Value

MD5 digest of key specified in server_side_encryption_customer_key.

default_storage_class: Option<String>

default storage_class for this backend.

Available values:

• DEEP_ARCHIVE
• GLACIER
• GLACIER_IR
• INTELLIGENT_TIERING
• ONEZONE_IA
• OUTPOSTS
• REDUCED_REDUNDANCY
• STANDARD
• STANDARD_IA

S3 compatible services don’t support all of them

enable_virtual_host_style: bool

Enable virtual host style so that opendal will send API requests in virtual host style instead of path style.

• By default, opendal will send API to https://s3.us-east-1.amazonaws.com/bucket_name
• Enabled, opendal will send API to https://bucket_name.s3.us-east-1.amazonaws.com

batch_max_operations: Option<usize>

👎Deprecated since 0.52.0: Please use delete_max_size instead of batch_max_operations

Set maximum batch operations of this backend.

Some compatible services have a limit on the number of operations in a batch request. For example, R2 could return Internal Error while batch delete 1000 files.

Please tune this value based on services’ document.

delete_max_size: Option<usize>

Set the maximum delete size of this backend.

Some compatible services have a limit on the number of operations in a batch request. For example, R2 could return Internal Error while batch delete 1000 files.

Please tune this value based on services’ document.

disable_stat_with_override: bool

Disable stat with override so that opendal will not send stat request with override queries.

For example, R2 doesn’t support stat with response_content_type query.

checksum_algorithm: Option<String>

Checksum Algorithm to use when sending checksums in HTTP headers. This is necessary when writing to AWS S3 Buckets with Object Lock enabled for example.

Available options:

• “crc32c”

disable_write_with_if_match: bool

Disable write with if match so that opendal will not send write request with if match headers.

For example, Ceph RADOS S3 doesn’t support write with if match.

Trait Implementations

impl Clone for S3Config

fn clone(&self) -> S3Config

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Configurator for S3Config

type Builder = S3Builder

Associated builder for this configuration.

fn into_builder(self) -> <S3Config as Configurator>::Builder

Convert this configuration into a service builder.

fn from_iter( iter: impl IntoIterator<Item = (String, String)>, ) -> Result<Self, Error>

Deserialize from an iterator.

impl Debug for S3Config

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

Formats the value using the given formatter.

impl Default for S3Config

fn default() -> S3Config

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for S3Config

where S3Config: Default,

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for S3Config

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for S3Config

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for S3Config

impl StructuralPartialEq for S3Config