Object Storage Service：OSS SDK for Java 2.0 (preview)

Prasyarat

Java 8 atau versi yang lebih baru.

Anda dapat menjalankan perintah java -version untuk memeriksa versi Java Anda. Jika Java belum terinstal atau versinya lebih lama dari Java 8, Anda dapat mengunduh dan menginstal Java.

Instal SDK

Anda dapat menggunakan Maven untuk menginstal OSS SDK for Java 2.0.

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

mvn clean install -DskipTests -Dgpg.skip=true

Konfigurasikan kredensial akses

Anda dapat mengonfigurasi kredensial akses dengan menyetel variabel lingkungan menggunakan Pasangan Kunci Akses (AccessKey pair) dari Pengguna RAM.

Di Konsol RAM, buat Pengguna RAM dengan akses Permanent AccessKey Pair. Simpan Pasangan Kunci Akses tersebut, lalu berikan izin AliyunOSSFullAccess kepada pengguna tersebut.

Inisialisasi klien

• OSSClient mengimplementasikan AutoCloseable. Jika Anda membuat instans menggunakan pernyataan try-with-resources, sumber daya akan dilepas secara otomatis tanpa perlu memanggil close() secara manual.

• Membuat dan menghancurkan instans OSSClient merupakan operasi yang memakan waktu. Kami menyarankan agar Anda menggunakan pola singleton untuk menggunakan kembali instans OSSClient. Jika menggunakan pola ini, Anda harus memanggil close() secara manual sebelum aplikasi dihentikan guna mencegah kebocoran sumber daya.

  Pola singleton

  Sebelum menjalankan kode contoh, ganti <region-id> dengan wilayah dan titik akhir yang sebenarnya, seperti ap-southeast-1.

  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;
      }
  
      // Tutup instans OSSClient. Ini harus dipanggil secara eksplisit.
      public static void shutdown() {
          try {
              getInstance().close();
          } catch (Exception e) {
              // Tangani pengecualian saat menutup.
          }
      }
  }
  

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);
        }
    }
}

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);
        }
    }
}

Gunakan nama domain kustom

Jika Anda menggunakan nama domain OSS default untuk akses, Anda mungkin mengalami masalah seperti file tidak dapat diakses atau gagal dipratinjau. Dengan menggunakan nama domain kustom untuk mengakses OSS, Anda dapat langsung mempratinjau file di browser dan menggunakan CDN untuk pengiriman konten yang dipercepat.

Sebelum menjalankan kode contoh, ganti <region-id> dengan wilayah dan titik akhir yang sebenarnya, seperti ap-southeast-1.

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

public class Example {
    public static void main(String[] args) {
        // Muat informasi kredensial dari variabel lingkungan untuk verifikasi identitas.
        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 klien OSS dengan informasi yang telah dikonfigurasi.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                // Catatan: Setel useCName ke true untuk mengaktifkan opsi CNAME. Jika tidak, Anda tidak dapat menggunakan nama domain kustom.
                .useCName(true)
                .build()) {

            // Gunakan klien yang telah dibuat untuk operasi selanjutnya...

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

Kontrol waktu tunggu

Sebelum menjalankan kode contoh, ganti <region-id> dengan wilayah dan titik akhir yang sebenarnya, seperti ap-southeast-1.

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 informasi kredensial dari variabel lingkungan untuk verifikasi identitas.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

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

        // Buat klien OSS dengan informasi yang telah dikonfigurasi.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                // Atur waktu tunggu untuk membangun koneksi. Nilai default adalah 5 detik.
                .connectTimeout(Duration.ofSeconds(30))
                // Atur waktu tunggu untuk membaca dan menulis data. Nilai default adalah 20 detik.
                .readWriteTimeout(Duration.ofSeconds(30))
                .build()) {

            // Gunakan klien yang telah dibuat untuk operasi selanjutnya...

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

Kebijakan pengulangan

Sebelum menjalankan kode contoh, ganti <region-id> dengan wilayah dan titik akhir yang sebenarnya, seperti ap-southeast-1.

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) {
        /*
         * Deskripsi konfigurasi kebijakan pengulangan SDK:
         *
         * Kebijakan pengulangan default:
         * Saat tidak ada kebijakan pengulangan yang dikonfigurasi, SDK menggunakan StandardRetryer sebagai implementasi klien default.
         * Konfigurasi default-nya adalah sebagai berikut:
         * - maxAttempts: Menetapkan jumlah maksimum upaya. Default adalah 3.
         * - maxBackoff: Menetapkan waktu backoff maksimum dalam detik. Default adalah 20 detik.
         * - baseDelay: Menetapkan waktu tunda dasar dalam detik. Default adalah 0,2 detik.
         * - backoffDelayer: Menetapkan algoritma backoff. Default adalah algoritma backoff FullJitter.
         *   Rumus: [0.0, 1.0) * min(2^attempts * baseDelay, maxBackoff)
         * - errorRetryables: Jenis kesalahan yang dapat diulang, termasuk kode status HTTP, kode kesalahan layanan, dan kesalahan klien.
         *
         * Saat terjadi kesalahan yang dapat diulang, konfigurasi yang disediakan digunakan untuk menunda lalu mengulang permintaan.
         * Latensi keseluruhan permintaan meningkat seiring jumlah pengulangan. Jika konfigurasi default
         * tidak memenuhi kebutuhan skenario Anda, Anda dapat mengonfigurasi parameter pengulangan atau memodifikasi implementasi pengulangan.
         */

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

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

        // Contoh konfigurasi kebijakan pengulangan:

        // 1. Sesuaikan jumlah maksimum pengulangan (default adalah 3, di sini diatur menjadi 5).
        Retryer customRetryer = StandardRetryer.newBuilder()
                .maxAttempts(5)
                .build();

        // 2. Sesuaikan waktu tunda backoff.
        // Sesuaikan 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 tunda tetap alih-alih algoritma FullJitter default, dengan tunda 2 detik setiap kali.
        // Retryer customRetryer = StandardRetryer.newBuilder()
        //         .backoffDelayer(new FixedDelayBackoff(Duration.ofSeconds(2)))
        //         .build();

        // 4. Nonaktifkan kebijakan pengulangan.
        // Untuk menonaktifkan semua upaya pengulangan, gunakan implementasi NopRetryer.
        // Retryer customRetryer = new NopRetryer();

        // Buat klien OSS dengan informasi yang telah dikonfigurasi.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .retryer(customRetryer)
                .build()) {

            // Gunakan klien yang telah dibuat untuk operasi selanjutnya...

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

Protokol HTTP/HTTPS

Anda dapat menggunakan disableSsl(true) untuk menonaktifkan HTTPS.

Sebelum menjalankan kode contoh, ganti <region-id> dengan wilayah dan titik akhir yang sebenarnya, seperti ap-southeast-1.

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

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

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

        // Buat klien OSS dengan informasi yang telah dikonfigurasi.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                // Atur agar tidak menggunakan permintaan HTTPS.
                .disableSsl(true)
                .build()) {

            // Gunakan klien yang telah dibuat untuk operasi selanjutnya...

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

Gunakan titik akhir internal

Anda dapat menggunakan titik akhir internal untuk mengakses sumber daya OSS dalam wilayah yang sama. Hal ini mengurangi biaya trafik dan meningkatkan kecepatan akses.

Sebelum menjalankan kode contoh, ganti <region-id> dengan wilayah dan titik akhir yang sebenarnya, seperti ap-southeast-1.

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

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

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

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

        // Buat klien OSS dengan informasi yang telah dikonfigurasi.
        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 sebelumnya.
                .build()) {

            // Gunakan klien yang telah dibuat untuk operasi selanjutnya...

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

Gunakan titik akhir akselerasi transfer

Sebelum menjalankan kode contoh, ganti <region-id> dengan wilayah dan titik akhir yang sebenarnya, seperti ap-southeast-1.

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

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

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

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

        // Buat klien OSS dengan informasi yang telah dikonfigurasi.
        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 sebelumnya.
                .build()) {

            // Gunakan klien yang telah dibuat untuk operasi selanjutnya...

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

Gunakan domain privat

Sebelum menjalankan kode contoh, ganti <region-id> dengan wilayah dan titik akhir yang sebenarnya, seperti ap-southeast-1.

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

public class Example {
    public static void main(String[] args) {
        // Muat informasi kredensial dari variabel lingkungan untuk verifikasi identitas.
        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 klien OSS dengan informasi yang telah dikonfigurasi.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                .build()) {

            // Gunakan klien yang telah dibuat untuk operasi selanjutnya...

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

Gunakan HTTPClient kustom

Jika parameter konfigurasi standar tidak memenuhi kebutuhan Anda, Anda dapat menggunakan klien HTTP kustom.

Sebelum menjalankan kode contoh, ganti <region-id> dengan wilayah dan titik akhir yang sebenarnya, seperti ap-southeast-1.

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 informasi kredensial dari variabel lingkungan untuk verifikasi identitas.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

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

        // Atur parameter untuk klien HTTP.
        HttpClientOptions httpClientOptions = HttpClientOptions.custom()
                // Waktu tunggu koneksi. Nilai default adalah 5 detik.
                .connectTimeout(Duration.ofSeconds(30))
                // Waktu tunggu untuk membaca dan menulis data. Nilai default adalah 20 detik.
                .readWriteTimeout(Duration.ofSeconds(30))
                // Jumlah maksimum koneksi. Nilai default adalah 1024.
                .maxConnections(2048)
                // Menentukan apakah akan melewati verifikasi sertifikat. Secara default, ini bernilai false.
                .insecureSkipVerify(false)
                // Menentukan apakah akan mengaktifkan pengalihan HTTP. Secara default, ini dinonaktifkan.
                .redirectsEnabled(false)
                // Atur server proxy.
                // .proxyHost("http://user:passswd@proxy.example-***.com")
                .build();

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

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

            // Gunakan klien yang telah dibuat untuk operasi selanjutnya...

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

Gunakan kredensial akses kustom

Jika metode konfigurasi kredensial di atas tidak memenuhi kebutuhan Anda, Anda dapat mengimplementasikan metode kustom untuk memperoleh kredensial. SDK Java menyediakan berbagai cara untuk melakukan ini.

Implementasikan melalui antarmuka Supplier

Sebelum menjalankan kode contoh, ganti <region-id> dengan wilayah dan titik akhir yang sebenarnya, seperti ap-southeast-1.

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 klien OSS.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("<region-id>") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan klien yang telah dibuat untuk operasi selanjutnya...
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}

Akses anonim

Jika Anda hanya perlu mengakses sumber daya OSS baca-publik, Anda dapat menggunakan akses anonim tanpa memberikan kredensial.

Sebelum menjalankan kode contoh, ganti <region-id> dengan wilayah dan titik akhir yang sebenarnya, seperti ap-southeast-1.

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 klien OSS.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region("<region-id>") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan klien yang telah dibuat untuk operasi selanjutnya...
            // Catatan: Akses anonim hanya dapat digunakan untuk sumber daya dengan izin baca-publik.
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}