Caricare file con Cloud Storage sulle piattaforme Apple

Cloud Storage for Firebase ti consente di caricare rapidamente e facilmente file in un bucket Cloud Storage fornito e gestito da Firebase.

Creazione di un riferimento

Per caricare un file, innanzitutto crea un riferimento Cloud Storage alla posizione in Cloud Storage in cui vuoi caricare il file.

Puoi creare un riferimento aggiungendo i percorsi secondari alla radice del tuo bucket 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

Non puoi caricare dati con un riferimento alla radice del tuo Cloud Storage bucket. Il riferimento deve indirizzare a un URL secondario.

Carica file

Una volta creato un riferimento, puoi caricare i file su Cloud Storage in due modi:

  1. Carica da dati in memoria
  2. Caricamento da un URL che rappresenta un file sul dispositivo

Carica da dati in memoria

Il metodo putData:metadata:completion: è il modo più semplice per caricare un file su Cloud Storage. putData:metadata:completion: prende un oggetto NSData e restituisce un FIRStorageUploadTask, che puoi utilizzare per gestire il caricamento e monitorarne lo stato.

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

Carica da un file locale

Puoi caricare file locali sui dispositivi, ad esempio foto e video della fotocamera, con il metodo putFile:metadata:completion:. putFile:metadata:completion: riceve un NSURL e restituisce un FIRStorageUploadTask, che puoi utilizzare per gestire il caricamento e monitorarne lo stato.

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 vuoi gestire attivamente il caricamento, puoi utilizzare i metodi putData: o putFile: e osservare l'attività di caricamento anziché utilizzare il gestore del completamento. Per ulteriori informazioni, consulta Gestire i caricamenti.

Aggiungere metadati dei file

Puoi anche includere i metadati quando carichi i file. Questi metadati contengono proprietà di metadati dei file comuni come name, size e contentType (comunemente noto come tipo MIME). Il metodo putFile: ricava automaticamente il tipo di contenuti dall'estensione del nome file NSURL, ma puoi sostituire il tipo rilevato automaticamente specificando contentType nei metadati. Se non fornisci un contentType e Cloud Storage non può dedurre un valore predefinito dall'estensione del file, Cloud Storage utilizzerà application/octet-stream. Per ulteriori informazioni sui metadati dei file, consulta la sezione Utilizzare i metadati dei file.

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

Gestisci caricamenti

Oltre ad avviare i caricamenti, puoi metterli in pausa, riprenderli e annullarli utilizzando i metodi pause, resume e cancel. Questi metodi generano eventi pause, resume e cancel. L'annullamento di un caricamento ne causa il fallimento con un errore che indica che il caricamento è stato annullato.

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

Monitorare l'avanzamento del caricamento

Puoi associare osservatori ai FIRStorageUploadTask per monitorare l'avanzamento del caricamento. L'aggiunta di un osservatore restituisce un FIRStorageHandle che può essere utilizzato per rimuoverlo.

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

Questi osservatori possono essere aggiunti a un evento FIRStorageTaskStatus:

FIRStorageTaskStatus evento Utilizzo tipico
FIRStorageTaskStatusResume Questo evento viene attivato quando l'attività inizia o riprende il caricamento e viene spesso utilizzato in combinazione con l'evento FIRStorageTaskStatusPause.
FIRStorageTaskStatusProgress Questo evento viene attivato ogni volta che i dati vengono caricati in Cloud Storage e può essere utilizzato per compilare un indicatore dell'avanzamento del caricamento.
FIRStorageTaskStatusPause Questo evento viene attivato ogni volta che il caricamento viene messo in pausa e viene spesso utilizzato in combinazione con l'evento FIRStorageTaskStatusResume.
FIRStorageTaskStatusSuccess Questo evento viene attivato al termine di un caricamento.
FIRStorageTaskStatusFailure Questo evento viene attivato quando un caricamento non è riuscito. Esamina l'errore per determinare il motivo dell'errore.

Quando si verifica un evento, viene restituito un oggetto FIRStorageTaskSnapshot. Questo snapshot è una vista immutabile dell'attività al momento in cui si è verificato l'evento. Questo oggetto contiene le seguenti proprietà:

Proprietà Tipo Descrizione
progress NSProgress Un oggetto NSProgress contenente l'avanzamento del caricamento.
error NSError Eventuale errore che si è verificato durante il caricamento.
metadata FIRStorageMetadata Durante il caricamento contiene i metadati in fase di caricamento. Dopo un evento FIRTaskStatusSuccess, contiene i metadati del file caricato.
task FIRStorageUploadTask L'attività di cui è stato eseguito uno snapshot, che può essere utilizzata per gestire (pause, resume, cancel) l'attività.
reference FIRStorageReference Il riferimento da cui proviene l'attività.

Puoi anche rimuovere gli osservatori singolarmente, in base allo stato o rimuovere tutti.

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

Per evitare perdite di memoria, tutti gli osservatori vengono rimossi dopo un FIRStorageTaskStatusSuccess o FIRStorageTaskStatusFailure.

Gestione degli errori

Esistono diversi motivi per cui potrebbero verificarsi errori durante il caricamento, ad esempio il file locale non esiste o l'utente non dispone dell'autorizzazione per caricare il file desiderato. Puoi trovare ulteriori informazioni sugli errori nella sezione Gestire gli errori della documentazione.

Esempio completo

Di seguito è riportato un esempio completo di caricamento con monitoraggio dell'avanzamento e gestione degli errori:

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

Ora che hai caricato i file, scopri come scaricarli da Cloud Storage.