Fazer upload de arquivos com o Cloud Storage para Unity

Com o Cloud Storage for Firebase, é possível fazer upload de arquivos com rapidez e facilidade para um bucket do Cloud Storage fornecido e gerenciado pelo Firebase.

Observação: por padrão, um bucket Cloud Storage for Firebase exige o Firebase Authentication para realizar qualquer ação nos dados ou arquivos do bucket. É possível mudar o Firebase Security Rules para Cloud Storage e permitir o acesso não autenticado em situações específicas. No entanto, na maioria das situações, recomendamos restringir o acesso e configurar regras de segurança avançadas, em especial para apps de produção. Se você usar Google App Engine e tiver um bucket Cloud Storage padrão com um formato de nome *.appspot.com, talvez seja necessário considerar como as regras de segurança afetam o acesso aos arquivos App Engine.

Observação: nos projetos do plano do Spark, o Firebase bloqueia o upload e a hospedagem de determinados tipos de arquivos executáveis para Windows (arquivos com as extensões .exe, .dll e .bat), Android (extensão .apk) e Apple (extensão .ipa) pelo Cloud Storage for Firebase e Firebase Hosting. Esta política existe para evitar abusos na nossa plataforma. Os projetos no plano Blaze não são afetados. Para mais informações, consulte estas perguntas frequentes.

Criar uma referência

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

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 root reference
StorageReference storageRef = storage.RootReference;

// 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
Assert.AreEqual(mountainsRef.Name, mountainImagesRef.Name);
Assert.AreNotEqual(mountainsRef.Path, mountainImagesRef.Path);

Não é possível fazer upload de dados com uma referência à raiz do bucket do Cloud Storage. Sua referência precisa apontar para um URL filho.

Fazer upload de arquivos

Assim que tiver uma referência, faça upload dos arquivos para Cloud Storage de duas maneiras:

1. Fazer upload de uma matriz de bytes na memória.
2. Fazer upload de um caminho de arquivo que representa um arquivo no dispositivo.

Fazer upload de dados na memória

O método PutBytesAsync() é a maneira mais simples de fazer upload de um arquivo para o Cloud Storage. O PutBytesAsync() usa um byte[] e retorna um System.Task<Firebase.Storage.StorageMetadata> que conterá informações sobre o arquivo quando a tarefa for concluída. Você também pode usar um IProgress<UploadState> (normalmente StorageProgress<UploadState>) para monitorar o status do upload.

// Data in memory
var customBytes = new byte[] {
    /*...*/
};

// Create a reference to the file you want to upload
StorageReference riversRef = storageRef.Child("images/rivers.jpg");

// Upload the file to the path "images/rivers.jpg"
riversRef.PutBytesAsync(customBytes)
    .ContinueWith((Task<StorageMetadata> task) => {
        if (task.IsFaulted || task.IsCanceled) {
            Debug.Log(task.Exception.ToString());
            // Uh-oh, an error occurred!
        }
        else {
            // Metadata contains file metadata such as size, content-type, and md5hash.
            StorageMetadata metadata = task.Result;
            string md5Hash = metadata.Md5Hash;
            Debug.Log("Finished uploading...");
            Debug.Log("md5 hash = " + md5Hash);
        }
    });

Fazer upload de um arquivo local

Você pode fazer upload de arquivos locais nos dispositivos, como fotos e vídeos da câmera, com o método PutFileAsync(). O PutFileAsync() usa uma string que representa o caminho para o arquivo e retorna um System.Task<Firebase.Storage.StorageMetadata> que conterá informações sobre o arquivo quando a tarefa for concluída. Você também pode usar um IProgress<UploadState> (normalmente StorageProgress<UploadState>) para monitorar o status do upload.

// File located on disk
string localFile = "...";

// Create a reference to the file you want to upload
StorageReference riversRef = storageRef.Child("images/rivers.jpg");

// Upload the file to the path "images/rivers.jpg"
riversRef.PutFileAsync(localFile)
    .ContinueWith((Task<StorageMetadata> task) => {
        if (task.IsFaulted || task.IsCanceled) {
            Debug.Log(task.Exception.ToString());
            // Uh-oh, an error occurred!
        }
        else {
            // Metadata contains file metadata such as size, content-type, and download URL.
            StorageMetadata metadata = task.Result;
            string md5Hash = metadata.Md5Hash;
            Debug.Log("Finished uploading...");
            Debug.Log("md5 hash = " + md5Hash);
        }
    });

Se você quiser monitorar seu upload ativamente, use uma classe StorageProgress ou sua própria classe que implemente IProgress<UploadState> com os métodos PutFileAsync() ou PutBytesAsync(). Saiba mais na seção Gerenciar uploads.

Adicionar metadados de arquivo

Você também pode incluir metadados ao fazer upload de arquivos. Esses metadados de arquivos contêm propriedades típicas, como Name, Size e ContentType, frequentemente chamadas de tipo MIME. O método PutFileAsync() infere automaticamente o tipo de conteúdo a partir da extensão do nome de arquivo, mas você pode modificar o tipo detectado automaticamente especificando ContentType nos metadados. Se você não fornecer um ContentType e o Cloud Storage não puder inferir um padrão pela extensão de arquivo, o Cloud Storage usará application/octet-stream. Veja mais informações sobre metadados de arquivos na seção Usar metadados de arquivos.

// Create storage reference
StorageReference mountainsRef = storageRef.Child("images/mountains.jpg");

byte[] customBytes = new byte[] {
    /*...*/
};
string localFile = "...";

// Create file metadata including the content type
var newMetadata = new MetadataChange();
newMetadata.ContentType = "image/jpeg";

// Upload data and metadata
mountainsRef.PutBytesAsync(customBytes, newMetadata, null,
    CancellationToken.None); // .ContinueWithOnMainThread(...
// Upload file and metadata
mountainsRef.PutFileAsync(localFile, newMetadata, null,
    CancellationToken.None); // .ContinueWithOnMainThread(...

Monitorar o andamento do upload

Você pode anexar listeners aos uploads 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 um retorno de chamada para verificação do andamento.

// Start uploading a file
var task = storageRef.Child("images/mountains.jpg")
    .PutFileAsync(localFile, null,
        new StorageProgress<UploadState>(state => {
            // called periodically during the upload
            Debug.Log(String.Format("Progress: {0} of {1} bytes transferred.",
                state.BytesTransferred, state.TotalByteCount));
        }), CancellationToken.None, null);

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

Tratamento de erros

Há uma série de motivos pelos quais erros podem ocorrer no upload, incluindo arquivo local não existente ou o usuário não ter permissão para fazer upload do arquivo desejado. Encontre mais informações sobre erros na seção Tratamento de erros da documentação.

Próximas etapas

Agora que você já sabe fazer upload de arquivos, veja como baixá-los do Cloud Storage.