Mengupload file dengan Cloud Storage di Android

Cloud Storage for Firebase memungkinkan Anda mengupload file dengan cepat dan mudah ke bucket Cloud Storage yang disediakan dan dikelola oleh Firebase.

Upload File

Untuk mengupload file ke Cloud Storage, buat referensi ke jalur lengkap file terlebih dahulu, termasuk nama filenya.

Kotlin

// Create a storage reference from our app
val storageRef = storage.reference

// Create a reference to "mountains.jpg"
val mountainsRef = storageRef.child("mountains.jpg")

// Create a reference to 'images/mountains.jpg'
val mountainImagesRef = storageRef.child("images/mountains.jpg")

// While the file names are the same, the references point to different files
mountainsRef.name == mountainImagesRef.name // true
mountainsRef.path == mountainImagesRef.path // false

Java

// Create a storage reference from our app
StorageReference storageRef = storage.getReference();

// Create a reference to "mountains.jpg"
StorageReference mountainsRef = storageRef.child("mountains.jpg");

// Create a reference to 'images/mountains.jpg'
StorageReference mountainImagesRef = storageRef.child("images/mountains.jpg");

// While the file names are the same, the references point to different files
mountainsRef.getName().equals(mountainImagesRef.getName());    // true
mountainsRef.getPath().equals(mountainImagesRef.getPath());    // false

Setelah Anda membuat referensi yang sesuai, panggil metode putBytes(), putFile(), atau putStream() untuk mengupload file ke Cloud Storage.

Anda tidak dapat mengupload data dengan referensi ke root bucket Cloud Storage. Referensi Anda harus mengarah ke URL turunan.

Mengupload dari data di memori

Metode putBytes() adalah cara termudah untuk mengupload file ke Cloud Storage. putBytes() menggunakan byte[] dan menampilkan UploadTask yang dapat Anda gunakan untuk mengelola serta memantau status upload.

Kotlin

// Get the data from an ImageView as bytes
imageView.isDrawingCacheEnabled = true
imageView.buildDrawingCache()
val bitmap = (imageView.drawable as BitmapDrawable).bitmap
val baos = ByteArrayOutputStream()
bitmap.compress(Bitmap.CompressFormat.JPEG, 100, baos)
val data = baos.toByteArray()

var uploadTask = mountainsRef.putBytes(data)
uploadTask.addOnFailureListener {
    // Handle unsuccessful uploads
}.addOnSuccessListener { taskSnapshot ->
    // taskSnapshot.metadata contains file metadata such as size, content-type, etc.
    // ...
}

Java

// Get the data from an ImageView as bytes
imageView.setDrawingCacheEnabled(true);
imageView.buildDrawingCache();
Bitmap bitmap = ((BitmapDrawable) imageView.getDrawable()).getBitmap();
ByteArrayOutputStream baos = new ByteArrayOutputStream();
bitmap.compress(Bitmap.CompressFormat.JPEG, 100, baos);
byte[] data = baos.toByteArray();

UploadTask uploadTask = mountainsRef.putBytes(data);
uploadTask.addOnFailureListener(new OnFailureListener() {
    @Override
    public void onFailure(@NonNull Exception exception) {
        // Handle unsuccessful uploads
    }
}).addOnSuccessListener(new OnSuccessListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onSuccess(UploadTask.TaskSnapshot taskSnapshot) {
        // taskSnapshot.getMetadata() contains file metadata such as size, content-type, etc.
        // ...
    }
});

Karena putBytes() menerima byte[], aplikasi Anda harus menampung seluruh konten file dalam memori sekaligus. Sebaiknya gunakan putStream() atau putFile() agar penggunaan memori lebih kecil.

Mengupload dari stream

Metode putStream() adalah cara yang paling fleksibel untuk mengupload file ke Cloud Storage. putStream() menggunakan InputStream dan menampilkan UploadTask yang dapat Anda gunakan untuk mengelola serta memantau status upload.

Kotlin

val stream = FileInputStream(File("path/to/images/rivers.jpg"))

uploadTask = mountainsRef.putStream(stream)
uploadTask.addOnFailureListener {
    // Handle unsuccessful uploads
}.addOnSuccessListener { taskSnapshot ->
    // taskSnapshot.metadata contains file metadata such as size, content-type, etc.
    // ...
}

Java

InputStream stream = new FileInputStream(new File("path/to/images/rivers.jpg"));

uploadTask = mountainsRef.putStream(stream);
uploadTask.addOnFailureListener(new OnFailureListener() {
    @Override
    public void onFailure(@NonNull Exception exception) {
        // Handle unsuccessful uploads
    }
}).addOnSuccessListener(new OnSuccessListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onSuccess(UploadTask.TaskSnapshot taskSnapshot) {
        // taskSnapshot.getMetadata() contains file metadata such as size, content-type, etc.
        // ...
    }
});

Mengupload dari file lokal

Anda dapat mengupload file lokal pada perangkat, seperti foto dan video dari kamera, dengan metode putFile(). putFile() menggunakan File dan menampilkan UploadTask yang dapat Anda gunakan untuk mengelola serta memantau status upload.

Kotlin

var file = Uri.fromFile(File("path/to/images/rivers.jpg"))
val riversRef = storageRef.child("images/${file.lastPathSegment}")
uploadTask = riversRef.putFile(file)

// Register observers to listen for when the download is done or if it fails
uploadTask.addOnFailureListener {
    // Handle unsuccessful uploads
}.addOnSuccessListener { taskSnapshot ->
    // taskSnapshot.metadata contains file metadata such as size, content-type, etc.
    // ...
}

Java

Uri file = Uri.fromFile(new File("path/to/images/rivers.jpg"));
StorageReference riversRef = storageRef.child("images/"+file.getLastPathSegment());
uploadTask = riversRef.putFile(file);

// Register observers to listen for when the download is done or if it fails
uploadTask.addOnFailureListener(new OnFailureListener() {
    @Override
    public void onFailure(@NonNull Exception exception) {
        // Handle unsuccessful uploads
    }
}).addOnSuccessListener(new OnSuccessListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onSuccess(UploadTask.TaskSnapshot taskSnapshot) {
        // taskSnapshot.getMetadata() contains file metadata such as size, content-type, etc.
        // ...
    }
});

Mendapatkan URL download

Setelah mengupload file, Anda bisa mendapatkan URL untuk mendownload file tersebut dengan memanggil metode getDownloadUrl() pada StorageReference:

Kotlin

val ref = storageRef.child("images/mountains.jpg")
uploadTask = ref.putFile(file)

val urlTask = uploadTask.continueWithTask { task ->
    if (!task.isSuccessful) {
        task.exception?.let {
            throw it
        }
    }
    ref.downloadUrl
}.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val downloadUri = task.result
    } else {
        // Handle failures
        // ...
    }
}

Java

final StorageReference ref = storageRef.child("images/mountains.jpg");
uploadTask = ref.putFile(file);

Task<Uri> urlTask = uploadTask.continueWithTask(new Continuation<UploadTask.TaskSnapshot, Task<Uri>>() {
    @Override
    public Task<Uri> then(@NonNull Task<UploadTask.TaskSnapshot> task) throws Exception {
        if (!task.isSuccessful()) {
            throw task.getException();
        }

        // Continue with the task to get the download URL
        return ref.getDownloadUrl();
    }
}).addOnCompleteListener(new OnCompleteListener<Uri>() {
    @Override
    public void onComplete(@NonNull Task<Uri> task) {
        if (task.isSuccessful()) {
            Uri downloadUri = task.getResult();
        } else {
            // Handle failures
            // ...
        }
    }
});

Menambahkan Metadata File

Anda juga dapat menyertakan metadata ketika mengupload file. Metadata ini berisi properti metadata file standar, seperti name, size, dan contentType (umumnya dikenal sebagai jenis MIME). Metode putFile() secara otomatis menyimpulkan jenis MIME dari ekstensi File, tetapi Anda bisa mengganti jenis yang terdeteksi otomatis dengan menetapkan contentType pada metadata. Jika Anda tidak menyediakan contentType dan Cloud Storage tidak dapat menyimpulkan default dari ekstensi file, Cloud Storage akan menggunakan application/octet-stream. Baca bagian Menggunakan Metadata File untuk mengetahui informasi selengkapnya mengenai metadata file.

Kotlin

// Create file metadata including the content type
var metadata = storageMetadata {
    contentType = "image/jpg"
}

// Upload the file and metadata
uploadTask = storageRef.child("images/mountains.jpg").putFile(file, metadata)

Java

// Create file metadata including the content type
StorageMetadata metadata = new StorageMetadata.Builder()
        .setContentType("image/jpg")
        .build();

// Upload the file and metadata
uploadTask = storageRef.child("images/mountains.jpg").putFile(file, metadata);

Mengelola Upload

Selain memulai upload, Anda dapat menjeda, melanjutkan, dan membatalkan upload menggunakan metode pause(), resume(), dan cancel(). Peristiwa jeda menyebabkan perubahan status pause dan peristiwa lanjutkan menyebabkan perubahan status progress. Jika dibatalkan, upload akan gagal dengan pesan error yang menunjukkan bahwa upload telah dibatalkan.

Kotlin

uploadTask = storageRef.child("images/mountains.jpg").putFile(file)

// Pause the upload
uploadTask.pause()

// Resume the upload
uploadTask.resume()

// Cancel the upload
uploadTask.cancel()

Java

uploadTask = storageRef.child("images/mountains.jpg").putFile(file);

// Pause the upload
uploadTask.pause();

// Resume the upload
uploadTask.resume();

// Cancel the upload
uploadTask.cancel();

Memantau Progres Upload

Anda dapat menambahkan pemroses untuk menangani keberhasilan, kegagalan, progres, atau jeda dalam tugas upload:

Jenis Pemroses Penggunaan Standar
OnProgressListener Pemroses ini dipanggil secara berkala saat data ditransfer dan dapat digunakan untuk mengisi indikator upload/download.
OnPausedListener Pemroses ini dipanggil saat tugas dijeda.
OnSuccessListener Pemroses ini dipanggil saat tugas berhasil diselesaikan.
OnFailureListener Pemroses ini dipanggil saat upload gagal. Hal ini dapat terjadi karena waktu tunggu jaringan habis, kegagalan otorisasi, atau jika Anda membatalkan tugas.

OnFailureListener dipanggil dengan instance Exception. Pemroses lain dipanggil dengan objek UploadTask.TaskSnapshot. Objek ini adalah tampilan tetap dari tugas pada saat peristiwa terjadi. UploadTask.TaskSnapshot berisi properti berikut:

Properti Jenis Deskripsi
getDownloadUrl String URL yang dapat digunakan untuk mendownload objek. Ini adalah URL bersifat publik yang tidak dapat ditebak, yang dapat dibagikan dengan klien lain. Nilai ini diisi setelah upload selesai.
getError Exception Jika tugas gagal, penyebabnya akan muncul sebagai Exception.
getBytesTransferred long Total jumlah byte yang telah ditransfer saat snapshot ini diambil.
getTotalByteCount long Total perkiraan jumlah byte yang akan diupload.
getUploadSessionUri String URI yang dapat digunakan untuk melanjutkan tugas ini melalui panggilan lain ke putFile.
getMetadata StorageMetadata Sebelum upload selesai, ini adalah metadata yang dikirim ke server. Setelah upload selesai, ini adalah metadata yang ditampilkan oleh server.
getTask UploadTask Tugas yang membuat snapshot ini. Gunakan tugas ini untuk membatalkan, menjeda, atau melanjutkan upload.
getStorage StorageReference StorageReference yang digunakan untuk membuat UploadTask.

Pemroses peristiwa UploadTask memberikan cara sederhana dan efektif untuk memantau peristiwa upload.

Kotlin

// Observe state change events such as progress, pause, and resume
// You'll need to import com.google.firebase.storage.component1 and
// com.google.firebase.storage.component2
uploadTask.addOnProgressListener { (bytesTransferred, totalByteCount) ->
    val progress = (100.0 * bytesTransferred) / totalByteCount
    Log.d(TAG, "Upload is $progress% done")
}.addOnPausedListener {
    Log.d(TAG, "Upload is paused")
}

Java

// Observe state change events such as progress, pause, and resume
uploadTask.addOnProgressListener(new OnProgressListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onProgress(UploadTask.TaskSnapshot taskSnapshot) {
        double progress = (100.0 * taskSnapshot.getBytesTransferred()) / taskSnapshot.getTotalByteCount();
        Log.d(TAG, "Upload is " + progress + "% done");
    }
}).addOnPausedListener(new OnPausedListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onPaused(UploadTask.TaskSnapshot taskSnapshot) {
        Log.d(TAG, "Upload is paused");
    }
});

Menangani Perubahan Siklus Proses Aktivitas

Upload akan berlanjut di latar belakang, bahkan setelah siklus proses aktivitas berubah (seperti menampilkan sebuah dialog atau memutar layar). Setiap pemroses yang telah terpasang juga akan tetap melekat. Pemanggilan pemroses setelah aktivitas dihentikan dapat menyebabkan hasil yang tidak diharapkan.

Anda bisa mengatasi masalah ini dengan membuat pemroses berlangganan cakupan aktivitas agar pendaftarannya dibatalkan secara otomatis saat aktivitas berhenti. Lalu, gunakan metode getActiveUploadTasks saat aktivitas dimulai ulang untuk memperoleh tugas upload yang masih berjalan atau baru saja diselesaikan.

Contoh di bawah memperlihatkan hal ini dan juga menampilkan cara mempertahankan jalur referensi penyimpanan yang digunakan.

Kotlin

override fun onSaveInstanceState(outState: Bundle) {
    super.onSaveInstanceState(outState)

    // If there's an upload in progress, save the reference so you can query it later
    outState.putString("reference", storageRef.toString())
}

override fun onRestoreInstanceState(savedInstanceState: Bundle) {
    super.onRestoreInstanceState(savedInstanceState)

    // If there was an upload in progress, get its reference and create a new StorageReference
    val stringRef = savedInstanceState.getString("reference") ?: return

    storageRef = Firebase.storage.getReferenceFromUrl(stringRef)

    // Find all UploadTasks under this StorageReference (in this example, there should be one)

    val tasks = storageRef.activeUploadTasks

    if (tasks.size > 0) {
        // Get the task monitoring the upload
        val task = tasks[0]

        // Add new listeners to the task using an Activity scope
        task.addOnSuccessListener(this) {
            // Success!
            // ...
        }
    }
}

Java

@Override
protected void onSaveInstanceState(Bundle outState) {
    super.onSaveInstanceState(outState);

    // If there's an upload in progress, save the reference so you can query it later
    if (mStorageRef != null) {
        outState.putString("reference", mStorageRef.toString());
    }
}

@Override
protected void onRestoreInstanceState(Bundle savedInstanceState) {
    super.onRestoreInstanceState(savedInstanceState);

    // If there was an upload in progress, get its reference and create a new StorageReference
    final String stringRef = savedInstanceState.getString("reference");
    if (stringRef == null) {
        return;
    }
    mStorageRef = FirebaseStorage.getInstance().getReferenceFromUrl(stringRef);

    // Find all UploadTasks under this StorageReference (in this example, there should be one)
    List<UploadTask> tasks = mStorageRef.getActiveUploadTasks();
    if (tasks.size() > 0) {
        // Get the task monitoring the upload
        UploadTask task = tasks.get(0);

        // Add new listeners to the task using an Activity scope
        task.addOnSuccessListener(this, new OnSuccessListener<UploadTask.TaskSnapshot>() {
            @Override
            public void onSuccess(UploadTask.TaskSnapshot state) {
                // Success!
                // ...
            }
        });
    }
}

getActiveUploadTasks mengambil semua tugas upload aktif, pada dan di bawah referensi yang diberikan, sehingga Anda mungkin perlu menangani beberapa tugas.

Melanjutkan Upload Setelah Proses Dimulai Ulang

Jika proses Anda dihentikan, setiap upload yang sedang berjalan akan terhenti. Namun, Anda dapat melanjutkan upload setelah proses dimulai ulang dengan cara melanjutkan sesi upload dengan server. Hal ini dapat menghemat waktu dan bandwidth karena upload tidak dimulai dari awal file.

Untuk melakukannya, mulai upload melalui putFile. Pada StorageTask yang dihasilkan, panggil getUploadSessionUri, lalu simpan nilai yang dihasilkan dalam penyimpanan persisten (seperti SharedPreferences).

Kotlin

uploadTask = storageRef.putFile(localFile)
uploadTask.addOnProgressListener { taskSnapshot ->
    sessionUri = taskSnapshot.uploadSessionUri
    if (sessionUri != null && !saved) {
        saved = true
        // A persisted session has begun with the server.
        // Save this to persistent storage in case the process dies.
    }
}

Java

uploadTask = mStorageRef.putFile(localFile);
uploadTask.addOnProgressListener(new OnProgressListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onProgress(UploadTask.TaskSnapshot taskSnapshot) {
        Uri sessionUri = taskSnapshot.getUploadSessionUri();
        if (sessionUri != null && !mSaved) {
            mSaved = true;
            // A persisted session has begun with the server.
            // Save this to persistent storage in case the process dies.
        }
    }
});

Setelah proses dimulai ulang dengan upload yang terputus, panggil lagi putFile. Namun, kali ini teruskan juga URI yang disimpan.

Kotlin

// resume the upload task from where it left off when the process died.
// to do this, pass the sessionUri as the last parameter
uploadTask = storageRef.putFile(
    localFile,
    storageMetadata { },
    sessionUri,
)

Java

//resume the upload task from where it left off when the process died.
//to do this, pass the sessionUri as the last parameter
uploadTask = mStorageRef.putFile(localFile,
        new StorageMetadata.Builder().build(), sessionUri);

Sesi akan bertahan selama satu minggu. Jika Anda mencoba untuk melanjutkan sesi setelah masa berlakunya habis atau jika mengalami error, Anda akan menerima callback kegagalan. Anda bertanggung jawab untuk memastikan file tidak berubah di antara upload.

Penanganan Error

Ada sejumlah penyebab terjadinya error saat upload, termasuk tidak adanya file lokal, atau pengguna tidak memiliki izin untuk mengupload file yang diinginkan. Anda dapat menemukan informasi lebih lanjut tentang error di bagian Menangani Error pada dokumentasi.

Contoh Lengkap

Contoh lengkap upload dengan pemantauan progres dan penanganan error ditampilkan di bawah ini:

Kotlin

// File or Blob
file = Uri.fromFile(File("path/to/mountains.jpg"))

// Create the file metadata
metadata = storageMetadata {
    contentType = "image/jpeg"
}

// Upload file and metadata to the path 'images/mountains.jpg'
uploadTask = storageRef.child("images/${file.lastPathSegment}").putFile(file, metadata)

// Listen for state changes, errors, and completion of the upload.
// You'll need to import com.google.firebase.storage.component1 and
// com.google.firebase.storage.component2
uploadTask.addOnProgressListener { (bytesTransferred, totalByteCount) ->
    val progress = (100.0 * bytesTransferred) / totalByteCount
    Log.d(TAG, "Upload is $progress% done")
}.addOnPausedListener {
    Log.d(TAG, "Upload is paused")
}.addOnFailureListener {
    // Handle unsuccessful uploads
}.addOnSuccessListener {
    // Handle successful uploads on complete
    // ...
}

Java

// File or Blob
file = Uri.fromFile(new File("path/to/mountains.jpg"));

// Create the file metadata
metadata = new StorageMetadata.Builder()
        .setContentType("image/jpeg")
        .build();

// Upload file and metadata to the path 'images/mountains.jpg'
uploadTask = storageRef.child("images/"+file.getLastPathSegment()).putFile(file, metadata);

// Listen for state changes, errors, and completion of the upload.
uploadTask.addOnProgressListener(new OnProgressListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onProgress(UploadTask.TaskSnapshot taskSnapshot) {
        double progress = (100.0 * taskSnapshot.getBytesTransferred()) / taskSnapshot.getTotalByteCount();
        Log.d(TAG, "Upload is " + progress + "% done");
    }
}).addOnPausedListener(new OnPausedListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onPaused(UploadTask.TaskSnapshot taskSnapshot) {
        Log.d(TAG, "Upload is paused");
    }
}).addOnFailureListener(new OnFailureListener() {
    @Override
    public void onFailure(@NonNull Exception exception) {
        // Handle unsuccessful uploads
    }
}).addOnSuccessListener(new OnSuccessListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onSuccess(UploadTask.TaskSnapshot taskSnapshot) {
        // Handle successful uploads on complete
        // ...
    }
});

Setelah mengupload file, pelajari caramendownloadnya dari Cloud Storage.