Fazer o download de arquivos com o Cloud Storage para C++

Com o Cloud Storage para Firebase, é possível fazer o download de maneira rápida e fácil de arquivos de um bucket do Cloud Storage fornecido e gerenciado pelo Firebase.

Criar uma referência

Para fazer o download de um arquivo, primeiro crie uma referência do Cloud Storage para o arquivo que você quer transferir.

Crie uma referência anexando caminhos filhos à raiz do bucket do Cloud Storage ou crie uma referência usando um URL gs:// ou https:// ao referenciar um objeto no 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");

Fazer download de arquivos

Com uma referência, é possível fazer o download de arquivos do Cloud Storage de três maneiras:

  1. Fazer o download para um buffer na memória.
  2. Fazer o download para um caminho específico do dispositivo.
  3. Gerar um URL de string que represente o arquivo on-line.

Fazer download em memória

Faça o download do arquivo para um buffer de bytes na memória usando o método GetBytes(). Essa é a forma mais fácil e rápida de fazer download de um arquivo, mas exige o carregamento de todo o conteúdo dele para a memória. Ocorrerá uma falha se o arquivo solicitado for maior do que a memória disponível no seu app. Para evitar esse problema de memória, configure o tamanho máximo que seu app é capaz de processar ou use outro método de download.

// 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 future = island_ref.GetBytes(byte_buffer, kMaxAllowedSize);

Neste ponto, a solicitação já foi feita, mas temos que esperar a classe "Future" ser concluída para lermos o arquivo. Como os jogos geralmente são executados em um loop e têm menos retornos de chamada do que outros apps, você normalmente terá que solicitar a conclusão.

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

Fazer o download para um arquivo local

O método GetFile() faz o download de um arquivo diretamente para um dispositivo local. Use esse método se os seus usuários quiserem acessar arquivo off-line ou para compartilhá-lo em outro 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 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() usa um argumento Controller opcional, que pode ser usado para gerenciar o download. Saiba mais em Gerenciar downloads.

Gerar um URL de download

Se você já tiver uma infraestrutura de download com base em URLs ou apenas quiser um URL para compartilhar, você poderá obter o URL de download de um arquivo chamando o método GetDownloadUrl() em uma referência do Cloud Storage.

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

Gerenciar downloads

Além de iniciar downloads, você pode pausar, retomar e cancelar downloads usando os métodos Pause(), Resume() e Cancel() em Controller, que podem ser opcionalmente transmitidos para os métodos GetBytes() ou GetFile().

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

Monitorar o andamento de downloads

Você pode adicionar listeners aos downloads para monitorar o andamento deles.

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

Como lidar com erros

Durante os downloads, é possível que erros ocorram por vários motivos. Por exemplo, o arquivo não existe ou o usuário não tem permissão para acessá-lo. Saiba mais sobre erros na seção Como lidar com erros do documento.

Próximas etapas

Também é possível receber e atualizar metadados de arquivos armazenados no Cloud Storage.