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, per prima cosa crea un riferimento Cloud Storage nella posizione in Cloud Storage in cui vuoi caricare il file.

Puoi creare un riferimento aggiungendo percorsi figlio alla radice del file Cloud Storage bucket:

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 directory principale Cloud Storage bucket. Il tuo riferimento deve indirizzare a un URL secondario.

Carica file

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

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

Carica dai dati in memoria

Il metodo putData:metadata:completion: è il modo più semplice per caricare un file a Cloud Storage. putData:metadata:completion: richiede un NSData e restituisce un valore FIRStorageUploadTask, che puoi utilizzare per gestire caricare e monitorare 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, fotocamera, con il metodo putFile:metadata:completion:. putFile:metadata:completion: richiede NSURL e restituisce un FIRStorageUploadTask, che puoi utilizzare per gestire il caricamento e monitorarne .

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

Aggiungi metadati dei file

Puoi anche includere i metadati quando carichi i file. Questi metadati contengono le tipiche proprietà dei metadati dei file, come name, size, e contentType (comunemente 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 nel 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. Consulta le Utilizzare i metadati dei file per ulteriori informazioni sui 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 pause, Eventi resume e cancel. Se annulli un caricamento, il caricamento non riesce 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];

Monitora 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 su Cloud Storage e può essere utilizzato per completare 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 viene 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 uno snapshot è una visualizzazione immutabile dell'attività, nel 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 Un errore che si è verificato durante il caricamento, se presente.
metadata FIRStorageMetadata Durante il caricamento, contiene i metadati che stai caricando. 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 questa 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 fughe di memoria, tutti gli osservatori vengono rimossi dopo Si verifica FIRStorageTaskStatusSuccess o FIRStorageTaskStatusFailure.

Gestione degli errori

Esistono diversi motivi per cui possono verificarsi errori in fase di caricamento, ad esempio: il file locale non esiste o l'utente non dispone dell'autorizzazione per caricarlo del file desiderato. Puoi trovare ulteriori informazioni sugli errori nel Gestire gli errori sezione dei documenti.

Esempio completo

Esempio completo di caricamento con monitoraggio dell'avanzamento e gestione degli errori è mostrato di seguito:

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.