Cargar archivos con Cloud Storage en Android

Cloud Storage para Firebase le permite cargar archivos de forma rápida y sencilla a un depósito de Cloud Storage proporcionado y administrado por Firebase.

Subir archivos

Para cargar un archivo en Cloud Storage, primero crea una referencia a la ruta completa del archivo, incluido el nombre del archivo.

Kotlin+KTX

// 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

Una vez que haya creado una referencia adecuada, llame al método putBytes() , putFile() o putStream() para cargar el archivo en Cloud Storage.

No puedes cargar datos con una referencia a la raíz de tu depósito de Cloud Storage. Su referencia debe apuntar a una URL secundaria.

Cargar desde datos en la memoria

El método putBytes() es la forma más sencilla de cargar un archivo en Cloud Storage. putBytes() toma un byte[] y devuelve una UploadTask que puedes usar para administrar y monitorear el estado de la carga.

Kotlin+KTX

// 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.
        // ...
    }
});

Debido a que putBytes() acepta un byte[] , requiere que su aplicación contenga todo el contenido de un archivo en la memoria a la vez. Considere usar putStream() o putFile() para usar menos memoria.

Subir desde una secuencia

El método putStream() es la forma más versátil de cargar un archivo en Cloud Storage. putStream() toma un InputStream y devuelve un UploadTask que puedes usar para administrar y monitorear el estado de la carga.

Kotlin+KTX

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.
        // ...
    }
});

Subir desde un archivo local

Puede cargar archivos locales en el dispositivo, como fotos y vídeos de la cámara, con el método putFile() . putFile() toma un File y devuelve una UploadTask que puede usar para administrar y monitorear el estado de la carga.

Kotlin+KTX

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.
        // ...
    }
});

Obtener una URL de descarga

Después de cargar un archivo, puede obtener una URL para descargar el archivo llamando al método getDownloadUrl() en StorageReference :

Kotlin+KTX

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
            // ...
        }
    }
});

Agregar metadatos de archivo

También puedes incluir metadatos cuando subes archivos. Estos metadatos contienen propiedades típicas de metadatos de archivos, como name , size y contentType (comúnmente denominado tipo MIME). El método putFile() infiere automáticamente el tipo MIME a partir de la extensión File , pero puede anular el tipo detectado automáticamente especificando contentType en los metadatos. Si no proporciona un contentType y Cloud Storage no puede inferir un valor predeterminado a partir de la extensión del archivo, Cloud Storage usa application/octet-stream . Consulte la sección Usar metadatos de archivos para obtener más información sobre los metadatos de archivos.

Kotlin+KTX

// 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);

Administrar cargas

Además de iniciar las cargas, puede pausarlas, reanudarlas y cancelarlas utilizando los métodos pause() , resume() y cancel() . Los eventos de pausa y reanudación generan cambios de estado pause y progress respectivamente. Cancelar una carga hace que la carga falle con un error que indica que la carga fue cancelada.

Kotlin+KTX

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();

Supervisar el progreso de la carga

Puede agregar oyentes para controlar el éxito, el fracaso, el progreso o las pausas en su tarea de carga:

Tipo de oyente Uso típico
OnProgressListener Este oyente se llama periódicamente a medida que se transfieren los datos y se puede utilizar para completar un indicador de carga/descarga.
OnPausedListener Se llama a este oyente cada vez que se pausa la tarea.
OnSuccessListener Se llama a este oyente cuando la tarea se completa con éxito.
OnFailureListener Se llama a este oyente cada vez que falla la carga. Esto puede suceder debido a tiempos de espera de la red, fallas de autorización o si cancela la tarea.

OnFailureListener se llama con una instancia Exception . Se llama a otros oyentes con un objeto UploadTask.TaskSnapshot . Este objeto es una vista inmutable de la tarea en el momento en que ocurrió el evento. Un UploadTask.TaskSnapshot contiene las siguientes propiedades:

Propiedad Tipo Descripción
getDownloadUrl String Una URL que se puede utilizar para descargar el objeto. Esta es una URL pública imposible de adivinar que se puede compartir con otros clientes. Este valor se completa una vez que se completa la carga.
getError Exception Si la tarea falló, esta tendrá la causa como Excepción.
getBytesTransferred long El número total de bytes que se transfirieron cuando se tomó esta instantánea.
getTotalByteCount long El número total de bytes que se espera cargar.
getUploadSessionUri String Un URI que se puede utilizar para continuar esta tarea mediante otra llamada a putFile.
getMetadata StorageMetadata Antes de que se complete una carga, estos son los metadatos que se envían al servidor. Una vez completada la carga, estos son los metadatos devueltos por el servidor.
getTask UploadTask La tarea que creó esta instantánea. Utilice esta tarea para cancelar, pausar o reanudar la carga.
getStorage StorageReference StorageReference utilizada para crear UploadTask .

Los detectores de eventos UploadTask proporcionan una manera sencilla y poderosa de monitorear eventos de carga.

Kotlin+KTX

// 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");
    }
});

Manejar los cambios en el ciclo de vida de la actividad

Las cargas continúan en segundo plano incluso después de cambios en el ciclo de vida de la actividad (como presentar un cuadro de diálogo o rotar la pantalla). Todos los oyentes que haya adjuntado también permanecerán adjuntos. Esto podría provocar resultados inesperados si reciben una llamada después de que se detiene la actividad.

Puede resolver este problema suscribiendo a sus oyentes con un alcance de actividad para cancelar su registro automáticamente cuando la actividad se detenga. Luego, utilice el método getActiveUploadTasks cuando se reinicie la actividad para obtener las tareas de carga que aún se están ejecutando o se completaron recientemente.

El siguiente ejemplo demuestra esto y también muestra cómo conservar la ruta de referencia de almacenamiento utilizada.

Kotlin+KTX

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 recupera todas las tareas de carga activas en la referencia proporcionada y debajo de ella, por lo que es posible que deba manejar varias tareas.

Cargas continuas durante los reinicios del proceso

Si se cierra su proceso, se interrumpirán todas las cargas en curso. Sin embargo, puede continuar cargando una vez que se reinicie el proceso reanudando la sesión de carga con el servidor. Esto puede ahorrar tiempo y ancho de banda al no iniciar la carga desde el inicio del archivo.

Para hacer esto, comience a cargar a través de putFile . En la StorageTask resultante, llame getUploadSessionUri y guarde el valor resultante en un almacenamiento persistente (como SharedPreferences).

Kotlin+KTX

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.
        }
    }
});

Después de que su proceso se reinicie con una carga interrumpida, llame a putFile nuevamente. Pero esta vez también pasa el Uri que se salvó.

Kotlin+KTX

// 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);

Las sesiones duran una semana. Si intenta reanudar una sesión después de que haya expirado o si ha experimentado un error, recibirá una devolución de llamada de error. Es su responsabilidad asegurarse de que el archivo no haya cambiado entre cargas.

Manejo de errores

Hay varias razones por las que pueden ocurrir errores durante la carga, incluido el archivo local que no existe o que el usuario no tiene permiso para cargar el archivo deseado. Puede encontrar más información sobre los errores en la sección Manejar errores de los documentos.

Ejemplo completo

A continuación se muestra un ejemplo completo de una carga con seguimiento del progreso y manejo de errores:

Kotlin+KTX

// 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
        // ...
    }
});

Ahora que has subido archivos, aprendamos cómo descargarlos desde Cloud Storage.