Faça upload de arquivos com Cloud Storage em plataformas Apple

O Cloud Storage para Firebase permite fazer upload de arquivos de forma rápida e fácil para um bucket do Cloud Storage fornecido e gerenciado pelo Firebase.

Crie uma referência

Para fazer upload de um arquivo, primeiro crie uma referência do Cloud Storage para o local no Cloud Storage para o qual você deseja fazer upload do arquivo.

Você pode criar uma referência anexando caminhos secundários à raiz do bucket do Cloud Storage:

Rápido

// Create a root reference
let storageRef = storage.reference()

// Create a reference to "mountains.jpg"
let mountainsRef = storageRef.child("mountains.jpg")

// Create a reference to 'images/mountains.jpg'
let 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

Objetivo-C

// Create a root reference
FIRStorageReference *storageRef = [storage reference];

// Create a reference to "mountains.jpg"
FIRStorageReference *mountainsRef = [storageRef child:@"mountains.jpg"];

// Create a reference to 'images/mountains.jpg'
FIRStorageReference *mountainImagesRef = [storageRef child:@"images/mountains.jpg"];

// While the file names are the same, the references point to different files
[mountainsRef.name isEqualToString:mountainImagesRef.name];         // true
[mountainsRef.fullPath isEqualToString:mountainImagesRef.fullPath]; // false

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

Fazer upload de arquivos

Depois de ter uma referência, você poderá fazer upload de arquivos para o Cloud Storage de duas maneiras:

  1. Upload de dados na memória
  2. Fazer upload de um URL que representa um arquivo no dispositivo

Upload de dados na memória

O método putData:metadata:completion: é a maneira mais simples de fazer upload de um arquivo para o Cloud Storage. putData:metadata:completion: pega um objeto NSData e retorna um FIRStorageUploadTask , que você pode usar para gerenciar seu upload e monitorar seu status.

Rápido

// Data in memory
let data = Data()

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

// Upload the file to the path "images/rivers.jpg"
let uploadTask = riversRef.putData(data, metadata: nil) { (metadata, error) in
  guard let metadata = metadata else {
    // Uh-oh, an error occurred!
    return
  }
  // Metadata contains file metadata such as size, content-type.
  let size = metadata.size
  // You can also access to download URL after upload.
  riversRef.downloadURL { (url, error) in
    guard let downloadURL = url else {
      // Uh-oh, an error occurred!
      return
    }
  }
}

Objetivo-C

// Data in memory
NSData *data = [NSData dataWithContentsOfFile:@"rivers.jpg"];

// Create a reference to the file you want to upload
FIRStorageReference *riversRef = [storageRef child:@"images/rivers.jpg"];

// Upload the file to the path "images/rivers.jpg"
FIRStorageUploadTask *uploadTask = [riversRef putData:data
                                             metadata:nil
                                           completion:^(FIRStorageMetadata *metadata,
                                                        NSError *error) {
  if (error != nil) {
    // Uh-oh, an error occurred!
  } else {
    // Metadata contains file metadata such as size, content-type, and download URL.
    int size = metadata.size;
    // You can also access to download URL after upload.
    [riversRef downloadURLWithCompletion:^(NSURL * _Nullable URL, NSError * _Nullable error) {
      if (error != nil) {
        // Uh-oh, an error occurred!
      } else {
        NSURL *downloadURL = URL;
      }
    }];
  }
}];

Carregar 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 putFile:metadata:completion: putFile:metadata:completion: pega um NSURL e retorna um FIRStorageUploadTask , que você pode usar para gerenciar seu upload e monitorar seu status.

Rápido

// File located on disk
let localFile = URL(string: "path/to/image")!

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

// Upload the file to the path "images/rivers.jpg"
let uploadTask = riversRef.putFile(from: localFile, metadata: nil) { metadata, error in
  guard let metadata = metadata else {
    // Uh-oh, an error occurred!
    return
  }
  // Metadata contains file metadata such as size, content-type.
  let size = metadata.size
  // You can also access to download URL after upload.
  riversRef.downloadURL { (url, error) in
    guard let downloadURL = url else {
      // Uh-oh, an error occurred!
      return
    }
  }
}

Objetivo-C

// File located on disk
NSURL *localFile = [NSURL URLWithString:@"path/to/image"];

// Create a reference to the file you want to upload
FIRStorageReference *riversRef = [storageRef child:@"images/rivers.jpg"];

// Upload the file to the path "images/rivers.jpg"
FIRStorageUploadTask *uploadTask = [riversRef putFile:localFile metadata:nil completion:^(FIRStorageMetadata *metadata, NSError *error) {
  if (error != nil) {
    // Uh-oh, an error occurred!
  } else {
    // Metadata contains file metadata such as size, content-type, and download URL.
    int size = metadata.size;
    // You can also access to download URL after upload.
    [riversRef downloadURLWithCompletion:^(NSURL * _Nullable URL, NSError * _Nullable error) {
      if (error != nil) {
        // Uh-oh, an error occurred!
      } else {
        NSURL *downloadURL = URL;
      }
    }];
  }
}];

Se quiser gerenciar ativamente seu upload, você pode usar os métodos putData: ou putFile: e observar a tarefa de upload, em vez de usar o manipulador de conclusão. Consulte Gerenciar uploads para obter mais informações.

Adicionar metadados de arquivo

Você também pode incluir metadados ao fazer upload de arquivos. Esses metadados contêm propriedades típicas de metadados de arquivo, como name , size e contentType (comumente chamado de tipo MIME). O método putFile: infere automaticamente o tipo de conteúdo da extensão de nome de arquivo NSURL , mas você pode substituir 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 da extensão do arquivo, o Cloud Storage usará application/octet-stream . Consulte a seção Usar metadados de arquivo para obter mais informações sobre metadados de arquivo.

Rápido

// Create storage reference
let mountainsRef = storageRef.child("images/mountains.jpg")

// Create file metadata including the content type
let metadata = StorageMetadata()
metadata.contentType = "image/jpeg"

// Upload data and metadata
mountainsRef.putData(data, metadata: metadata)

// Upload file and metadata
mountainsRef.putFile(from: localFile, metadata: metadata)

Objetivo-C

// Create storage reference
FIRStorageReference *mountainsRef = [storageRef child:@"images/mountains.jpg"];

// Create file metadata including the content type
FIRStorageMetadata *metadata = [[FIRStorageMetadata alloc] init];
metadata.contentType = @"image/jpeg";

// Upload data and metadata
FIRStorageUploadTask *uploadTask = [mountainsRef putData:data metadata:metadata];

// Upload file and metadata
uploadTask = [mountainsRef putFile:localFile metadata:metadata];

Gerenciar envios

Além de iniciar uploads, você pode pausar, retomar e cancelar uploads usando os métodos pause , resume e cancel . Esses métodos geram eventos pause , resume e cancel . Cancelar um upload faz com que ele falhe com um erro indicando que o upload foi cancelado.

Rápido

// Start uploading a file
let uploadTask = storageRef.putFile(from: localFile)

// Pause the upload
uploadTask.pause()

// Resume the upload
uploadTask.resume()

// Cancel the upload
uploadTask.cancel()

Objetivo-C

// Start uploading a file
FIRStorageUploadTask *uploadTask = [storageRef putFile:localFile];

// Pause the upload
[uploadTask pause];

// Resume the upload
[uploadTask resume];

// Cancel the upload
[uploadTask cancel];

Monitore o progresso do upload

Você pode anexar observadores a FIRStorageUploadTask s para monitorar o progresso do upload. Adicionar um observador retorna um FIRStorageHandle que pode ser usado para remover o observador.

Rápido

// Add a progress observer to an upload task
let observer = uploadTask.observe(.progress) { snapshot in
  // A progress event occured
}

Objetivo-C

// Add a progress observer to an upload task
FIRStorageHandle observer = [uploadTask observeStatus:FIRStorageTaskStatusProgress
                                              handler:^(FIRStorageTaskSnapshot *snapshot) {
                                                // A progress event occurred
                                              }];

Esses observadores podem ser adicionados a um evento FIRStorageTaskStatus :

Evento FIRStorageTaskStatus Uso típico
FIRStorageTaskStatusResume Esse evento é acionado quando a tarefa inicia ou retoma o upload e geralmente é usado em conjunto com o evento FIRStorageTaskStatusPause .
FIRStorageTaskStatusProgress Esse evento é acionado sempre que há upload de dados para o Cloud Storage e pode ser usado para preencher um indicador de progresso de upload.
FIRStorageTaskStatusPause Esse evento é acionado sempre que o upload é pausado e geralmente é usado em conjunto com o evento FIRStorageTaskStatusResume .
FIRStorageTaskStatusSuccess Este evento é acionado quando um upload é concluído com êxito.
FIRStorageTaskStatusFailure Este evento é acionado quando um upload falha. Inspecione o erro para determinar o motivo da falha.

Quando ocorre um evento, um objeto FIRStorageTaskSnapshot é passado de volta. Este instantâneo é uma visão imutável da tarefa no momento em que o evento ocorreu. Este objeto contém as seguintes propriedades:

Propriedade Tipo Descrição
progress NSProgress Um objeto NSProgress que contém o progresso do upload.
error NSError Um erro que ocorreu durante o upload, se houver.
metadata FIRStorageMetadata Durante o upload contém metadados sendo carregados. Após um evento FIRTaskStatusSuccess , contém os metadados do arquivo carregado.
task FIRStorageUploadTask A tarefa da qual este é um instantâneo, que pode ser usado para gerenciar ( pause , resume , cancel ) a tarefa.
reference FIRStorageReference A referência de onde veio esta tarefa.

Você também pode remover observadores, individualmente, por status ou removendo todos eles.

Rápido

// Create a task listener handle
let observer = uploadTask.observe(.progress) { snapshot in
  // A progress event occurred
}

// Remove an individual observer
uploadTask.removeObserver(withHandle: observer)

// Remove all observers of a particular status
uploadTask.removeAllObservers(for: .progress)

// Remove all observers
uploadTask.removeAllObservers()

Objetivo-C

// Create a task listener handle
FIRStorageHandle observer = [uploadTask observeStatus:FIRStorageTaskStatusProgress
                                              handler:^(FIRStorageTaskSnapshot *snapshot) {
                                                // A progress event occurred
                                              }];

// Remove an individual observer
[uploadTask removeObserverWithHandle:observer];

// Remove all observers of a particular status
[uploadTask removeAllObserversForStatus:FIRStorageTaskStatusProgress];

// Remove all observers
[uploadTask removeAllObservers];

Para evitar vazamentos de memória, todos os observadores são removidos após a ocorrência de um FIRStorageTaskStatusSuccess ou FIRStorageTaskStatusFailure .

Manipulação de erros

Há vários motivos pelos quais podem ocorrer erros no upload, incluindo a inexistência do arquivo local ou o usuário não ter permissão para fazer upload do arquivo desejado. Você pode encontrar mais informações sobre erros na seção Tratar erros dos documentos.

Exemplo completo

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

Rápido

// Local file you want to upload
let localFile = URL(string: "path/to/image")!

// Create the file metadata
let metadata = StorageMetadata()
metadata.contentType = "image/jpeg"

// Upload file and metadata to the object 'images/mountains.jpg'
let uploadTask = storageRef.putFile(from: localFile, metadata: metadata)

// Listen for state changes, errors, and completion of the upload.
uploadTask.observe(.resume) { snapshot in
  // Upload resumed, also fires when the upload starts
}

uploadTask.observe(.pause) { snapshot in
  // Upload paused
}

uploadTask.observe(.progress) { snapshot in
  // Upload reported progress
  let percentComplete = 100.0 * Double(snapshot.progress!.completedUnitCount)
    / Double(snapshot.progress!.totalUnitCount)
}

uploadTask.observe(.success) { snapshot in
  // Upload completed successfully
}

uploadTask.observe(.failure) { snapshot in
  if let error = snapshot.error as? NSError {
    switch (StorageErrorCode(rawValue: error.code)!) {
    case .objectNotFound:
      // File doesn't exist
      break
    case .unauthorized:
      // User doesn't have permission to access file
      break
    case .cancelled:
      // User canceled the upload
      break

    /* ... */

    case .unknown:
      // Unknown error occurred, inspect the server response
      break
    default:
      // A separate error occurred. This is a good place to retry the upload.
      break
    }
  }
}

Objetivo-C

// Local file you want to upload
NSURL *localFile = [NSURL URLWithString:@"path/to/image"];

// Create the file metadata
FIRStorageMetadata *metadata = [[FIRStorageMetadata alloc] init];
metadata.contentType = @"image/jpeg";

// Upload file and metadata to the object 'images/mountains.jpg'
FIRStorageUploadTask *uploadTask = [storageRef putFile:localFile metadata:metadata];

// Listen for state changes, errors, and completion of the upload.
[uploadTask observeStatus:FIRStorageTaskStatusResume handler:^(FIRStorageTaskSnapshot *snapshot) {
  // Upload resumed, also fires when the upload starts
}];

[uploadTask observeStatus:FIRStorageTaskStatusPause handler:^(FIRStorageTaskSnapshot *snapshot) {
  // Upload paused
}];

[uploadTask observeStatus:FIRStorageTaskStatusProgress handler:^(FIRStorageTaskSnapshot *snapshot) {
  // Upload reported progress
  double percentComplete = 100.0 * (snapshot.progress.completedUnitCount) / (snapshot.progress.totalUnitCount);
}];

[uploadTask observeStatus:FIRStorageTaskStatusSuccess handler:^(FIRStorageTaskSnapshot *snapshot) {
  // Upload completed successfully
}];

// Errors only occur in the "Failure" case
[uploadTask observeStatus:FIRStorageTaskStatusFailure handler:^(FIRStorageTaskSnapshot *snapshot) {
  if (snapshot.error != nil) {
    switch (snapshot.error.code) {
      case FIRStorageErrorCodeObjectNotFound:
        // File doesn't exist
        break;

      case FIRStorageErrorCodeUnauthorized:
        // User doesn't have permission to access file
        break;

      case FIRStorageErrorCodeCancelled:
        // User canceled the upload
        break;

      /* ... */

      case FIRStorageErrorCodeUnknown:
        // Unknown error occurred, inspect the server response
        break;
    }
  }
}];

Agora que você fez upload dos arquivos, vamos aprender como baixá-los do Cloud Storage.