Object Storage Service：OSS Kotlin SDK V2（預覽版）

環境準備

• Kotlin：2.1.0 及以上版本

• Java：運行時需要 Java 8+（從源碼構建需要 Java 11+）

• 支援平台：JVM（Desktop / Server）、Android、JavaScript（Node.js、Browser）、WebAssembly（wasmJs：Node.js、Browser）、iOS（iosArm64、iosSimulatorArm64）和 macOS（macosArm64）

通過專案的 build.gradle.kts 檔案查看 Kotlin 版本。如果當前環境沒有 Kotlin 或版本過低，請升級您的 Kotlin 版本。

安裝SDK

建議使用 Gradle 方式安裝 OSS Kotlin SDK V2。

方式一：Gradle 依賴（推薦）

在 build.gradle.kts 添加依賴：

dependencies {
    implementation("com.aliyun:kotlin-oss-v2:<latest-version>")

    // 如需擴充功能（如跨域資源共用介面）
    // implementation("com.aliyun:kotlin-oss-v2-extension:0.1.0-dev")
}

包說明：

• kotlin-oss-v2：提供 Bucket 基礎介面、對象類介面和進階介面（分頁器、預簽名）

• kotlin-oss-v2-extension：包含儲存空間配置類介面，例如跨域資源共用、日誌轉存、儲存空間清單和圖片樣式

方式二：從源碼構建

從 Github擷取最新版本的 OSS Kotlin SDK V2，並通過 Gradle 構建和安裝：

# clone工程
$ git clone https://github.com/aliyun/alibabacloud-oss-kotlin-sdk-v2.git

# 進入目錄
$ cd alibabacloud-oss-kotlin-sdk-v2/

# 發布到 MavenLocal
$ ./gradlew clean publishToMavenLocal

添加 mavenLocal 到倉庫配置：

repositories {
    ...
    mavenLocal()
}

添加依賴到你的專案中

implementation("com.aliyun:kotlin-oss-v2:<latest-version>")
// implementation("com.aliyun:kotlin-oss-v2-extension:<latest-version>")

方式三：手動引入依賴包

# clone工程
$ git clone https://github.com/aliyun/alibabacloud-oss-kotlin-sdk-v2.git

# 進入目錄
$ cd aliyun-oss-kotlin-sdk-v2/

# 執行打包指令碼
$ ./gradlew :oss-sdk:assemble
# ./gradlew :oss-sdk-extension:assemble

# 以aar為例
# 進入打包組建目錄，包產生在該目錄下
$ cd oss-sdk/build/outputs/aar && ls
# cd oss-sdk-extension/build/outputs/aar && ls

配置訪問憑證

將 RAM 使用者的 AccessKey 寫入環境變數作為憑證。

在 RAM 控制台，建立 使用永久 AccessKey 訪問 的 RAM 使用者，儲存 AccessKey，然後為該使用者授予 AliyunOSSFullAccess 許可權。

初始化用戶端

使用地區和Endpoint初始化 OSSClient。

• OSSClient 實現了 Closeable 介面，使用 use 擴充函數時會自動釋放資源，無需手動調用 close。

• OSSClient 建立和銷毀是耗時的，可採用單例模式複用 OSSClient，但應用終止前必須手動調用 close，否則資源會泄漏。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider
import com.aliyun.kotlin.sdk.service.oss2.models.ListBucketsRequest
import com.aliyun.kotlin.sdk.service.oss2.paginator.listBucketsPaginator

suspend fun main() {
    val region = "cn-hangzhou"

    // 使用SDK預設配置
    // 從環境變數中載入憑證資訊
    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
    }

    OSSClient.create(config).use { client ->
        // 使用分頁器列舉所有Bucket
        client.listBucketsPaginator(ListBucketsRequest {}).collect { result ->
            result.buckets?.forEach { bucket ->
                println("bucket: name:${bucket.name}, region:${bucket.region}, storageClass:${bucket.storageClass}")
            }
        }
    }
}

運行後將會看到當前帳號在所有地區下的 Bucket：

bucket: name: examplebucket01, region: cn-hangzhou, storageClass: Standard
bucket: name: examplebucket02, region: cn-hangzhou, storageClass: Standard

使用自訂網域名

使用 OSS 預設網域名稱訪問時，可能會出現檔案禁止訪問、檔案無法預覽等問題；通過自訂網域名訪問 OSS，不僅支援瀏覽器直接預覽檔案，還可結合 CDN 加速分發。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 填寫 Bucket 所在地區。以華東1（杭州）為例，Region 填寫為 cn-hangzhou
    val region = "cn-hangzhou"
    
    // 請填寫您的自訂網域名。例如 www.example-***.com
    val endpoint = "https://www.example-***.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        this.endpoint = endpoint
        // 請注意，設定 true 開啟 CNAME 選項，否則無法使用自訂網域名
        this.useCName = true
        credentialsProvider = EnvironmentVariableCredentialsProvider()
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

逾時控制

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider
import kotlin.time.Duration.Companion.seconds

suspend fun main() {
    val region = "cn-hangzhou"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
        // 設定建立串連的逾時時間, 預設值 10 秒
        connectTimeout = 30.seconds
        // 設定應用讀寫資料的逾時時間, 預設值 20 秒
        readWriteTimeout = 30.seconds
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

重試策略

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider
import com.aliyun.kotlin.sdk.service.oss2.retry.StandardRetryer
import com.aliyun.kotlin.sdk.service.oss2.retry.FullJitterBackoff
import com.aliyun.kotlin.sdk.service.oss2.retry.FixedDelayBackoff
import com.aliyun.kotlin.sdk.service.oss2.retry.NopRetryer
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds

suspend fun main() {
    /*
     * SDK 重試策略配置說明：
     *
     * 預設重試策略：
     * 當沒有配置重試策略時，SDK 使用 StandardRetryer 作為用戶端的預設實現，其預設配置如下：
     * - maxAttempts：設定最大嘗試次數。預設為 3 次
     * - maxBackoff：設定最大退避時間。預設為 20 秒
     * - baseDelay：設定基礎延遲時間。預設為 200 毫秒
     * - backoffDelayer：設定退避演算法。預設使用 FullJitter 退避演算法
     *   計算公式為：[0.0, 1.0) * min(2^attempts * baseDelay, maxBackoff)
     * - errorRetryable：可重試的錯誤類型，包括 HTTP 狀態代碼、服務錯誤碼、用戶端錯誤等
     *
     * 當發生可重試錯誤時，將使用其提供的配置來延遲並隨後重試該請求。
     * 請求的總體延遲會隨著重試次數而增加，如果預設配置不滿足您的情境需求時，
     * 可配置重試參數或者修改重試實現。
     */

    val region = "cn-hangzhou"

    // 配置重試策略樣本：

    // 1. 自訂最大重試次數（預設為 3 次，這裡設定為 5 次）
    val customRetryer = StandardRetryer.newBuilder()
        .setMaxAttempts(5)
        .build()

    // 2. 自訂退避延遲時間
    // 調整基礎延遲時間 baseDelay 為 500 毫秒（預設 200 毫秒），最大退避時間 maxBackoff 為 25 秒（預設 20 秒）
    // val customRetryer = StandardRetryer.newBuilder()
    //     .setBackoffDelayer(FullJitterBackoff(500.milliseconds, 25.seconds))
    //     .build()

    // 3. 自訂退避演算法
    // 使用固定時間退避演算法替代預設的 FullJitter 演算法，每次延遲 2 秒
    // val customRetryer = StandardRetryer.newBuilder()
    //     .setBackoffDelayer(FixedDelayBackoff(2.seconds))
    //     .build()

    // 4. 禁用重試策略
    // 如需禁用所有重試嘗試時，可以使用 NopRetryer 實現
    // val customRetryer = NopRetryer()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
        retryer = customRetryer
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

HTTP/HTTPS 協議

使用 disableSsl = true 設定不使用 HTTPS 協議。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    val region = "cn-hangzhou"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
        // 設定不使用 https 請求
        disableSsl = true
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

使用內網網域名稱

使用內網網域名稱訪問同地區的 OSS 資源，可以降低流量成本並提高訪問速度。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 方式一：填寫 Region 並設定 useInternalEndpoint 為 true
    val region = "cn-hangzhou"

    // 方式二：直接填寫 Region 和 Endpoint
    // val region = "cn-hangzhou"
    // val endpoint = "oss-cn-hangzhou-internal.aliyuncs.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
        useInternalEndpoint = true
        // 如果使用方式二，取消注釋下一行並注釋上一行
        // this.endpoint = endpoint
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

使用傳輸加速網域名稱

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 方式一：填寫 Region 並設定 useAccelerateEndpoint 為 true
    val region = "cn-hangzhou"

    // 方式二：直接填寫 Region 和傳輸加速 Endpoint
    // val region = "cn-hangzhou"
    // val endpoint = "https://oss-accelerate.aliyuncs.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
        useAccelerateEndpoint = true
        // 如果使用方式二，取消注釋下一行並注釋上一行
        // this.endpoint = endpoint
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

使用專有域

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    val region = "cn-hangzhou"
    
    // 請填寫您的專有域。例如：https://service.corp.example.com
    val endpoint = "https://service.corp.example.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        this.endpoint = endpoint
        credentialsProvider = EnvironmentVariableCredentialsProvider()
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

使用政務雲網域名稱

以下是使用政務雲網域名稱配置 OSSClient 的範例程式碼。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 填寫 Bucket 所在地區。以華北2 阿里政務雲1為例，Region 填寫為 cn-north-2-gov-1
    val region = "cn-north-2-gov-1"
    
    // 填寫 Bucket 所在地區對應的內網 Endpoint。以華北2 阿里政務雲1為例
    // 如需指定為 http 協議，請在指定網域名稱時填寫為 'http://oss-cn-north-2-gov-1-internal.aliyuncs.com'
    val endpoint = "https://oss-cn-north-2-gov-1-internal.aliyuncs.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        this.endpoint = endpoint
        credentialsProvider = EnvironmentVariableCredentialsProvider()
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

使用RAM使用者的AK

如果您的應用程式部署運行在安全、穩定且不易受外部攻擊的環境中，需要長期訪問您的 OSS，且不能頻繁輪轉憑證時，您可以使用阿里雲主帳號或 RAM 使用者的 AK（Access Key ID、Access Key Secret）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個 AK，存在安全性風險和維護複雜度增加的風險。

環境變數配置

setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

程式碼範例

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 從環境變數中載入憑證資訊，用於身分識別驗證
    val credentialsProvider = EnvironmentVariableCredentialsProvider()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // 填寫 Bucket 所在地區
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

靜態憑證配置

以下範例程式碼展示了如何對訪問憑據直接進行寫入程式碼，顯式設定要使用的存取金鑰。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.StaticCredentialsProvider

suspend fun main() {
    // 建立靜態憑證提供者，顯式設定存取金鑰
    // 請替換為您的 RAM 使用者的 AccessKey ID 和 AccessKey Secret
    val credentialsProvider = StaticCredentialsProvider(
        accessKeyId = "YOUR_ACCESS_KEY_ID",
        accessKeySecret = "YOUR_ACCESS_KEY_SECRET"
    )

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // 填寫 Bucket 所在地區
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

使用STS臨時訪問憑證

如果您的應用程式需要臨時訪問 OSS，您可以使用通過 STS 服務擷取的臨時身份憑證（Access Key ID、Access Key Secret 和 Security Token）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個 STS Token，存在安全性風險和維護複雜度增加的風險。此外，如果您需要多次臨時訪問 OSS，您需要手動重新整理 STS Token。

• 請注意，STS Token 在產生的時候需要指定到期時間，到期後自動失效不能再使用。

環境變數配置

export OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
export OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
export OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

set OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
set OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
set OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

程式碼範例

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider

suspend fun main() {
    // 從環境變數中載入訪問 OSS 所需的認證資訊，用於身分識別驗證
    val credentialsProvider = EnvironmentVariableCredentialsProvider()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // 填寫 Bucket 所在地區
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

靜態憑證配置

以下範例程式碼展示了如何對訪問憑據直接進行寫入程式碼，顯式設定要使用的臨時存取金鑰。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.StaticCredentialsProvider

suspend fun main() {
    // 填寫擷取的臨時存取金鑰 AccessKey ID 和 AccessKey Secret
    // 請注意區分 STS 服務擷取的 Access Key ID 是以 STS 開頭
    val stsAccessKeyId = "STS.****************"
    val stsAccessKeySecret = "yourAccessKeySecret"
    val stsSecurityToken = "yourSecurityToken"

    // 建立靜態憑證提供者，顯式設定臨時存取金鑰和 STS 安全性權杖
    val credentialsProvider = StaticCredentialsProvider(
        accessKeyId = stsAccessKeyId,
        accessKeySecret = stsAccessKeySecret,
        securityToken = stsSecurityToken
    )

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // 填寫 Bucket 所在地區
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

使用自訂訪問憑證

當以上憑證配置方式不滿足要求時，您可以自訂擷取憑證的方式。Kotlin SDK 支援通過實現 CredentialsProvider 介面來自訂憑證提供者。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.Credentials
import com.aliyun.kotlin.sdk.service.oss2.credentials.CredentialsProvider

class CustomCredentialsProvider : CredentialsProvider {
    
    override suspend fun getCredentials(): Credentials {
        // TODO: 實現您的自訂憑證擷取邏輯
        
        // 返回長期憑證
        return Credentials("access_key_id", "access_key_secret")
        
        // 返回 STS 臨時憑證（如果需要）
        // 對於臨時憑證，需要根據到期時間重新整理憑證
        // return Credentials("sts_access_key_id", "sts_access_key_secret", "security_token")
    }
}

suspend fun main() {
    // 建立自訂憑證提供者
    val credentialsProvider = CustomCredentialsProvider()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // 填寫 Bucket 所在地區
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.CredentialsProvider
import com.aliyun.kotlin.sdk.service.oss2.credentials.RefreshCredentialsProvider
import kotlin.time.Duration.Companion.seconds

suspend fun main() {
    // 您的原始憑證提供者
    val baseProvider: CredentialsProvider = CustomCredentialsProvider()
    
    // 使用 RefreshCredentialsProvider 封裝，自動重新整理憑證
    // 預設重新整理間隔為 300 秒
    val credentialsProvider = RefreshCredentialsProvider(
        provider = baseProvider,
        refreshInterval = 300.seconds
    )

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
    }
}

匿名訪問

如果您只需要訪問公用讀取許可權的 OSS 資源，可以使用匿名訪問方式，無需提供任何憑證。

import com.aliyun.kotlin.sdk.service.oss2.ClientConfiguration
import com.aliyun.kotlin.sdk.service.oss2.OSSClient
import com.aliyun.kotlin.sdk.service.oss2.credentials.AnonymousCredentialsProvider

suspend fun main() {
    // 建立匿名憑證提供者
    val credentialsProvider = AnonymousCredentialsProvider()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // 填寫 Bucket 所在地區
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // 使用建立好的 client 執行後續操作...
        // 注意：匿名訪問只能訪問具有公用讀取許可權的資源
    }
}

運行 CLI 樣本

# 編譯專案 
./gradlew :sample:cli:build

# 進入樣本程式目錄 
cd sample/cli/build/libs/

# 通過環境變數，配置訪問憑證
export OSS_ACCESS_KEY_ID="your access key id"
export OSS_ACCESS_KEY_SECRET="your access key secret"

# 以 ListBuckets 為例
java -jar cli-jvm.jar ListBuckets --region cn-hangzhou

運行 UI 樣本

> - 運行 `sample.composeApp` 或 `sample[jvm]`
> - 填寫 `AccessKeyId`, `AccessKeySecret` 及 `Region`
> - 點擊 `Set Client` 完成 client 初始化
> - 以 ListObjects 為例，填寫 bucket 名稱，點擊 `ListObjects`