Caricare file con Cloud Storage sulle piattaforme Apple

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

Creazione di un riferimento

Per caricare un file, devi prima creare 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 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 bucket Cloud Storage. Il riferimento deve rimandare a un URL secondario.

Carica file

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

  1. Caricare i dati dalla memoria
  2. Caricare da un URL che rappresenta un file sul dispositivo

Caricare i dati dalla memoria

Il metodo putData:metadata:completion: è il modo più semplice per caricare un file su Cloud Storage. putData:metadata:completion: accetta 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;
      }
    }];
  }
}];

Caricare da un file locale

Puoi caricare file locali sui dispositivi, come foto e video dalla fotocamera, con il metodo putFile:metadata:completion:. putFile:metadata:completion: accetta 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 di completamento. Per ulteriori informazioni, consulta Gestire i caricamenti.

Aggiungere metadati del file

Puoi anche includere i metadati quando carichi i file. Questi metadati contengono le proprietà tipiche dei metadati dei file, come name, size e contentType (comunemente indicato come tipo MIME). Il metodo putFile: deduce automaticamente il tipo di contenuti dall'estensione del nome file NSURL, ma puoi ignorare 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 utilizza application/octet-stream. Per saperne di più 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 l'esito negativo 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 allegare osservatori ai FIRStorageUploadTask per monitorare l'avanzamento del caricamento. L'aggiunta di un osservatore restituisce un FIRStorageHandle che può essere utilizzato per rimuovere l'osservatore.

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
NSString *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 su Cloud Storage e può essere utilizzato per popolare un indicatore di 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 quando un caricamento è stato completato correttamente.
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 visualizzazione immutabile dell'attività al momento dell'evento. Questo oggetto contiene le seguenti proprietà:

Proprietà Tipo Descrizione
progress NSProgress Un oggetto NSProgress contenente l'avanzamento del caricamento.
error NSError Un errore verificatosi durante il caricamento, se presente.
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 viene acquisita un'istantanea, che può essere utilizzata per gestire (pause, resume, cancel) l'attività.
reference FIRStorageReference Il riferimento da cui proviene questa attività.

Puoi anche rimuovere gli osservatori singolarmente, in base allo stato o rimuovendoli 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
NSString *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 che si verifica un FIRStorageTaskStatusSuccess o un FIRStorageTaskStatusFailure.

Gestione degli errori

Esistono diversi motivi per cui potrebbero verificarsi errori durante il caricamento, tra cui l'assenza del file locale o la mancanza 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, scopriamo come scaricarli da Cloud Storage.