COS Rust SDK

https://docs.rs/cos-rust-sdk/0.1.2
Admin
A Rust SDK for Tencent Cloud Object Storage (COS) that provides complete API functionality for...
Tokens:80,255
Snippets:442
Trust Score:9.7
Update:9 months ago
Show doc for...
Tokens:
Raw
### Quick Start: Initialize and Use COS Rust SDK

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/index_search=

Demonstrates how to initialize the COS Rust SDK, configure it with credentials and endpoint, and perform basic object operations like uploading and downloading. It requires the `cos_rust_sdk` crate and `tokio` for asynchronous operations.

```rust
use cos_rust_sdk::{Config, CosClient, ObjectClient};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create configuration
    let config = Config::new(
        "your-secret-id",
        "your-secret-key",
        "ap-beijing",
        "your-bucket-name-appid"
    ).with_timeout(Duration::from_secs(30));

    // Create client
    let cos_client = CosClient::new(config)?;
    let object_client = ObjectClient::new(cos_client.clone());

    // Upload file
    let data = b"Hello, COS!";
    object_client.put_object("test.txt", data.to_vec(), Some("text/plain")).await?;

    // Download file
    let response = object_client.get_object("test.txt").await?;
    println!("Downloaded: {}", String::from_utf8_lossy(&response.data));

    Ok(())
}
```

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

### CosClient Initialization and Request Methods in Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/client.rs_search=std%3A%3Avec

Demonstrates how to create a `CosClient` instance with configuration and defines methods for various HTTP request types (GET, PUT, POST, DELETE, HEAD). These methods abstract the common request logic.

```rust
use crate::auth::Auth;
use crate::config::Config;
use crate::error::{CosError, Result};
use chrono::{Duration, Utc};
use reqwest::{Client, Method, Response};
use serde_json::Value;
use std::collections::HashMap;

/// COS HTTP 客户端
#[derive(Debug, Clone)]
pub struct CosClient {
    config: Config,
    auth: Auth,
    http_client: Client,
}

impl CosClient {
    /// 创建新的 COS 客户端
    pub fn new(config: Config) -> Result<Self> {
        config.validate()?;
        
        let auth = Auth::new(&config.secret_id, &config.secret_key);
        let http_client = Client::builder()
            .timeout(config.timeout)
            .build()
            .map_err(|e| CosError::other(format!("Failed to create HTTP client: {}", e)))?;

        Ok(Self {
            config,
            auth,
            http_client,
        })
    }

    /// 发送 GET 请求
    pub async fn get(&self, path: &str, params: HashMap<String, String>) -> Result<Response> {
        self.request(Method::GET, path, params, None::<&[u8]>).await
    }

    /// 发送 PUT 请求
    pub async fn put<T>(&self, path: &str, params: HashMap<String, String>, body: Option<T>) -> Result<Response>
    where
        T: Into<reqwest::Body>,
    {
        self.request(Method::PUT, path, params, body).await
    }

    /// 发送 POST 请求
    pub async fn post<T>(&self, path: &str, params: HashMap<String, String>, body: Option<T>) -> Result<Response>
    where
        T: Into<reqwest::Body>,
    {
        self.request(Method::POST, path, params, body).await
    }

    /// 发送 DELETE 请求
    pub async fn delete(&self, path: &str, params: HashMap<String, String>) -> Result<Response> {
        self.request(Method::DELETE, path, params, None::<&[u8]>).await
    }

    /// 发送 HEAD 请求
    pub async fn head(&self, path: &str, params: HashMap<String, String>) -> Result<Response> {
        self.request(Method::HEAD, path, params, None::<&[u8]>).await
    }

    /// 通用请求方法
    async fn request<T>(
        &self,
        method: Method,
        path: &str,
        params: HashMap<String, String>,
        body: Option<T>,
    ) -> Result<Response>
    where
        T: Into<reqwest::Body>,
    {
        let url = self.build_url(path, &params)?;
        let mut headers = self.build_headers(&method, path, &params)?;
        
        // 构建请求
        let mut request_builder = self.http_client.request(method.clone(), &url);
        
        // 添加请求头
        for (key, value) in headers.iter() {
            request_builder = request_builder.header(key, value);
        }
        
        // 添加请求体
        if let Some(body) = body {
            request_builder = request_builder.body(body);
        }
        
        // 发送请求
        let response = request_builder
            .send()
            .await
            .map_err(|e| CosError::other(format!("Request failed: {}", e)))?;
        
        // 检查响应状态
        if !response.status().is_success() {
            let status = response.status();
            let error_text = response
                .text()
                .await
                .unwrap_or_else(|_| "Unknown error".to_string());
            
            return Err(CosError::server(
                status.to_string(),
                error_text
            ));
        }
        
        Ok(response)
    }

    /// 构建完整的 URL
    fn build_url(&self, path: &str, params: &HashMap<String, String>) -> Result<String> {
        let base_url = if path.starts_with('/') {
            self.config.bucket_url()? 
        } else {
            self.config.service_url()
        };
        
        let mut url = format!("{}{}", base_url, path);
        
        if !params.is_empty() {
            let query_string = params
                .iter()
                .map(|(k, v)| format!("{}={}", k, urlencoding::encode(v)))
                .collect::<Vec<_>>()
                .join("&");
            url.push('?');
            url.push_str(&query_string);
        }
        
        Ok(url)
    }

    /// 构建请求头
    fn build_headers(
        &self,
        method: &Method,
        path: &str,
        params: &HashMap<String, String>,
    ) -> Result<HashMap<String, String>> {
        let mut headers = HashMap::new();
        
        // 基础请求头
        headers.insert("User-Agent".to_string(), crate::USER_AGENT.to_string());
        headers.insert("Host".to_string(), self.get_host(path)?);
        
        // 时间相关
        let now = Utc::now();
        let start_time = now - Duration::minutes(5); // 提前5分钟
        let end_time = now + Duration::hours(1);     // 1小时后过期
        
        // Placeholder for actual header building logic like signature generation
        // This part is not fully implemented in the provided snippet.

        Ok(headers)
    }

    // Helper method to get the host, likely derived from config or path
    fn get_host(&self, path: &str) -> Result<String> {
        // Placeholder for host retrieval logic
        // This would typically involve parsing the bucket URL or using a default.
        // For now, returning a dummy value or extracting from config.
        Ok(self.config.cos_domain.clone().unwrap_or_else(|| "cos.ap-guangzhou.myqcloud.com".to_string()))
    }
}
```

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

### Quick Start: Upload and Download Object with COS Rust SDK

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/index

Demonstrates how to use the cos-rust-sdk to initialize a client, upload a file, and download it from Tencent Cloud COS. It requires configuration with secret ID, secret key, region, and bucket name. The output is the content of the downloaded file.

```rust
use cos_rust_sdk::{Config, CosClient, ObjectClient};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建配置
    let config = Config::new(
        "your-secret-id",
        "your-secret-key",
        "ap-beijing",
        "your-bucket-name-appid"
    ).with_timeout(Duration::from_secs(30));

    // 创建客户端
    let cos_client = CosClient::new(config)?;
    let object_client = ObjectClient::new(cos_client.clone());

    // 上传文件
    let data = b"Hello, COS!";
    object_client.put_object("test.txt", data.to_vec(), Some("text/plain")).await?;

    // 下载文件
    let response = object_client.get_object("test.txt").await?;
    println!("Downloaded: {}", String::from_utf8_lossy(&response.data));

    Ok(())
}
```

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

### CosClient Initialization and HTTP Request Methods in Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/client.rs_search=

Defines the CosClient for interacting with Tencent Cloud COS. It includes methods for creating a new client, and sending various HTTP requests (GET, PUT, POST, DELETE, HEAD). These methods abstract the underlying request building and sending logic.

```rust
use crate::auth::Auth;
use crate::config::Config;
use crate::error::{CosError, Result};
use chrono::{Duration, Utc};
use reqwest::{Client, Method, Response};
use serde_json::Value;
use std::collections::HashMap;

/// COS HTTP 客户端
#[derive(Debug, Clone)]
pub struct CosClient {
    config: Config,
    auth: Auth,
    http_client: Client,
}

impl CosClient {
    /// 创建新的 COS 客户端
    pub fn new(config: Config) -> Result<Self> {
        config.validate()?;
        
        let auth = Auth::new(&config.secret_id, &config.secret_key);
        let http_client = Client::builder()
            .timeout(config.timeout)
            .build()
            .map_err(|e| CosError::other(format!("Failed to create HTTP client: {}", e)))?;

        Ok(Self {
            config,
            auth,
            http_client,
        })
    }

    /// 发送 GET 请求
    pub async fn get(&self, path: &str, params: HashMap<String, String>) -> Result<Response> {
        self.request(Method::GET, path, params, None::<&[u8]>).await
    }

    /// 发送 PUT 请求
    pub async fn put<T>(&self, path: &str, params: HashMap<String, String>, body: Option<T>) -> Result<Response>
    where
        T: Into<reqwest::Body>,
    {
        self.request(Method::PUT, path, params, body).await
    }

    /// 发送 POST 请求
    pub async fn post<T>(&self, path: &str, params: HashMap<String, String>, body: Option<T>) -> Result<Response>
    where
        T: Into<reqwest::Body>,
    {
        self.request(Method::POST, path, params, body).await
    }

    /// 发送 DELETE 请求
    pub async fn delete(&self, path: &str, params: HashMap<String, String>) -> Result<Response> {
        self.request(Method::DELETE, path, params, None::<&[u8]>).await
    }

    /// 发送 HEAD 请求
    pub async fn head(&self, path: &str, params: HashMap<String, String>) -> Result<Response> {
        self.request(Method::HEAD, path, params, None::<&[u8]>).await
    }

    /// 通用请求方法
    async fn request<T>(
        &self,
        method: Method,
        path: &str,
        params: HashMap<String, String>,
        body: Option<T>,
    ) -> Result<Response>
    where
        T: Into<reqwest::Body>,
    {
        let url = self.build_url(path, &params)?;
        let mut headers = self.build_headers(&method, path, &params)?;
        
        // 构建请求
        let mut request_builder = self.http_client.request(method.clone(), &url);
        
        // 添加请求头
        for (key, value) in headers.iter() {
            request_builder = request_builder.header(key, value);
        }
        
        // 添加请求体
        if let Some(body) = body {
            request_builder = request_builder.body(body);
        }
        
        // 发送请求
        let response = request_builder
            .send()
            .await
            .map_err(|e| CosError::other(format!("Request failed: {}", e)))?;
        
        // 检查响应状态
        if !response.status().is_success() {
            let status = response.status();
            let error_text = response
                .text()
                .await
                .unwrap_or_else(|_| "Unknown error".to_string());
            
            return Err(CosError::server(
                status.to_string(),
                error_text
            ));
        }
        
        Ok(response)
    }

    /// 构建完整的 URL
    fn build_url(&self, path: &str, params: &HashMap<String, String>) -> Result<String> {
        let base_url = if path.starts_with('/') {
            self.config.bucket_url()? 
        } else {
            self.config.service_url()
        };
        
        let mut url = format!("{}{}", base_url, path);
        
        if !params.is_empty() {
            let query_string = params
                .iter()
                .map(|(k, v)| format!("{}={}", k, urlencoding::encode(v)))
                .collect::<Vec<_>>()
                .join("&");
            url.push('?');
            url.push_str(&query_string);
        }
        
        Ok(url)
    }

    /// 构建请求头
    fn build_headers(
        &self,
        method: &Method,
        path: &str,
        params: &HashMap<String, String>,
    ) -> Result<HashMap<String, String>> {
        let mut headers = HashMap::new();
        
        // 基础请求头
        headers.insert("User-Agent".to_string(), crate::USER_AGENT.to_string());
        headers.insert("Host".to_string(), self.get_host(path)?);
        
        // 时间相关
        let now = Utc::now();
        let start_time = now - Duration::minutes(5); // 提前5分钟
        let end_time = now + Duration::hours(1);     // 1小时后过期
        
        // ... (rest of the header building logic would follow)
```

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

### GET /<key> to file

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/object.rs_search=

Downloads an object from the storage and saves it to a specified file path on the local system.

```APIDOC
## GET /<key> to file

### Description
Downloads an object from the storage and saves it to a specified file path on the local system.

### Method
GET

### Endpoint
`/<key>`

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique identifier for the object.
- **file_path** (string) - Required - The local file path where the object will be saved.

### Request Example
```json
{
  "example": "Not applicable for GET request body"
}
```

### Response
#### Success Response (200)
- **(empty)** - Indicates the file was successfully downloaded and saved.

#### Response Example
```json
{
  "example": "Success"
}
```
```

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

### ListObjectsV2Options

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/bucket/struct.ListObjectsV2Options

Options for the ListObjectsV2 API call. This struct allows you to specify parameters like prefix, delimiter, continuation token, max keys, and start after.

```APIDOC
## Struct ListObjectsV2Options

### Description
Options for the ListObjectsV2 API call. This struct allows you to specify parameters like prefix, delimiter, continuation token, max keys, and start after.

### Fields
- **prefix** (Option<String>) - The prefix to filter objects by.
- **delimiter** (Option<String>) - The delimiter to group objects by.
- **continuation_token** (Option<String>) - The token to retrieve the next page of results.
- **max_keys** (Option<u32>) - The maximum number of keys to return.
- **start_after** (Option<String>) - The key to start listing objects after.

### Methods
- **clone() -> ListObjectsV2Options**: Returns a duplicate of the value.
- **clone_from(&mut self, source: &Self)**: Performs copy-assignment from `source`.
- **fmt(&self, f: &mut Formatter<'_>) -> Result**: Formats the value using the given formatter.
- **default() -> ListObjectsV2Options**: Returns the “default value” for a type.

### Trait Implementations
- Clone
- Debug
- Default
```

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

### Create a New Policy in Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/sts/struct.Policy_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides a constructor function `new()` for creating an empty `Policy` object. This is the starting point for building a new access policy. No external dependencies for this specific function.

```rust
pub fn new() -> Self
```

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

### CosClient: Create and HTTP Requests (Rust)

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/client/struct.CosClient

Provides methods for creating a new CosClient instance and performing common HTTP operations like GET, PUT, POST, DELETE, and HEAD. It utilizes a Config object for initialization and supports optional request bodies for PUT and POST. Responses are handled as Result<Response>.

```Rust
pub struct CosClient { /* private fields */ }

impl CosClient {
    pub fn new(config: Config) -> Result<Self>;
    pub async fn get(&self, path: &str, params: HashMap<String, String>) -> Result<Response>;
    pub async fn put<T>(&self, path: &str, params: HashMap<String, String>, body: Option<T>) -> Result<Response> where T: Into<Body>;
    pub async fn post<T>(&self, path: &str, params: HashMap<String, String>, body: Option<T>) -> Result<Response> where T: Into<Body>;
    pub async fn delete(&self, path: &str, params: HashMap<String, String>) -> Result<Response>;
    pub async fn head(&self, path: &str, params: HashMap<String, String>) -> Result<Response>;
    pub fn config(&self) -> &Config;
}

```

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

### Get CosClient Configuration - Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/client/struct.CosClient_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns a reference to the configuration associated with the CosClient. This allows inspection of the client's settings without modifying them.

```rust
pub fn config(&self) -> &Config
```

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

### Get Hostname from URL in Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/client.rs_search=

Retrieves the hostname from a given URL path. It determines the appropriate base URL (bucket or service) based on whether the path starts with '/'. It parses the URL and extracts the host, defaulting to 'localhost' if not found.

```rust
fn get_host(&self, path: &str) -> Result<String> {
        let url = if path.starts_with('/') {
            self.config.bucket_url()? 
        } else {
            self.config.service_url()
        };
        
        let parsed_url = url::Url::parse(&url)
            .map_err(|e| CosError::other(format!("Invalid URL: {}", e)))?;
        
        Ok(parsed_url.host_str().unwrap_or("localhost").to_string())
    }
```

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

### Send GET Request with CosClient - Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/client/struct.CosClient_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Asynchronously sends an HTTP GET request using the CosClient. It takes a path, a HashMap of parameters, and returns a Result containing the Response or an error.

```rust
pub async fn get( &self, path: &str, params: HashMap<String, String>, ) -> Result<Response>
```

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

### CosClient Initialization

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/client/struct.CosClient_search=

Demonstrates how to create a new instance of the CosClient with the provided configuration.

```APIDOC
## CosClient::new

### Description
Creates a new COS client instance.

### Method
`new`

### Parameters
* `config` (Config) - Required - The configuration object for the client.

### Response
* `Result<CosClient>` - A Result containing the newly created CosClient or an error.
```

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

### Get Bucket Location using Rust SDK

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/bucket.rs_search=u32+-%3E+bool

Retrieves the location of the cloud storage bucket. This function sends a GET request with a 'location' parameter and parses the XML response to extract the location constraint.

```rust
/// 获取存储桶位置
pub async fn get_bucket_location(&self) -> Result<String> {
    let mut params = HashMap::new();
    params.insert("location".to_string(), "".to_string());
    
    let response = self.client.get("/", params).await?;
    let response_text = response
        .text()
        .await
        .map_err(|e| CosError::other(format!("Failed to read response: {}", e)))?;
    
    let location_response: LocationResponse = quick_xml::de::from_str(&response_text)
        .map_err(|e| CosError::other(format!("Failed to parse location response: {}", e)))?;
    
    Ok(location_response.location_constraint)
}
```

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

### ObjectClient Initialization

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/object/struct.ObjectClient

Creates a new ObjectClient instance for interacting with object storage.

```APIDOC
## POST /object_client

### Description
Creates a new ObjectClient instance. This client is used to perform operations on objects.

### Method
POST

### Endpoint
`/object_client`

### Parameters
#### Request Body
- **client** (CosClient) - Required - An authenticated CosClient instance to be used by the ObjectClient.

### Request Example
```json
{
  "client": { /* CosClient details */ }
}
```

### Response
#### Success Response (200)
- **ObjectClient** (ObjectClient) - A newly created ObjectClient instance.

#### Response Example
```json
{
  "message": "ObjectClient created successfully",
  "client": { /* ObjectClient details */ }
}
```
```

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

### Get Bucket Versioning Status - Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/bucket.rs_search=std%3A%3Avec

Retrieves the versioning status of a specified bucket. It sends a GET request with a 'versioning' parameter and parses the XML response into a VersioningResponse struct. Handles potential errors during the request and parsing.

```rust
/// 获取存储桶版本控制状态
    pub async fn get_bucket_versioning(&self) -> Result<VersioningResponse> {
        let mut params = HashMap::new();
        params.insert("versioning".to_string(), "".to_string());
        
        let response = self.client.get("/", params).await?;
        let response_text = response
            .text()
            .await
            .map_err(|e| CosError::other(format!("Failed to read response: {}", e)))?;
        
        let versioning_response: VersioningResponse = quick_xml::de::from_str(&response_text)
            .map_err(|e| CosError::other(format!("Failed to parse versioning response: {}", e)))?;
        
        Ok(versioning_response)
    }
```

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

### Get Bucket ACL - Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/bucket.rs_search=std%3A%3Avec

Retrieves the Access Control List (ACL) for a specified bucket. It sends a GET request with an 'acl' parameter and parses the XML response into a BucketAclResponse struct. Errors during network requests or XML parsing are handled.

```rust
/// 获取存储桶ACL
    pub async fn get_bucket_acl(&self) -> Result<BucketAclResponse> {
        let mut params = HashMap::new();
        params.insert("acl".to_string(), "".to_string());
        
        let response = self.client.get("/", params).await?;
        let response_text = response
            .text()
            .await
            .map_err(|e| CosError::other(format!("Failed to read response: {}", e)))?;
        
        let acl_response: BucketAclResponse = quick_xml::de::from_str(&response_text)
            .map_err(|e| CosError::other(format!("Failed to parse ACL response: {}", e)))?;
        
        Ok(acl_response)
    }
```

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

### BucketClient API

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/bucket/struct.BucketClient_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides methods for managing storage buckets, including creation, deletion, existence checks, location retrieval, object listing, and ACL management.

```APIDOC
## BucketClient

This client provides methods for interacting with storage buckets.

### Methods

#### `new(client: CosClient) -> Self`

**Description**: Creates a new `BucketClient` instance.

**Method**: `new`

**Parameters**:
*   `client` (CosClient) - The `CosClient` instance to use for underlying requests.

#### `create_bucket(acl: Option<BucketAcl>) -> Result<()>`

**Description**: Creates a new storage bucket.

**Method**: `create_bucket`

**Parameters**:
*   `acl` (Option<BucketAcl>) - Optional Access Control List settings for the new bucket.

**Returns**: `Result<()>` indicating success or failure.

#### `delete_bucket() -> Result<()>`

**Description**: Deletes the storage bucket.

**Method**: `delete_bucket`

**Returns**: `Result<()>` indicating success or failure.

#### `bucket_exists() -> Result<bool>`

**Description**: Checks if the storage bucket exists.

**Method**: `bucket_exists`

**Returns**: `Result<bool>` where `true` indicates the bucket exists, and `false` otherwise.

#### `get_bucket_location() -> Result<String>`

**Description**: Retrieves the location of the storage bucket.

**Method**: `get_bucket_location`

**Returns**: `Result<String>` containing the bucket's location.

#### `list_objects(options: Option<ListObjectsOptions>) -> Result<ListObjectsResponse>`

**Description**: Lists objects within the storage bucket.

**Method**: `list_objects`

**Parameters**:
*   `options` (Option<ListObjectsOptions>) - Optional parameters for listing objects.

**Returns**: `Result<ListObjectsResponse>` containing the list of objects.

#### `list_objects_v2(options: Option<ListObjectsV2Options>) -> Result<ListObjectsV2Response>`

**Description**: Lists objects within the storage bucket using V2 versioning.

**Method**: `list_objects_v2`

**Parameters**:
*   `options` (Option<ListObjectsV2Options>) - Optional parameters for listing objects (V2).

**Returns**: `Result<ListObjectsV2Response>` containing the list of objects.

#### `get_bucket_acl() -> Result<BucketAclResponse>`

**Description**: Retrieves the Access Control List (ACL) of the storage bucket.

**Method**: `get_bucket_acl`

**Returns**: `Result<BucketAclResponse>` containing the bucket's ACL.

#### `put_bucket_acl(acl: BucketAcl) -> Result<()>`

**Description**: Sets the Access Control List (ACL) for the storage bucket.

**Method**: `put_bucket_acl`

**Parameters**:
*   `acl` (BucketAcl) - The `BucketAcl` to set for the bucket.

**Returns**: `Result<()>` indicating success or failure.

#### `get_bucket_versioning() -> Result<VersioningResponse>`

**Description**: Retrieves the versioning status of the storage bucket.

**Method**: `get_bucket_versioning`

**Returns**: `Result<VersioningResponse>` containing the bucket's versioning status.

```

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

### Get Bucket Versioning Status in Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/bucket.rs_search=

Retrieves the versioning status of a bucket. This asynchronous function makes an HTTP GET request to the bucket endpoint with the 'versioning' parameter. The XML response is deserialized into a `VersioningResponse` struct. It requires the 'quick_xml' crate for parsing.

```Rust
pub async fn get_bucket_versioning(&self) -> Result<VersioningResponse> {
    let mut params = HashMap::new();
    params.insert("versioning".to_string(), "".to_string());
    
    let response = self.client.get("/", params).await?;
    let response_text = response
        .text()
        .await
        .map_err(|e| CosError::other(format!("Failed to read response: {}", e)))?;
    
    let versioning_response: VersioningResponse = quick_xml::de::from_str(&response_text)
        .map_err(|e| CosError::other(format!("Failed to parse versioning response: {}", e)))?;
    
    Ok(versioning_response)
}
```

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

### Initialize CosClient in Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/client.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new `CosClient` instance with the provided configuration. It validates the configuration and sets up the authentication and HTTP client components. Dependencies include `crate::auth::Auth`, `crate::config::Config`, `crate::error::{CosError, Result}`, and `reqwest::Client`.

```rust
pub fn new(config: Config) -> Result<Self> {
    config.validate()?;
    
    let auth = Auth::new(&config.secret_id, &config.secret_key);
    let http_client = Client::builder()
        .timeout(config.timeout)
        .build()
        .map_err(|e| CosError::other(format!("Failed to create HTTP client: {}", e)))?;

    Ok(Self {
        config,
        auth,
        http_client,
    })
}
```

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

### Get Bucket ACL in Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/bucket.rs_search=

Retrieves the Access Control List (ACL) for a specified bucket. This function makes an HTTP GET request to the bucket endpoint with the 'acl' parameter. It parses the XML response into a `BucketAclResponse` struct. Dependencies include the 'quick_xml' crate for XML deserialization.

```Rust
pub async fn get_bucket_acl(&self) -> Result<BucketAclResponse> {
    let mut params = HashMap::new();
    params.insert("acl".to_string(), "".to_string());
    
    let response = self.client.get("/", params).await?;
    let response_text = response
        .text()
        .await
        .map_err(|e| CosError::other(format!("Failed to read response: {}", e)))?;
    
    let acl_response: BucketAclResponse = quick_xml::de::from_str(&response_text)
        .map_err(|e| CosError::other(format!("Failed to parse ACL response: {}", e)))?;
    
    Ok(acl_response)
}
```

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

### Get Temporary Credentials using STS in Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/sts.rs_search=u32+-%3E+bool

Asynchronously retrieves temporary security credentials from the STS service. This function takes a `GetCredentialsRequest` which includes a policy, optional duration, and a session name. It utilizes Tencent Cloud's official STS SDK signature method via a GET request with URL parameters.

```rust
    /// 获取临时密钥
    /// 使用腾讯云官方STS SDK的签名方法
    pub async fn get_credentials(
        &self,
        request: GetCredentialsRequest,
    ) -> Result<TemporaryCredentials, CosError> {
        let policy_json = serde_json::to_string(&request.policy)
            .map_err(|e| CosError::other(format!("Policy serialization error: {}", e)))?;
        
        let duration_seconds = request.duration_seconds.unwrap_or(1800);
        let name = request.name.unwrap_or_else(|| "temp-user".to_string());
        
        // 使用腾讯云STS SDK的方式：GET请求 + URL参数
        let timestamp = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_secs();
        
        let nonce = timestamp; // 使用时间戳作为随机数
        
        // 构建请求参数 - 先创建所有字符串变量以确保生命周期
          let timestamp_str = timestamp.to_string();
          let nonce_str = nonce.to_string();
          // Policy参数需要URL编码，不是base64编码
          let encoded_policy = urlencoding::encode(&policy_json).to_string();
          let duration_str = duration_seconds.to_string();
         
          let mut params = HashMap::new();
           params.insert("Action", "GetFederationToken");
           params.insert("Version", "2018-08-13");
           params.insert("Region", &self.region);
           params.insert("SecretId", &self.secret_id);
           params.insert("Timestamp", &timestamp_str);
           params.insert("Nonce", &nonce_str);
           params.insert("Name", &name);
            params.insert("Policy", &encoded_policy);
            params.insert("DurationSeconds", &duration_str);
          
          // 生成签名
          let signature = self.generate_signature(&params)?;
          params.insert("Signature", &signature);
         
         // 构建URL
         let query_string = params.iter()
             .map(|(k, v)| {
                 let encoded_value = form_urlencoded::byte_serialize(v.as_bytes()).collect::<String>();

```

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

### BucketClient API

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/bucket/struct.BucketClient

This section details the methods available on the BucketClient for interacting with storage buckets.

```APIDOC
## BucketClient

### Description
Provides methods for managing storage buckets.

### Methods

#### `new(client: CosClient) -> Self`

*   **Description**: Creates a new BucketClient.
*   **Method**: `new`
*   **Parameters**: 
    *   `client` (CosClient) - The CosClient instance to use.

#### `create_bucket(acl: Option<BucketAcl>) -> Result<()>`

*   **Description**: Creates a new bucket.
*   **Method**: `create_bucket`
*   **Parameters**: 
    *   `acl` (Option<BucketAcl>) - Optional Access Control List settings for the bucket.
*   **Returns**: `Result<()>`

#### `delete_bucket() -> Result<()>`

*   **Description**: Deletes the bucket.
*   **Method**: `delete_bucket`
*   **Returns**: `Result<()>`

#### `bucket_exists() -> Result<bool>`

*   **Description**: Checks if the bucket exists.
*   **Method**: `bucket_exists`
*   **Returns**: `Result<bool>`

#### `get_bucket_location() -> Result<String>`

*   **Description**: Retrieves the location of the bucket.
*   **Method**: `get_bucket_location`
*   **Returns**: `Result<String>`

#### `list_objects(options: Option<ListObjectsOptions>) -> Result<ListObjectsResponse>`

*   **Description**: Lists objects within the bucket.
*   **Method**: `list_objects`
*   **Parameters**: 
    *   `options` (Option<ListObjectsOptions>) - Optional parameters for listing objects.
*   **Returns**: `Result<ListObjectsResponse>`

#### `list_objects_v2(options: Option<ListObjectsV2Options>) -> Result<ListObjectsV2Response>`

*   **Description**: Lists objects within the bucket using V2 versioning.
*   **Method**: `list_objects_v2`
*   **Parameters**: 
    *   `options` (Option<ListObjectsV2Options>) - Optional parameters for listing objects (V2).
*   **Returns**: `Result<ListObjectsV2Response>`

#### `get_bucket_acl() -> Result<BucketAclResponse>`

*   **Description**: Retrieves the Access Control List (ACL) of the bucket.
*   **Method**: `get_bucket_acl`
*   **Returns**: `Result<BucketAclResponse>`

#### `put_bucket_acl(acl: BucketAcl) -> Result<()>`

*   **Description**: Sets the Access Control List (ACL) for the bucket.
*   **Method**: `put_bucket_acl`
*   **Parameters**: 
    *   `acl` (BucketAcl) - The BucketAcl settings to apply.
*   **Returns**: `Result<()>`

#### `get_bucket_versioning() -> Result<VersioningResponse>`

*   **Description**: Retrieves the versioning status of the bucket.
*   **Method**: `get_bucket_versioning`
*   **Returns**: `Result<VersioningResponse>`
```

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

### Get Temporary Credentials using STS Client in Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/sts.rs_search=std%3A%3Avec

Obtains temporary security credentials by making a GET request to the STS API. This function takes a GetCredentialsRequest which includes a policy, optional duration, and an optional session name. It handles URL encoding of parameters and generates a signature using the provided secret key.

```rust
impl StsClient {
    /// 获取临时密钥
    /// 使用腾讯云官方STS SDK的签名方法
    pub async fn get_credentials(
        &self,
        request: GetCredentialsRequest,
    ) -> Result<TemporaryCredentials, CosError> {
        let policy_json = serde_json::to_string(&request.policy)
            .map_err(|e| CosError::other(format!("Policy serialization error: {}", e)))?;
        
        let duration_seconds = request.duration_seconds.unwrap_or(1800);
        let name = request.name.unwrap_or_else(|| "temp-user".to_string());
        
        // 使用腾讯云STS SDK的方式：GET请求 + URL参数
        let timestamp = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_secs();
        
        let nonce = timestamp; // 使用时间戳作为随机数
        
        // 构建请求参数 - 先创建所有字符串变量以确保生命周期
          let timestamp_str = timestamp.to_string();
          let nonce_str = nonce.to_string();
          // Policy参数需要URL编码，不是base64编码
          let encoded_policy = urlencoding::encode(&policy_json).to_string();
          let duration_str = duration_seconds.to_string();
         
         let mut params = HashMap::new();
          params.insert("Action", "GetFederationToken");
          params.insert("Version", "2018-08-13");
          params.insert("Region", &self.region);
          params.insert("SecretId", &self.secret_id);
          params.insert("Timestamp", &timestamp_str);
          params.insert("Nonce", &nonce_str);
          params.insert("Name", &name);
           params.insert("Policy", &encoded_policy);
           params.insert("DurationSeconds", &duration_str);
         
         // 生成签名
         let signature = self.generate_signature(&params)?;
         params.insert("Signature", &signature);
        
        // 构建URL
        let query_string = params.iter()
            .map(|(k, v)| {
                let encoded_value = form_urlencoded::byte_serialize(v.as_bytes()).collect::<String>();

```

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

### Test Build URL with Parameters in Rust

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/client.rs_search=std%3A%3Avec

Tests the `build_url` function for constructing URLs with query parameters. It creates a client, defines a HashMap of parameters, and calls `build_url`. Asserts that the generated URL contains the expected bucket domain and query parameters.

```rust
#[test]
    fn test_build_url() {
        let config = Config::new("test_id", "test_key", "ap-beijing", "test-bucket-123");
        let client = CosClient::new(config).unwrap();
        
        let mut params = HashMap::new();
        params.insert("key".to_string(), "value".to_string());
        
        let url = client.build_url("/test", &params).unwrap();
        assert!(url.contains("test-bucket-123.cos.ap-beijing.myqcloud.com"));
        assert!(url.contains("key=value"));
    }
```

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

### Bucket Management API

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/bucket/index_search=

This section details the APIs for managing buckets, including creation, deletion, and listing functionalities. It outlines the available structs and enums for interacting with bucket-related operations.

```APIDOC
## Module bucket

### Description
Provides bucket management functionalities such as creation, deletion, and listing.

### Structs

*   **AccessControlList**: Represents an access control list.
*   **BucketAclResponse**: Response structure for bucket ACL.
*   **BucketClient**: Client for performing bucket operations.
*   **CommonPrefix**: Represents a common prefix for object listing.
*   **Grant**: Information about an authorization grant.
*   **Grantee**: Details of the grantee.
*   **ListObjectsOptions**: Options for listing objects.
*   **ListObjectsResponse**: Response structure for listing objects.
*   **ListObjectsV2Options**: Options for listing objects using V2.
*   **ListObjectsV2Response**: Response structure for listing objects using V2.
*   **ObjectInfo**: Information about an object.
*   **Owner**: Information about the object owner.
*   **VersioningResponse**: Response structure for versioning status.

### Enums

*   **BucketAcl**: Represents the type of bucket ACL.
```

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

### Rust: Get Temporary Credentials using STS

Source: https://docs.rs/cos-rust-sdk/0.1.2/src/cos_rust_sdk/sts.rs

Fetches temporary security credentials by making a GET request to the STS API with specified parameters. It handles policy serialization, duration, and name, generating a signature based on the provided credentials and request details. It uses URL encoding for the policy parameter as per Tencent Cloud STS SDK documentation.

```rust
pub async fn get_credentials(
        &self,
        request: GetCredentialsRequest,
    ) -> Result<TemporaryCredentials, CosError> {
        let policy_json = serde_json::to_string(&request.policy)
            .map_err(|e| CosError::other(format!("Policy serialization error: {}", e)))?;
        
        let duration_seconds = request.duration_seconds.unwrap_or(1800);
        let name = request.name.unwrap_or_else(|| "temp-user".to_string());
        
        let timestamp = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_secs();
        
        let nonce = timestamp; 
        
        let timestamp_str = timestamp.to_string();
        let nonce_str = nonce.to_string();
        let encoded_policy = urlencoding::encode(&policy_json).to_string();
        let duration_str = duration_seconds.to_string();
       
        let mut params = HashMap::new();
        params.insert("Action", "GetFederationToken");
        params.insert("Version", "2018-08-13");
        params.insert("Region", &self.region);
        params.insert("SecretId", &self.secret_id);
        params.insert("Timestamp", &timestamp_str);
        params.insert("Nonce", &nonce_str);
        params.insert("Name", &name);
        params.insert("Policy", &encoded_policy);
        params.insert("DurationSeconds", &duration_str);
       
        let signature = self.generate_signature(&params)?;
        params.insert("Signature", &signature);
       
        let query_string = params.iter()
            .map(|(k, v)| {
                let encoded_value = form_urlencoded::byte_serialize(v.as_bytes()).collect::<String>();
                format!("{}", encoded_value)
            })
            .collect::<Vec<String>>()
            .join("&");
            
        let url = format!("https://sts.tencentcloudapi.com/?{}", query_string);

        let response = self.client.get(&url).send().await.map_err(|e| CosError::other(format!("STS request error: {}", e)))?;
        let response_body = response.text().await.map_err(|e| CosError::other(format!("STS response body error: {}", e)))?;

        let sts_response: StsResponse = serde_json::from_str(&response_body)
            .map_err(|e| CosError::other(format!("STS response parse error: {}, body: {}", e, response_body)))?;

        match sts_response.response.credentials {
            Some(credentials) => Ok(credentials),
            None => {
                let error_message = sts_response.response.error.map(|e| format!("{}: {}", e.code, e.message)).unwrap_or_else(|| "Unknown STS error".to_string());
                Err(CosError::other(format!("Failed to get STS credentials: {}", error_message)))
            }
        }
    }
```

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

### Get Credentials

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/sts/struct.StsClient_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves temporary credentials using the Tencent Cloud official STS SDK signing method.

```APIDOC
## POST /sts/get_credentials

### Description
Obtains temporary security credentials using Tencent Cloud's official STS SDK signing method.

### Method
POST

### Endpoint
/sts/get_credentials

### Parameters
#### Request Body
- **request** (Object) - Required - The request object for getting credentials. See GetCredentialsRequest structure.

### Request Example
```json
{
  "request": {
    "role_arn": "acs:iam::1234567890123456:role/your-role-name",
    "role_session_name": "your-session-name",
    "policy": "{\"Version\":\"1\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"cos:GetObject\"],\"Resource\":\"acs:cos:*:*:bucket-name/*\"}]}"
  }
}
```

### Response
#### Success Response (200)
- **TemporaryCredentials** (Object) - An object containing the temporary security credentials.

#### Response Example
```json
{
  "credentials": {
    "access_key_id": "YOUR_ACCESS_KEY_ID",
    "secret_access_key": "YOUR_SECRET_ACCESS_KEY",
    "session_token": "YOUR_SESSION_TOKEN",
    "expiration": "2023-10-27T10:00:00Z"
  }
}
```
```

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

### CosClient API

Source: https://docs.rs/cos-rust-sdk/0.1.2/cos_rust_sdk/client/struct.CosClient_search=u32+-%3E+bool

Provides methods for initializing the CosClient and performing various HTTP operations.

```APIDOC
## CosClient

COS HTTP 客户端

### new

**Description**: Creates a new COS client.

**Method**: `new`

**Parameters**:
* **config** (`Config`) - Required - Configuration for the COS client.

**Returns**: `Result<Self>` - A new instance of CosClient.

---

## HTTP Request Methods

### get

**Description**: Sends a GET request.

**Method**: `get`

**Endpoint**: (Path parameter depends on usage)

**Parameters**:
* **path** (`&str`) - Required - The path for the GET request.
* **params** (`HashMap<String, String>`) - Required - Query parameters for the request.

**Returns**: `Result<Response>`

---

### put

**Description**: Sends a PUT request.

**Method**: `put`

**Endpoint**: (Path parameter depends on usage)

**Parameters**:
* **path** (`&str`) - Required - The path for the PUT request.
* **params** (`HashMap<String, String>`) - Required - Query parameters for the request.
* **body** (`Option<T>`) - Optional - The request body, must implement `Into<Body>`.

**Returns**: `Result<Response>`

---

### post

**Description**: Sends a POST request.

**Method**: `post`

**Endpoint**: (Path parameter depends on usage)

**Parameters**:
* **path** (`&str`) - Required - The path for the POST request.
* **params** (`HashMap<String, String>`) - Required - Query parameters for the request.
* **body** (`Option<T>`) - Optional - The request body, must implement `Into<Body>`.

**Returns**: `Result<Response>`

---

### delete

**Description**: Sends a DELETE request.

**Method**: `delete`

**Endpoint**: (Path parameter depends on usage)

**Parameters**:
* **path** (`&str`) - Required - The path for the DELETE request.
* **params** (`HashMap<String, String>`) - Required - Query parameters for the request.

**Returns**: `Result<Response>`

---

### head

**Description**: Sends a HEAD request.

**Method**: `head`

**Endpoint**: (Path parameter depends on usage)

**Parameters**:
* **path** (`&str`) - Required - The path for the HEAD request.
* **params** (`HashMap<String, String>`) - Required - Query parameters for the request.

**Returns**: `Result<Response>`

---

## Response Handling

### parse_xml_response

**Description**: Parses an XML response.

**Method**: `parse_xml_response`

**Parameters**:
* **response** (`Response`) - Required - The response object to parse.

**Returns**: `Result<Value>`

---

### config

**Description**: Gets the client's configuration.

**Method**: `config`

**Returns**: `&Config` - A reference to the client's configuration.

```
Tokens:
Raw