Fazer o download de arquivos com o Cloud Storage para Unity

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 baixar.

Crie uma referência anexando caminhos filhos à raiz do bucket do Cloud Storage ou crie uma referência usando um URL gs:// ou https:// atual ao referenciar um objeto no Cloud Storage.

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

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

// Create a reference from an HTTPS URL
// Note that in the URL, characters are URL escaped!
StorageReference httpsReference =
    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 quatro maneiras:

  1. Fazer o download a partir de um URL
  2. Fazer o download para uma matriz de bytes.
  3. Fazer o download por streaming.
  4. Fazer o download para um arquivo local.

O método usado para recuperar os arquivos dependerá da forma como quer consumir dados no jogo.

Fazer o download a partir de um URL

Se você quiser usar um URL com o WWW ou o UnityWebRequest do Unity, poderá receber um URL de download para um arquivo chamando GetDownloadUrlAsync().

// Fetch the download URL
reference.GetDownloadUrlAsync().ContinueWithOnMainThread(task => {
    if (!task.IsFaulted && !task.IsCanceled) {
        Debug.Log("Download URL: " + task.Result);
        // ... now download the file via WWW or UnityWebRequest.
    }
});

Fazer o download para uma matriz de bytes.

É possível fazer o download do arquivo para um buffer de bytes na memória usando o método GetBytesAsync(). Este método carregará todo o conteúdo do arquivo para a memória. Caso o arquivo solicitado seja maior do que a memória disponível do app, ocorrerá uma falha. Para evitar problemas de memória, configure o tamanho máximo para um valor que possa ser processado pelo app ou use outro método de download.

// Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes)
const long maxAllowedSize = 1 * 1024 * 1024;
reference.GetBytesAsync(maxAllowedSize).ContinueWithOnMainThread(task => {
    if (task.IsFaulted || task.IsCanceled) {
        Debug.LogException(task.Exception);
        // Uh-oh, an error occurred!
    }
    else {
        byte[] fileContents = task.Result;
        Debug.Log("Finished downloading!");
    }
});

Fazer o download por streaming

O download do arquivo por streaming permite processar os dados conforme são carregados. Isso proporciona flexibilidade máxima ao lidar com seu download. Chame GetStreamAsync() e transmita seu próprio processador de stream como o primeiro argumento. Este delegado será chamado em segundo plano com um stream que permite executar operações ou cálculos de alto consumo de latência, como armazenar o conteúdo em disco.

// Download via a Stream
reference.GetStreamAsync(stream => {
    // Do something with the stream here.
    //
    // This code runs on a background thread which reduces the impact
    // to your framerate.
    //
    // If you want to do something on the main thread, you can do that in the
    // progress eventhandler (second argument) or ContinueWith to execute it
    // at task completion.
}, null, CancellationToken.None);

GetStreamAsync() usa um argumento opcional do processador de stream que permite cancelar a operação ou ser notificado sobre o progresso.

Fazer o download para um arquivo local.

O método GetFileAsync() faz o download de um arquivo diretamente para um dispositivo local. Use esse método quando os usuários quiserem acessar o arquivo off-line ou compartilhá-lo em outro app.

// Create local filesystem URL
string localUrl = "file:///local/images/island.jpg";

// Download to the local filesystem
reference.GetFileAsync(localUrl).ContinueWithOnMainThread(task => {
    if (!task.IsFaulted && !task.IsCanceled) {
        Debug.Log("File downloaded.");
    }
});

Conecte listeners aos downloads para monitorar o andamento deles. O listener segue a interface System.IProgress<T> padrão. Você pode usar uma instância da classe StorageProgress para fornecer seu próprio Action<T> como retorno de chamada para verificação do andamento.

// Create local filesystem URL
string localUrl = "file:///local/images/island.jpg";

// Start downloading a file
Task task = reference.GetFileAsync(localFile,
    new StorageProgress<DownloadState>(state => {
        // called periodically during the download
        Debug.Log(String.Format(
            "Progress: {0} of {1} bytes transferred.",
            state.BytesTransferred,
            state.TotalByteCount
        ));
    }), CancellationToken.None);

task.ContinueWithOnMainThread(resultTask => {
    if (!resultTask.IsFaulted && !resultTask.IsCanceled) {
        Debug.Log("Download finished.");
    }
});

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.