OSS Java SDK V2 - Object Storage Service - Alibaba Cloud Documentation Center

OSS SDK for Java 2.0 memungkinkan aplikasi Java mengunggah, mengunduh, dan mengelola file di Alibaba Cloud Object Storage Service (OSS). SDK ini dirancang untuk pengembang yang membangun situs web dan aplikasi enterprise berbasis penyimpanan file cloud.

GitHub | OSS SDK for Java API | mvnrepository | deepwiki

Quick start

Ikuti langkah-langkah berikut untuk menggunakan OSS Java SDK V2.

Prasyarat

Java 8 atau versi yang lebih baru.

Instal SDK

Kami merekomendasikan menginstal OSS Java SDK V2 dengan Maven.

Maven

Tambahkan dependensi berikut ke file pom.xml Anda. Ganti <version> dengan nomor versi terbaru dari Maven Repository.

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>alibabacloud-oss-v2</artifactId>
    <version><!-- Specify the latest version number--></version>
</dependency>

Kode sumber

Ambil versi terbaru OSS Java SDK V2 dari GitHub, lalu build dan instal menggunakan Maven:

mvn clean install -DskipTests -Dgpg.skip=true

Konfigurasikan kredensial akses

Simpan AccessKey Pengguna RAM dalam variabel lingkungan sebagai kredensial akses Anda.

Linux

Jalankan perintah berikut untuk menambahkan pengaturan variabel lingkungan ke file ~/.bashrc.
```
echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc
```
1. Jalankan perintah berikut untuk menerapkan perubahan.
```
source ~/.bashrc
```
2. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.
```
echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
```

macOS

Jalankan perintah berikut di terminal untuk memeriksa shell default Anda.
```
echo $SHELL
```
1. Ikuti langkah-langkah sesuai jenis shell default Anda.
  Zsh
  1. Jalankan perintah berikut untuk menambahkan pengaturan variabel lingkungan ke file ~/.zshrc.
    echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc
  2. Jalankan perintah berikut untuk menerapkan perubahan.
    source ~/.zshrc
  3. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.
    echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
  Bash
  1. Jalankan perintah berikut untuk menambahkan pengaturan variabel lingkungan ke file ~/.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
  2. Jalankan perintah berikut untuk menerapkan perubahan.
    source ~/.bash_profile
  3. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.
    echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET

Windows

CMD

Jalankan perintah berikut di Command Prompt.

setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.
```
echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%
```

PowerShell

Jalankan perintah berikut di 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)

Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.

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

Inisialisasi client

Penting

Karena adanya perubahan kebijakan untuk meningkatkan kepatuhan dan keamanan, mulai 20 Maret 2025, pengguna OSS baru harus menggunakan nama domain kustom (CNAME) untuk melakukan operasi API data pada bucket OSS yang berada di wilayah daratan Tiongkok. Titik akhir publik default dibatasi untuk operasi ini. Lihat pengumuman resmi untuk daftar lengkap operasi yang terdampak. Jika Anda mengakses data melalui HTTPS, Anda harus mengikat Sertifikat SSL yang valid ke domain kustom Anda. Ini adalah wajib untuk akses Konsol OSS, karena konsol menerapkan HTTPS.

OSSClient mengimplementasikan AutoCloseable. Saat Anda membuat instance menggunakan pernyataan try-with-resources, resource akan dilepas secara otomatis. Anda tidak perlu memanggil metode close() secara manual.

Kami merekomendasikan menggunakan pola singleton untuk menggunakan kembali instance OSSClient. Untuk mencegah kebocoran resource saat menggunakan pola ini, Anda harus memanggil metode close() secara manual sebelum aplikasi dihentikan.

Pola singleton

public class OssClientSingleton {
    private OssClientSingleton() {}

    private static class Holder {
        private static final OSSClient INSTANCE = OSSClient.newBuilder()
            .credentialsProvider(new EnvironmentVariableCredentialsProvider())
            .region("<region-id>")
            .build();
    }

    public static OSSClient getInstance() {
        return Holder.INSTANCE;
    }

    // Menghentikan OSSClient. Ini harus dipanggil secara eksplisit.
    public static void shutdown() {
        try {
            getInstance().close();
        } catch (Exception e) {
            // Tangani exception close.
        }
    }
}

Synchronous OSSClient

Jika Anda ingin menunggu hingga suatu operasi selesai sebelum melanjutkan, gunakan OSSClient sinkron.

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.OSSClientBuilder;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.exceptions.ServiceException;
import com.aliyun.sdk.service.oss2.models.*;
import com.aliyun.sdk.service.oss2.paginator.ListBucketsIterable;

public class Example {
    public static void main(String[] args) {
        String region = "<region-id>";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();
        OSSClientBuilder clientBuilder = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region(region);

        try (OSSClient client = clientBuilder.build()) {

            ListBucketsIterable paginator = client.listBucketsPaginator(
                    ListBucketsRequest.newBuilder()
                            .build());

            for (ListBucketsResult result : paginator) {
                for (BucketSummary info : result.buckets()) {
                    System.out.printf("bucket: name:%s, region:%s, storageClass:%s\n", info.name(), info.region(), info.storageClass());
                }
            }

        } catch (Exception e) {
//            ServiceException se = ServiceException.asCause(e);
//            if (se != null) {
//                System.out.printf("ServiceException: requestId:%s, errorCode:%s\n", se.requestId(), se.errorCode());
//            }
            System.out.printf("error:\n%s", e);
        }
    }
}

Asynchronous OSSClient

Jika Anda perlu memproses beberapa operasi OSS secara konkuren dan tidak bergantung pada hasil setiap operasi, gunakan OSSClient asinkron.

import com.aliyun.sdk.service.oss2.OSSAsyncClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.exceptions.ServiceException;
import com.aliyun.sdk.service.oss2.models.*;

import java.util.concurrent.CompletableFuture;

public class ExampleAsync {
    public static void main(String[] args) {
        String region = "<region-id>";
        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSAsyncClient client = OSSAsyncClient.newBuilder()
                .region(region)
                .credentialsProvider(provider)
                .build()) {

            CompletableFuture<ListBucketsResult> future = client.listBucketsAsync(
                    ListBucketsRequest.newBuilder().build()
            );

            future.thenAccept(result -> {
                        for (BucketSummary info : result.buckets()) {
                            System.out.printf("bucket: name:%s, region:%s, storageClass:%s\n",
                                    info.name(), info.region(), info.storageClass());
                        }
                    })
                    .exceptionally(e -> {
//                ServiceException se = ServiceException.asCause(e);
//                if (se != null) {
//                    System.out.printf("Async ServiceException: requestId:%s, errorCode:%s\n",
//                            se.requestId(), se.errorCode());
//                }
                        System.out.printf("async error:\n%s\n", e);
                        return null;
                    });

            future.join();

        } catch (Exception e) {
            System.out.printf("main error:\n%s\n", e);
        }
    }
}

Setelah menjalankan kode, output akan menampilkan daftar bucket di semua wilayah yang terkait dengan akun Anda.

Konfigurasi client

Konfigurasi client yang didukung

Parameter	Deskripsi
region	(Wajib) Wilayah tempat permintaan dikirim.
credentialsProvider	(Wajib) Kredensial untuk otentikasi.
endpoint	Titik akhir permintaan.
httpClient	HTTP client.
retryMaxAttempts	Jumlah maksimum upaya pengulangan untuk permintaan HTTP. Nilai default adalah 3.
retryer	Kebijakan pengulangan untuk permintaan HTTP.
connectTimeout	Timeout koneksi. Nilai default adalah 5 detik.
readWriteTimeout	Timeout baca/tulis. Nilai default adalah 20 detik.
insecureSkipVerify	Apakah akan melewati verifikasi sertifikat SSL. Nilai default adalah false.
enabledRedirect	Apakah akan mengaktifkan pengalihan HTTP. Nilai default adalah false.
signatureVersion	Versi signature. Nilai default adalah v4.
disableSsl	Apakah akan menonaktifkan HTTPS. Nilai default adalah false.
usePathStyle	Apakah akan menggunakan akses gaya path (misalnya, `https://endpoint/bucket-name`). Nilai default adalah `false`, yang menggunakan akses gaya virtual-hosted (misalnya, `https://bucket-name.endpoint`).
useCName	Apakah akan menggunakan nama domain kustom untuk akses. Nilai default adalah `false`.
useDualStackEndpoint	Apakah akan menggunakan titik akhir dual-stack untuk akses. Nilai default adalah `false`.
useAccelerateEndpoint	Apakah akan menggunakan titik akhir percepatan transfer untuk akses. Nilai default adalah `false`.
useInternalEndpoint	Apakah akan menggunakan titik akhir internal untuk akses. Nilai default adalah `false`.
additionalHeaders	Header permintaan tambahan yang disertakan dalam signature v4.
userAgent	String kustom yang ditambahkan ke header User-Agent.

Nama domain kustom

Menggunakan titik akhir OSS default dapat mencegah Anda mengakses atau melihat pratinjau file. Untuk mengatasi hal ini, Anda dapat menggunakan nama domain kustom untuk mengakses OSS. Hal ini juga memungkinkan Anda melihat pratinjau file langsung di browser dan menggunakan CDN untuk pengiriman konten yang dipercepat.

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // Muat kredensial dari variabel lingkungan untuk otentikasi.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Tentukan wilayah tempat bucket berada.
        String region = "<region-id>";

        // Tentukan nama domain kustom Anda. Misalnya, www.example-***.com.
        String endpoint = "https://www.example-***.com";

        // Buat client OSS dengan konfigurasi yang ditentukan.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                // Catatan: Set useCName ke true. Jika tidak, Anda tidak dapat menggunakan nama domain kustom.
                .useCName(true)
                .build()) {

            // Gunakan client untuk melakukan operasi selanjutnya...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Timeout

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) {
        // Muat kredensial dari variabel lingkungan untuk otentikasi.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Tentukan wilayah tempat bucket berada.
        String region = "<region-id>";

        // Buat client OSS dengan konfigurasi yang ditentukan.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                // Atur timeout koneksi. Nilai default adalah 5 detik.
                .connectTimeout(Duration.ofSeconds(30))
                // Atur timeout baca/tulis. Nilai default adalah 20 detik.
                .readWriteTimeout(Duration.ofSeconds(30))
                .build()) {

            // Gunakan client untuk melakukan operasi selanjutnya...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Kebijakan pengulangan

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;
import com.aliyun.sdk.service.oss2.retry.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) {
        /*
         * Konfigurasi kebijakan pengulangan SDK:
         *
         * Kebijakan pengulangan default:
         * Jika tidak ada kebijakan pengulangan yang dikonfigurasi, SDK menggunakan StandardRetryer sebagai implementasi client default.
         * Pengaturan default adalah sebagai berikut:
         * - maxAttempts: Jumlah maksimum upaya pengulangan. Nilai default adalah 3.
         * - maxBackoff: Waktu backoff maksimum. Nilai default adalah 20 detik.
         * - baseDelay: Delay dasar untuk pengulangan. Nilai default adalah 0,2 detik.
         * - backoffDelayer: Algoritma backoff. Nilai default adalah FullJitter. Rumusnya adalah: [0.0, 1.0) * min(2^attempts * baseDelay, maxBackoff).
         * - errorRetryables: Jenis error yang dapat diulang, termasuk kode status HTTP tertentu, kode error layanan, dan error client.
         *
         * Ketika terjadi error yang dapat diulang, SDK menggunakan pengaturan ini untuk menunda dan kemudian mengulang permintaan.
         * Latensi meningkat dengan setiap pengulangan. Jika nilai default tidak memenuhi kebutuhan Anda,
         * Anda dapat menyesuaikan parameter atau implementasi pengulangan.
         */

        // Muat kredensial dari variabel lingkungan untuk otentikasi.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Tentukan wilayah tempat bucket berada.
        String region = "<region-id>";

        // Contoh konfigurasi kebijakan pengulangan:

        // 1. Sesuaikan jumlah maksimum pengulangan. Nilai default adalah 3. Contoh ini mengatur nilainya menjadi 5.
        Retryer customRetryer = StandardRetryer.newBuilder()
                .maxAttempts(5)
                .build();

        // 2. Sesuaikan waktu delay backoff.
        // Atur baseDelay menjadi 0,5 detik (default: 0,2 detik) dan maxBackoff menjadi 25 detik (default: 20 detik).
        // Retryer customRetryer = StandardRetryer.newBuilder()
        //         .backoffDelayer(new FullJitterBackoff(Duration.ofMillis(500), Duration.ofSeconds(25)))
        //         .build();

        // 3. Sesuaikan algoritma backoff.
        // Gunakan algoritma backoff delay tetap alih-alih FullJitter default. Contoh ini mengatur delay 2 detik untuk setiap pengulangan.
        // Retryer customRetryer = StandardRetryer.newBuilder()
        //         .backoffDelayer(new FixedDelayBackoff(Duration.ofSeconds(2)))
        //         .build();

        // 4. Nonaktifkan kebijakan pengulangan.
        // Gunakan NopRetryer untuk menonaktifkan semua upaya pengulangan.
        // Retryer customRetryer = new NopRetryer();

        // Buat client OSS dengan konfigurasi yang ditentukan.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .retryer(customRetryer)
                .build()) {

            // Gunakan client untuk melakukan operasi selanjutnya...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

HTTP/HTTPS

Untuk menggunakan HTTP alih-alih HTTPS, panggil disableSsl(true).

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // Muat kredensial dari variabel lingkungan untuk otentikasi.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Tentukan wilayah tempat bucket berada.
        String region = "<region-id>";

        // Buat client OSS dengan konfigurasi yang ditentukan.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                // Nonaktifkan permintaan HTTPS.
                .disableSsl(true)
                .build()) {

            // Gunakan client untuk melakukan operasi selanjutnya...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Titik akhir internal

Anda dapat menggunakan titik akhir internal untuk mengakses resource OSS dari layanan Alibaba Cloud di wilayah yang sama. Hal ini mengurangi biaya trafik dan meningkatkan kecepatan akses.

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // Muat kredensial dari variabel lingkungan untuk otentikasi.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Metode 1: Tentukan wilayah dan atur useInternalEndpoint ke true.
        // Tentukan wilayah tempat bucket berada.
        String region = "<region-id>";

        // // Metode 2: Tentukan wilayah dan titik akhir internal.
        // // Tentukan wilayah tempat bucket berada.
        // String region = "<region-id>";
        // // Tentukan titik akhir internal untuk wilayah bucket.
        // String endpoint = "<endpoint>";

        // Buat client OSS dengan konfigurasi yang ditentukan.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .useInternalEndpoint(true)
                // .endpoint(endpoint) // Jika menggunakan Metode 2, hapus komentar baris ini dan beri komentar pada baris `useInternalEndpoint(true)` di atas.
                .build()) {

            // Gunakan client untuk melakukan operasi selanjutnya...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Titik akhir percepatan transfer

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // Muat kredensial dari variabel lingkungan untuk otentikasi.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Metode 1: Tentukan wilayah dan atur useAccelerateEndpoint ke true.
        // Tentukan wilayah tempat bucket berada.
        String region = "<region-id>";

        // // Metode 2: Tentukan wilayah dan titik akhir percepatan transfer.
        // // Tentukan wilayah tempat bucket berada.
        // String region = "<region-id>";
        // // Tentukan titik akhir percepatan transfer untuk wilayah bucket, misalnya 'https://oss-accelerate.aliyuncs.com'.
        // String endpoint = "https://oss-accelerate.aliyuncs.com";

        // Buat client OSS dengan konfigurasi yang ditentukan.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .useAccelerateEndpoint(true)
                // .endpoint(endpoint) // Jika menggunakan Metode 2, hapus komentar baris ini dan beri komentar pada baris `useAccelerateEndpoint(true)` di atas.
                .build()) {

            // Gunakan client untuk melakukan operasi selanjutnya...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Domain privat

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;

public class Example {
    public static void main(String[] args) {
        // Muat kredensial dari variabel lingkungan untuk otentikasi.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Tentukan wilayah tempat bucket berada.
        String region = "<region-id>";

        // Tentukan domain privat Anda, misalnya https://service.corp.example.com.
        String endpoint = "https://service.corp.example.com";

        // Buat client OSS dengan konfigurasi yang ditentukan.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                .build()) {

            // Gunakan client untuk melakukan operasi selanjutnya...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

HTTP client kustom

Jika konfigurasi standar tidak mencukupi, Anda dapat menggunakan HTTP client kustom.

Catatan

Contoh berikut menunjukkan konfigurasi HttpClient kustom untuk client sinkron (OSSClient). Jika Anda menggunakan client asinkron (OSSAsyncClient), ganti Apache5HttpClientBuilder dengan Apache5AsyncHttpClientBuilder. Parameter konfigurasi lainnya sama.

import com.aliyun.sdk.service.oss2.*;
import com.aliyun.sdk.service.oss2.credentials.*;
import com.aliyun.sdk.service.oss2.transport.HttpClient;
import com.aliyun.sdk.service.oss2.transport.HttpClientOptions;
import com.aliyun.sdk.service.oss2.transport.apache5client.Apache5HttpClientBuilder;
import java.time.Duration;

public class Example {
    public static void main(String[] args) {
        // Muat kredensial dari variabel lingkungan untuk otentikasi.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Tentukan wilayah tempat bucket berada.
        String region = "<region-id>";

        // Atur parameter untuk HTTP client.
        HttpClientOptions httpClientOptions = HttpClientOptions.custom()
                // Timeout koneksi. Nilai default adalah 5 detik.
                .connectTimeout(Duration.ofSeconds(30))
                // Timeout baca/tulis. Nilai default adalah 20 detik.
                .readWriteTimeout(Duration.ofSeconds(30))
                // Jumlah maksimum koneksi. Nilai default adalah 1024.
                .maxConnections(2048)
                // Menentukan apakah akan melewati verifikasi sertifikat. Nilai default: false.
                .insecureSkipVerify(false)
                // Menentukan apakah akan mengaktifkan pengalihan HTTP. Nilai default: false.
                .redirectsEnabled(false)
                // Atur server proxy.
                // .proxyHost("http://user:passswd@proxy.example-***.com")
                .build();

        // Buat HTTP client dan teruskan parameter HTTP client.
        HttpClient httpClient = Apache5HttpClientBuilder.create()
                .options(httpClientOptions)
                .build();

        // Buat client OSS menggunakan informasi yang dikonfigurasi.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .httpClient(httpClient)
                .build()) {

            // Gunakan client yang dibuat untuk melakukan operasi selanjutnya...

        } catch (Exception e) {
            System.err.println("Error occurred: " + e.getMessage());
        }
    }
}

Kredensial akses

OSS SDK for Java V2 menyediakan berbagai cara untuk mengonfigurasi kredensial akses. Pilih metode inisialisasi yang sesuai berdasarkan kebutuhan otentikasi dan otorisasi Anda.

Pilih kredensial akses

Metode inisialisasi	Skenario	Dukungan Java SDK V2	Kredensial dasar	Masa berlaku	Rotasi dan refresh
Gunakan pasangan AccessKey Pengguna RAM	Untuk aplikasi yang berjalan di lingkungan aman dan memerlukan akses jangka panjang ke layanan cloud tanpa rotasi kredensial yang sering.	Dukungan bawaan	Pasangan AccessKey	Jangka panjang	Rotasi manual
Gunakan token STS	Untuk aplikasi yang berjalan di lingkungan tidak tepercaya yang memerlukan kontrol atas masa berlaku akses dan izin.	Dukungan bawaan	Token STS	Sementara	Refresh manual
Gunakan kredensial ARN Peran RAM	Untuk akses lintas akun ke resource OSS yang memerlukan kredensial sementara yang diperoleh dengan mengasumsikan Peran RAM.	Dukungan Diperpanjang	Token STS	Sementara	Refresh otomatis
Gunakan kredensial Peran RAM Instans ECS	Untuk aplikasi yang berjalan di instans ECS, instans ECI, atau node pekerja Container Service for Kubernetes.	Dukungan Diperpanjang	Token STS	Sementara	Refresh otomatis
Gunakan kredensial ARN Peran OIDC	Untuk menggunakan fitur RAM Roles for Service Accounts (RRSA) di Container Service for Kubernetes guna mencapai isolasi izin tingkat Pod.	Dukungan Diperpanjang	Token STS	Sementara	Refresh otomatis
Gunakan penyedia kredensial kustom	Jika metode di atas tidak memenuhi kebutuhan Anda, Anda dapat mengimplementasikan cara kustom untuk mendapatkan kredensial.	Dukungan bawaan	Custom	Kustom	Custom
Akses anonim	Akses resource OSS baca-publik tanpa menyediakan kredensial apa pun.	Dukungan bawaan	Tidak ada	Tidak ada	Tidak ada

Fitur yang ditandai sebagai Dukungan ekstensi memerlukan penggunaan metode kredensial akses kustom dengan pustaka manajemen kredensial Alibaba Cloud. SDK menyediakan dukungan bawaan untuk konfigurasi kredensial dasar. Anda dapat mengimplementasikan fitur ekstensi dengan mengintegrasikan pustaka credentials-java.

Gunakan pasangan AccessKey Pengguna RAM

Jika aplikasi Anda berjalan di lingkungan aman yang memerlukan akses jangka panjang ke OSS tanpa rotasi kredensial yang sering, Anda dapat menginisialisasi penyedia kredensial menggunakan pasangan AccessKey (ID AccessKey dan Rahasia AccessKey) dari Akun Alibaba Cloud atau Pengguna RAM. Metode ini mengharuskan Anda memelihara pasangan AccessKey secara manual, sehingga meningkatkan risiko keamanan dan kompleksitas pemeliharaan.

Penting

Akun Alibaba Cloud memiliki izin penuh atas resource-nya. Jika pasangan AccessKey Akun Alibaba Cloud bocor, hal ini menimbulkan risiko keamanan signifikan bagi sistem Anda. Kami merekomendasikan menggunakan pasangan AccessKey Pengguna RAM dengan izin minimum yang diperlukan.
Untuk membuat pasangan AccessKey untuk Pengguna RAM, lihat Buat pasangan AccessKey. ID AccessKey dan Rahasia AccessKey hanya ditampilkan saat pasangan tersebut dibuat. Anda harus segera menyimpannya. Jika Anda lupa pasangan AccessKey tersebut, buat yang baru untuk menggantinya.

Variabel lingkungan

Linux/macOS

Atur variabel lingkungan menggunakan pasangan AccessKey Pengguna RAM:

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

Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah diatur:
```
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)

Kode contoh

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;

public class OSSExample {
    public static void main(String[] args) {
        // Muat informasi kredensial dari variabel lingkungan untuk otentikasi.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();
        
        // Buat client OSS.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("<region-id>") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan client yang dibuat untuk operasi selanjutnya.
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}

Kredensial statis

Kode berikut menunjukkan cara menyematkan kredensial akses dengan secara eksplisit mengatur pasangan AccessKey.

Peringatan

Jangan menyematkan kredensial akses dalam aplikasi produksi Anda. Metode ini hanya untuk tujuan pengujian.

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.StaticCredentialsProvider;

public class OSSExample {
    public static void main(String[] args) {
        // Buat penyedia kredensial statis dan atur secara eksplisit pasangan AccessKey.
        // Ganti dengan ID AccessKey dan Rahasia AccessKey Pengguna RAM Anda.
        CredentialsProvider credentialsProvider = new StaticCredentialsProvider(
                "YOUR_ACCESS_KEY_ID",
                "YOUR_ACCESS_KEY_SECRET"
        );
        
        // Buat client OSS.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("<region-id>") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan client yang dibuat untuk operasi selanjutnya.
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}

Gunakan token STS

Jika aplikasi Anda memerlukan akses sementara ke OSS, Anda dapat menggunakan kredensial akses sementara (ID AccessKey, Rahasia AccessKey, dan token keamanan) yang diperoleh dari Security Token Service (STS) untuk menginisialisasi penyedia kredensial. Metode ini mengharuskan Anda memelihara token STS secara manual, sehingga meningkatkan risiko keamanan dan kompleksitas pemeliharaan. Jika Anda perlu melakukan beberapa permintaan sementara ke OSS, Anda harus merefresh token STS secara manual.

Untuk segera mendapatkan token STS menggunakan API, lihat AssumeRole - Dapatkan kredensial identitas sementara untuk peran RAM.
Untuk mendapatkan token STS menggunakan SDK, lihat Gunakan token STS untuk mengakses OSS.
Anda harus menentukan waktu kedaluwarsa saat menghasilkan token STS. Token tersebut menjadi tidak valid setelah kedaluwarsa.
Untuk daftar titik akhir layanan STS, lihat Titik akhir layanan.

Variabel lingkungan

Penting

Metode ini menggunakan kredensial akses sementara (ID AccessKey, Rahasia AccessKey, dan token keamanan) yang diperoleh dari STS, bukan pasangan AccessKey Pengguna RAM.
ID AccessKey yang diperoleh dari STS diawali dengan "STS", misalnya, "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>

Kode contoh

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;

public class OSSExample {
    public static void main(String[] args) {
        // Muat informasi otentikasi yang diperlukan untuk mengakses OSS dari variabel lingkungan.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();
        
        // Buat client OSS.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("<region-id>") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan client yang dibuat untuk operasi selanjutnya.
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}

Kredensial statis

Kode berikut menunjukkan cara menyematkan kredensial akses dengan secara eksplisit mengatur pasangan AccessKey sementara dan token keamanan.

Peringatan

Jangan menyematkan kredensial akses dalam aplikasi produksi Anda. Metode ini hanya untuk tujuan pengujian.

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.StaticCredentialsProvider;

public class OSSExample {
    public static void main(String[] args) {
        // Tentukan ID AccessKey sementara dan Rahasia AccessKey yang diperoleh.
        // Perhatikan bahwa ID AccessKey yang diperoleh dari STS diawali dengan "STS".
        String stsAccessKeyId = "STS.****************";
        String stsAccessKeySecret = "yourAccessKeySecret";
        String stsSecurityToken = "yourSecurityToken";
        
        // Buat penyedia kredensial statis dan atur secara eksplisit pasangan AccessKey sementara dan token keamanan.
        CredentialsProvider credentialsProvider = new StaticCredentialsProvider(
                stsAccessKeyId,
                stsAccessKeySecret,
                stsSecurityToken
        );
        
        // Buat client OSS.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("<region-id>") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan client yang dibuat untuk operasi selanjutnya.
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}

Gunakan kredensial ARN Peran RAM

Jika aplikasi Anda memerlukan akses berotorisasi ke OSS, seperti untuk akses lintas akun, Anda dapat menggunakan Nama Sumber Daya Alibaba Cloud (ARN) dari peran RAM untuk menginisialisasi penyedia kredensial. Metode ini menggunakan token STS. Saat Anda menentukan ARN peran RAM, alat kredensial secara otomatis mendapatkan dan merefresh token STS dengan memanggil operasi API AssumeRole. Anda juga dapat mengatur parameter policy untuk lebih membatasi izin peran tersebut.

Penting

Akun Alibaba Cloud memiliki izin penuh atas resource-nya. Jika pasangan AccessKey Akun Alibaba Cloud bocor, hal ini menimbulkan risiko keamanan signifikan bagi sistem Anda. Kami merekomendasikan menggunakan pasangan AccessKey Pengguna RAM dengan izin minimum yang diperlukan.
Untuk membuat pasangan AccessKey untuk Pengguna RAM, lihat Buat pasangan AccessKey. ID AccessKey dan Rahasia AccessKey hanya ditampilkan saat pasangan tersebut dibuat. Anda harus segera menyimpannya. Jika Anda lupa pasangan AccessKey tersebut, buat yang baru untuk menggantinya.
Untuk mendapatkan ARN peran RAM, lihat Buat peran RAM.

Tambahkan dependensi

Tambahkan dependensi manajemen kredensial Alibaba Cloud ke file pom.xml Anda:

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>credentials-java</artifactId>
    <version>0.3.4</version>
</dependency>

Konfigurasikan pasangan AccessKey dan ARN Peran RAM

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.Credentials;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProviderSupplier;
// Catatan: Impor berikut berasal dari dependensi eksternal credentials-java.
import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class OSSExample {
    public static void main(String[] args) {
        // Konfigurasikan kredensial ARN Peran RAM.
        Config credentialConfig = new Config()
                .setType("ram_role_arn")
                // Dapatkan pasangan AccessKey Pengguna RAM (ID AccessKey dan Rahasia AccessKey) dari variabel lingkungan.
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                // ARN peran RAM yang akan diasumsikan. Contoh: acs:ram::123456789012****:role/adminrole
                // Anda dapat mengatur RoleArn menggunakan variabel lingkungan ALIBABA_CLOUD_ROLE_ARN.
                .setRoleArn("acs:ram::123456789012****:role/adminrole")
                // Nama sesi peran. Anda dapat mengatur RoleSessionName menggunakan variabel lingkungan ALIBABA_CLOUD_ROLE_SESSION_NAME.
                .setRoleSessionName("your-session-name")
                // Opsional. Kebijakan izin yang lebih restriktif. Contoh: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
                .setPolicy("{\"Statement\": [{\"Action\": [\"*\"],\"Effect\": \"Allow\",\"Resource\": [\"*\"]}],\"Version\":\"1\"}")
                // Opsional. Masa berlaku sesi peran dalam detik. Nilai default adalah 3.600 detik (1 jam).
                .setRoleSessionExpiration(3600);

        Client credentialClient = new Client(credentialConfig);

        // Buat penyedia kredensial untuk memuat kredensial secara dinamis.
        CredentialsProvider credentialsProvider = new CredentialsProviderSupplier(() -> {
            try {
                com.aliyun.credentials.models.CredentialModel cred = credentialClient.getCredential();
                return new Credentials(
                    cred.getAccessKeyId(),
                    cred.getAccessKeySecret(),
                    cred.getSecurityToken()
                );
            } catch (Exception e) {
                throw new RuntimeException("Gagal mendapatkan kredensial", e);
            }
        });

        // Buat instance client OSS.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("<region-id>") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan client untuk operasi selanjutnya.
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}

Gunakan kredensial Peran RAM Instans ECS

Jika aplikasi Anda berjalan di instans ECS, instans ECI, atau node pekerja Container Service for Kubernetes, kami merekomendasikan menggunakan Peran RAM Instans ECS untuk menginisialisasi penyedia kredensial. Metode ini menggunakan token STS. Saat Anda menyambungkan Peran RAM Instans ECS ke instans, SDK secara otomatis mengambil dan merefresh token STS sementara peran tersebut. Metode ini menghilangkan risiko pengelolaan manual pasangan AccessKey atau token STS. Untuk informasi lebih lanjut tentang cara membuat Peran RAM Instans ECS, lihat Buat peran RAM.

Tambahkan dependensi

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>credentials-java</artifactId>
    <version>0.3.4</version>
</dependency>

Konfigurasikan Peran RAM Instans ECS

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.Credentials;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProviderSupplier;
// Catatan: Impor berikut berasal dari dependensi eksternal credentials-java.
import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class OSSExample {
    public static void main(String[] args) {
        // Konfigurasikan kredensial Peran RAM Instans ECS.
        Config credentialConfig = new Config()
                .setType("ecs_ram_role")      // Jenis kredensial akses. Harus ecs_ram_role.
                .setRoleName("EcsRoleExample"); // Opsional. Nama peran RAM yang disambungkan ke instans ECS. Jika Anda tidak mengatur parameter ini, peran akan diambil secara otomatis. Kami sangat menyarankan Anda mengatur parameter ini untuk mengurangi permintaan.

        Client credentialClient = new Client(credentialConfig);

        // Buat penyedia kredensial untuk memuat kredensial secara dinamis.
        CredentialsProvider credentialsProvider = new CredentialsProviderSupplier(() -> {
            try {
                com.aliyun.credentials.models.CredentialModel cred = credentialClient.getCredential();
                return new Credentials(
                    cred.getAccessKeyId(),
                    cred.getAccessKeySecret(),
                    cred.getSecurityToken()
                );
            } catch (Exception e) {
                throw new RuntimeException("Gagal mendapatkan kredensial", e);
            }
        });

        // Buat instance client OSS.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("<region-id>") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan client untuk operasi selanjutnya.
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}

Gunakan kredensial ARN Peran OIDC

Setelah mengonfigurasi peran RAM untuk node pekerja di Container Service for Kubernetes, aplikasi dalam Pod pada node tersebut dapat memperoleh token STS untuk peran yang disambungkan melalui layanan metadata, mirip dengan aplikasi di ECS. Namun, Anda mungkin tidak ingin aplikasi yang tidak tepercaya, seperti yang diajukan oleh pelanggan Anda, memperoleh token STS untuk peran RAM instans node pekerja. Untuk memungkinkan aplikasi tersebut memperoleh token STS yang diperlukan dengan izin minimal sekaligus melindungi resource cloud Anda, Anda dapat menggunakan RAM Roles for Service Accounts (RRSA). Metode ini menggunakan token STS. Kluster container Alibaba Cloud membuat dan memasang file token OpenID Connect (OIDC) yang sesuai untuk Pod aplikasi yang berbeda dan menyuntikkan informasi konfigurasi ke variabel lingkungan. Alat kredensial menggunakan konfigurasi ini untuk memanggil operasi STS AssumeRoleWithOIDC, menukar token OIDC dengan token STS yang terikat peran. Metode ini menghilangkan risiko pengelolaan manual pasangan AccessKey atau token STS. Untuk informasi lebih lanjut, lihat Gunakan RRSA untuk mengonfigurasi izin RAM untuk ServiceAccount dan mengisolasi izin Pod.

Tambahkan dependensi

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>credentials-java</artifactId>
    <version>0.3.4</version>
</dependency>

Konfigurasikan ARN Peran OIDC

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.Credentials;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProviderSupplier;
// Catatan: Impor berikut berasal dari dependensi eksternal credentials-java.
import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class OSSExample {
    public static void main(String[] args) {
        // Konfigurasikan kredensial ARN Peran OIDC.
        Config credentialConfig = new Config()
                // Tentukan jenis kredensial. Harus oidc_role_arn.
                .setType("oidc_role_arn")
                // ARN peran RAM. Anda dapat mengatur RoleArn menggunakan variabel lingkungan ALIBABA_CLOUD_ROLE_ARN.
                .setRoleArn(System.getenv("ALIBABA_CLOUD_ROLE_ARN"))
                // ARN penyedia OIDC. Anda dapat mengatur OidcProviderArn menggunakan variabel lingkungan ALIBABA_CLOUD_OIDC_PROVIDER_ARN.
                .setOidcProviderArn(System.getenv("ALIBABA_CLOUD_OIDC_PROVIDER_ARN"))
                // Jalur file token OIDC. Anda dapat mengatur OidcTokenFilePath menggunakan variabel lingkungan ALIBABA_CLOUD_OIDC_TOKEN_FILE.
                .setOidcTokenFilePath(System.getenv("ALIBABA_CLOUD_OIDC_TOKEN_FILE"))
                // Nama sesi peran. Anda dapat mengatur RoleSessionName menggunakan variabel lingkungan ALIBABA_CLOUD_ROLE_SESSION_NAME.
                .setRoleSessionName("your-session-name")
                // Opsional. Kebijakan izin yang lebih restriktif. Contoh: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
                .setPolicy("{\"Statement\": [{\"Action\": [\"*\"],\"Effect\": \"Allow\",\"Resource\": [\"*\"]}],\"Version\":\"1\"}")
                // Opsional. Masa berlaku sesi peran dalam detik. Nilai default adalah 3.600 detik (1 jam).
                .setRoleSessionExpiration(3600);

        Client credentialClient = new Client(credentialConfig);

        // Buat penyedia kredensial untuk memuat kredensial secara dinamis.
        CredentialsProvider credentialsProvider = new CredentialsProviderSupplier(() -> {
            try {
                com.aliyun.credentials.models.CredentialModel cred = credentialClient.getCredential();
                return new Credentials(
                    cred.getAccessKeyId(),
                    cred.getAccessKeySecret(),
                    cred.getSecurityToken()
                );
            } catch (Exception e) {
                throw new RuntimeException("Gagal mendapatkan kredensial", e);
            }
        });

        // Buat instance client OSS.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("<region-id>") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan client untuk operasi selanjutnya.
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}

Penyedia kredensial kustom

Jika metode di atas tidak memenuhi kebutuhan Anda, Anda dapat mengimplementasikan penyedia kredensial kustom. SDK for Java mendukung berbagai cara untuk melakukan hal ini.

Antarmuka Supplier

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.Credentials;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProviderSupplier;

public class OSSExample {
    public static void main(String[] args) {
        // Buat penyedia kredensial kustom.
        CredentialsProvider credentialsProvider = new CredentialsProviderSupplier(() -> {
            // TODO: Implementasikan logika pengambilan kredensial kustom Anda.
            
            // Kembalikan kredensial jangka panjang.
            return new Credentials("access_key_id", "access_key_secret");
            
            // Kembalikan token STS (jika diperlukan).
            // return new Credentials("sts_access_key_id", "sts_access_key_secret", "security_token");
        });
        
        // Buat client OSS.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("<region-id>") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan client yang dibuat untuk operasi selanjutnya.
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}

Antarmuka CredentialsProvider

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.Credentials;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;

public class CustomCredentialsProvider implements CredentialsProvider {
    
    @Override
    public Credentials getCredentials() {
        // TODO: Implementasikan logika pengambilan kredensial kustom Anda.
        
        // Kembalikan kredensial jangka panjang.
        return new Credentials("access_key_id", "access_key_secret");
        
        // Kembalikan token STS (jika diperlukan).
        // Untuk kredensial sementara, Anda harus merefresh berdasarkan waktu kedaluwarsanya.
        // return new Credentials("sts_access_key_id", "sts_access_key_secret", "security_token");
    }
}

public class OSSExample {
    public static void main(String[] args) {
        // Buat penyedia kredensial kustom.
        CredentialsProvider credentialsProvider = new CustomCredentialsProvider();
        
        // Buat client OSS.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("<region-id>") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan client yang dibuat untuk operasi selanjutnya.
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}

Akses anonim

Jika Anda hanya perlu mengakses resource OSS dengan izin baca-publik, Anda dapat menggunakan akses anonim tanpa menyediakan kredensial.

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.AnonymousCredentialsProvider;

public class OSSExample {
    public static void main(String[] args) {
        // Buat penyedia kredensial anonim.
        CredentialsProvider credentialsProvider = new AnonymousCredentialsProvider();
        
        // Buat client OSS.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("<region-id>") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan client yang dibuat untuk operasi selanjutnya.
            // Catatan: Akses anonim hanya berlaku untuk resource baca-publik.
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}

Kode contoh

Kategori fitur	Deskripsi	Versi Sinkron	Versi Asinkron
Bucket	Buat bucket	PutBucket.java	PutBucketAsync.java
	Daftar bucket	ListBuckets.java	ListBucketsAsync.java
	Dapatkan informasi bucket	GetBucketInfo.java	GetBucketInfoAsync.java
	Dapatkan wilayah bucket	GetBucketLocation.java	GetBucketLocationAsync.java
	Dapatkan statistik penyimpanan bucket	GetBucketStat.java	GetBucketStatAsync.java
	Hapus bucket	DeleteBucket.java	DeleteBucketAsync.java
Unggah objek	Unggah sederhana	PutObject.java	PutObjectAsync.java
	Unggahan tambahan	AppendObject.java	AppendObjectAsync.java
	Unggah multi-bagian	MultipartUpload.java	MultipartUploadAsync.java
	Daftar tugas unggah multi-bagian	ListMultipartUploads.java	ListMultipartUploadsAsync.java
	Daftar bagian yang diunggah	ListParts.java	ListPartsAsync.java
	Batalkan unggah multi-bagian	AbortMultipartUpload.java	AbortMultipartUploadAsync.java
Unduh objek	Unduh sederhana	GetObject.java	GetObjectAsync.java
Manajemen objek	Salin objek	CopyObject.java	CopyObjectAsync.java
	Periksa apakah objek ada	HeadObject.java	HeadObjectAsync.java
	Daftar objek	ListObjects.java	ListObjectsAsync.java
	Daftar objek (V2)	ListObjectsV2.java	ListObjectsV2Async.java
	Hapus objek	DeleteObject.java	DeleteObjectAsync.java
	Hapus beberapa objek	DeleteMultipleObjects.java	DeleteMultipleObjectsAsync.java
	Dapatkan metadata objek	GetObjectMeta.java	GetObjectMetaAsync.java
Objek arsip	Pulihkan objek	RestoreObject.java	RestoreObjectAsync.java
Objek arsip	Bersihkan objek yang dipulihkan	CleanRestoredObject.java	CleanRestoredObjectAsync.java
Tautan simbolik	Buat tautan simbolik	PutSymlink.java	PutSymlinkAsync.java
Tautan simbolik	Dapatkan tautan simbolik	GetSymlink.java	GetSymlinkAsync.java
Tagging objek	Atur tag objek	PutObjectTagging.java	PutObjectTaggingAsync.java
	Dapatkan tag objek	GetObjectTagging.java	GetObjectTaggingAsync.java
	Hapus tag objek	DeleteObjectTagging.java	DeleteObjectTaggingAsync.java
Kontrol akses	Atur ACL bucket	PutBucketAcl.java	PutBucketAclAsync.java
	Dapatkan ACL bucket	GetBucketAcl.java	GetBucketAclAsync.java
	Atur ACL objek	PutObjectAcl.java	PutObjectAclAsync.java
	Dapatkan ACL objek	GetObjectAcl.java	GetObjectAclAsync.java
Pengendalian versi	Atur pengendalian versi bucket	PutBucketVersioning.java	PutBucketVersioningAsync.java
	Dapatkan status pengendalian versi	GetBucketVersioning.java	GetBucketVersioningAsync.java
	Daftar versi objek	ListObjectVersions.java	ListObjectVersionsAsync.java
Cross-Origin Resource Sharing (CORS)	Atur aturan CORS	PutBucketCors.java	PutBucketCorsAsync.java
	Dapatkan aturan CORS	GetBucketCors.java	GetBucketCorsAsync.java
	Hapus aturan CORS	DeleteBucketCors.java	DeleteBucketCorsAsync.java
	Permintaan preflight	OptionObject.java	OptionObjectAsync.java
Fitur sistem	Kueri informasi titik akhir	DescribeRegions.java	DescribeRegionsAsync.java

Quick start

Prasyarat

Instal SDK

Maven

Kode sumber

Konfigurasikan kredensial akses

Linux

macOS

Zsh

Bash

Windows

CMD

PowerShell

Inisialisasi client

Synchronous OSSClient

Asynchronous OSSClient

Konfigurasi client

Nama domain kustom

Timeout

Kebijakan pengulangan

HTTP/HTTPS

Titik akhir internal

Titik akhir percepatan transfer

Domain privat

HTTP client kustom

Kredensial akses

Pilih kredensial akses

Gunakan pasangan AccessKey Pengguna RAM

Variabel lingkungan

Linux/macOS

Windows

CMD

PowerShell

Kode contoh

Kredensial statis

Gunakan token STS

Variabel lingkungan

Linux/macOS

Windows

Kode contoh

Kredensial statis

Gunakan kredensial ARN Peran RAM

Tambahkan dependensi

Konfigurasikan pasangan AccessKey dan ARN Peran RAM

Gunakan kredensial Peran RAM Instans ECS

Tambahkan dependensi

Konfigurasikan Peran RAM Instans ECS

Gunakan kredensial ARN Peran OIDC

Tambahkan dependensi

Konfigurasikan ARN Peran OIDC

Penyedia kredensial kustom

Antarmuka Supplier

Antarmuka CredentialsProvider

Akses anonim

Kode contoh