Sube archivos con Cloud Storage en Android

Cloud Storage for Firebase te permite subir archivos con rapidez y facilidad a un bucket de Cloud Storage proporcionado y administrado por Firebase.

Sube archivos

Para subir un archivo a Cloud Storage, primero debes crear una referencia a la ruta de acceso completa del archivo, incluido el nombre.

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
StorageActivity.kt

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
StorageActivity.java

Una vez que crees una referencia apropiada, llama al método putBytes(), putFile() o putStream() para subir el archivo a Cloud Storage.

No es posible subir datos con una referencia a la raíz de tu bucket de Cloud Storage. La referencia debe apuntar a una URL secundaria.

Sube archivos desde datos en la memoria

El método putBytes() es la forma más sencilla de subir un archivo a Cloud Storage. putBytes() toma un byte[] y muestra un UploadTask que puedes usar para administrar y supervisar 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.
    // ...
}
StorageActivity.kt

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

Debido a que putBytes() acepta un byte[], obliga a la app a conservar todo el contenido de un archivo en la memoria a la vez. Te recomendamos usar putStream() o putFile() para consumir menos memoria.

Sube archivos desde una transmisión

El método putStream() es la forma más versátil de subir un archivo a Cloud Storage. putStream() toma un InputStream y muestra una UploadTask que puedes usar para administrar y supervisar 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.
    // ...
}
StorageActivity.kt

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

Sube archivos desde un archivo local

Puedes subir archivos locales que se encuentran en el dispositivo, como fotos y videos de la cámara, con el método putFile(). putFile() toma un File y muestra una UploadTask que puedes usar para administrar y supervisar 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.
    // ...
}
StorageActivity.kt

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

Obtén una URL de descarga

Después de subir un archivo, llama al método getDownloadUrl() en StorageReference para obtener una URL de descarga del archivo:

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
        // ...
    }
}
StorageActivity.kt

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

Agrega metadatos de archivo

También puedes incluir metadatos cuando subas archivos. Estos metadatos contienen propiedades típicas de metadatos de archivo, como name, size y contentType (comúnmente denominado tipo de MIME). El método putFile() infiere el tipo de MIME de forma automática a partir de la extensión de File, pero puedes especificar contentType en los metadatos para anular el tipo detectado. Si no proporcionas un contentType y Cloud Storage no puede inferir un valor predeterminado a partir de la extensión de archivo, Cloud Storage usará application/octet-stream. Consulta la sección Usa metadatos de archivos para obtener más información acerca de estos.

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)
StorageActivity.kt

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);
StorageActivity.java

Administra cargas

Además de iniciar cargas, puedes detener, reanudar y cancelar cargas con los métodos pause(), resume() y cancel(). Los eventos de pausa y reanudación generan cambios de estado pause y progress, respectivamente. Cuando se cancela una carga, esta falla y muestra un error que indica que se canceló.

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()
StorageActivity.kt

Java

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

// Pause the upload
uploadTask.pause();

// Resume the upload
uploadTask.resume();

// Cancel the upload
uploadTask.cancel();
StorageActivity.java

Supervisa el progreso de la carga

Puedes agregar objetos de escucha que administren las tareas de carga correctas y fallidas, así como el progreso y las pausas:

Tipo de objeto de escucha Uso común
OnProgressListener Se llama periódicamente a este objeto de escucha mientras se transfieren datos, y se puede usar para propagar un indicador de carga y descarga.
OnPausedListener Se llama a este objeto de escucha cada vez que se pausa la tarea.
OnSuccessListener Se llama a este objeto de escucha cuando se completa la tarea de forma correcta.
OnFailureListener Se llama a este objeto de escucha cada vez que la carga falla. Esto puede suceder debido a tiempos de espera de la red o a errores de autorización, o si cancelas la tarea.

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

Propiedad Tipo Descripción
getDownloadUrl String Una URL que se puede usar para descargar el objeto. Es una URL pública indescifrable que se puede compartir con otros clientes. Se propaga este valor cuando finaliza una carga.
getError Exception Si la tarea falla, incluirá la causa como excepción.
getBytesTransferred long La cantidad total de bytes que se transfirieron cuando se tomó esta instantánea.
getTotalByteCount long La cantidad total de bytes que se espera subir.
getUploadSessionUri String Un URI que se puede usar para continuar la tarea mediante otra llamada a putFile.
getMetadata StorageMetadata Antes de que se complete una carga, indica los metadatos que se están enviando al servidor. Una vez que se completa una carga, indica los metadatos que muestra el servidor.
getTask UploadTask La tarea que creó esta instantánea. Úsala para cancelar, detener o reanudar la carga.
getStorage StorageReference La StorageReference que se usó para crear la UploadTask.

Los objetos de escucha de eventos UploadTask proporcionan una manera simple y potente de supervisar los 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")
}
StorageActivity.kt

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

Administra cambios en el ciclo de vida de la actividad

Las cargas continúan en segundo plano incluso después de que el ciclo de vida de una actividad cambia (como presentar un diálogo o rotar la pantalla). Si agregaste objetos de escucha, estos permanecen vinculados. Esto podría generar resultados inesperados si se los llama después de que se detiene la actividad.

Para solucionar este problema, puedes suscribir los objetos de escucha a un alcance de la actividad para cancelar su registro automáticamente cuando se detenga la actividad. Luego, usa el método getActiveUploadTasks cuando se reinicie la actividad para obtener tareas de carga que aún están en ejecución o que se completaron recientemente.

En el siguiente ejemplo se demuestra esto y cómo conservar la ruta de acceso de la referencia de almacenamiento usada.

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!
            // ...
        }
    }
}
UploadActivity.kt

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

getActiveUploadTasks recupera todas las tareas de carga activas en la referencia que se proporciona y bajo ella, por lo que es posible que debas administrar múltiples tareas.

Continúa las cargas después del reinicio del proceso

Si se desactiva el proceso, se interrumpirán las cargas en progreso. Sin embargo, puedes reanudar la sesión de carga con el servidor para seguir subiendo el archivo después de que se reinicie el proceso. Esto puede ahorrar tiempo y ancho de banda, ya que no inicia la carga desde el principio del archivo.

Para hacerlo, comienza la carga a través de putFile. En la StorageTask resultante, llama a getUploadSessionUri y guarda el valor resultante en el almacenamiento persistente (p. ej., 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.
    }
}
UploadActivity.kt

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

Después de que se reinicia el proceso con una carga interrumpida, vuelve a llamar a putFile. Sin embargo, esta vez pasa también el URI que se guardó.

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,
)
UploadActivity.kt

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);
UploadActivity.java

Las sesiones duran una semana. Si intentas reanudar una sesión después de que venza o si ocurrió un error, recibirás una devolución de llamada de error. Es tu responsabilidad garantizar que el archivo no cambie entre cargas.

Manejo de errores

Existen diferentes motivos por los que pueden producirse errores durante la carga, como que el archivo local no exista o que el usuario no tenga permiso para subir el archivo deseado. Para obtener más información sobre errores, consulta la sección Soluciona errores de la documentación.

Ejemplo completo

A continuación, se muestra un ejemplo completo de una carga con supervisión de 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
    // ...
}
StorageActivity.kt

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

Ahora que ya subiste archivos, veamos cómo descárgarlos desde Cloud Storage.