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.

Nota: per impostazione predefinita, un bucket Cloud Storage for Firebase richiede Firebase Authentication per eseguire qualsiasi azione sui dati o sui file del bucket. Puoi sostituire Firebase Security Rules con Cloud Storage per consentire l'accesso non autenticato per situazioni specifiche. Tuttavia, per la maggior parte delle situazioni, ti consigliamo vivamente di limitare l'accesso e configurare regole di sicurezza efficaci (soprattutto per le app di produzione). Tieni presente che se utilizzi Google App Engine e hai un bucket Cloud Storage predefinito con un formato del nome *.appspot.com, potresti dover considerare in che modo le tue regole di sicurezza influiscono sull'accesso ai file App Engine.

Nota: per i progetti con piano Spark, Firebase blocca il caricamento e l'hosting di determinati tipi di file eseguibili per Windows (file con estensioni .exe, .dll e .bat), Android (estensione .apk) e Apple (estensione .ipa) da Cloud Storage for Firebase e Firebase Hosting. Queste norme hanno lo scopo di prevenire gli abusi sulla nostra piattaforma. I progetti nel piano Blaze non sono interessati. Per ulteriori informazioni, consulta queste domande frequenti.

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.