Cargar archivos con Cloud Storage en plataformas Apple

Cloud Storage para Firebase le permite cargar archivos de forma rápida y sencilla a un depósito de Cloud Storage proporcionado y administrado por Firebase.

Crear una referencia

Para cargar un archivo, primero cree una referencia de Cloud Storage a la ubicación en Cloud Storage donde desea cargar el archivo.

Puedes crear una referencia agregando rutas secundarias a la raíz de tu depósito de 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

C objetivo

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

No puedes cargar datos con una referencia a la raíz de tu depósito de Cloud Storage. Su referencia debe apuntar a una URL secundaria.

Subir archivos

Una vez que tengas una referencia, podrás subir archivos a Cloud Storage de dos maneras:

  1. Cargar desde datos en la memoria
  2. Subir desde una URL que representa un archivo en el dispositivo

Cargar desde datos en la memoria

El método putData:metadata:completion: es la forma más sencilla de cargar un archivo en Cloud Storage. putData:metadata:completion: toma un objeto NSData y devuelve un FIRStorageUploadTask , que puedes usar para administrar tu carga y monitorear su estado.

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

C objetivo

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

Subir desde un archivo local

Puede cargar archivos locales en los dispositivos, como fotos y videos desde la cámara, con el método putFile:metadata:completion: putFile:metadata:completion: toma una NSURL y devuelve una FIRStorageUploadTask , que puedes usar para administrar tu carga y monitorear su estado.

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

C objetivo

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

Si desea administrar activamente su carga, puede usar los métodos putData: o putFile: y observar la tarea de carga, en lugar de usar el controlador de finalización. Consulte Administrar cargas para obtener más información.

Agregar metadatos de archivo

También puedes incluir metadatos cuando subes archivos. Estos metadatos contienen propiedades típicas de metadatos de archivos, como name , size y contentType (comúnmente denominado tipo MIME). El método putFile: infiere automáticamente el tipo de contenido a partir de la extensión del nombre de archivo NSURL , pero puede anular el tipo detectado automáticamente especificando contentType en los metadatos. Si no proporciona un contentType y Cloud Storage no puede inferir un valor predeterminado a partir de la extensión del archivo, Cloud Storage usa application/octet-stream . Consulte la sección Usar metadatos de archivos para obtener más información sobre los metadatos de archivos.

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)

C objetivo

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

Administrar cargas

Además de iniciar las cargas, puede pausarlas, reanudarlas y cancelarlas utilizando los métodos pause , resume y cancel . Estos métodos generan eventos pause , resume y cancel . Cancelar una carga hace que la carga falle con un error que indica que la carga fue cancelada.

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

C objetivo

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

// Pause the upload
[uploadTask pause];

// Resume the upload
[uploadTask resume];

// Cancel the upload
[uploadTask cancel];

Supervisar el progreso de la carga

Puede adjuntar observadores a FIRStorageUploadTask para monitorear el progreso de la carga. Agregar un observador devuelve un FIRStorageHandle que se puede usar para eliminar el observador.

Rápido

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

C objetivo

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

Estos observadores se pueden agregar a un evento FIRStorageTaskStatus :

Evento FIRStorageTaskStatus Uso típico
FIRStorageTaskStatusResume Este evento se activa cuando la tarea comienza o reanuda la carga y, a menudo, se usa junto con el evento FIRStorageTaskStatusPause .
FIRStorageTaskStatusProgress Este evento se activa cada vez que se cargan datos en Cloud Storage y se puede usar para completar un indicador de progreso de carga.
FIRStorageTaskStatusPause Este evento se activa cada vez que se pausa la carga y, a menudo, se usa junto con el evento FIRStorageTaskStatusResume .
FIRStorageTaskStatusSuccess Este evento se activa cuando una carga se completa exitosamente.
FIRStorageTaskStatusFailure Este evento se activa cuando falla una carga. Inspeccione el error para determinar el motivo de la falla.

Cuando ocurre un evento, se devuelve un objeto FIRStorageTaskSnapshot . Esta instantánea es una vista inmutable de la tarea, en el momento en que ocurrió el evento. Este objeto contiene las siguientes propiedades:

Propiedad Tipo Descripción
progress NSProgress Un objeto NSProgress que contiene el progreso de la carga.
error NSError Un error que ocurrió durante la carga, si lo hubo.
metadata FIRStorageMetadata Durante la carga contiene metadatos que se están cargando. Después de un evento FIRTaskStatusSuccess , contiene los metadatos del archivo cargado.
task FIRStorageUploadTask La tarea de la que se trata es una instantánea, que se puede utilizar para administrar ( pause , resume , cancel ) la tarea.
reference FIRStorageReference La referencia de la que surgió esta tarea.

También puede eliminar observadores, ya sea individualmente, por estado o eliminándolos a todos.

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

C objetivo

// 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 pérdidas de memoria, todos los observadores se eliminan después de que se produce un FIRStorageTaskStatusSuccess o FIRStorageTaskStatusFailure .

Manejo de errores

Hay varias razones por las que pueden ocurrir errores durante la carga, incluido el archivo local que no existe o que el usuario no tiene permiso para cargar el archivo deseado. Puede encontrar más información sobre los errores en la sección Manejar errores de los documentos.

Ejemplo completo

A continuación se muestra un ejemplo completo de una carga con seguimiento del progreso y manejo de errores:

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

C objetivo

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

Ahora que has subido archivos, aprendamos cómo descargarlos desde Cloud Storage.