Object Storage Service:OSS Kotlin SDK V2 (Preview)

Prepare the environment

• Kotlin: Version 2.1.0 or later

• Java: Java 8+ is required for the runtime. Java 11+ is required to build from source.

• Supported platforms: Android, Desktop (JVM)

Check the Kotlin version in your project's build.gradle.kts file. If Kotlin is not installed or the version is too old, upgrade your Kotlin version.

Install the SDK

We recommend that you use Gradle to install the OSS Kotlin SDK V2.

Method 1: Gradle dependency (Recommended)

Add the dependency to the build.gradle.kts file:

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

    // For extension features (such as cross-origin resource sharing interfaces)
    // implementation("com.aliyun:kotlin-oss-v2-extension:0.1.0-dev")
}

Package description:

• kotlin-oss-v2: Provides basic bucket interfaces, object-related interfaces, and advanced interfaces (paginators, presigning).

• kotlin-oss-v2-extension: Contains configuration-related interfaces, such as the cross-origin resource sharing interface.

Method 2: Build from source

Obtain the latest version of the OSS Kotlin SDK V2 from GitHub, and then build and install it using Gradle:

# Clone the project
$ git clone https://github.com/aliyun/alibabacloud-oss-kotlin-sdk-v2.git

# Go to the directory
$ cd alibabacloud-oss-kotlin-sdk-v2/

# Publish to MavenLocal
$ ./gradlew clean publishToMavenLocal

Add mavenLocal to your repository configuration:

repositories {
    ...
    mavenLocal()
}

Add the dependency to your project.

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

Method 3: Manually import dependency packages

# Clone the project
$ git clone https://github.com/aliyun/alibabacloud-oss-kotlin-sdk-v2.git

# Go to the directory
$ cd aliyun-oss-kotlin-sdk-v2/

# Run the packaging script
$ ./gradlew :oss-sdk:assemble
# ./gradlew :oss-sdk-extension:assemble

# Take aar as an example
# Go to the packaging output directory. The package is generated in this directory.
$ cd oss-sdk/build/outputs/aar && ls
# cd oss-sdk-extension/build/outputs/aar && ls

Configure access credentials

Set the AccessKey pair of a RAM user to environment variables as credentials.

In the RAM console, create a RAM user that uses a permanent AccessKey pair for access. Save the AccessKey pair, and then grant the AliyunOSSFullAccess permission to the user.

Initialize the client

Initialize the OSSClient with a region and endpoint.

• The OSSClient implements the Closeable interface. When you use the use extension function, resources are automatically released. You do not need to manually call close.

• Because creating and destroying an OSSClient is time-consuming, use the singleton pattern to reuse the OSSClient instance. To prevent resource leaks, manually call close before the application stops.

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"

    // Use the default SDK configurations.
    // Load credentials from environment variables.
    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
    }

    OSSClient.create(config).use { client ->
        // Use the paginator to list all buckets.
        client.listBucketsPaginator(ListBucketsRequest {}).collect { result ->
            result.buckets?.forEach { bucket ->
                println("bucket: name:${bucket.name}, region:${bucket.region}, storageClass:${bucket.storageClass}")
            }
        }
    }
}

The output shows the buckets for the current account in all regions:

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

Use a custom domain name

When you access OSS using the default domain name, you might encounter issues, such as blocked file access or the inability to preview files. However, accessing OSS through a custom domain name allows browsers to preview files directly and supports CDN acceleration.

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() {
    // Specify the region where your bucket is located. For example, use "cn-hangzhou" for China (Hangzhou).
    val region = "cn-hangzhou"
    
    // Enter your custom domain name. For example: www.example-***.com
    val endpoint = "https://www.example-***.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        this.endpoint = endpoint
        // Set useCName to true to enable CNAME. Otherwise, custom domains won't work.
        this.useCName = true
        credentialsProvider = EnvironmentVariableCredentialsProvider()
    }

    OSSClient.create(config).use { client ->
        // Use the created client to perform subsequent operations...
    }
}

Timeout control

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()
        // Set connection timeout. Default is 10 seconds.
        connectTimeout = 30.seconds
        // Set read/write data timeout. Default is 20 seconds.
        readWriteTimeout = 30.seconds
    }

    OSSClient.create(config).use { client ->
        // Use the created client to perform subsequent operations...
    }
}

Retry policy

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 retry policy configuration notes:
     *
     * Default retry policy:
     * If no retry policy is configured, the SDK uses StandardRetryer by default with these settings:
     * - maxAttempts: Maximum number of attempts. Default is 3.
     * - maxBackoff: Maximum backoff time. Default is 20 seconds.
     * - baseDelay: Base delay time. Default is 200 milliseconds.
     * - backoffDelayer: Backoff algorithm. Default uses FullJitter.
     *   Formula: [0.0, 1.0) * min(2^attempts * baseDelay, maxBackoff)
     * - errorRetryable: Retryable error types, including HTTP status codes, service error codes, and client errors.
     *
     * When a retryable error occurs, the request is delayed and retried based on these settings.
     * Overall request delay increases with each retry attempt.
     * If the default settings don't meet your needs, configure retry parameters or change the retry implementation.
     */

    val region = "cn-hangzhou"

    // Example retry policy configurations:

    // 1. Customize maximum retry attempts (default is 3; set to 5 here)
    val customRetryer = StandardRetryer.newBuilder()
        .setMaxAttempts(5)
        .build()

    // 2. Customize backoff delay
    // Set baseDelay to 500 ms (default 200 ms) and maxBackoff to 25 s (default 20 s)
    // val customRetryer = StandardRetryer.newBuilder()
    //     .setBackoffDelayer(FullJitterBackoff(500.milliseconds, 25.seconds))
    //     .build()

    // 3. Customize backoff algorithm
    // Use fixed-delay backoff instead of FullJitter, with 2-second delays
    // val customRetryer = StandardRetryer.newBuilder()
    //     .setBackoffDelayer(FixedDelayBackoff(2.seconds))
    //     .build()

    // 4. Disable retries entirely
    // Use NopRetryer to disable all retry attempts
    // val customRetryer = NopRetryer()

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

    OSSClient.create(config).use { client ->
        // Use the created client to perform subsequent operations...
    }
}

HTTP/HTTPS protocol

You can set disableSsl = true to use HTTP instead of 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()
        // Use HTTP instead of HTTPS
        disableSsl = true
    }

    OSSClient.create(config).use { client ->
        // Use the created client to perform subsequent operations...
    }
}

Use an internal same-region endpoint

Accessing OSS resources in the same region using an internal same-region endpoint reduces traffic costs and improves access speed.

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() {
    // Method 1: Specify the region and set useInternalEndpoint to true
    val region = "cn-hangzhou"

    // Method 2: Directly specify the region and 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
        // If using Method 2, uncomment the next line and comment out the previous line
        // this.endpoint = endpoint
    }

    OSSClient.create(config).use { client ->
        // Use the created client to perform subsequent operations...
    }
}

Use an acceleration endpoint

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() {
    // Method 1: Specify the region and set useAccelerateEndpoint to true
    val region = "cn-hangzhou"

    // Method 2: Directly specify the region and acceleration endpoint
    // val region = "cn-hangzhou"
    // val endpoint = "https://oss-accelerate.aliyuncs.com"

    val config = ClientConfiguration.loadDefault().apply {
        this.region = region
        credentialsProvider = EnvironmentVariableCredentialsProvider()
        useAccelerateEndpoint = true
        // If using Method 2, uncomment the next line and comment out the previous line
        // this.endpoint = endpoint
    }

    OSSClient.create(config).use { client ->
        // Use the created client to perform subsequent operations...
    }
}

Use a private domain

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"
    
    // Enter your private domain. For example: 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 ->
        // Use the created client to perform subsequent operations...
    }
}

Use Gov Cloud endpoints

The following example shows how to configure OSSClient using Alibaba Gov Cloud endpoints.

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() {
    // Specify the region where your bucket is located. For Alibaba Gov Cloud 1 in China North 2, use "cn-north-2-gov-1".
    val region = "cn-north-2-gov-1"
    
    // Specify the internal endpoint for the region. For Alibaba Gov Cloud 1 in China North 2:
    // To use HTTP, set the endpoint to '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 ->
        // Use the created client to perform subsequent operations...
    }
}

Use the AccessKey of a RAM user

If your application is deployed in a secure and stable environment, requires long-term access to OSS, and does not support frequent credential rotation, you can initialize the credential provider with the AccessKey pair (AccessKey ID and AccessKey secret) of an Alibaba Cloud account or a Resource Access Management (RAM) user. This method requires you to manually maintain the AccessKey pair, which increases security risks and maintenance complexity.

Configure environment variables

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)

Code example

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() {
    // Load credential information from environment variables for identity verification.
    val credentialsProvider = EnvironmentVariableCredentialsProvider()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // Specify the region where the bucket is located.
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // Use the created client for subsequent operations...
    }
}

Configure static credentials

The following code example shows how to hard-code access credentials and explicitly specify the AccessKey pair to use.

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() {
    // Create a static credential provider and explicitly set the AccessKey pair.
    // Replace with the AccessKey ID and AccessKey secret of your RAM user.
    val credentialsProvider = StaticCredentialsProvider(
        accessKeyId = "YOUR_ACCESS_KEY_ID",
        accessKeySecret = "YOUR_ACCESS_KEY_SECRET"
    )

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // Specify the region where the bucket is located.
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // Use the created client for subsequent operations...
    }
}

Use an STS temporary access credential

If your application needs temporary access to OSS, you can initialize the credential provider with a temporary identity credential (AccessKey ID, AccessKey secret, and Security Token Service token) obtained from the Security Token Service (STS). This method requires you to manually maintain the STS token, which increases security risks and maintenance complexity. Additionally, to access OSS multiple times, you must manually refresh the STS token.

• You must specify a time-to-live (TTL) when you generate an STS token. The token automatically expires after the specified TTL.

Configure environment variables

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>

Code example

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() {
    // Load the authentication information required to access OSS from environment variables for identity verification.
    val credentialsProvider = EnvironmentVariableCredentialsProvider()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // Specify the region where the bucket is located.
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // Use the created client for subsequent operations...
    }
}

Configure static credentials

The following code example shows how to hard-code access credentials and explicitly specify the temporary AccessKey pair to use.

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() {
    // Specify the temporary AccessKey ID and AccessKey secret.
    // Note that an AccessKey ID obtained from STS starts with "STS."
    val stsAccessKeyId = "STS.****************"
    val stsAccessKeySecret = "yourAccessKeySecret"
    val stsSecurityToken = "yourSecurityToken"

    // Create a static credential provider and explicitly set the temporary AccessKey pair and STS security token.
    val credentialsProvider = StaticCredentialsProvider(
        accessKeyId = stsAccessKeyId,
        accessKeySecret = stsAccessKeySecret,
        securityToken = stsSecurityToken
    )

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // Specify the region where the bucket is located.
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // Use the created client for subsequent operations...
    }
}

Use a custom access credential

If the preceding methods for configuring credentials do not meet your requirements, you can customize how credentials are provided. The Kotlin SDK lets you customize the credential provider by implementing the CredentialsProvider interface.

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: Implement your custom logic for obtaining credentials.
        
        // Return a long-term credential.
        return Credentials("access_key_id", "access_key_secret")
        
        // Return an STS temporary credential if needed.
        // For temporary credentials, you must refresh them based on their expiration time.
        // return Credentials("sts_access_key_id", "sts_access_key_secret", "security_token")
    }
}

suspend fun main() {
    // Create a custom credential provider.
    val credentialsProvider = CustomCredentialsProvider()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // Specify the region where the bucket is located.
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // Use the created client for subsequent operations...
    }
}

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() {
    // Your original credential provider.
    val baseProvider: CredentialsProvider = CustomCredentialsProvider()
    
    // Wrap with RefreshCredentialsProvider to auto-refresh credentials.
    // The default refresh interval is 300 seconds.
    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 ->
        // Use the created client for subsequent operations...
    }
}

Anonymous access

If you only need to access public-read OSS resources, you can use anonymous access without providing any credentials.

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() {
    // Create an anonymous credential provider.
    val credentialsProvider = AnonymousCredentialsProvider()

    val config = ClientConfiguration.loadDefault().apply {
        this.region = "cn-hangzhou"  // Specify the region where the bucket is located.
        this.credentialsProvider = credentialsProvider
    }

    OSSClient.create(config).use { client ->
        // Use the created client for subsequent operations...
        // Note: Anonymous access can only be used to access public-read resources.
    }
}

Run the CLI example

# Compile the project 
./gradlew :sample:cli:build

# Go to the sample program folder 
cd sample/cli/build/libs/

# Configure access credentials using environment variables
export OSS_ACCESS_KEY_ID="your access key id"
export OSS_ACCESS_KEY_SECRET="your access key secret"

# Example: ListBuckets
java -jar cli-jvm.jar ListBuckets --region cn-hangzhou

Run the UI example

> - Run `sample.composeApp` or `sample[jvm]`.
> - Enter the `AccessKeyId`, `AccessKeySecret`, and `Region`.
> - Click `Set Client` to initialize the client.
> - For example, to list objects, enter a bucket name and click `ListObjects`.