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
Terminal seluler merupakan lingkungan yang tidak tepercaya. Menyimpan AccessKeyId dan AccessKeySecret secara langsung pada terminal untuk menandatangani permintaan menimbulkan ancaman keamanan tinggi. Kami menyarankan agar Anda menggunakan mode autentikasi Security Token Service (STS) atau mode tanda tangan sendiri.
Anda dapat membuat OSSClient dengan salah satu cara berikut.
Untuk mempelajari cara memanggil antarmuka untuk operasi seperti unggah dan unduh, lihat Quick Start (Android SDK).
Metode inisialisasi OSSClient untuk mencantumkan bucket berbeda dari metode umum yang ditunjukkan dalam contoh ini. Untuk informasi selengkapnya, lihat List buckets (Android SDK).
Buat OSSClient menggunakan STS
Kode berikut menunjukkan cara membuat OSSClient menggunakan STS.
// Tetapkan yourEndpoint ke Titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan Titik akhir 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 Titik akhir 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);Konfigurasi OSSClient
ClientConfiguration adalah kelas konfigurasi untuk OSSClient. Anda dapat menggunakan kelas ini untuk mengonfigurasi parameter seperti server proxy, timeout koneksi, dan jumlah koneksi maksimum.
Parameter | Deskripsi | Metode |
maxConcurrentRequest | Jumlah maksimum permintaan bersamaan. 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 di user agent. | ClientConfiguration.setUserAgentMark |
httpDnsEnable | Menentukan apakah akan mengaktifkan HTTPDNS.
| ClientConfiguration.setHttpDnsEnable |
checkCRC64 | Menentukan apakah Pemeriksaan redundansi siklik 64-bit (CRC-64) diaktifkan. Nilai yang valid:
| ClientConfiguration.setCheckCRC64 |
followRedirectsEnable | Menentukan apakah akan mengaktifkan pengalihan HTTP. Nilai valid:
| ClientConfiguration.setFollowRedirectsEnable |
okHttpClient | okHttpClient kustom. | ClientConfiguration.setOkHttpClient |
Kode berikut menunjukkan cara menggunakan ClientConfiguration untuk mengonfigurasi parameter OSSClient.
// Tetapkan yourEndpoint ke Titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan Titik akhir 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 di 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);Mengaktifkan pencatatan log
Lingkungan terminal seluler bersifat kompleks. SDK OSS mungkin tidak berfungsi dengan benar di beberapa wilayah atau selama 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 penayangan 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 exception 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 exception selama panggilan antarmuka sinkron, ClientException atau ServiceException dilemparkan secara langsung. ClientException menunjukkan exception lokal, seperti masalah konektivitas jaringan atau parameter tidak valid. ServiceException menunjukkan kesalahan layanan yang dikembalikan oleh OSS, seperti kegagalan autentikasi atau kesalahan server.
Panggilan asinkron
Untuk antarmuka asinkron, Anda meneruskan fungsi callback saat membuat permintaan. Hasil permintaan diproses di dalam callback.
Ketika terjadi exception selama permintaan asinkron, exception tersebut ditangani di dalam fungsi callback.
Memanggil antarmuka asinkron secara langsung mengembalikan Tugas.
OSSAsyncTask task = oss.asyncGetObejct(...); task.cancel(); // Batalkan tugas. task.waitUntilFinished(); // Tunggu hingga tugas selesai. GetObjectResult result = task.getResult(); // Blokir thread dan tunggu hasilnya.