Descarga archivos con Cloud Storage para C++

Cloud Storage for Firebase te permite descargar contenido de forma rápida y sencilla archivos de un bucket de Cloud Storage que proporciona y administra Firebase.

Crea una referencia

Para descargar un archivo, primero crea una referencia de Cloud Storage al archivo que deseas descargar.

Para ello, puedes anexar rutas de acceso secundarias a la raíz de tu bucket de Cloud Storage, o bien crear una referencia a partir de una URL gs:// o https:// existente que haga referencia a un objeto en Cloud Storage.

// Create a reference with an initial file path and name
StorageReference path_reference = storage->GetReference("images/stars.jpg");

// Create a reference from a Cloud Storage URI
StorageReference gs_reference = storage->GetReferenceFromUrl("gs://bucket/images/stars.jpg");

// Create a reference from an HTTPS URL
// Note that in the URL, characters are URL escaped!
StorageReference https_reference = storage->GetReferenceFromUrl("https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg");

Descarga archivos

Cuando tengas una referencia, podrás descargar archivos de Cloud Storage de tres maneras:

  1. Descargarlos a un búfer en la memoria.
  2. Descargarlos a una ruta específica del dispositivo.
  3. Generar una URL en string que represente el archivo en línea.

Descarga en la memoria

Para descargar un archivo a un búfer de bytes en la memoria, usa el método GetBytes(). Esta es la forma más fácil de descargar un archivo con rapidez, pero debe cargar todo el contenido del archivo en la memoria. Si solicitas la descarga de un archivo más grande que la memoria disponible de tu app, esta fallará. Para brindar protección contra problemas de memoria, asegúrate de configurar el tamaño máximo en un valor que sepas que puede controlar la aplicación, o usa otro método de descarga.

// Create a reference to the file you want to download
StorageReference island_ref = storage_ref.Child("images/island.jpg");

// Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes)
const size_t kMaxAllowedSize = 1 * 1024 * 1024
int8_t byte_buffer[kMaxAllowedSize];
firebase::Future<size_t> future = island_ref.GetBytes(byte_buffer, kMaxAllowedSize);

En este momento, la solicitud ya se hizo, pero tenemos que esperar a que se complete la interfaz Future antes de leer el valor. Dado que los juegos tienden a ejecutarse en bucle y usan menos devoluciones de llamada que otras aplicaciones, lo normal es hacer un sondeo para determinar si se completó la operación.

// In the game loop that polls for the result...

if (future.status() != firebase::kFutureStatusPending) {
  if (future.status() != firebase::kFutureStatusComplete) {
    LogMessage("ERROR: GetBytes() returned an invalid future.");
    // Handle the error...
  } else if (future.Error() != firebase::storage::kErrorNone) {
    LogMessage("ERROR: GetBytes() returned error %d: %s", future.Error(),
               future.error_message());
    // Handle the error...
  } else {
    // byte_buffer is now populated with data for "images/island.jpg"
  }
}

Descarga en un archivo local

El método GetFile() permite descargar un archivo directamente en un dispositivo local. Úsalo si tus usuarios quieren tener acceso al archivo sin conexión o compartirlo en otra app.

// Create a reference to the file you want to download
StorageReference islandRef = storage_ref.Child("images/island.jpg"];

// Create local filesystem URL
const char* local_url = "file:///local/images/island.jpg";

// Download to the local filesystem
Future<size_t> future = islandRef.GetFile(local_url);

// Wait for Future to complete...

if (future.Error() != firebase::storage::kErrorNone) {
  // Uh-oh, an error occurred!
} else {
  // The file has been downloaded to local file URL "images/island.jpg"
}

GetFile() toma un argumento Controller opcional que puedes usar para administrar la descarga. Consulta Administra descargas para obtener más información.

Genera una URL de descarga

Si ya tienes una infraestructura de descarga basada en URLs o simplemente quieres una URL para compartir, puedes llamar al método GetDownloadUrl() en una referencia de Cloud Storage a fin de obtener la URL de descarga de un archivo.

// Create a reference to the file you want to download
StorageReference stars_ref = storage_ref.Child("images/stars.jpg");

// Fetch the download URL
firebase::Future<std::string> future = stars_ref.GetDownloadUrl();

// Wait for Future to complete...

if (future.Error() != firebase::storage::kErrorNone) {
  // Uh-oh, an error occurred!
} else {
  // Get the download URL for 'images/stars.jpg'
  std::string download_url = future.Result();
}

Administra descargas

Además de iniciar descargas, puedes detenerlas, reanudarlas y cancelarlas con los métodos Pause(), Resume() y Cancel() en Controller, que pueden pasarse a los métodos GetBytes() o GetFile() de manera opcional.

// Start downloading a file
Controller controller;
storage_ref.Child("images/mountains.jpg").GetFile(local_file, nullptr, &controller);

// Pause the download
controller.Pause();

// Resume the download
controller.Resume();

// Cancel the download
controller.Cancel();

Supervisa el progreso de la descarga

Puedes adjuntar agentes de escucha a las descargas para monitorear su progreso.

class MyListener : public firebase::storage::Listener {
 public:
  virtual void OnProgress(firebase::storage::Controller* controller) {
    // A progress event occurred
  }
};

{
  // Start uploading a file
  MyEventListener my_listener;
  storage_ref.Child("images/mountains.jpg").GetFile(local_file, my_listener);
}

Soluciona errores

Existen varios motivos por los cuales se pueden producir errores en una descarga: por ejemplo, es posible que el archivo no exista o que el usuario no tenga permiso para acceder al archivo deseado. Para obtener más información sobre los errores, consulta la sección de los documentos denominada Soluciona errores.

Próximos pasos

También puedes obtener y actualizar metadatos para los archivos almacenados en Cloud Storage.