Lire et écrire des données sur les plateformes Apple

(Facultatif) Prototyper et tester avec Firebase Local Emulator Suite

Avant de parler de la façon dont votre application lit et écrit dans la base de données en temps réel, présentons un ensemble d'outils que vous pouvez utiliser pour prototyper et tester les fonctionnalités de la base de données en temps réel : Firebase Local Emulator Suite. Si vous essayez différents modèles de données, optimisez vos règles de sécurité ou cherchez le moyen le plus rentable d'interagir avec le back-end, pouvoir travailler localement sans déployer de services en direct peut être une excellente idée.

Un émulateur de base de données en temps réel fait partie de Local Emulator Suite, qui permet à votre application d'interagir avec le contenu et la configuration de votre base de données émulée, ainsi qu'éventuellement avec les ressources de votre projet émulé (fonctions, autres bases de données et règles de sécurité).

L'utilisation de l'émulateur Realtime Database ne nécessite que quelques étapes :

  1. Ajout d'une ligne de code à la configuration de test de votre application pour vous connecter à l'émulateur.
  2. À partir de la racine du répertoire de votre projet local, exécutez firebase emulators:start .
  3. Effectuer des appels à partir du code prototype de votre application à l'aide d'un SDK de plateforme Realtime Database comme d'habitude ou à l'aide de l'API REST Realtime Database.

Une présentation détaillée impliquant la base de données en temps réel et les fonctions cloud est disponible. Vous devriez également jeter un œil à l’introduction de Local Emulator Suite .

Obtenir une référence FIRDatabaseReference

Pour lire ou écrire des données de la base de données, vous avez besoin d'une instance de FIRDatabaseReference :

Rapide

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
var ref: DatabaseReference!

ref = Database.database().reference()

Objectif c

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
@property (strong, nonatomic) FIRDatabaseReference *ref;

self.ref = [[FIRDatabase database] reference];

Écrire des données

Ce document couvre les bases de la lecture et de l'écriture de données Firebase.

Les données Firebase sont écrites dans une référence Database et récupérées en attachant un écouteur asynchrone à la référence. L'écouteur est déclenché une fois pour l'état initial des données et de nouveau à chaque fois que les données changent.

Opérations d'écriture de base

Pour les opérations d'écriture de base, vous pouvez utiliser setValue pour enregistrer les données dans une référence spécifiée, en remplaçant toutes les données existantes à ce chemin. Vous pouvez utiliser cette méthode pour :

  • Transmettez les types qui correspondent aux types JSON disponibles comme suit :
    • NSString
    • NSNumber
    • NSDictionary
    • NSArray

Par exemple, vous pouvez ajouter un utilisateur avec setValue comme suit :

Rapide

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
self.ref.child("users").child(user.uid).setValue(["username": username])

Objectif c

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
[[[self.ref child:@"users"] child:authResult.user.uid]
    setValue:@{@"username": username}];

L'utilisation setValue de cette manière écrase les données à l'emplacement spécifié, y compris les nœuds enfants. Cependant, vous pouvez toujours mettre à jour un enfant sans réécrire l'intégralité de l'objet. Si vous souhaitez autoriser les utilisateurs à mettre à jour leur profil, vous pouvez mettre à jour le nom d'utilisateur comme suit :

Rapide

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
self.ref.child("users/\(user.uid)/username").setValue(username)

Objectif c

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
[[[[_ref child:@"users"] child:user.uid] child:@"username"] setValue:username];

Lire des données

Lire les données en écoutant les événements de valeur

Pour lire des données sur un chemin et écouter les modifications, utilisez observeEventType:withBlock de FIRDatabaseReference pour observer les événements FIRDataEventTypeValue .

Type d'événement Utilisation typique
FIRDataEventTypeValue Lisez et écoutez les modifications apportées à l'ensemble du contenu d'un chemin.

Vous pouvez utiliser l'événement FIRDataEventTypeValue pour lire les données sur un chemin donné, tel qu'il existe au moment de l'événement. Cette méthode est déclenchée une fois lorsque l'écouteur est attaché et à nouveau chaque fois que les données, y compris les enfants, changent. Le rappel d'événement reçoit un snapshot contenant toutes les données à cet emplacement, y compris les données enfants. S'il n'y a pas de données, l'instantané renverra false lorsque vous appellerez exists() et nil lorsque vous lirez sa propriété value .

L'exemple suivant montre une application de blog social récupérant les détails d'une publication de la base de données :

Rapide

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
refHandle = postRef.observe(DataEventType.value, with: { snapshot in
  // ...
})

Objectif c

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
_refHandle = [_postRef observeEventType:FIRDataEventTypeValue withBlock:^(FIRDataSnapshot * _Nonnull snapshot) {
  NSDictionary *postDict = snapshot.value;
  // ...
}];

L'écouteur reçoit un FIRDataSnapshot qui contient les données à l'emplacement spécifié dans la base de données au moment de l'événement dans sa propriété value . Vous pouvez attribuer les valeurs au type natif approprié, tel que NSDictionary . Si aucune donnée n'existe à l'emplacement, la value est nil .

Lire les données une fois

Lire une fois en utilisant getData()

Le SDK est conçu pour gérer les interactions avec les serveurs de bases de données, que votre application soit en ligne ou hors ligne.

En règle générale, vous devez utiliser les techniques d'événements de valeur décrites ci-dessus pour lire les données et être averti des mises à jour des données depuis le backend. Ces techniques réduisent votre utilisation et votre facturation et sont optimisées pour offrir à vos utilisateurs la meilleure expérience lorsqu'ils se connectent et hors ligne.

Si vous n'avez besoin des données qu'une seule fois, vous pouvez utiliser getData() pour obtenir un instantané des données de la base de données. Si, pour une raison quelconque getData() ne parvient pas à renvoyer la valeur du serveur, le client sondera le cache de stockage local et renverra une erreur si la valeur n'est toujours pas trouvée.

L'exemple suivant montre la récupération unique du nom d'utilisateur public d'un utilisateur à partir de la base de données :

Rapide

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
do {
  let snapshot = try await ref.child("users/\(uid)/username").getData()
  let userName = snapshot.value as? String ?? "Unknown"
} catch {
  print(error)
}

Objectif c

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
NSString *userPath = [NSString stringWithFormat:@"users/%@/username", uid];
[[ref child:userPath] getDataWithCompletionBlock:^(NSError * _Nullable error, FIRDataSnapshot * _Nonnull snapshot) {
  if (error) {
    NSLog(@"Received an error %@", error);
    return;
  }
  NSString *userName = snapshot.value;
}];

L'utilisation inutile de getData() peut augmenter l'utilisation de la bande passante et entraîner une perte de performances, ce qui peut être évité en utilisant un écouteur en temps réel comme indiqué ci-dessus.

Lire les données une fois avec un observateur

Dans certains cas, vous souhaiterez peut-être que la valeur du cache local soit renvoyée immédiatement, au lieu de rechercher une valeur mise à jour sur le serveur. Dans ces cas, vous pouvez utiliser observeSingleEventOfType pour obtenir immédiatement les données du cache disque local.

Ceci est utile pour les données qui ne doivent être chargées qu’une seule fois et qui ne devraient pas changer fréquemment ni nécessiter une écoute active. Par exemple, l'application de blog dans les exemples précédents utilise cette méthode pour charger le profil d'un utilisateur lorsqu'il commence à rédiger un nouveau message :

Rapide

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
let userID = Auth.auth().currentUser?.uid
ref.child("users").child(userID!).observeSingleEvent(of: .value, with: { snapshot in
  // Get user value
  let value = snapshot.value as? NSDictionary
  let username = value?["username"] as? String ?? ""
  let user = User(username: username)

  // ...
}) { error in
  print(error.localizedDescription)
}

Objectif c

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
NSString *userID = [FIRAuth auth].currentUser.uid;
[[[_ref child:@"users"] child:userID] observeSingleEventOfType:FIRDataEventTypeValue withBlock:^(FIRDataSnapshot * _Nonnull snapshot) {
  // Get user value
  User *user = [[User alloc] initWithUsername:snapshot.value[@"username"]];

  // ...
} withCancelBlock:^(NSError * _Nonnull error) {
  NSLog(@"%@", error.localizedDescription);
}];

Mise à jour ou suppression de données

Mettre à jour des champs spécifiques

Pour écrire simultanément sur des enfants spécifiques d'un nœud sans écraser les autres nœuds enfants, utilisez la méthode updateChildValues .

Lorsque vous appelez updateChildValues ​​, vous pouvez mettre à jour les valeurs enfants de niveau inférieur en spécifiant un chemin pour la clé. Si les données sont stockées à plusieurs emplacements pour mieux évoluer, vous pouvez mettre à jour toutes les instances de ces données à l'aide de la répartition des données . Par exemple, une application de blog social peut souhaiter créer une publication et la mettre simultanément à jour avec le flux d'activité récente et le flux d'activité de l'utilisateur qui a publié la publication. Pour ce faire, l'application de blogging utilise un code comme celui-ci :

Rapide

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
guard let key = ref.child("posts").childByAutoId().key else { return }
let post = ["uid": userID,
            "author": username,
            "title": title,
            "body": body]
let childUpdates = ["/posts/\(key)": post,
                    "/user-posts/\(userID)/\(key)/": post]
ref.updateChildValues(childUpdates)

Objectif c

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
NSString *key = [[_ref child:@"posts"] childByAutoId].key;
NSDictionary *post = @{@"uid": userID,
                       @"author": username,
                       @"title": title,
                       @"body": body};
NSDictionary *childUpdates = @{[@"/posts/" stringByAppendingString:key]: post,
                               [NSString stringWithFormat:@"/user-posts/%@/%@/", userID, key]: post};
[_ref updateChildValues:childUpdates];

Cet exemple utilise childByAutoId pour créer une publication dans le nœud contenant les publications pour tous les utilisateurs de /posts/$postid et récupérer simultanément la clé avec getKey() . La clé peut ensuite être utilisée pour créer une deuxième entrée dans les publications de l'utilisateur à /user-posts/$userid/$postid .

À l'aide de ces chemins, vous pouvez effectuer des mises à jour simultanées à plusieurs emplacements dans l'arborescence JSON avec un seul appel à updateChildValues ​​, par exemple comment cet exemple crée la nouvelle publication aux deux emplacements. Les mises à jour simultanées effectuées de cette manière sont atomiques : soit toutes les mises à jour réussissent, soit toutes les mises à jour échouent.

Ajouter un bloc de complétion

Si vous souhaitez savoir quand vos données ont été validées, vous pouvez ajouter un bloc de complétion. setValue et updateChildValues ​​prennent tous deux un bloc d'achèvement facultatif qui est appelé lorsque l'écriture a été validée dans la base de données. Cet écouteur peut être utile pour savoir quelles données ont été enregistrées et quelles données sont toujours en cours de synchronisation. Si l'appel échoue, l'auditeur reçoit un objet d'erreur indiquant la raison de l'échec.

Rapide

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
do {
  try await ref.child("users").child(user.uid).setValue(["username": username])
  print("Data saved successfully!")
} catch {
  print("Data could not be saved: \(error).")
}

Objectif c

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
[[[_ref child:@"users"] child:user.uid] setValue:@{@"username": username} withCompletionBlock:^(NSError *error, FIRDatabaseReference *ref) {
  if (error) {
    NSLog(@"Data could not be saved: %@", error);
  } else {
    NSLog(@"Data saved successfully.");
  }
}];

Suprimmer les données

Le moyen le plus simple de supprimer des données consiste à appeler removeValue sur une référence à l'emplacement de ces données.

Vous pouvez également supprimer en spécifiant nil comme valeur pour une autre opération d'écriture telle que setValue ou updateChildValues ​​. Vous pouvez utiliser cette technique avec updateChildValues ​​pour supprimer plusieurs enfants en un seul appel d'API.

Détacher les auditeurs

Les observateurs n'arrêtent pas automatiquement la synchronisation des données lorsque vous quittez un ViewController . Si un observateur n'est pas correctement supprimé, il continue de synchroniser les données avec la mémoire locale. Lorsqu'un observateur n'est plus nécessaire, supprimez-le en passant le FIRDatabaseHandle associé à la méthode removeObserverWithHandle .

Lorsque vous ajoutez un bloc de rappel à une référence, un FIRDatabaseHandle est renvoyé. Ces handles peuvent être utilisés pour supprimer le bloc de rappel.

Si plusieurs écouteurs ont été ajoutés à une référence de base de données, chaque écouteur est appelé lorsqu'un événement est déclenché. Afin d'arrêter la synchronisation des données à cet emplacement, vous devez supprimer tous les observateurs d'un emplacement en appelant la méthode removeAllObservers .

L’appel de removeObserverWithHandle ou removeAllObservers sur un écouteur ne supprime pas automatiquement les écouteurs enregistrés sur ses nœuds enfants ; vous devez également garder une trace de ces références ou poignées pour les supprimer.

Enregistrer les données en tant que transactions

Lorsque vous travaillez avec des données susceptibles d'être corrompues par des modifications simultanées, telles que des compteurs incrémentiels, vous pouvez utiliser une opération de transaction . Vous donnez à cette opération deux arguments : une fonction de mise à jour et un rappel d'achèvement facultatif. La fonction de mise à jour prend l'état actuel des données comme argument et renvoie le nouvel état souhaité que vous souhaitez écrire.

Par exemple, dans l'exemple d'application de blog social, vous pouvez autoriser les utilisateurs à suivre et à supprimer des publications et à suivre le nombre d'étoiles qu'une publication a reçue comme suit :

Rapide

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
ref.runTransactionBlock({ (currentData: MutableData) -> TransactionResult in
  if var post = currentData.value as? [String: AnyObject],
    let uid = Auth.auth().currentUser?.uid {
    var stars: [String: Bool]
    stars = post["stars"] as? [String: Bool] ?? [:]
    var starCount = post["starCount"] as? Int ?? 0
    if let _ = stars[uid] {
      // Unstar the post and remove self from stars
      starCount -= 1
      stars.removeValue(forKey: uid)
    } else {
      // Star the post and add self to stars
      starCount += 1
      stars[uid] = true
    }
    post["starCount"] = starCount as AnyObject?
    post["stars"] = stars as AnyObject?

    // Set value and report transaction success
    currentData.value = post

    return TransactionResult.success(withValue: currentData)
  }
  return TransactionResult.success(withValue: currentData)
}) { error, committed, snapshot in
  if let error = error {
    print(error.localizedDescription)
  }
}

Objectif c

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
[ref runTransactionBlock:^FIRTransactionResult * _Nonnull(FIRMutableData * _Nonnull currentData) {
  NSMutableDictionary *post = currentData.value;
  if (!post || [post isEqual:[NSNull null]]) {
    return [FIRTransactionResult successWithValue:currentData];
  }

  NSMutableDictionary *stars = post[@"stars"];
  if (!stars) {
    stars = [[NSMutableDictionary alloc] initWithCapacity:1];
  }
  NSString *uid = [FIRAuth auth].currentUser.uid;
  int starCount = [post[@"starCount"] intValue];
  if (stars[uid]) {
    // Unstar the post and remove self from stars
    starCount--;
    [stars removeObjectForKey:uid];
  } else {
    // Star the post and add self to stars
    starCount++;
    stars[uid] = @YES;
  }
  post[@"stars"] = stars;
  post[@"starCount"] = @(starCount);

  // Set value and report transaction success
  currentData.value = post;
  return [FIRTransactionResult successWithValue:currentData];
} andCompletionBlock:^(NSError * _Nullable error,
                       BOOL committed,
                       FIRDataSnapshot * _Nullable snapshot) {
  // Transaction completed
  if (error) {
    NSLog(@"%@", error.localizedDescription);
  }
}];

L'utilisation d'une transaction évite que le nombre d'étoiles soit incorrect si plusieurs utilisateurs marquent la même publication en même temps ou si le client dispose de données obsolètes. La valeur contenue dans la classe FIRMutableData est initialement la dernière valeur connue du client pour le chemin, ou nil s'il n'y en a pas. Le serveur compare la valeur initiale à sa valeur actuelle et accepte la transaction si les valeurs correspondent, ou la rejette. Si la transaction est rejetée, le serveur renvoie la valeur actuelle au client, qui exécute à nouveau la transaction avec la valeur mise à jour. Cela se répète jusqu'à ce que la transaction soit acceptée ou que trop de tentatives aient été effectuées.

Incréments atomiques côté serveur

Dans le cas d'utilisation ci-dessus, nous écrivons deux valeurs dans la base de données : l'ID de l'utilisateur qui marque/désactive la publication et le nombre d'étoiles incrémenté. Si nous savons déjà que cet utilisateur met en vedette la publication, nous pouvons utiliser une opération d'incrémentation atomique au lieu d'une transaction.

Rapide

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
let updates = [
  "posts/\(postID)/stars/\(userID)": true,
  "posts/\(postID)/starCount": ServerValue.increment(1),
  "user-posts/\(postID)/stars/\(userID)": true,
  "user-posts/\(postID)/starCount": ServerValue.increment(1)
] as [String : Any]
Database.database().reference().updateChildValues(updates)

Objectif c

Remarque : Ce produit Firebase n'est pas disponible sur la cible App Clip.
NSDictionary *updates = @{[NSString stringWithFormat: @"posts/%@/stars/%@", postID, userID]: @TRUE,
                        [NSString stringWithFormat: @"posts/%@/starCount", postID]: [FIRServerValue increment:@1],
                        [NSString stringWithFormat: @"user-posts/%@/stars/%@", postID, userID]: @TRUE,
                        [NSString stringWithFormat: @"user-posts/%@/starCount", postID]: [FIRServerValue increment:@1]};
[[[FIRDatabase database] reference] updateChildValues:updates];

Ce code n'utilise pas d'opération de transaction, il n'est donc pas automatiquement réexécuté en cas de mise à jour conflictuelle. Cependant, étant donné que l'opération d'incrémentation s'effectue directement sur le serveur de base de données, il n'y a aucun risque de conflit.

Si vous souhaitez détecter et rejeter les conflits spécifiques à une application, tels qu'un utilisateur mettant en vedette une publication qu'il a déjà mise en vedette auparavant, vous devez écrire des règles de sécurité personnalisées pour ce cas d'utilisation.

Travailler avec des données hors ligne

Si un client perd sa connexion réseau, votre application continuera à fonctionner correctement.

Chaque client connecté à une base de données Firebase conserve sa propre version interne de toutes les données actives. Lorsque les données sont écrites, elles sont d’abord écrites dans cette version locale. Le client Firebase synchronise ensuite ces données avec les serveurs de base de données distants et avec d'autres clients dans la mesure du possible.

Par conséquent, toutes les écritures dans la base de données déclenchent immédiatement des événements locaux, avant que des données ne soient écrites sur le serveur. Cela signifie que votre application reste réactive quelle que soit la latence ou la connectivité du réseau.

Une fois la connectivité rétablie, votre application reçoit l'ensemble d'événements approprié afin que le client se synchronise avec l'état actuel du serveur, sans avoir à écrire de code personnalisé.

Nous parlerons davantage du comportement hors ligne dans En savoir plus sur les fonctionnalités en ligne et hors ligne .

Prochaines étapes