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, unduh dan instal Java.

Instal SDK

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

<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

Atur pasangan AccessKey pengguna RAM sebagai variabel lingkungan untuk menggunakannya sebagai kredensial.

Di Konsol RAM, buat pengguna RAM dan Permanent AccessKey Pair untuk akses. Simpan pasangan AccessKey tersebut dan berikan izin AliyunOSSFullAccess kepada pengguna.

Inisialisasi client

Inisialisasi OSSClient dengan menentukan wilayah.

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

• Pembuatan dan penghancuran instans OSSClient bisa 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 untuk mencegah kebocoran resource.

  Pola Singleton

  public class OssClientSingleton {
      private OssClientSingleton() {}
  
      private static class Holder {
          private static final OSSClient INSTANCE = OSSClient.newBuilder()
              .credentialsProvider(new EnvironmentVariableCredentialsProvider())
              .region("cn-hangzhou")
              .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 exception saat penutupan.
          }
      }
  }
  

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 = "cn-hangzhou";

        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 = "cn-hangzhou";
        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. Jika Anda menggunakan nama domain kustom untuk mengakses OSS, Anda dapat mempratinjau 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 informasi kredensial dari variabel lingkungan untuk verifikasi identitas.
        CredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();

        // Tentukan wilayah tempat bucket berada. Misalnya, untuk China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

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

        // Buat client OSS dengan informasi yang dikonfigurasi.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .endpoint(endpoint)
                // Catatan: Atur useCName ke true untuk mengaktifkan opsi CNAME. Jika tidak, Anda tidak dapat menggunakan nama domain kustom.
                .useCName(true)
                .build()) {

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

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

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

        // Tentukan wilayah tempat bucket berada. Misalnya, untuk China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

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

            // Gunakan client yang dibuat untuk 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) {
        /*
         * Deskripsi konfigurasi kebijakan pengulangan SDK:
         *
         * Kebijakan pengulangan default:
         * Saat tidak ada kebijakan pengulangan yang dikonfigurasi, SDK menggunakan StandardRetryer sebagai implementasi client 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 delay dasar dalam detik. Default adalah 0,2 detik.
         * - backoffDelayer: Menetapkan algoritma backoff. Default adalah algoritma FullJitter.
         *   Formula: [0.0, 1.0) * min(2^attempts * baseDelay, maxBackoff)
         * - errorRetryables: Jenis kesalahan yang dapat diulang, termasuk kode status HTTP, kode kesalahan layanan, dan kesalahan client.
         *
         * 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. Misalnya, untuk China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

        // 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 delay 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 delay tetap alih-alih algoritma FullJitter default, dengan delay 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 client OSS dengan informasi yang dikonfigurasi.
        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(credentialsProvider)
                .region(region)
                .retryer(customRetryer)
                .build()) {

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

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

Protokol HTTP/HTTPS

Anda dapat menggunakan disableSsl(true) untuk menonaktifkan protokol HTTPS.

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. Misalnya, untuk China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

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

            // Gunakan client yang 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 resource OSS dalam wilayah yang sama guna 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 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. Misalnya, untuk China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

        // // Metode 2: Langsung tentukan wilayah dan titik akhir.
        // // Tentukan wilayah tempat bucket berada. Misalnya, untuk China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        // String region = "cn-hangzhou";
        // // Tentukan titik akhir internal untuk wilayah bucket tersebut. Untuk China (Hangzhou), titik akhirnya adalah 'oss-cn-hangzhou-internal.aliyuncs.com'.
        // String endpoint = "oss-cn-hangzhou-internal.aliyuncs.com";

        // Buat client OSS dengan informasi yang 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 client yang dibuat untuk operasi selanjutnya...

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

Gunakan titik akhir akselerasi transfer

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. Misalnya, untuk China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

        // // Metode 2: Langsung tentukan wilayah dan titik akhir akselerasi transfer.
        // // Tentukan wilayah tempat bucket berada. Misalnya, untuk China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        // String region = "cn-hangzhou";
        // // Tentukan titik akhir akselerasi transfer untuk wilayah bucket tersebut, misalnya 'https://oss-accelerate.aliyuncs.com'.
        // String endpoint = "https://oss-accelerate.aliyuncs.com";

        // Buat client OSS dengan informasi yang 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 client yang dibuat untuk operasi selanjutnya...

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

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

        // Tentukan wilayah tempat bucket berada. Misalnya, untuk China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

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

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

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

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

Gunakan nama domain Alibaba Gov Cloud

Kode contoh berikut menunjukkan cara mengonfigurasi OSSClient menggunakan nama domain Alibaba Gov Cloud.

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 dan titik akhir.
        // Tentukan wilayah tempat bucket berada. Untuk Alibaba Gov Cloud 1 China (Beijing), atur wilayah menjadi cn-north-2-gov-1.
        String region = "cn-north-2-gov-1";
        // Tentukan titik akhir internal untuk wilayah bucket tersebut. Untuk Alibaba Gov Cloud 1 China (Beijing), titik akhirnya adalah 'https://oss-cn-north-2-gov-1-internal.aliyuncs.com'.
        // Untuk menentukan protokol HTTP, atur domain menjadi 'http://oss-cn-north-2-gov-1-internal.aliyuncs.com'.
        String endpoint = "https://oss-cn-north-2-gov-1-internal.aliyuncs.com";

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

            // Gunakan client yang 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 HTTP client kustom.

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. Misalnya, untuk China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

        // Atur parameter untuk HTTP client.
        HttpClientOptions httpClientOptions = HttpClientOptions.custom()
                // Timeout koneksi. Nilai default adalah 5 detik.
                .connectTimeout(Duration.ofSeconds(30))
                // Timeout 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 verifikasi sertifikat dilewati. Secara default, ini false.
                .insecureSkipVerify(false)
                // Menentukan apakah pengalihan HTTP diaktifkan. Secara default, ini dinonaktifkan.
                .redirectsEnabled(false)
                // Atur server proxy.
                // .proxyHost("http://user:passswd@proxy.example-***.com")
                .build();

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

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

            // Gunakan client yang 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 menyesuaikan cara memperoleh kredensial tersebut. SDK Java mendukung berbagai metode implementasi untuk tujuan ini.

Implementasikan melalui 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("cn-hangzhou") // 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 sumber daya Object Storage Service (OSS) dengan izin public-read, Anda dapat menggunakan akses anonim tanpa menyediakan kredensial apa pun.

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("cn-hangzhou") // Tentukan wilayah tempat bucket berada.
                .build()) {
            
            // Gunakan client yang telah dibuat untuk operasi selanjutnya...
            // Catatan: Akses anonim hanya dapat digunakan untuk sumber daya dengan izin public-read.
            
        } catch (Exception e) {
            System.err.println("Operasi gagal: " + e.getMessage());
        }
    }
}