接入对象存储实现文件上传下载管理-OSS Kotlin SDK V2-对象存储-阿里云

使用 OSS Kotlin SDK V2 在 Kotlin 和 Android 应用中接入阿里云对象存储 OSS，实现文件的上传、下载和管理功能，适合移动端应用、跨平台开发者进行云端文件存储操作。

Github| OSS Kotlin SDK V2开发者指南

快速接入

接入 OSS Kotlin SDK V2 的流程如下：

环境准备

Kotlin: 2.1.0 及以上版本
Java: 运行时需要 Java 8+（从源码构建需要 Java 11+）
支持平台: Android、Desktop (JVM)

通过项目的 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 权限。

Linux

在命令行界面执行以下命令来将环境变量设置追加到 ~/.bashrc 文件中。

echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

执行以下命令使变更生效。
```
source ~/.bashrc
```

执行以下命令检查环境变量是否生效。

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

macOS

在终端中执行以下命令，查看默认 Shell 类型。
```
echo $SHELL
```

根据默认 Shell 类型进行操作。

Zsh

执行以下命令来将环境变量设置追加到 ~/.zshrc 文件中。

echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

执行以下命令使变更生效。
```
source ~/.zshrc
```

执行以下命令检查环境变量是否生效。

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

Bash

执行以下命令来将环境变量设置追加到 ~/.bash_profile 文件中。

echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

执行以下命令使变更生效。
```
source ~/.bash_profile
```

执行以下命令检查环境变量是否生效。

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

Windows

CMD

在 CMD 中运行以下命令。

setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

运行以下命令，检查环境变量是否生效。
```
echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%
```

PowerShell

在 PowerShell 中运行以下命令。

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

运行以下命令，检查环境变量是否生效。

[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

初始化客户端

使用地域和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

客户端配置

客户端支持哪些配置？

参数名	说明
region	(必选)请求发送的区域
credentialsProvider	(必选)设置访问凭证
endpoint	访问域名
httpTransport	HTTP 传输层
retryMaxAttempts	HTTP 请求时的最大尝试次数，默认值为 3
retryer	HTTP 请求时的重试实现
connectTimeout	建立连接的超时时间，默认值为 10 秒
readWriteTimeout	应用读写数据的超时时间，默认值为 20 秒
insecureSkipVerify	是否跳过 SSL 证书校验，默认检查 SSL 证书
enabledRedirect	是否开启 HTTP 重定向，默认不开启
proxyHost	设置代理服务器
signatureVersion	签名版本，默认值为 v4
disableSsl	不使用 https 请求，默认使用 https
usePathStyle	使用路径请求风格，即二级域名请求风格，默认为 bucket 托管域名
useCName	是否使用自定义域名访问，默认不使用
useDualStackEndpoint	是否使用双栈域名访问，默认不使用
useAccelerateEndpoint	是否使用传输加速域名访问，默认不使用
useInternalEndpoint	是否使用内网域名访问，默认不使用
additionalHeaders	指定额外的签名请求头，V4 签名下有效
userAgent	指定额外的 User-Agent 信息
disableUploadCRC64Check	禁用上传 CRC64 校验，默认开启
disableDownloadCRC64Check	禁用下载 CRC64 校验，默认开启

使用自定义域名

使用 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 所在地域。以华东1 金融云为例，Region 填写为 cn-hangzhou-finance
    val region = "cn-hangzhou-finance"
    
    // 填写 Bucket 所在地域对应的内网 Endpoint。以华东1 金融云为例
    // 如需指定为 http 协议，请在指定域名时填写为 'http://oss-cn-hzjbp-a-internal.aliyuncs.com'
    val endpoint = "https://oss-cn-hzjbp-a-internal.aliyuncs.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 执行后续操作...
    }
}

访问凭证配置

阿里云对象存储 OSS Kotlin SDK V2 提供多种访问凭证配置方式。请根据您的认证和授权需求选择合适的初始化方式。

如何选择访问凭证？

凭证提供者初始化方式	适用场景	Kotlin SDK V2支持情况	底层实现基于的凭证	凭证有效期	凭证轮转或刷新方式
使用RAM用户的AK	部署运行在安全、稳定且不易受外部攻击的环境的应用程序，无需频繁轮转凭证就可以长期访问云服务	内置支持	AK	长期	手动轮转
使用STS临时访问凭证	部署运行在不可信的环境的应用程序，希望能控制访问的有效期、权限	内置支持	STS Token	临时	手动刷新
使用自定义访问凭证	如果以上凭证配置方式都不满足要求时，您可以自定义获取凭证的方式	内置支持	自定义	自定义	自定义
匿名访问	访问公共读取权限的 OSS 资源，无需提供任何凭证	内置支持	无	无	无

使用RAM用户的AK

如果您的应用程序部署运行在安全、稳定且不易受外部攻击的环境中，需要长期访问您的 OSS，且不能频繁轮转凭证时，您可以使用阿里云主账号或 RAM 用户的 AK（Access Key ID、Access Key Secret）初始化凭证提供者。需要注意的是，该方式需要您手动维护一个 AK，存在安全性风险和维护复杂度增加的风险。

重要

阿里云账号拥有资源的全部权限，AK 一旦泄露，会给系统带来巨大风险，不建议使用。推荐使用最小化授权的 RAM 用户的 AK。
如需创建 RAM 用户的 AK，请直接访问创建AccessKey。RAM 用户的 Access Key ID、Access Key Secret 信息仅在创建时显示，请及时保存，如若遗忘请考虑创建新的 AK 进行轮换。

环境变量配置

Linux/macOS

使用 RAM 用户 AccessKey 配置环境变量：

export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'
export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'

执行以下命令检查环境变量是否生效：

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

Windows

CMD

setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

PowerShell

[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 在生成的时候需要指定过期时间，过期后自动失效不能再使用。

环境变量配置

重要

请注意，此处使用的是通过 STS 服务获取的临时身份凭证（Access Key ID、Access Key Secret 和 Security Token），而非 RAM 用户的 AK。
请注意区分 STS 服务获取的 Access Key ID 以 STS 开头，例如 "STS.L4aBSCSJVMuKg5U1****"。

Linux/macOS

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>

Windows

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 接口来自定义凭证提供者。

实现 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 执行后续操作...
    }
}

使用 RefreshCredentialsProvider 自动刷新凭证

如果您需要自动刷新凭证，可以使用 RefreshCredentialsProvider 包装您的凭证提供者：

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 secrect"

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

运行 UI 示例

> - 运行 `sample.composeApp` 或 `sample[jvm]`
> - 填写 `AccessKeyId`, `AccessKeySecret` 及 `Region`
> - 点击 `Set Client` 完成 client 初始化
> - 以 ListObjects 为例，填写 bucket 名称，点击 `ListObjects`

示例代码

功能分类	示例说明	示例代码
存储空间	创建存储空间	PutBucket.kt
	列举存储空间	ListBuckets.kt
	获取存储空间信息	GetBucketInfo.kt
	获取存储空间地域	GetBucketLocation.kt
	获取存储容量统计	GetBucketStat.kt
	删除存储空间	DeleteBucket.kt
	判断存储空间是否存在	IsBucketExist.kt
文件上传	简单上传	PutObject.kt
	追加上传	AppendObject.kt
	分片上传-初始化	InitiateMultipartUpload.kt
	分片上传-上传分片	UploadPart.kt
	分片上传-完成上传	CompleteMultipartUpload.kt
	列举分片上传任务	ListMultipartUploads.kt
	列举已上传分片	ListParts.kt
	取消分片上传	AbortMultipartUpload.kt
文件下载	简单下载	GetObject.kt
文件下载	下载到本地文件	GetObjectToFile.kt
文件管理	拷贝文件	CopyObject.kt
	判断文件是否存在	HeadObject.kt
	判断对象是否存在	IsObjectExist.kt
	列举文件	ListObjects.kt
	列举文件V2	ListObjectsV2.kt
	删除文件	DeleteObject.kt
	批量删除文件	DeleteMultipleObjects.kt
	获取文件元数据	GetObjectMeta.kt
归档文件	解冻文件	RestoreObject.kt
软链接	创建软链接	PutSymlink.kt
软链接	获取软链接	GetSymlink.kt
对象标签	设置对象标签	PutObjectTagging.kt
	获取对象标签	GetObjectTagging.kt
	删除对象标签	DeleteObjectTagging.kt
访问控制	设置存储空间ACL	PutBucketAcl.kt
	获取存储空间ACL	GetBucketAcl.kt
	设置文件ACL	PutObjectAcl.kt
	获取文件ACL	GetObjectAcl.kt
版本控制	设置版本控制	PutBucketVersioning.kt
版本控制	获取版本控制状态	GetBucketVersioning.kt
预签名	生成预签名URL	Presign.kt
系统功能	查询Endpoint信息	DescribeRegions.kt