aliyun-oss-rs

https://docs.rs/aliyun-oss-rs/0.3.0/
Admin
An unofficial Rust SDK for Alibaba Cloud Object Storage Service (OSS) providing async and sync APIs...
Tokens:384,458
Snippets:2,082
Trust Score:9.7
Update:8 months ago
Show doc for...
Tokens:
Raw
### Initiate Aliyun OSS Bucket WORM Configuration (Rust)

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/oss_bucket.rs_search=std%3A%3Avec

This function initiates a WORM (Write Once, Read Many) retention configuration for an Aliyun OSS bucket. It requires the `_async-base` feature. The function returns an `InitiateBucketWorm` object to start the WORM setup process.

```rust
/// Initiate WORM retention configuration.
///
/// 初始化 WORM 合规保留策略。
#[cfg(feature = "_async-base")]
pub fn initiate_bucket_worm(&self) -> InitiateBucketWorm {
    InitiateBucketWorm::new(self.oss.clone())
}
```

--------------------------------

### Rust: Stream Object Download Example

Source: https://docs.rs/aliyun-oss-rs/0.3.0/aliyun_oss_rs/object/struct.GetObject_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

An example demonstrating how to download an object from Alibaba Cloud OSS as a stream using `download_to_stream()` and process the chunks of data as they arrive. It utilizes `futures_util::StreamExt` for stream manipulation.

```rust
use futures_util::StreamExt;

let mut stream = object.get_object().download_to_stream().await.unwrap();
while let Some(item) = stream.next().await {
match item {
Ok(bytes) => {
// Do something with bytes...
}
Err(e) => eprintln!("Error: {}", e),
}
}
```

--------------------------------

### Retrieve Bucket Website Configuration using Rust

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/get_bucket_website.rs

This Rust code defines a struct `GetBucketWebsite` to retrieve the static website configuration of an Alibaba Cloud OSS bucket. It utilizes the `OssRequest` type and sends a GET request with the 'website' query parameter. The response is then parsed into a `WebsiteConfiguration` struct. Dependencies include `crate::{Error, common::body_to_bytes, error::normal_error, request::{Oss, OssRequest}}` and `http::Method`.

```rust
use crate::{
    Error,
    common::body_to_bytes,
    error::normal_error,
    request::{Oss, OssRequest},
};
use http::Method;

use super::WebsiteConfiguration;

/// Retrieve the static website configuration of a bucket.
///
/// See the [Alibaba Cloud documentation](https://help.aliyun.com/zh/oss/developer-reference/getbucketwebsite) for details.
///
/// 获取 Bucket 静态网站配置。
///
/// 详情参见 [阿里云文档](https://help.aliyun.com/zh/oss/developer-reference/getbucketwebsite)。
pub struct GetBucketWebsite {
    req: OssRequest,
}

impl GetBucketWebsite {
    pub(super) fn new(oss: Oss) -> Self {
        let mut req = OssRequest::new(oss, Method::GET);
        req.insert_query("website", "");
        GetBucketWebsite { req }
    }

    /// Send the request and return the parsed configuration.
    ///
    /// 发送请求并返回解析后的配置。
    pub async fn send(self) -> Result<WebsiteConfiguration, Error> {
        let response = self.req.send_to_oss()?.await?;
        match response.status() {
            code if code.is_success() => {
                let bytes = body_to_bytes(response.into_body()).await?;
                let config: WebsiteConfiguration =
                    serde_xml_rs::from_reader(bytes.as_ref()).map_err(|_| Error::OssInvalidResponse(Some(bytes)))?;
                Ok(config)
            }
            _ => Err(normal_error(response).await),
        }
    }
}
```

--------------------------------

### Set Byte Range for GetObject Request in Rust

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/object/get_object.rs

Configures the `GetObject` request to retrieve a specific byte range of an object. The `start` parameter specifies the beginning of the range (inclusive), and `end` (optional) specifies the end of the range (inclusive). Byte indexing starts at 0. Invalid ranges will result in the entire object being downloaded.

```Rust
pub fn set_range(mut self, start: usize, end: Option<usize>) -> Self {
        self.req.insert_header(
            "Range",
            format!("bytes={}-{}", start, end.map(|v| v.to_string()).unwrap_or_else(|| String::new())),
        );
        self
    }
```

--------------------------------

### Quick Start: List Buckets (Async)

Source: https://docs.rs/aliyun-oss-rs/0.3.0/aliyun_oss_rs/index

Initializes an OssClient and lists buckets with a specified prefix using asynchronous operations. Requires a Tokio runtime. Replace placeholders with your actual AccessKeyId, AccessKeySecret, and region.

```rust
use aliyun_oss_rs::OssClient;

#[tokio::main] async fn main() {
    let mut client = OssClient::new("<AccessKeyId>", "<AccessKeySecret>", "cn-zhangjiakou");
    // Optional: internal/dualstack/custom endpoints
    // client.set_endpoint("oss-cn-zhangjiakou-internal.aliyuncs.com");

    let buckets = client.list_buckets().set_prefix("rust").send().await;
    println!("buckets = {:?}", buckets);
}
```

--------------------------------

### List Buckets with aliyun-oss-rs

Source: https://docs.rs/aliyun-oss-rs/0.3.0/aliyun_oss_rs/client/struct.ListBuckets

Demonstrates how to list buckets using the aliyun-oss-rs client. It shows initialization of the client and calling the list_buckets method with an optional prefix filter. The output is then printed to the console. This function requires valid Alibaba Cloud credentials and region.

```rust
let client = OssClient::new("AccessKey ID", "AccessKey Secret", "cn-beijing");
let buckets = client.list_buckets().set_prefix("rust").send().await;
println!("{:#?}", buckets);
```

--------------------------------

### OssClient Initialization and Configuration

Source: https://docs.rs/aliyun-oss-rs/0.3.0/aliyun_oss_rs/struct.OssClient_search=u32+-%3E+bool

This section details how to create and configure an OssClient instance for interacting with Alibaba Cloud OSS.

```APIDOC
## OssClient

### Description

Entry point for OSS, providing service-level APIs such as listing buckets and regions.
OSS 的入口类型，提供列举存储空间与地域等服务级 API。

### Methods

#### `new(ak_id: impl Into<String>, ak_secret: impl Into<String>, region: impl Into<String>) -> Self`

**Description:** Create a new client with AccessKey credentials and region.
`ak_id` is the AccessKey ID, `ak_secret` is the AccessKey Secret.
`region` is required for Signature V4 (for example, `cn-hangzhou`).

**Usage:**
```rust
let client = OssClient::new("your_ak_id", "your_ak_secret", "cn-hangzhou");
```

#### `disable_https(self) -> Self`

**Description:** Disable HTTPS and use HTTP for all requests.
禁用 HTTPS，所有请求改为使用 HTTP。

**Usage:**
```rust
let client = OssClient::new("your_ak_id", "your_ak_secret", "cn-hangzhou").disable_https();
```

#### `with_security_token(self, token: impl Into<String>) -> Self`

**Description:** Attach a temporary security token for STS authentication.
设置临时安全令牌用于 STS 鉴权。

**Usage:**
```rust
let client = OssClient::new("your_ak_id", "your_ak_secret", "cn-hangzhou").with_security_token("your_security_token");
```

#### `set_endpoint(&mut self, endpoint: impl Into<String>)`

**Description:** Override the endpoint used for subsequent requests.
覆盖后续请求使用的 Endpoint。

**Usage:**
```rust
let mut client = OssClient::new("your_ak_id", "your_ak_secret", "cn-hangzhou");
client.set_endpoint("oss-cn-hangzhou.aliyuncs.com");
```

#### `set_security_token(&mut self, token: impl Into<String>)`

**Description:** Update the security token in place for reuse.
就地更新安全令牌，便于复用。

**Usage:**
```rust
let mut client = OssClient::new("your_ak_id", "your_ak_secret", "cn-hangzhou");
client.set_security_token("your_updated_security_token");
```
```

--------------------------------

### GET /bucket/location

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/get_bucket_location.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the location (region) of an Aliyun OSS bucket. This operation is used to get the region identifier of a bucket.

```APIDOC
## GET /bucket/location

### Description
Retrieves the location (region) of an Aliyun OSS bucket. This operation is used to get the region identifier of a bucket.

### Method
GET

### Endpoint
/bucket/location

### Parameters
#### Query Parameters
- **location** (string) - Optional - Used to specify the query for location.

### Request Example
```json
{
  "bucket_name": "your-bucket-name"
}
```

### Response
#### Success Response (200)
- **location** (string) - The region identifier of the bucket.

#### Response Example
```json
{
  "location": "oss-cn-hangzhou"
}
```
```

--------------------------------

### Rust: Initialize OssClient and List Buckets (Async)

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/lib.rs

Demonstrates how to initialize the OssClient with credentials and region, and then asynchronously list buckets with a specified prefix. Requires a Tokio runtime. The client can be configured with custom endpoints.

```rust
use aliyun_oss_rs::OssClient;

#[tokio::main]
async fn main() {
    let mut client = OssClient::new("<AccessKeyId>", "<AccessKeySecret>", "cn-zhangjiakou");
    // Optional: internal/dualstack/custom endpoints
    // client.set_endpoint("oss-cn-zhangjiakou-internal.aliyuncs.com");

    let buckets = client.list_buckets().set_prefix("rust").send().await;
    println!("buckets = {:?}", buckets);
}
```

--------------------------------

### GET /object/tagging

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/object/get_object_tagging.rs_search=std%3A%3Avec

Retrieves the tag information associated with an object in Aliyun OSS. This endpoint allows you to get the key-value pairs of tags applied to a specific object.

```APIDOC
## GET /object/tagging

### Description
Retrieves the tag information associated with an object in Aliyun OSS. This endpoint allows you to get the key-value pairs of tags applied to a specific object.

### Method
GET

### Endpoint
/object/tagging

### Query Parameters
- **tagging** (string) - Required - Used to specify that the request is for object tagging.

### Request Example
```
GET /your-object-key?tagging HTTP/1.1
Host: your-bucket-name.oss.aliyuncs.com

```

### Response
#### Success Response (200)
- **TagSet** (object) - Contains the set of tags.
  - **Tag** (array of objects) - Optional - A list of tags, where each tag is an object with 'Key' and 'Value' fields.
    - **Key** (string) - The tag key.
    - **Value** (string) - The tag value.

#### Response Example
```json
{
  "TagSet": {
    "Tag": [
      {
        "Key": "environment",
        "Value": "production"
      },
      {
        "Key": "owner",
        "Value": "team-a"
      }
    ]
  }
}
```

#### Error Response
- **Error** (object) - Contains error details if the request fails.
  - **Code** (string) - The error code.
  - **Message** (string) - The error message.
  - **RequestId** (string) - The request ID for tracking the error.
  - **HostId** (string) - The host ID associated with the error.
```

--------------------------------

### OssClient Initialization and Configuration

Source: https://docs.rs/aliyun-oss-rs/0.3.0/aliyun_oss_rs/client/struct.OssClient_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This section details how to create and configure an OssClient instance for interacting with Alibaba Cloud OSS.

```APIDOC
## OssClient

Entry point for OSS, providing service-level APIs such as listing buckets and regions.

### `OssClient::new(ak_id: impl Into<String>, ak_secret: impl Into<String>, region: impl Into<String>) -> Self`

**Description**: Create a new client with AccessKey credentials and region.

- `ak_id`: The AccessKey ID.
- `ak_secret`: The AccessKey Secret.
- `region`: Required for Signature V4 (e.g., `cn-hangzhou`).

### `OssClient::disable_https(self) -> Self`

**Description**: Disable HTTPS and use HTTP for all requests.

### `OssClient::with_security_token(self, token: impl Into<String>) -> Self`

**Description**: Attach a temporary security token for STS authentication.

### `OssClient::set_endpoint(&mut self, endpoint: impl Into<String>)`

**Description**: Override the endpoint used for subsequent requests.

### `OssClient::set_security_token(&mut self, token: impl Into<String>)`

**Description**: Update the security token in place for reuse.

### `OssClient::bucket(&self, bucket: impl Into<String>) -> OssBucket`

**Description**: Bind a bucket name and create a bucket handle.

### `OssClient::describe_regions(&self) -> DescribeRegions`

**Description**: List OSS regions and their endpoints.

### `OssClient::list_buckets(&self) -> ListBuckets`

**Description**: List all buckets owned by the current account.
```

--------------------------------

### GET /object/tagging

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/object/get_object_tagging.rs_search=u32+-%3E+bool

Retrieves the tag information of an object. This endpoint allows you to get the key-value pairs associated with an object in Alibaba Cloud Object Storage Service (OSS).

```APIDOC
## GET /object/tagging

### Description
Retrieve tag information of an object. This endpoint allows you to get the key-value pairs associated with an object in Alibaba Cloud Object Storage Service (OSS).

### Method
GET

### Endpoint
/object/{object_name}?tagging

### Parameters
#### Query Parameters
- **tagging** (string) - Required - Used to specify that you want to retrieve the tagging information for the object.

### Request Example
```
GET /your-object-key?tagging HTTP/1.1
Host: your-bucket-name.oss.aliyuncs.com
Date: Tue, 28 May 2024 10:00:00 GMT
Authorization: OSS <AccessKeyId>:<Signature>
```

### Response
#### Success Response (200)
- **TagSet** (object) - Contains the set of tags associated with the object.
  - **Tag** (array) - An array of Tag objects, where each Tag object has 'Key' and 'Value' fields.
    - **Key** (string) - The tag key.
    - **Value** (string) - The tag value.

#### Response Example
```json
{
    "TagSet": {
        "Tag": [
            {
                "Key": "environment",
                "Value": "production"
            },
            {
                "Key": "owner",
                "Value": "devops"
            }
        ]
    }
}
```

#### Error Response
- **Error** (object) - Contains details about the error if the request fails.
  - **Code** (string) - The error code.
  - **Message** (string) - The error message.
  - **RequestId** (string) - The request ID for tracing the error.

#### Error Response Example
```json
{
    "Error": {
        "Code": "NoSuchKey",
        "Message": "The specified key does not exist.",
        "RequestId": "65F7C3A5A24F453F3381XXXX"
    }
}
```
```

--------------------------------

### List Buckets Configuration Methods - Rust

Source: https://docs.rs/aliyun-oss-rs/0.3.0/aliyun_oss_rs/client/struct.ListBuckets_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides Rust examples for configuring the `ListBuckets` request in aliyun-oss-rs. It illustrates using methods like `set_prefix`, `set_marker`, `set_max_keys`, `set_group_id`, and `set_endpoint` to customize the bucket listing query. These methods allow for fine-grained control over the results returned by the Alibaba Cloud OSS API.

```rust
pub fn set_prefix(self, prefix: impl Into<String>) -> Self
pub fn set_marker(self, marker: impl Into<String>) -> Self
pub fn set_max_keys(self, max_keys: u32) -> Self
pub fn set_group_id(self, group_id: impl Into<String>) -> Self
pub fn set_endpoint(self, endpoint: impl Into<String>) -> Self
```

--------------------------------

### Get Bucket Website Configuration

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/get_bucket_website.rs

Retrieves the static website configuration for a specified bucket. This endpoint allows you to get the current website settings of your OSS bucket.

```APIDOC
## GET /bucket/website

### Description
Retrieve the static website configuration of a bucket.

### Method
GET

### Endpoint
`/bucket/{bucket_name}/?website`

### Parameters
#### Query Parameters
- **website** (string) - Required - Used to specify that the request is for website configuration.

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **WebsiteConfiguration** (object) - Contains the website configuration details.
  - **IndexDocument** (string) - The index document for the website.
  - **ErrorDocument** (string) - The error document for the website.

#### Response Example
```json
{
  "example": "{\"IndexDocument\": \"index.html\", \"ErrorDocument\": \"error.html\"}"
}
```
```

--------------------------------

### GET /object/symlink

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/object/get_symlink.rs

Retrieves the symlink target of an object in Aliyun OSS. This operation allows you to find out where a symbolic link points to.

```APIDOC
## GET /object/symlink

### Description
Retrieves the symlink target of an object in Aliyun OSS. This operation allows you to find out where a symbolic link points to.

### Method
GET

### Endpoint
`/object/{object_key}?symlink`

### Parameters
#### Query Parameters
- **symlink** (string) - Required - This parameter is used to indicate that the request is to get the symlink target.

### Request Example
```json
{
  "example": "GET /your-bucket/your-object?symlink"
}
```

### Response
#### Success Response (200)
- **x-oss-symlink-target** (string) - The target path of the symbolic link.

#### Response Example
```json
{
  "example": "x-oss-symlink-target: path/to/target/object"
}
```
```

--------------------------------

### GET /bucket/acl

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/get_bucket_acl.rs

Retrieves the Access Control List (ACL) for a specified bucket. This allows you to view the permissions associated with the bucket.

```APIDOC
## GET /bucket/acl

### Description
Retrieves the Access Control List (ACL) for a specified bucket. This allows you to view the permissions associated with the bucket.

### Method
GET

### Endpoint
`/bucket/{bucket_name}/acl`

### Parameters
#### Query Parameters
- **acl** (string) - Required - Used to specify the retrieval of the bucket ACL.

### Request Example
```json
{
  "example": "GET /my-bucket/acl?acl HTTP/1.1\nHost: oss.aliyuncs.com\nDate: Tue, 20 Dec 2022 07:08:00 GMT\nAuthorization: OSS <AccessKeyId>:<Signature>"
}
```

### Response
#### Success Response (200)
- **owner** (object) - Information about the bucket owner.
  - **id** (string) - The ID of the owner.
  - **display_name** (string) - The display name of the owner.
- **access_control_list** (object) - The list of access control grants.
  - **grant** (string) - The ACL grant, e.g., 'private', 'public-read', 'public-read-write'.

#### Response Example
```json
{
  "example": "{\n  \"owner\": {\n    \"id\": \"12345678901234567890\",\n    \"display_name\": \"example-owner\"\n  },\n  \"access_control_list\": {\n    \"grant\": \"private\"\n  }\n}"
}
```
```

--------------------------------

### Configure Bucket Website Hosting (Rust)

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/put_bucket_website.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Configures static website hosting for an Alibaba Cloud OSS bucket. It allows setting the index document suffix and the error document key. The configuration is sent as an XML payload. Dependencies include `crate::{Error, error::normal_error, request::{Oss, OssRequest}}`, `bytes::Bytes`, `http::Method`, and `http_body_util::Full`. It returns a `Result<(), Error>`.

```rust
use crate::{
    Error,
    error::normal_error,
    request::{Oss, OssRequest},
};
use bytes::Bytes;
use http::Method;
use http_body_util::Full;

use super::{ErrorDocument, IndexDocument, WebsiteConfiguration};

/// Configure bucket static website hosting.
///
/// See the [Alibaba Cloud documentation](https://help.aliyun.com/zh/oss/developer-reference/putbucketwebsite) for details.
///
/// 配置 Bucket 静态网站托管。
///
/// 详情参见 [阿里云文档](https://help.aliyun.com/zh/oss/developer-reference/putbucketwebsite)。
pub struct PutBucketWebsite {
    req: OssRequest,
    config: WebsiteConfiguration,
}

impl PutBucketWebsite {
    pub(super) fn new(oss: Oss) -> Self {
        let mut req = OssRequest::new(oss, Method::PUT);
        req.insert_query("website", "");
        PutBucketWebsite { req, config: WebsiteConfiguration::default() }
    }

    /// Set the index document suffix (e.g., `index.html`).
    ///
    /// 设置索引文档后缀（如 `index.html`）。
    pub fn set_index_document(mut self, suffix: impl Into<String>) -> Self {
        self.config.index_document = Some(IndexDocument { suffix: suffix.into() });
        self
    }

    /// Set the error document key (e.g., `error.html`).
    ///
    /// 设置错误文档 Key（如 `error.html`）。
    pub fn set_error_document(mut self, key: impl Into<String>) -> Self {
        self.config.error_document = Some(ErrorDocument { key: key.into() });
        self
    }

    /// Replace the entire configuration object.
    ///
    /// 替换完整配置对象。
    pub fn set_configuration(mut self, config: WebsiteConfiguration) -> Self {
        self.config = config;
        self
    }

    /// Send the request.
    ///
    /// 发送请求。
    pub async fn send(mut self) -> Result<(), Error> {
        let body = serde_xml_rs::to_string(&self.config).map_err(|_| Error::InvalidCharacter)?;
        self.req.set_body(Full::new(Bytes::from(body)));
        let response = self.req.send_to_oss()?.await?;
        match response.status() {
            code if code.is_success() => Ok(()),
            _ => Err(normal_error(response).await),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_website_serialization() {
        let config = WebsiteConfiguration {
            index_document: Some(IndexDocument { suffix: "index.html".into() }),
            error_document: Some(ErrorDocument { key: "error.html".into() }),
            routing_rules: None,
        };
        let xml = serde_xml_rs::to_string(&config).unwrap();
        assert!(xml.contains("<WebsiteConfiguration>"));
        assert!(xml.contains("<Suffix>index.html</Suffix>"));
        assert!(xml.contains("<Key>error.html</Key>"));
    }
}
```

--------------------------------

### GET /bucket/acl

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/get_bucket_acl.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the Access Control List (ACL) for a specified bucket. This allows you to view who has what type of access to your bucket.

```APIDOC
## GET /bucket/acl

### Description
Retrieves the Access Control List (ACL) for a specified bucket. This allows you to view who has what type of access to your bucket.

### Method
GET

### Endpoint
`/bucket/acl`

### Parameters
#### Query Parameters
- **acl** (string) - Required - This parameter is used to specify that you want to retrieve the bucket's ACL.

### Request Example
```json
{
  "example": "GET /?acl HTTP/1.1\nHost: your-bucket-name.oss.aliyuncs.com\nDate: Tue, 28 May 2024 10:00:00 GMT\nAuthorization: OSS <AccessKeyId>:<Signature>"
}
```

### Response
#### Success Response (200)
- **owner** (object) - Information about the bucket owner.
  - **id** (string) - The ID of the bucket owner.
- **access_control_list** (object) - The list of access control grants for the bucket.
  - **grant** (string) - The ACL grant for the bucket (e.g., 'private', 'public-read', 'public-read-write').

#### Response Example
```json
{
  "example": "<?xml version="1.0" encoding="UTF-8"?>\n<AccessControlPolicy>\n  <Owner>\n    <ID>your-owner-id</ID>\n  </Owner>\n  <AccessControlList>\n    <Grant>private</Grant>\n  </AccessControlList>\n</AccessControlPolicy>"
}
```
```

--------------------------------

### Configure Static Website Hosting (Rust)

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/oss_bucket.rs

Configures static website hosting for an Aliyun OSS bucket. This allows serving website content directly from the bucket. Requires the `_async-base` feature.

```Rust
pub fn put_bucket_website(&self) -> PutBucketWebsite {
    PutBucketWebsite::new(self.oss.clone())
}
```

--------------------------------

### Get Bucket Tags

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/get_bucket_tags.rs

Retrieves the tags associated with an Aliyun OSS bucket. This endpoint allows you to fetch the key-value pairs that categorize your bucket.

```APIDOC
## GET /bucket/tags

### Description
Retrieves the tags associated with an Aliyun OSS bucket. This endpoint allows you to fetch the key-value pairs that categorize your bucket.

### Method
GET

### Endpoint
`/bucket/{bucket_name}/?tagging`

### Parameters
#### Query Parameters
- **tagging** (string) - Required - Used to specify the retrieval of bucket tags.

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **BucketTagging** (object) - Contains the tags associated with the bucket.
  - **TagSet** (object) - A collection of tags.
    - **Tag** (array) - An array of individual tags.
      - **Key** (string) - The key of the tag.
      - **Value** (string) - The value of the tag.

#### Response Example
```json
{
  "example": "{\n  \"TagSet\": {\n    \"Tag\": [\n      {\n        \"Key\": \"environment\",\n        \"Value\": \"production\"\n      },\n      {\n        \"Key\": \"project\",\n        \"Value\": \"data-analytics\"\n      }\n    ]\n  }\n}"
}
```
```

--------------------------------

### Build Pre-signed Object URL with AliCloud OSS

Source: https://docs.rs/aliyun-oss-rs/0.3.0/aliyun_oss_rs/object/struct.GetObjectUrl_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to construct a pre-signed URL for an object in Alibaba Cloud OSS. This allows private objects to be downloaded directly via a signed URL. Refer to Alibaba Cloud documentation for more details.

```rust
impl GetObjectUrl {
    // ... other methods
    pub fn url(self, expires: OffsetDateTime) -> String {
        // Generate the signed URL with the given expiration time.
        // 使用给定的过期时间生成签名 URL。
    }
}
```

--------------------------------

### Rust: Set Byte Range for Object Retrieval

Source: https://docs.rs/aliyun-oss-rs/0.3.0/aliyun_oss_rs/object/struct.GetObject

Configures the byte range for an object retrieval operation using the `set_range` method on the `GetObject` struct. The `start` and `end` parameters define the byte range (inclusive start, exclusive end). Invalid values result in the entire object being downloaded. Byte indexing starts at 0.

```Rust
pub fn set_range(self, start: usize, end: Option<usize>) -> Self
```

--------------------------------

### OssClient Initialization and Configuration

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/client/oss_client.rs_search=

This section covers the creation of an OssClient instance and its various configuration options.

```APIDOC
## OssClient

### Description
Entry point for OSS, providing service-level APIs such as listing buckets and regions.

### Methods

#### `new(ak_id: impl Into<String>, ak_secret: impl Into<String>, region: impl Into<String>) -> Self`
Create a new client with AccessKey credentials and region.

- `ak_id`: The AccessKey ID.
- `ak_secret`: The AccessKey Secret.
- `region`: Required for Signature V4 (e.g., `cn-hangzhou`).

#### `disable_https(self) -> Self`
Disable HTTPS and use HTTP for all requests.

#### `with_security_token(self, token: impl Into<String>) -> Self`
Attach a temporary security token for STS authentication.

- `token`: The temporary security token.

#### `set_endpoint(&mut self, endpoint: impl Into<String>)`
Override the endpoint used for subsequent requests.

- `endpoint`: The custom endpoint string.

#### `set_security_token(&mut self, token: impl Into<String>)`
Update the security token in place for reuse.

- `token`: The security token to update.

#### `bucket(&self, bucket: impl Into<String>) -> OssBucket`
Bind a bucket name and create a bucket handle.

- `bucket`: The name of the bucket.

### Request Example (new)
```rust
let client = OssClient::new("your_ak_id", "your_ak_secret", "cn-hangzhou");
```

### Request Example (disable_https)
```rust
let client = OssClient::new("your_ak_id", "your_ak_secret", "cn-hangzhou").disable_https();
```

### Request Example (with_security_token)
```rust
let client = OssClient::new("your_ak_id", "your_ak_secret", "cn-hangzhou").with_security_token("your_security_token");
```

### Request Example (set_endpoint)
```rust
let mut client = OssClient::new("your_ak_id", "your_ak_secret", "cn-hangzhou");
client.set_endpoint("oss-cn-hangzhou.aliyuncs.com");
```

### Request Example (set_security_token)
```rust
let mut client = OssClient::new("your_ak_id", "your_ak_secret", "cn-hangzhou");
client.set_security_token("your_security_token");
```

### Request Example (bucket)
```rust
let client = OssClient::new("your_ak_id", "your_ak_secret", "cn-hangzhou");
let bucket_handle = client.bucket("your_bucket_name");
```
```

--------------------------------

### GET /bucket/transferAcceleration

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/get_bucket_transfer_acceleration.rs

Retrieves the transfer acceleration configuration for a specified Aliyun OSS bucket. This allows you to check if transfer acceleration is enabled and its current status.

```APIDOC
## GET /bucket/transferAcceleration

### Description
Retrieves the transfer acceleration configuration of a bucket. This endpoint allows you to check if transfer acceleration is enabled for your bucket and view its current settings.

### Method
GET

### Endpoint
`/bucket/{bucketName}?transferAcceleration`

### Parameters
#### Query Parameters
- **transferAcceleration** (string) - Required - This parameter must be set to an empty string to indicate the request is for transfer acceleration configuration.

### Request Example
```
GET /my-bucket?transferAcceleration HTTP/1.1
Host: aliyun-oss.com
Date: Tue, 28 May 2024 10:00:00 GMT
Authorization: OSS <AccessKeyId>:<Signature>
```

### Response
#### Success Response (200)
- **TransferAccelerationConfiguration** (object) - Contains the transfer acceleration configuration details.
  - **Status** (string) - The status of transfer acceleration (e.g., 'Enabled', 'Disabled').

#### Response Example
```json
{
  "Status": "Enabled"
}
```
```

--------------------------------

### Get Bucket Logging Configuration

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/get_bucket_logging.rs

Retrieves the logging configuration for a specified OSS bucket. This allows you to check if bucket logging is enabled and where the logs are being stored.

```APIDOC
## GET /bucket/get_bucket_logging

### Description
Retrieves the bucket logging configuration. This endpoint allows you to check if bucket logging is enabled and where the logs are being stored.

### Method
GET

### Endpoint
`/bucket/get_bucket_logging?logging=`

### Query Parameters
- **logging** (string) - Required - This parameter is used to specify the retrieval of bucket logging status.

### Request Body
None

### Response
#### Success Response (200)
- **LoggingEnabled** (object) - Contains the logging configuration if enabled.
  - **target_bucket** (string) - The target bucket storing logs.
  - **target_prefix** (string) - The log object key prefix.

#### Response Example
```json
{
  "LoggingEnabled": {
    "target_bucket": "my-log-bucket",
    "target_prefix": "logs/"
  }
}
```

#### Error Response
- **Error** (object) - Contains details about the error.
  - **Code** (string) - The error code.
  - **Message** (string) - The error message.
  - **RequestId** (string) - The request ID.
```

--------------------------------

### Working with a Bucket: Upload File (Async)

Source: https://docs.rs/aliyun-oss-rs/0.3.0/aliyun_oss_rs/index

Demonstrates uploading a file to an OSS bucket using an asynchronous operation. This involves creating an OssClient, selecting a bucket and object, and then sending the file content. Handles potential errors.

```rust
use aliyun_oss_rs::OssClient;

#[tokio::main] async fn main() -> Result<(), aliyun_oss_rs::Error> {
    let client = OssClient::new("<AccessKeyId>", "<AccessKeySecret>", "cn-zhangjiakou");
    let bucket = client.bucket("example-bucket");
    let object = bucket.object("rust.png");

    object.put_object().send_file("/path/to/file.png").await?;
    Ok(())
}
```

--------------------------------

### GET /object/{object_key}

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/object/get_object.rs

Retrieves the content of an object from Aliyun OSS. Supports conditional retrieval based on modification time, ETag, and byte range.

```APIDOC
## GET /object/{object_key}

### Description
Retrieves the object's content. Supports conditional retrieval based on modification time, ETag, and byte range.

### Method
GET

### Endpoint
/object/{object_key}

### Parameters
#### Query Parameters
- **object_key** (string) - Required - The key of the object to retrieve.

#### Header Parameters
- **Range** (string) - Optional - Sets the response byte range (e.g., `bytes=0-499`).
- **If-Modified-Since** (string) - Optional - Succeeds if the object was modified after the given time (RFC 1123 format).
- **If-Unmodified-Since** (string) - Optional - Succeeds if the object was not modified since the given time (RFC 1123 format).
- **If-Match** (string) - Optional - Succeeds if the provided ETag matches the object's ETag.
- **If-None-Match** (string) - Optional - Succeeds if the provided ETag does not match the object's ETag.

### Request Example
```rust
use aliyun_oss_rs::object::GetObject;

// Assuming 'oss' is an initialized Oss client
let get_object_request = GetObject::new(oss)
    .set_range(0, Some(1023)); // Example: Get the first 1024 bytes

// To download to a file:
// let result = get_object_request.download_to_file("path/to/save/object.txt").await;

// To get as bytes:
// let result = get_object_request.get_object_as_bytes().await;
```

### Response
#### Success Response (200 OK)
- **body** (stream) - The object's content as a stream of bytes.
- **headers** (object) - Response headers, including Content-Type, Content-Length, ETag, Last-Modified, etc.

#### Response Example (Success)
```json
{
  "status": 200,
  "headers": {
    "Content-Type": "application/octet-stream",
    "Content-Length": "1024",
    "ETag": "\"a1b2c3d4e5f67890\"",
    "Last-Modified": "Tue, 15 Nov 1994 12:45:26 GMT"
  },
  "body": "...stream of object data..."
}
```

#### Error Response (e.g., 404 Not Found)
- **code** (string) - Error code.
- **message** (string) - Error message.

#### Response Example (Error)
```json
{
  "status": 404,
  "body": {
    "code": "NoSuchKey",
    "message": "The specified key does not exist."
  }
}
```
```

--------------------------------

### Configure Bucket Static Website Hosting

Source: https://docs.rs/aliyun-oss-rs/0.3.0/aliyun_oss_rs/bucket/struct.PutBucketWebsite_search=u32+-%3E+bool

This endpoint allows you to configure static website hosting for an Alibaba Cloud OSS bucket. You can set the index document, error document, and replace the entire configuration.

```APIDOC
## PUT /websites/{bucketName}

### Description
Configure bucket static website hosting.

### Method
PUT

### Endpoint
`/websites/{bucketName}`

### Parameters
#### Query Parameters
- **index-document** (string) - Optional - Set the index document suffix (e.g., `index.html`).
- **error-document** (string) - Optional - Set the error document key (e.g., `error.html`).

#### Request Body
- **WebsiteConfiguration** (object) - Optional - Replace the entire configuration object. If not provided, index and error documents can be set via query parameters.
  - **IndexDocument** (object) - Required if WebsiteConfiguration is provided - Specifies the index document.
    - **Suffix** (string) - Required - The suffix of the index document.
  - **ErrorDocument** (object) - Optional - Specifies the error document.
    - **Key** (string) - Required - The key of the error document.

### Request Example
```json
{
  "IndexDocument": {
    "Suffix": "index.html"
  },
  "ErrorDocument": {
    "Key": "error.html"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the website configuration was updated.

#### Response Example
```json
{
  "message": "Website configuration updated successfully."
}
```
```

--------------------------------

### Initialize OssClient and List Buckets (Rust)

Source: https://docs.rs/aliyun-oss-rs/0.3.0/aliyun_oss_rs/client/struct.ListBuckets_search=

Shows the basic usage of the OssClient to list all buckets. The client is initialized with credentials and a region, and the list_buckets method is called to retrieve the bucket information.

```Rust
let client = OssClient::new("AccessKey ID", "AccessKey Secret", "cn-beijing");
let buckets = client.list_buckets().send().await;
println!("{:#?}", buckets);
```

--------------------------------

### GET /bucket/worm

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/get_bucket_worm.rs_search=u32+-%3E+bool

Retrieves the WORM configuration of a specified bucket. This operation allows you to check the WORM settings applied to a bucket, which are crucial for data immutability compliance.

```APIDOC
## GET /bucket/worm

### Description
Retrieve the WORM configuration of a bucket. This is useful for understanding the data immutability policies applied to your OSS bucket.

### Method
GET

### Endpoint
`/bucket?worm`

### Parameters
#### Query Parameters
- **worm** (string) - Required - An empty string to indicate the WORM configuration retrieval.

### Request Example
```
GET /your-bucket-name?worm HTTP/1.1
Host: your-oss-endpoint.aliyuncs.com
Date: Tue, 28 May 2024 07:00:00 GMT
Authorization: OSS yourAccessKeyId:signature
```

### Response
#### Success Response (200)
- **BucketWormConfiguration** (object) - Contains the WORM configuration details.
  - **DefaultRetention** (object) - Default retention settings.
    - **Days** (integer) - The number of days for the default retention period.
    - **Date** (string) - The date until which the default retention applies (ISO 8601 format).
  - **AllowAppendage** (boolean) - Indicates if appending objects is allowed.

#### Response Example
```json
{
  "DefaultRetention": {
    "Days": 30,
    "Date": "2024-06-27T00:00:00Z"
  },
  "AllowAppendage": false
}
```
```

--------------------------------

### Get Bucket Policy

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/get_bucket_policy.rs

Retrieves the bucket policy document for a specified Aliyun OSS bucket. This operation allows you to view the access control policy associated with your bucket.

```APIDOC
## GET /bucket/policy

### Description
Retrieve the bucket policy document. This endpoint fetches the access control policy configured for an Aliyun OSS bucket.

### Method
GET

### Endpoint
`/bucket/policy`

### Parameters
#### Query Parameters
- **policy** (string) - Required - This parameter is used to specify that the request is for the bucket policy.

### Request Example
```
GET /example-bucket?policy HTTP/1.1
Host: oss-cn-hangzhou.aliyuncs.com
Date: Tue, 28 May 2024 09:00:00 GMT
Authorization: OSS <AccessKeyId>:<Signature>
```

### Response
#### Success Response (200)
- **policy** (string) - The bucket policy document in JSON format.

#### Response Example
```json
{
  "Version": "1",
  "Statement": [
    {
      "Action": "oss:GetObject",
      "Effect": "Allow",
      "Principal": {
        "RAM": "acs:ram::1234567890123456:root"
      },
      "Resource": "acs:oss:*:*:example-bucket/*"
    }
  ]
}
```
```

--------------------------------

### Synchronous Bucket Creation/Configuration (Rust)

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/mod.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Synchronous methods for creating and configuring Aliyun OSS buckets. These operations are part of the '_sync-base' feature. They allow for setting various bucket properties like tags, versioning, and website configuration.

```Rust
put_bucket_sync::PutBucketSync,
put_bucket_tags_sync::PutBucketTagsSync,
put_bucket_transfer_acceleration_sync::PutBucketTransferAccelerationSync,
put_bucket_versioning_sync::PutBucketVersioningSync,
put_bucket_website_sync::PutBucketWebsiteSync;
```

--------------------------------

### Get Bucket Inventory

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/get_bucket_inventory.rs

Retrieves a specific inventory task configuration for an Alibaba Cloud OSS bucket. This allows you to get details about a previously configured inventory task.

```APIDOC
## GET /bucket/inventory

### Description
Retrieves a specific inventory task configuration for an Alibaba Cloud OSS bucket. This allows you to get details about a previously configured inventory task.

### Method
GET

### Endpoint
`/bucket?inventory=&inventoryId={inventory_id}`

### Parameters
#### Query Parameters
- **inventory** (string) - Required - Used to specify the inventory operation. Should be an empty string for this endpoint.
- **inventoryId** (string) - Required - The ID of the inventory task configuration to retrieve.

### Request Example
```json
{
  "inventory_id": "your_inventory_id"
}
```

### Response
#### Success Response (200)
- **inventory_xml** (string) - The XML content representing the inventory task configuration.

#### Response Example
```xml
<InventoryConfiguration>
  <Id>your_inventory_id</Id>
  <IsEnabled>true</IsEnabled>
  <Destination>
    <OssBucketDestination>
      <Bucket>your_bucket_name</Bucket>
      <Prefix>inventory/</Prefix>
      <StorageClass>StandardStorage</StorageClass>
    </OssBucketDestination>
  </Destination>
  <Schedule>
    <Frequency>Daily</Frequency>
  </Schedule>
  <IncludedObjectVersions>All</IncludedObjectVersions>
  <OptionalFields>
    <Field>Size</Field>
    <Field>LastModifiedDate</Field>
  </OptionalFields>
</InventoryConfiguration>
```
```

--------------------------------

### Configure Aliyun OSS Bucket Static Website (Rust)

Source: https://docs.rs/aliyun-oss-rs/0.3.0/src/aliyun_oss_rs/bucket/oss_bucket.rs_search=std%3A%3Avec

This function configures the static website hosting for an Aliyun OSS bucket. It requires the `_async-base` feature. The function returns a `PutBucketWebsite` object, used to set up website routing and error documents.

```rust
/// Configure static website behavior.
///
/// 配置静态网站规则。
#[cfg(feature = "_async-base")]
pub fn put_bucket_website(&self) -> PutBucketWebsite {
    PutBucketWebsite::new(self.oss.clone())
}
```

--------------------------------

### Configure ListObjects Request in Rust

Source: https://docs.rs/aliyun-oss-rs/0.3.0/aliyun_oss_rs/bucket/struct.ListObjects_search=std%3A%3Avec

Demonstrates how to configure a `ListObjects` request in Rust using the `aliyun-oss-rs` crate. It shows methods for setting a delimiter, specifying a starting point for pagination, providing a continuation token, setting a prefix for filtering, and defining the maximum number of keys to return. The `fetch_owner` method can also be used to include owner information.

```rust
pub fn set_delimiter(self, delimiter: impl Into<String>) -> Self
pub fn set_start_after(self, start_after: impl Into<String>) -> Self
pub fn set_continuation_token( self, continuation_token: impl Into<String>, ) -> Self
pub fn set_prefix(self, prefix: impl Into<String>) -> Self
pub fn set_max_keys(self, max_keys: u32) -> Self
pub fn fetch_owner(self) -> Self
```
Tokens:
Raw