Contoh kode unggah yang dapat dilanjutkan untuk Android SDK - Object Storage Service

Mengunggah file besar melalui jaringan nirkabel bisa memakan waktu lama. Unggahan tersebut berisiko gagal akibat kondisi jaringan yang buruk atau perubahan jaringan, sehingga Anda harus memulai ulang unggahan dari awal. SDK Android menyediakan fitur unggah yang dapat dilanjutkan untuk mengatasi masalah ini.

Catatan penggunaan

OSS SDK untuk Android menyediakan dua metode untuk melakukan unggah yang dapat dilanjutkan: resumableUpload dan sequenceUpload.

(Direkomendasikan) resumableUpload mengunggah beberapa bagian secara paralel, dengan maksimal lima bagian diunggah bersamaan.
sequenceUpload mengunggah bagian-bagian secara berurutan, di mana bagian berikutnya baru diunggah setelah bagian sebelumnya berhasil diunggah.

Topik ini hanya memberikan contoh kode untuk metode resumableUpload. Jika Anda ingin mengunggah beberapa objek menggunakan unggah yang dapat dilanjutkan, buatlah permintaan resumableUpload terpisah untuk masing-masing objek.

Catatan penggunaan

Sebelum menjalankan contoh kode pada topik ini, Anda harus membuat instans OSSClient menggunakan metode seperti nama domain kustom atau Security Token Service (STS). Untuk informasi selengkapnya, lihat Inisialisasi (Android SDK).

Kami menyarankan agar Anda tidak menggunakan unggah yang dapat dilanjutkan untuk objek berukuran kurang dari 5 GB dari perangkat seluler. Fitur ini diimplementasikan menggunakan unggah multi-bagian, sehingga mengunggah satu objek memerlukan beberapa permintaan jaringan dan menjadi tidak efisien. Jika Anda mengunggah objek berukuran lebih dari 5 GB dengan unggah yang dapat dilanjutkan, perhatikan hal-hal berikut:

Sebelum unggah yang dapat dilanjutkan
Sebelum mengunggah objek ke OSS menggunakan unggah yang dapat dilanjutkan, tentukan direktori untuk file titik pemeriksaan yang menyimpan progres unggahan. File titik pemeriksaan hanya berlaku untuk tugas unggah yang sedang berjalan.
- Jika Anda tidak menentukan direktori untuk file titik pemeriksaan dan sebagian objek besar gagal diunggah karena masalah jaringan, Anda harus mengunggah ulang seluruh objek—proses ini memakan waktu lama dan menghabiskan banyak kuota data.
- Jika Anda menentukan direktori untuk file titik pemeriksaan, tugas unggah yang gagal dapat dilanjutkan dari posisi terakhir yang dicatat dalam file tersebut.
Saat unggah yang dapat dilanjutkan
- Unggah yang dapat dilanjutkan hanya mendukung pengunggahan file lokal. Fitur ini juga mendukung callback unggahan, yang digunakan dengan cara yang sama seperti pada tugas unggahan biasa. Untuk informasi selengkapnya, lihat Callback.
- Anda dapat melakukan unggah yang dapat dilanjutkan dengan memanggil operasi API berikut: InitMultipartUpload, UploadPart, ListParts, CompleteMultipartUpload, dan AbortMultipartUpload. Jika Anda menggunakan Security Token Service (STS), pastikan Anda memiliki otorisasi untuk memanggil operasi API tersebut.
- Secara default, validasi MD5 diaktifkan untuk setiap bagian selama unggah yang dapat dilanjutkan. Oleh karena itu, Anda tidak perlu menyetel header Content-Md5 dalam permintaan.
- Jika tugas unggah yang dapat dilanjutkan gagal dan tidak diselesaikan, bagian-bagian yang telah diunggah menjadi tidak diperlukan di OSS. Untuk mengatasinya, konfigurasikan aturan siklus hidup pada bucket tempat bagian-bagian tersebut disimpan agar secara otomatis menghapus bagian-bagian tersebut. Untuk informasi selengkapnya, lihat Konfigurasi aturan siklus hidup.

Contoh

Anda dapat mengunggah file lokal ke OSS secara sinkron atau asinkron menggunakan unggah yang dapat dilanjutkan.

Metode sinkron

Kode contoh berikut menunjukkan cara mengunggah file lokal bernama examplefile.txt secara sinkron ke direktori exampledir dalam bucket examplebucket. Setelah diunggah, objek tersebut diberi nama exampleobject.txt. File titik pemeriksaan disimpan di perangkat Anda.

// Tentukan nama bucket, misalnya examplebucket.
String bucketName = "examplebucket";
// Tentukan jalur lengkap objek, misalnya exampledir/exampleobject.txt. Jalur lengkap tidak boleh mengandung nama bucket.
String objectName = "exampledir/exampleobject.txt";
// Tentukan jalur lengkap file, misalnya /storage/emulated/0/oss/examplefile.txt.
String localFilepath = "/storage/emulated/0/oss/examplefile.txt";

String recordDirectory = Environment.getExternalStorageDirectory().getAbsolutePath() + "/oss_record/";

File recordDir = new File(recordDirectory);

// Pastikan folder untuk menyimpan catatan titik pemeriksaan sudah ada. Jika belum ada, buat folder tersebut.
if (!recordDir.exists()) {
    recordDir.mkdirs();
}

// Buat permintaan unggah yang dapat dilanjutkan dan tentukan jalur penyimpanan file catatan titik pemeriksaan. Jalur tersebut harus berupa jalur mutlak.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath, recordDirectory);
// Saat memanggil metode cancel() pada OSSAsyncTask, atur DeleteUploadOnCancelling ke false. Pengaturan ini mencegah penghapusan file catatan titik pemeriksaan. Saat Anda mengunggah file yang sama di lain waktu, unggahan akan dilanjutkan dari titik pemeriksaan tersebut. Jika parameter ini tidak diatur, nilai default-nya adalah true, yang akan menghapus file catatan titik pemeriksaan. Akibatnya, unggahan berikutnya akan dimulai dari awal.
request.setDeleteUploadOnCancelling(false);
// Atur callback unggahan.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
    @Override
    public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
        Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
    }
});


ResumableUploadResult uploadResult = oss.resumableUpload(request);

Kode contoh berikut menunjukkan cara menggunakan URI file untuk mengunggah file ke OSS dengan penyimpanan terbatas (scoped storage) pada Android 10 atau versi yang lebih baru:

// Tentukan nama bucket, misalnya examplebucket.
String bucketName = "examplebucket";
// Tentukan jalur lengkap objek, misalnya exampledir/exampleobject.txt. Jalur lengkap tidak boleh mengandung nama bucket.
String objectName = "exampledir/exampleobject.txt";

String recordDirectory = getApplication().getFilesDir().getAbsolutePath() + "/oss_record/";

File recordDir = new File(recordDirectory);

// Pastikan folder untuk menyimpan catatan titik pemeriksaan sudah ada. Jika belum ada, buat folder tersebut.
if (!recordDir.exists()) {
    recordDir.mkdirs();
}

// Buat permintaan unggah yang dapat dilanjutkan dan tentukan jalur penyimpanan file catatan titik pemeriksaan. Jalur tersebut harus berupa jalur mutlak.
// Parameter "fileUri" harus diatur ke URI aktual file tersebut.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, fileUri, recordDirectory);
// Saat memanggil metode cancel() pada OSSAsyncTask, atur DeleteUploadOnCancelling ke false. Pengaturan ini mencegah penghapusan file catatan titik pemeriksaan. Saat Anda mengunggah file yang sama di lain waktu, unggahan akan dilanjutkan dari titik pemeriksaan tersebut. Jika parameter ini tidak diatur, nilai default-nya adalah true, yang akan menghapus file catatan titik pemeriksaan. Akibatnya, unggahan berikutnya akan dimulai dari awal.
request.setDeleteUploadOnCancelling(false);
// Atur callback unggahan.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
    @Override
    public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
        Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
    }
});


ResumableUploadResult uploadResult = oss.resumableUpload(request);

Kode contoh berikut menunjukkan cara melakukan unggah yang dapat dilanjutkan tanpa menyimpan file titik pemeriksaan di perangkat Anda:

// Tentukan nama bucket, misalnya examplebucket.
String bucketName = "examplebucket";
// Tentukan jalur lengkap objek, misalnya exampledir/exampleobject.txt. Jalur lengkap tidak boleh mengandung nama bucket.
String objectName = "exampledir/exampleobject.txt";
// Tentukan jalur lengkap file, misalnya /storage/emulated/0/oss/examplefile.txt.
String localFilepath = "/storage/emulated/0/oss/examplefile.txt";

// Buat permintaan unggah yang dapat dilanjutkan.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath);
// Atur callback unggahan.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
    @Override
    public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
        Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
    }
});


ResumableUploadResult uploadResult = oss.resumableUpload(request);

Metode asinkron

Kode contoh berikut menunjukkan cara mengunggah file lokal bernama examplefile.txt secara asinkron ke direktori exampledir dalam bucket examplebucket. Setelah diunggah, objek tersebut diberi nama exampleobject.txt. File titik pemeriksaan disimpan di perangkat Anda.

// Tentukan nama bucket, misalnya examplebucket.
String bucketName = "examplebucket";
// Tentukan jalur lengkap objek, misalnya exampledir/exampleobject.txt. Jalur lengkap tidak boleh mengandung nama bucket.
String objectName = "exampledir/exampleobject.txt";
// Tentukan jalur lengkap file, misalnya /storage/emulated/0/oss/examplefile.txt.
String localFilepath = "/storage/emulated/0/oss/examplefile.txt";
String recordDirectory = Environment.getExternalStorageDirectory().getAbsolutePath() + "/oss_record/";

File recordDir = new File(recordDirectory);

// Pastikan jalur untuk menyimpan catatan titik pemeriksaan sudah ada. Jika belum ada, buat jalur tersebut.
if (!recordDir.exists()) {
    recordDir.mkdirs();
}

// Buat permintaan unggah yang dapat dilanjutkan dan tentukan jalur penyimpanan file catatan titik pemeriksaan. Jalur tersebut harus berupa jalur mutlak.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath, recordDirectory);
// Saat memanggil metode cancel() pada OSSAsyncTask, atur DeleteUploadOnCancelling ke false. Pengaturan ini mencegah penghapusan file catatan titik pemeriksaan. Saat Anda mengunggah file yang sama di lain waktu, unggahan akan dilanjutkan dari titik pemeriksaan tersebut. Jika parameter ini tidak diatur, nilai default-nya adalah true, yang akan menghapus file catatan titik pemeriksaan. Akibatnya, unggahan berikutnya akan dimulai dari awal.
request.setDeleteUploadOnCancelling(false);
// Atur callback progres unggahan.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
    @Override
    public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
        Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
    }
});


OSSAsyncTask resumableTask = oss.asyncResumableUpload(request, new OSSCompletedCallback<ResumableUploadRequest, ResumableUploadResult>() {
    @Override
    public void onSuccess(ResumableUploadRequest request, ResumableUploadResult result) {
        Log.d("resumableUpload", "success!");
    }

    @Override
    public void onFailure(ResumableUploadRequest request, ClientException clientExcepion, ServiceException serviceException) {
        // Tangani exception.
    }
});

// Tunggu hingga tugas unggah yang dapat dilanjutkan selesai.
resumableTask.waitUntilFinished();

Kode contoh berikut menunjukkan cara menggunakan URI file untuk mengunggah file ke OSS dengan penyimpanan terbatas (scoped storage) pada Android 10 atau versi yang lebih baru:

// Tentukan nama bucket, misalnya examplebucket.
String bucketName = "examplebucket";
// Tentukan jalur lengkap objek, misalnya exampledir/exampleobject.txt. Jalur lengkap tidak boleh mengandung nama bucket.
String objectName = "exampledir/exampleobject.txt";
String recordDirectory = getApplication().getFilesDir().getAbsolutePath() + "/oss_record/";

File recordDir = new File(recordDirectory);

// Pastikan folder untuk menyimpan catatan titik pemeriksaan sudah ada. Jika belum ada, buat folder tersebut.
if (!recordDir.exists()) {
    recordDir.mkdirs();
}

// Buat permintaan unggah yang dapat dilanjutkan dan tentukan jalur penyimpanan file catatan titik pemeriksaan. Jalur tersebut harus berupa jalur mutlak.
// Parameter "fileUri" harus diatur ke URI aktual file tersebut.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, fileUri, recordDirectory);
// Saat memanggil metode cancel() pada OSSAsyncTask, atur DeleteUploadOnCancelling ke false. Pengaturan ini mencegah penghapusan file catatan titik pemeriksaan. Saat Anda mengunggah file yang sama di lain waktu, unggahan akan dilanjutkan dari titik pemeriksaan tersebut. Jika parameter ini tidak diatur, nilai default-nya adalah true, yang akan menghapus file catatan titik pemeriksaan. Akibatnya, unggahan berikutnya akan dimulai dari awal.
request.setDeleteUploadOnCancelling(false);
// Atur callback unggahan.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
    @Override
    public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
        Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
    }
});


OSSAsyncTask resumableTask = oss.asyncResumableUpload(request, new OSSCompletedCallback<ResumableUploadRequest, ResumableUploadResult>() {
    @Override
    public void onSuccess(ResumableUploadRequest request, ResumableUploadResult result) {
        Log.d("resumableUpload", "success!");
    }

    @Override
    public void onFailure(ResumableUploadRequest request, ClientException clientExcepion, ServiceException serviceException) {
        // Tangani exception.
    }
});

// Tunggu hingga tugas unggah yang dapat dilanjutkan selesai.
resumableTask.waitUntilFinished();

Kode contoh berikut menunjukkan cara melakukan unggah yang dapat dilanjutkan tanpa menyimpan file titik pemeriksaan di perangkat Anda:

// Tentukan nama bucket, misalnya examplebucket.
String bucketName = "examplebucket";
// Tentukan jalur lengkap objek, misalnya exampledir/exampleobject.txt. Jalur lengkap tidak boleh mengandung nama bucket.
String objectName = "exampledir/exampleobject.txt";
// Tentukan jalur lengkap file, misalnya /storage/emulated/0/oss/examplefile.txt.
String localFilepath = "/storage/emulated/0/oss/examplefile.txt";

// Buat permintaan unggah yang dapat dilanjutkan.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath);

// Atur callback progres unggahan.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
    @Override
    public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
        Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
    }
});
// Panggil metode unggah yang dapat dilanjutkan secara asinkron.
OSSAsyncTask resumableTask = oss.asyncResumableUpload(request, new OSSCompletedCallback<ResumableUploadRequest, ResumableUploadResult>() {
    @Override
    public void onSuccess(ResumableUploadRequest request, ResumableUploadResult result) {
        Log.d("resumableUpload", "success!");
    }

    @Override
    public void onFailure(ResumableUploadRequest request, ClientException clientExcepion, ServiceException serviceException) {
        // Tangani exception.
    }
});

// Tunggu hingga tugas unggah yang dapat dilanjutkan selesai.
resumableTask.waitUntilFinished();

Referensi

Untuk informasi selengkapnya tentang cara mengonfigurasi aturan siklus hidup untuk bucket, lihat Konfigurasi aturan siklus hidup.
Untuk informasi selengkapnya tentang cara mengimplementasikan callback unggahan dalam unggah yang dapat dilanjutkan, lihat Callback.
Untuk informasi selengkapnya tentang cara menginisialisasi instans OSSClient, lihat Inisialisasi.