OSSClient adalah klien Android untuk layanan OSS yang menyediakan metode untuk mengelola bucket dan objek. Sebelum menggunakan kit pengembangan perangkat lunak (SDK) untuk mengirim permintaan ke OSS, Anda harus menginisialisasi instans OSSClient dan mengonfigurasi pengaturannya.
Siklus hidup OSSClient harus sesuai dengan siklus hidup aplikasi. Buat OSSClient secara global saat aplikasi dimulai, dan hapus OSSClient saat aplikasi diakhiri.
Inisialisasi OSSClient
Lingkungan terminal seluler merupakan lingkungan yang tidak tepercaya. Menyimpan AccessKeyId dan AccessKeySecret secara langsung di terminal untuk menandatangani permintaan menimbulkan ancaman keamanan tinggi. Kami menyarankan agar Anda menggunakan mode otentikasi Security Token Service (STS) atau mode tanda tangan sendiri.
Meskipun kredensial STS sementara dapat diekstraksi setelah mencapai klien seluler, Anda tetap harus membatasinya lebih lanjut melalui kebijakan RAM yang membatasi cakupan izin hanya untuk satu pengguna serta periode validitas yang singkat. Untuk skenario yang melibatkan data sensitif seperti KTP, gambar wajah, atau kredensial pembayaran, mintalah server aplikasi Anda menghasilkan URL yang ditandatangani sebelumnya (presigned URL) untuk digunakan oleh aplikasi seluler—aplikasi seluler itu sendiri tidak pernah menyimpan kredensial apa pun. Untuk pemilihan penyedia kredensial, lihat Konfigurasikan kredensial akses (Android SDK). Untuk informasi mengenai URL yang ditandatangani sebelumnya, lihat Otorisasi akses (Android SDK).
Anda dapat membuat OSSClient dengan salah satu cara berikut.
Untuk mempelajari cara memanggil antarmuka untuk operasi seperti unggah dan unduh, lihat Mulai Cepat (Android SDK).
Metode inisialisasi OSSClient untuk menampilkan daftar bucket berbeda dari metode umum yang ditunjukkan dalam contoh ini. Untuk informasi selengkapnya, lihat Tampilkan daftar bucket (Android SDK).
Buat OSSClient menggunakan STS
Kode berikut menunjukkan cara membuat OSSClient menggunakan STS.
// Tetapkan yourEndpoint ke Endpoint wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan Endpoint ke https://oss-cn-hangzhou.aliyuncs.com.
String endpoint = "yourEndpoint";
// ID AccessKey temporary dan Rahasia AccessKey yang diperoleh dari layanan STS.
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// Token keamanan yang diperoleh dari layanan STS.
String securityToken = "yourSecurityToken";
// Tetapkan region ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan region ke cn-hangzhou.
String region = "yourRegion";
OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);
ClientConfiguration config = new ClientConfiguration();
config.setSignVersion(SignVersion.V4);
// Buat instans OSSClient.
OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);Buat OSSClient menggunakan nama domain kustom
Kode berikut menunjukkan cara membuat OSSClient menggunakan nama domain kustom.
// Tetapkan yourEndpoint ke nama domain kustom.
String endpoint = "yourEndpoint";
// ID AccessKey temporary dan Rahasia AccessKey yang diperoleh dari layanan STS.
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// Token keamanan yang diperoleh dari layanan STS.
String securityToken = "yourSecurityToken";
// Tetapkan region ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan region ke cn-hangzhou.
String region = "yourRegion";
OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);
ClientConfiguration config = new ClientConfiguration();
config.setSignVersion(SignVersion.V4);
// Buat instans OSSClient.
OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);Buat OSSClient di lingkungan Apsara Stack atau domain privat
Kode berikut menunjukkan cara membuat OSSClient di lingkungan Apsara Stack atau domain privat.
// Tetapkan yourEndpoint ke Endpoint wilayah tempat bucket berada.
String endpoint = "yourEndpoint";
// ID AccessKey temporary dan Rahasia AccessKey yang diperoleh dari layanan STS.
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// Token keamanan yang diperoleh dari layanan STS.
String securityToken = "yourSecurityToken";
// Tetapkan region ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan region ke cn-hangzhou.
String region = "yourRegion";
OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);
ClientConfiguration configuration = new ClientConfiguration();
// Lewati penguraian CNAME.
List<String> excludeList = new ArrayList<>();
excludeList.add(endpoint);
configuration.setCustomCnameExcludeList(excludeList);
// Buat instans OSSClient.
configuration.setSignVersion(SignVersion.V4);
// Buat instans OSSClient.
OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);Konfigurasikan OSSClient
ClientConfiguration adalah kelas konfigurasi untuk OSSClient. Anda dapat menggunakan kelas ini untuk mengonfigurasi parameter seperti proxy, timeout koneksi, dan jumlah koneksi maksimum.
|
Parameter |
Deskripsi |
Metode |
|
maxConcurrentRequest |
Jumlah maksimum permintaan konkuren. Nilai default: 5. |
ClientConfiguration.setMaxConcurrentRequest |
|
socketTimeout |
Periode timeout untuk transmisi data di lapisan socket, dalam milidetik. Nilai default: 60000. |
ClientConfiguration.setSocketTimeout |
|
connectionTimeout |
Periode timeout untuk membangun koneksi, dalam milidetik. Nilai default: 60000. |
ClientConfiguration.setConnectionTimeout |
|
max_log_size |
Ukuran file log. Nilai default: 5 MB. |
ClientConfiguration.setMaxLogSize |
|
maxErrorRetry |
Jumlah maksimum percobaan ulang setelah permintaan gagal. Nilai default: 2. |
ClientConfiguration.setMaxErrorRetry |
|
customCnameExcludeList |
Elemen dalam daftar akan melewati penguraian canonical name (CNAME). |
ClientConfiguration.setCustomCnameExcludeList |
|
proxyHost |
Alamat host Server proxy. |
ClientConfiguration.setProxyHost |
|
proxyPort |
Port Server proxy. |
ClientConfiguration.setProxyPort |
|
mUserAgentMark |
Header User-Agent HTTP pada user agent. |
ClientConfiguration.setUserAgentMark |
|
httpDnsEnable |
Menentukan apakah HTTPDNS diaktifkan.
|
ClientConfiguration.setHttpDnsEnable |
|
checkCRC64 |
Menentukan apakah Pemeriksaan redundansi siklik 64-bit (CRC-64) diaktifkan. Nilai yang valid:
|
ClientConfiguration.setCheckCRC64 |
|
followRedirectsEnable |
Menentukan apakah Pengalihan HTTP diaktifkan. Nilai yang valid:
|
ClientConfiguration.setFollowRedirectsEnable |
|
okHttpClient |
okHttpClient kustom. |
ClientConfiguration.setOkHttpClient |
Kode berikut menunjukkan cara menggunakan ClientConfiguration untuk mengonfigurasi parameter OSSClient.
// Tetapkan yourEndpoint ke Endpoint wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan Endpoint ke https://oss-cn-hangzhou.aliyuncs.com.
String endpoint = "yourEndpoint";
// ID AccessKey temporary dan Rahasia AccessKey yang diperoleh dari layanan STS.
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// Token keamanan yang diperoleh dari layanan STS.
String securityToken = "yourSecurityToken";
// Tetapkan region ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan region ke cn-hangzhou.
String region = "yourRegion";
ClientConfiguration configuration = new ClientConfiguration();
// Tetapkan jumlah maksimum permintaan konkuren. Nilai default: 5.
// configuration.setMaxConcurrentRequest(3);
// Tetapkan periode timeout untuk transmisi data di lapisan socket. Nilai default: 60 detik.
// configuration.setSocketTimeout(50000);
// Tetapkan periode timeout untuk membangun koneksi. Nilai default: 60 detik.
// configuration.setConnectionTimeout(50000);
// Tetapkan ukuran file log. Nilai default: 5 MB.
// configuration.setMaxLogSize(3 * 1024 * 1024);
// Tetapkan jumlah maksimum percobaan ulang setelah permintaan gagal. Nilai default: 2.
// configuration.setMaxErrorRetry(3);
// Elemen dalam daftar akan melewati penguraian CNAME.
// List<String> cnameExcludeList = new ArrayList<>();
// cnameExcludeList.add("cname");
// configuration.setCustomCnameExcludeList(cnameExcludeList);
// Alamat host Server proxy.
// configuration.setProxyHost("yourProxyHost");
// Port Server proxy.
// configuration.setProxyPort(8080);
// Header User-Agent HTTP pada user agent.
// configuration.setUserAgentMark("yourUserAgent");
// Menentukan apakah Pemeriksaan redundansi siklik (CRC) diaktifkan. Nilai default: false.
// configuration.setCheckCRC64(true);
// Menentukan apakah Pengalihan HTTP diaktifkan. Nilai default: false.
// configuration.setFollowRedirectsEnable(true);
// Tetapkan OkHttpClient kustom.
// OkHttpClient.Builder builder = new OkHttpClient.Builder();
// configuration.setOkHttpClient(builder.build());
OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);
configuration.setSignVersion(SignVersion.V4);
// Buat instans OSSClient.
OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);Aktifkan logging
Lingkungan terminal seluler sangat kompleks. SDK OSS mungkin tidak berfungsi dengan benar di beberapa wilayah atau pada periode tertentu. Untuk membantu developer mengidentifikasi masalah, SDK OSS mencatat informasi log secara lokal setelah fitur logging diaktifkan. Untuk mengaktifkan logging, Anda harus menginisialisasinya sebelum menggunakan OSSClient. Panggil metode berikut.
// Gaya log.
// Panggil OSSLog.enableLog() untuk mengaktifkan penampilan log di Konsol.
// Anda dapat menulis file log ke path \OSSLog\logs.csv pada kartu SD internal ponsel. Fitur ini dinonaktifkan secara default.
// Log mencatat data permintaan, data respons, dan informasi pengecualian untuk operasi OSS.
// Misalnya, requestId dan header respons.
// Berikut adalah contoh catatan log.
// Versi Android.
// android_version: 5.1
// Model ponsel Android.
// mobile_model: XT1085
// Status jaringan.
// network_state: connected
// Jenis koneksi jaringan.
// network_type: WIFI
// Informasi perilaku operasi spesifik.
// [2017-09-05 16:54:52] - Encounter local execpiton: //java.lang.IllegalArgumentException: The bucket name is invalid.
// A bucket name must:
// 1) be comprised of lower-case characters, numbers or dash(-);
// 2) start with lower case or numbers;
// 3) be between 3-63 characters long.
//------>end of log
// Panggil metode ini untuk mengaktifkan logging.
OSSLog.enableLog(); Anda dapat mengunggah file tersebut ke server Anda atau menggunakan Alibaba Cloud Simple Log Service untuk mengunggah file log.
Antarmuka sinkron dan asinkron
SDK Android menyediakan contoh panggilan sinkron dan asinkron untuk antarmuka unggah dan unduh karena permintaan jaringan tidak diizinkan di thread UI dalam pengembangan aplikasi seluler. Untuk antarmuka lainnya, contoh panggilan asinkron merupakan contoh utama yang disediakan.
-
Panggilan sinkron
-
Panggilan antarmuka sinkron memblokir thread hingga hasil dikembalikan.
-
Jangan memanggil antarmuka sinkron di thread UI.
-
Ketika terjadi pengecualian selama panggilan antarmuka sinkron, ClientException atau ServiceException dilemparkan secara langsung. ClientException menunjukkan pengecualian lokal, seperti masalah konektivitas jaringan atau parameter yang tidak valid. ServiceException menunjukkan kesalahan layanan yang dikembalikan oleh OSS, seperti kegagalan otentikasi atau kesalahan server.
-
-
Panggilan asinkron
-
Untuk antarmuka asinkron, Anda meneruskan fungsi callback saat membuat permintaan. Hasil permintaan diproses di dalam callback.
-
Ketika terjadi pengecualian selama permintaan asinkron, pengecualian tersebut ditangani di dalam fungsi callback.
-
Memanggil antarmuka asinkron secara langsung mengembalikan Task.
OSSAsyncTask task = oss.asyncGetObejct(...); task.cancel(); // Batalkan task. task.waitUntilFinished(); // Tunggu hingga task selesai. GetObjectResult result = task.getResult(); // Blokir thread dan tunggu hasilnya.
-