Fazer upload de arquivos com o Cloud Storage em plataformas da Apple

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 ao local no Cloud Storage para onde você quer enviar o arquivo.

Para criar uma referência, anexe caminhos filhos à raiz do bucket do Cloud Storage:

Swift

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

Objective-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 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 dados na memória
2. Fazer upload de um URL que representa um arquivo no dispositivo.

Fazer 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: usa um objeto NSData e retorna um FIRStorageUploadTask, que pode ser usado para gerenciar o upload e monitorar o status dele.

Swift

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

Objective-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;
      }
    }];
  }
}];
  

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 putFile:metadata:completion:. O putFile:metadata:completion: usa um NSURL e retorna um FIRStorageUploadTask, que pode ser usado para gerenciar o upload e monitorar o status dele.

Swift

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

Objective-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 você quiser gerenciar o upload ativamente, use os métodos putData: ou putFile: e observe a tarefa de upload em vez de usar o gerenciador de conclusão. Saiba mais na seção Gerenciar uploads.

Adicionar metadados de arquivo

Você também pode incluir metadados ao fazer upload de arquivos. Em geral, esses metadados contêm propriedades típicas de arquivos, como name, size e contentType (frequentemente chamadas de tipo MIME). O método putFile: infere automaticamente o tipo de conteúdo pela extensão do nome de arquivo NSURL, mas é possível 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.

Swift

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

Objective-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 uploads

Além de iniciar os 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.

Swift

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

Objective-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];
  

Monitorar o andamento do upload

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

Swift

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

Objective-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:

FIRStorageTaskStatus evento	Uso típico
FIRStorageTaskStatusResume	Este evento é disparado quando a tarefa inicia ou retoma o upload e geralmente é usado junto com o evento FIRStorageTaskStatusPause.
FIRStorageTaskStatusProgress	Esse evento dispara sempre que ocorre upload de dados para o Cloud Storage, podendo ser usado para preencher o indicador de andamento de um upload.
FIRStorageTaskStatusPause	Este evento é disparado sempre que o upload é pausado e geralmente é usado junto com o evento FIRStorageTaskStatusResume.
FIRStorageTaskStatusSuccess	Acionado quando um upload é concluído com sucesso.
FIRStorageTaskStatusFailure	Acionado quando ocorre falha em um upload. Inspecione o erro para determinar o motivo da falha.

Quando ocorre um evento, um objeto FIRStorageTaskSnapshot é retornado. O snapshot é uma visualização imutável da tarefa no momento em que esse evento ocorreu. Esse 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 for o caso.
metadata	FIRStorageMetadata	Durante o upload, contém os metadados que estão sendo enviados. Depois de um evento FIRTaskStatusSuccess, contém os metadados do arquivo enviado.
task	FIRStorageUploadTask	A tarefa a que se refere o instantâneo, que pode ser usada para gerenciar (pause, resume, cancel) a tarefa.
reference	FIRStorageReference	A referência de onde veio essa tarefa.

Os observadores também podem ser removidos individualmente, por status ou todos de uma vez.

Swift

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

Objective-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 depois que ocorre um FIRStorageTaskStatusSuccess ou FIRStorageTaskStatusFailure.

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.

Exemplo completo

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

Swift

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

Objective-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ê já sabe fazer upload de arquivos, veja como baixá-los do Cloud Storage.