Ir para o console

Fazer upload de arquivos na Web

Com o Cloud Storage, os desenvolvedores ganham rapidez e facilidade ao fazer upload de arquivos para um intervalo do Google Cloud Storage fornecido e gerenciado pelo Firebase.

Como o app padrão do Google App Engine e o Firebase compartilham esse intervalo, a configuração do acesso público se aplica também aos arquivos do App Engine enviados recentemente. Restrinja novamente o acesso ao intervalo do Storage quando configurar a autenticação.

Fazer upload de arquivos

Para fazer upload de um arquivo para o Cloud Storage, primeiro crie uma referência ao caminho completo do arquivo, incluindo o nome dele.

// Create a root reference
var storageRef = firebase.storage().ref();

// Create a reference to 'mountains.jpg'
var mountainsRef = storageRef.child('mountains.jpg');

// Create a reference to 'images/mountains.jpg'
var 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.fullPath === mountainImagesRef.fullPath    // false

Upload de um Blob ou File

Depois de criar uma referência adequada, chame o método put(). O put() recolhe os arquivos por meio da APIs File e Blob de JavaScript e faz upload deles para o Cloud Storage.

var file = ... // use the Blob or File API
ref.put(file).then(function(snapshot) {
  console.log('Uploaded a blob or file!');
});

Upload de uma matriz de bytes

Além dos tipos File e Blob , o método put() também é capaz de enviar uma Uint8Array para o Cloud Storage.

// Uint8Array
var bytes = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x2c, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x21]);
ref.put(bytes).then(function(snapshot) {
  console.log('Uploaded an array!');
});

Upload de uma string

Se um Blob, File, ou Uint8Array não estiver disponível, use o método putString() para fazer upload de um base64, base64url bruto ou sequência codificada data_url para o Cloud Storage.

// Raw string is the default if no format is provided
var message = 'This is my message.';
ref.putString(message).then(function(snapshot) {
  console.log('Uploaded a raw string!');
});

// Base64 formatted string
var message = '5b6p5Y+344GX44G+44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
ref.putString(message, 'base64').then(function(snapshot) {
  console.log('Uploaded a base64 string!');
});

// Base64url formatted string
var message = '5b6p5Y-344GX44G-44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
ref.putString(message, 'base64url').then(function(snapshot) {
  console.log('Uploaded a base64url string!');
});

// Data URL string
var message = 'data:text/plain;base64,5b6p5Y+344GX44G+44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
ref.putString(message, 'data_url').then(function(snapshot) {
  console.log('Uploaded a data_url string!');
});

put() e putString() retornam uma UploadTask que pode ser usada como uma promessa ou para gerenciar e monitorar o status do upload.

Como a referência define o caminho completo do arquivo, certifique-se de que você esteja fazendo upload para um caminho não vazio.

Adicionar metadados de arquivo

Ao fazer o upload de um arquivo, você também pode especificar metadados para ele. Em geral, esses metadados contêm propriedades típicas de arquivo, como name, size e contentType, frequentemente chamadas de tipo MIME. O tipo de conteúdo é inferido automaticamente pelo Cloud Storage a partir da extensão de arquivo onde o arquivo é armazenado em disco, mas se um contentType for especificado nos metadados, ele modificará o tipo detectado automaticamente. Quando nenhum metadado contentType é especificado e o arquivo não tem uma extensão, o Cloud Storage usa como padrão o tipo application/octet-stream. Veja mais informações sobre os metadados de arquivo na seção Usar metadados de arquivo.

// Create file metadata including the content type
var metadata = {
  contentType: 'image/jpeg',
};

// Upload the file and metadata
var uploadTask = storageRef.child('images/mountains.jpg').put(file, metadata);

Gerenciar uploads

Além de iniciar uploads, é possível pausar, retomar e cancelar uploads usando os métodos pause(), resume() e cancel(). Chamar pause() ou resume() acionará as alterações de estado pause ou running. Chamar o método cancel() resulta na falha do upload e retorna um erro indicando que o upload foi cancelado.

// Upload the file and metadata
var uploadTask = storageRef.child('images/mountains.jpg').put(file);

// Pause the upload
uploadTask.pause();

// Resume the upload
uploadTask.resume();

// Cancel the upload
uploadTask.cancel();

Monitorar o andamento dos uploads

Durante o upload, a tarefa de upload pode acionar eventos de andamento no observador state_changed, como:

Tipo de evento Uso típico
running Este evento é acionado quando a tarefa é iniciada ou o upload é retomado, e é geralmente utilizado com o evento pause.
progress Este evento é acionado sempre que os dados são enviados para o Cloud Storage e pode ser utilizado para preencher o indicador de andamento de um upload.
pause Este evento é acionado quando o upload é pausado e é geralmente utilizado com o evento running.

Quando ocorre um evento, um objeto TaskSnapshot é transmitido de volta. Esse instantâneo é uma visualização não alterável da tarefa no momento em que o evento ocorreu. Esse objeto contém as seguintes propriedades:

Propriedade Tipo Descrição
bytesTransferred Number O número total de bytes que foram transferidos quando esse instantâneo foi capturado.
totalBytes Number O número total de bytes esperados no upload.
state firebase.storage.TaskState Estado atual do upload.
metadata firebaseStorage.Metadata Antes de o upload ser concluído, os metadados são enviados para o servidor. Após a conclusão do upload, o servidor retorna os metadados enviados.
task firebaseStorage.UploadTask A tarefa que esse instantâneo representa. Pode ser usada para "pausar", "retomar" ou "cancelar" a tarefa.
ref firebaseStorage.Reference A referência de onde veio essa tarefa.

Essas alterações de estado, combinadas com as propriedades de TaskSnapshot, oferecem uma maneira simples, mas avançada, para monitorar eventos de upload.

var uploadTask = storageRef.child('images/rivers.jpg').put(file);

// Register three observers:
// 1. 'state_changed' observer, called any time the state changes
// 2. Error observer, called on failure
// 3. Completion observer, called on successful completion
uploadTask.on('state_changed', function(snapshot){
  // Observe state change events such as progress, pause, and resume
  // Get task progress, including the number of bytes uploaded and the total number of bytes to be uploaded
  var progress = (snapshot.bytesTransferred / snapshot.totalBytes) * 100;
  console.log('Upload is ' + progress + '% done');
  switch (snapshot.state) {
    case firebase.storage.TaskState.PAUSED: // or 'paused'
      console.log('Upload is paused');
      break;
    case firebase.storage.TaskState.RUNNING: // or 'running'
      console.log('Upload is running');
      break;
  }
}, function(error) {
  // Handle unsuccessful uploads
}, function() {
  // Handle successful uploads on complete
  // For instance, get the download URL: https://firebasestorage.googleapis.com/...
  uploadTask.snapshot.ref.getDownloadURL().then(function(downloadURL) {
    console.log('File available at', downloadURL);
  });
});

Como lidar com 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. Saiba mais sobre erros na seção Como lidar com erros do documento.

Exemplo completo

Um exemplo completo de upload com monitoramento de andamento e tratamento de erros é mostrado abaixo:

// File or Blob named mountains.jpg
var file = ...

// Create the file metadata
var metadata = {
  contentType: 'image/jpeg'
};

// Upload file and metadata to the object 'images/mountains.jpg'
var uploadTask = storageRef.child('images/' + file.name).put(file, metadata);

// Listen for state changes, errors, and completion of the upload.
uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, // or 'state_changed'
  function(snapshot) {
    // Get task progress, including the number of bytes uploaded and the total number of bytes to be uploaded
    var progress = (snapshot.bytesTransferred / snapshot.totalBytes) * 100;
    console.log('Upload is ' + progress + '% done');
    switch (snapshot.state) {
      case firebase.storage.TaskState.PAUSED: // or 'paused'
        console.log('Upload is paused');
        break;
      case firebase.storage.TaskState.RUNNING: // or 'running'
        console.log('Upload is running');
        break;
    }
  }, function(error) {

  // A full list of error codes is available at
  // https://firebase.google.com/docs/storage/web/handle-errors
  switch (error.code) {
    case 'storage/unauthorized':
      // User doesn't have permission to access the object
      break;

    case 'storage/canceled':
      // User canceled the upload
      break;

    ...

    case 'storage/unknown':
      // Unknown error occurred, inspect error.serverResponse
      break;
  }
}, function() {
  // Upload completed successfully, now we can get the download URL
  uploadTask.snapshot.ref.getDownloadURL().then(function(downloadURL) {
    console.log('File available at', downloadURL);
  });
});

Agora que você já sabe fazer upload de arquivos, veja como fazer o download no Cloud Storage.