aliyun-oss-rs

aliyun-oss-rs is an unofficial Rust SDK for Alibaba Cloud Object Storage Service (OSS). It provides a simple, chainable API with minimal abstractions. Async is enabled by default; a sync feature is available for selected APIs.

Install

Add the dependency in your Cargo.toml:

# Async by default
aliyun-oss-rs = { version = "0.1.1" }

Enable synchronous APIs if needed:

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

Quick Start (Async)

use aliyun_oss_rs::OssClient;

#[tokio::main]
async fn main() {
    let client = OssClient::new("<AccessKeyId>", "<AccessKeySecret>");

    // 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>");
    let bucket = client.bucket("example-bucket", "oss-cn-zhangjiakou.aliyuncs.com");

    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>");
    let bucket = client.bucket("example-bucket", "oss-cn-zhangjiakou.aliyuncs.com");
    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>");
    let bucket = client.bucket("example-bucket", "oss-cn-zhangjiakou.aliyuncs.com");
    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>");
    let bucket = client.bucket("example-bucket", "oss-cn-zhangjiakou.aliyuncs.com");
    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"], several bucket-level APIs offer *_sync variants (e.g. get_bucket_location_sync).
• For object operations that remain async-only, prefer using async directly for now; the sync feature set will continue to expand over time.

Implemented APIs

• Basic

  • List buckets (ListBuckets)
  • List regions (DescribeRegions)

• Bucket operations

  • Create bucket (PutBucket)
  • Delete bucket (DeleteBucket)
  • List objects in bucket (ListObjectsV2)
  • Get bucket information (GetBucketInfo)
  • Get bucket statistics (GetBucketStat)
  • Delete multiple objects (DeleteMultipleObjects)
  • List unfinished multipart uploads (ListMultipartUploads)
  • Get bucket ACL (GetBucketAcl)
  • Set bucket ACL (PutBucketAcl)
  • Get bucket location (GetBucketLocation)
  • Get bucket logging (GetBucketLogging)
  • Set bucket logging (PutBucketLogging)
  • Delete bucket logging (DeleteBucketLogging)
  • Manage bucket CORS (Get/Put/DeleteBucketCors)
  • Manage lifecycle rules (Get/Put/DeleteBucketLifecycle)
  • Configure referer protection (Get/Put/DeleteBucketReferer)
  • Configure static website hosting (Get/Put/DeleteBucketWebsite)
  • Manage bucket policies (Get/Put/DeleteBucketPolicy)
  • Manage default encryption (Get/Put/DeleteBucketEncryption)
  • Work with WORM retention (Initiate/Get/Complete/Extend/AbortBucketWorm)
  • Configure inventory reports (Put/Get/Delete/ListBucketInventory)

• Object operations

  • Upload object (PutObject)
  • Download object (GetObject)
  • Query object with OSS Select (SelectObject)
  • Copy object (CopyObject)
  • Append object (AppendObject)
  • Delete object (DeleteObject)
  • Restore object (RestoreObject)
  • Head object (HeadObject)
  • Get object metadata (GetObjectMeta)
  • Generate object URL (GetObjectUrl)
  • Multipart upload
    • Initiate multipart upload (InitiateMultipartUpload)
    • Upload part (UploadPart)
    • Upload part copy (UploadPartCopy)
    • Complete multipart upload (CompleteMultipartUpload)
    • Abort multipart upload (AbortMultipartUpload)
    • List parts (ListParts)
  • Object ACL
    • Get object ACL (GetObjectAcl)
    • Set object ACL (PutObjectAcl)
  • Tagging
    • Get object tagging (GetObjectTagging)
    • Set object tagging (PutObjectTagging)
    • Delete object tagging (DeleteObjectTagging)
  • Symlink
    • Create symlink (PutSymlink)
    • Get symlink (GetSymlink)

This project is a work in progress and not an official Alibaba Cloud product. Pull requests are welcome.