aliyun-oss-rs

aliyun-oss-rs is an unofficial Rust SDK for Alibaba Cloud Object Storage Service (OSS). It provides a small, chainable API surface. Async is enabled by default; sync enables synchronous variants for all APIs. Public features are limited to async, sync, async-native-tls, and sync-native-tls; any feature starting with _ is internal and not stable. This SDK targets OSS Signature V4; region is required and drives the default endpoint selection.

Install

Add the dependency in your Cargo.toml:

# Async (rustls) by default
aliyun-oss-rs = { version = "0.3.0" }

Enable synchronous APIs if needed:

aliyun-oss-rs = { version = "0.3.0", features = ["sync"] }

Use native-tls if required:

aliyun-oss-rs = { version = "0.3.0", default-features = false, features = ["async-native-tls"] }

Quick Start (Async)

use aliyun_oss_rs::OssClient;

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

    // List buckets
    let buckets = client
        .list_buckets()
        .set_prefix("rust")
        .send()
        .await;

    println!("buckets = {:?}", buckets);
}

Need to work with STS credentials? Use OssClient::with_security_token(token) (or the corresponding bucket/object helpers) before sending requests.

Common Operations (Async)

List objects in a bucket:

use aliyun_oss_rs::OssClient;

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

    let objects = bucket
        .list_objects()
        .set_prefix("rust")
        .set_max_keys(200)
        .send()
        .await;

    println!("objects = {:?}", objects);
}

Upload a file from disk:

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(())
}

Download to a local file:

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
        .get_object()
        .download_to_file("./downloads/rust.png")
        .await?;

    Ok(())
}

Generate a pre-signed URL:

use aliyun_oss_rs::OssClient;
use time::{Duration, OffsetDateTime};

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

    let expires = OffsetDateTime::now_utc() + Duration::hours(24);
    // Optionally bind a custom domain and HTTPS for the URL
    let url = object
        .get_object_url()
        .set_custom_domain("cdn.example.com", true)
        .url(expires);

    println!("signed url = {}", url);
}

Synchronous notes:

• When enabling features = ["sync"], all APIs provide *_sync variants.
• Object APIs support streaming uploads/downloads in sync mode via blocking readers/writers.

Implemented APIs

Doc last updated times are taken from the Alibaba Cloud OSS documentation (UTC).

Basic

Bucket operations

Object operations

Multipart upload operations

Missing API categories:

• Replication and cross-region replication (CRR/RTC)
• Live channel and media processing
• CDN and image processing
• Bucket-level advanced security features beyond ACL/policy

aliyun-oss-rs

aliyun-oss-rs 是阿里云对象存储服务（OSS）的非官方 Rust SDK。 提供精简、可链式调用的 API。默认启用异步；开启 sync 后可使用所有同步 API 变体。 对外只提供 async、sync、async-native-tls、sync-native-tls 四个 feature，以下划线 _ 开头的 feature 为内部使用且不保证稳定。 本 SDK 使用 OSS Signature V4；必须提供 region，并由此推导默认 Endpoint。

安装

在 Cargo.toml 中添加依赖：

# 默认异步（rustls）
aliyun-oss-rs = { version = "0.3.0" }

需要同步 API 时启用特性：

aliyun-oss-rs = { version = "0.3.0", features = ["sync"] }

需要 native-tls 时启用特性：

aliyun-oss-rs = { version = "0.3.0", default-features = false, features = ["async-native-tls"] }

快速开始（异步）

use aliyun_oss_rs::OssClient;

#[tokio::main]
async fn main() {
    let mut client = OssClient::new("<AccessKeyId>", "<AccessKeySecret>", "cn-zhangjiakou");
    // 可选：设置内网/双栈/自定义 Endpoint
    // client.set_endpoint("oss-cn-zhangjiakou-internal.aliyuncs.com");

    // 列举 Bucket
    let buckets = client
        .list_buckets()
        .set_prefix("rust")
        .send()
        .await;

    println!("buckets = {:?}", buckets);
}

需要 STS 临时凭证？可使用 OssClient::with_security_token(token)（或对应 bucket/object 的 helper）后再发送请求。

常用操作（异步）

列举 Bucket 中的对象：

use aliyun_oss_rs::OssClient;

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

    let objects = bucket
        .list_objects()
        .set_prefix("rust")
        .set_max_keys(200)
        .send()
        .await;

    println!("objects = {:?}", objects);
}

上传本地文件：

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(())
}

下载到本地文件：

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
        .get_object()
        .download_to_file("./downloads/rust.png")
        .await?;

    Ok(())
}

生成预签名 URL：

use aliyun_oss_rs::OssClient;
use time::{Duration, OffsetDateTime};

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

    let expires = OffsetDateTime::now_utc() + Duration::hours(24);
    // 可选：绑定自定义域名并使用 HTTPS
    let url = object
        .get_object_url()
        .set_custom_domain("cdn.example.com", true)
        .url(expires);

    println!("signed url = {}", url);
}

同步说明：

• 启用 features = ["sync"] 后，所有 API 均提供 *_sync 变体。
• Object 相关操作在同步模式下支持流式上传/下载（阻塞式读取/写入）。

已实现 API

文档更新时间取自阿里云 OSS 文档（UTC）。

基础

Bucket 操作

Object 操作

分片上传

缺失 API 分类：

• 跨区域复制与实时同步（CRR/RTC）
• 直播通道与媒体处理
• CDN 与图片处理
• 超出 ACL/Policy 的高级安全能力