Sube archivos con Cloud Storage en plataformas de Apple

Cloud Storage for Firebase te permite subir archivos con rapidez y facilidad a un bucket de Cloud Storage proporcionado y administrado por Firebase.

Crea una referencia

Para subir un archivo, primero crea una referencia de Cloud Storage a la ubicación de Cloud Storage a la que quieres subir el archivo.

Para ello, puedes anexar rutas de acceso secundarias a la raíz de tu bucket de 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

No es posible subir datos con una referencia a la raíz de tu bucket de Cloud Storage. La referencia debe apuntar a una URL secundaria.

Sube archivos

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

  1. Sube archivos desde datos en la memoria
  2. subir desde una URL que represente un archivo en el dispositivo

Sube archivos desde datos en la memoria

El método putData:metadata:completion: es la forma más sencilla de subir un archivo a Cloud Storage. putData:metadata:completion: toma un objeto NSData y muestra un FIRStorageUploadTask que puedes usar para administrar la carga y supervisar su estado.

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

Sube archivos desde un archivo local

Puedes usar el método putFile:metadata:completion: para subir archivos locales de los dispositivos, como fotos y videos de la cámara. putFile:metadata:completion: toma un NSURL y muestra un FIRStorageUploadTask que puedes usar para administrar la carga y supervisar su estado.

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

Si deseas administrar activamente tu carga, puedes usar los métodos putData: o putFile: y observar esa tarea en lugar de usar el controlador de finalización. Consulta cómo administrar cargas para obtener más información.

Agrega metadatos de archivos

También puedes incluir metadatos cuando subas archivos. Estos metadatos contienen propiedades típicas de metadatos de archivo, como name, size y contentType (comúnmente denominadas tipos de MIME). El método putFile: infiere el tipo de contenido a partir de la extensión de nombre de archivo NSURL en forma automática, pero puedes especificar contentType en los metadatos para anular el tipo detectado. Si no proporcionas un contentType y Cloud Storage no puede inferir un valor predeterminado a partir de la extensión de archivo, Cloud Storage usará application/octet-stream. Consulta la sección Usa metadatos de archivos para obtener más información acerca de estos.

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

Administra cargas

Además de iniciar cargas, puedes detener, reanudar y cancelar cargas con los métodos pause, resume y cancel. Con estos métodos, se generan eventos pause, resume y cancel. Si se cancela una carga, se produce un error que indica que se canceló la carga.

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

Supervisa el progreso de la carga

Puedes adjuntar observadores como FIRStorageUploadTask para supervisar el progreso de la carga. Si agregas un observador, se muestra un FIRStorageHandle que se puede usar para quitar el 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
                                              }];

Estos observadores se pueden agregar a un evento FIRStorageTaskStatus:

Evento FIRStorageTaskStatus Uso común
FIRStorageTaskStatusResume Este evento se activa cuando la tarea inicia o reanuda la carga. A menudo, se usa en combinación con el evento FIRStorageTaskStatusPause.
FIRStorageTaskStatusProgress Este evento se activa cuando se suben datos a Cloud Storage y se puede usar para propagar un indicador de progreso de carga.
FIRStorageTaskStatusPause Este evento se activa cuando la carga se detiene. A menudo, se usa en combinación con el evento FIRStorageTaskStatusResume.
FIRStorageTaskStatusSuccess Este evento se activa cuando la carga se completó correctamente.
FIRStorageTaskStatusFailure Este evento se activa cuando se produce un error de carga. Inspecciona el error para determinar el motivo de la falla.

Cuando ocurre un evento, se envía 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 se produjo durante la carga, si existiese.
metadata FIRStorageMetadata Durante la carga contiene los metadatos que se suben. Después de un evento FIRTaskStatusSuccess, contiene los metadatos del archivo subido.
task FIRStorageUploadTask La tarea a la que corresponde esta instantánea, que se puede utilizar para administrar la tarea (pause, resume y cancel).
reference FIRStorageReference La referencia de la que provino la tarea.

También puedes quitar observadores, ya sea individualmente, por estado o quitarlos todos.

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 fugas de memoria, todos los observadores se quitan después de que ocurre un FIRStorageTaskStatusSuccess o un FIRStorageTaskStatusFailure.

Manejo de errores

Existen diferentes motivos por los que pueden producirse errores durante la carga, como que el archivo local no exista o que el usuario no tenga permiso para subir el archivo deseado. Para obtener más información sobre errores, consulta la sección Soluciona errores de la documentación.

Ejemplo completo

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

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

Ahora que ya subiste archivos, veamos cómo descárgarlos desde Cloud Storage.