Lire et écrire des données sur Android

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

Données Firebase est écrit à une FirebaseDatabase référence et récupéré par la fixation d' un auditeur asynchrone par rapport à la référence. L'écouteur est déclenché une fois pour l'état initial des données et à nouveau chaque fois que les données changent.

(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 la fonctionnalité 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 la suite d'émulateurs locaux, qui permet à votre application d'interagir avec le contenu et la configuration de votre base de données émulée, ainsi qu'éventuellement avec vos ressources de projet émulées (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. A partir de la racine de votre répertoire local du projet, en cours d' exécution firebase emulators:start .
  3. Passer des appels à partir du code prototype de votre application à l'aide d'un SDK de plate-forme Realtime Database comme d'habitude, ou à l'aide de l'API REST Realtime Database.

Une détaillée visite virtuelle en temps réel impliquant la base de données et les fonctions de Cloud est disponible. Vous devriez aussi jeter un oeil à l' adoption Emulator locale Suite .

Obtenir une référence de base de données

Pour lire ou données d'écriture à partir de la base de données, vous avez besoin d' une instance de DatabaseReference :

Java

private DatabaseReference mDatabase;
// ...
mDatabase = FirebaseDatabase.getInstance().getReference();

Kotlin+KTX

private lateinit var database: DatabaseReference
// ...
database = Firebase.database.reference

Écrire des données

Opérations d'écriture de base

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

  • Transmettez les types qui correspondent aux types JSON disponibles comme suit :
    • String
    • Long
    • Double
    • Boolean
    • Map<String, Object>
    • List<Object>
  • Transmettez un objet Java personnalisé, si la classe qui le définit a un constructeur par défaut qui ne prend aucun argument et a des getters publics pour les propriétés à affecter.

Si vous utilisez un objet Java, le contenu de votre objet est automatiquement mappé aux emplacements enfants de manière imbriquée. L'utilisation d'un objet Java rend également généralement votre code plus lisible et plus facile à gérer. Par exemple, si vous avez une application avec un profil d'utilisateur de base, votre User objet peut se présenter comme suit:

Java

@IgnoreExtraProperties
public class User {

    public String username;
    public String email;

    public User() {
        // Default constructor required for calls to DataSnapshot.getValue(User.class)
    }

    public User(String username, String email) {
        this.username = username;
        this.email = email;
    }

}

Kotlin+KTX

@IgnoreExtraProperties
data class User(val username: String? = null, val email: String? = null) {
    // Null default values create a no-argument default constructor, which is needed
    // for deserialization from a DataSnapshot.
}

Vous pouvez ajouter un utilisateur avec setValue() comme suit:

Java

public void writeNewUser(String userId, String name, String email) {
    User user = new User(name, email);

    mDatabase.child("users").child(userId).setValue(user);
}

Kotlin+KTX

fun writeNewUser(userId: String, name: String, email: String) {
    val user = User(name, email)

    database.child("users").child(userId).setValue(user)
}

L' utilisation setValue() de cette manière écrasera 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 leurs profils, vous pouvez mettre à jour le nom d'utilisateur comme suit :

Java

mDatabase.child("users").child(userId).child("username").setValue(name);

Kotlin+KTX

database.child("users").child(userId).child("username").setValue(name)

Lire les données

Lire des données avec des écouteurs persistants

Pour lire les données sur un chemin et écouter les modifications, utilisez la addValueEventListener() méthode pour ajouter un ValueEventListener à un DatabaseReference .

Auditeur Rappel d'événement Utilisation typique
ValueEventListener onDataChange() Lisez et écoutez les modifications apportées à l'ensemble du contenu d'un chemin.

Vous pouvez utiliser le onDataChange() méthode pour lire un instantané statique du contenu à un chemin donné, telles qu'elles existaient 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 instantané contenant toutes les données à cet emplacement, y compris les données enfants. S'il n'y a pas de données, l'instantané retourne false lorsque vous appelez exists() et null lorsque vous appelez getValue() sur elle.

L'exemple suivant illustre une application de blogs sociaux récupérant les détails d'une publication à partir de la base de données :

Java

ValueEventListener postListener = new ValueEventListener() {
    @Override
    public void onDataChange(DataSnapshot dataSnapshot) {
        // Get Post object and use the values to update the UI
        Post post = dataSnapshot.getValue(Post.class);
        // ..
    }

    @Override
    public void onCancelled(DatabaseError databaseError) {
        // Getting Post failed, log a message
        Log.w(TAG, "loadPost:onCancelled", databaseError.toException());
    }
};
mPostReference.addValueEventListener(postListener);

Kotlin+KTX

val postListener = object : ValueEventListener {
    override fun onDataChange(dataSnapshot: DataSnapshot) {
        // Get Post object and use the values to update the UI
        val post = dataSnapshot.getValue<Post>()
        // ...
    }

    override fun onCancelled(databaseError: DatabaseError) {
        // Getting Post failed, log a message
        Log.w(TAG, "loadPost:onCancelled", databaseError.toException())
    }
}
postReference.addValueEventListener(postListener)

L'auditeur reçoit un DataSnapshot qui contient les données à l'emplacement spécifié dans la base de données au moment de l'événement. Appel getValue() sur un rendement instantané de la représentation de l' objet Java des données. Si aucune donnée existe à l'emplacement, appelant getValue() rendement null .

Dans cet exemple, ValueEventListener définit également la onCancelled() méthode qui est appelée si la lecture est annulée. Par exemple, une lecture peut être annulée si le client n'est pas autorisé à lire à partir d'un emplacement de base de données Firebase. Cette méthode passe un DatabaseError objet indiquant pourquoi l'échec.

Lire les données une fois

Lire une fois en utilisant get()

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

En règle générale, vous devez utiliser les ValueEventListener techniques décrites ci - dessus pour lire les données pour être averti des mises à jour les données du back - end. Les techniques d'écoute réduisent votre utilisation et votre facturation, et sont optimisées pour offrir à vos utilisateurs la meilleure expérience lorsqu'ils sont en ligne et hors ligne.

Si vous avez besoin des données qu'une seule fois, vous pouvez utiliser get() pour obtenir un aperçu des données de la base de données. Si pour une raison quelconque get() est incapable de retourner la valeur du serveur, le client sonde le cache de stockage local et renvoie une erreur si la valeur est toujours introuvable.

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

Java

mDatabase.child("users").child(userId).get().addOnCompleteListener(new OnCompleteListener<DataSnapshot>() {
    @Override
    public void onComplete(@NonNull Task<DataSnapshot> task) {
        if (!task.isSuccessful()) {
            Log.e("firebase", "Error getting data", task.getException());
        }
        else {
            Log.d("firebase", String.valueOf(task.getResult().getValue()));
        }
    }
});

Kotlin+KTX

mDatabase.child("users").child(userId).get().addOnSuccessListener {
    Log.i("firebase", "Got value ${it.value}")
}.addOnFailureListener{
    Log.e("firebase", "Error getting data", it)
}

Lire une fois à l'aide d'un écouteur

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 addListenerForSingleValueEvent pour obtenir les données du cache du disque local immédiatement.

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 ou nécessiter une écoute active. Par exemple, l'application de blog des exemples précédents utilise cette méthode pour charger le profil d'un utilisateur lorsqu'il commence à créer un nouveau message.

Mettre à jour ou supprimer des données

Mettre à jour des champs spécifiques

Pour écrire simultanément aux enfants spécifiques d'un noeud sans écraser les autres nœuds enfants, utilisez la updateChildren() méthode.

Lors de l' appel updateChildren() , vous pouvez mettre à jour les valeurs des enfants de niveau inférieur en spécifiant un chemin pour la clé. Si les données sont stockées dans plusieurs endroits à l' échelle mieux, vous pouvez mettre à jour toutes les instances de ces données à l' aide de données sortance . Par exemple, une application blogging sociale pourrait avoir un Post classe comme ceci:

Java

@IgnoreExtraProperties
public class Post {

    public String uid;
    public String author;
    public String title;
    public String body;
    public int starCount = 0;
    public Map<String, Boolean> stars = new HashMap<>();

    public Post() {
        // Default constructor required for calls to DataSnapshot.getValue(Post.class)
    }

    public Post(String uid, String author, String title, String body) {
        this.uid = uid;
        this.author = author;
        this.title = title;
        this.body = body;
    }

    @Exclude
    public Map<String, Object> toMap() {
        HashMap<String, Object> result = new HashMap<>();
        result.put("uid", uid);
        result.put("author", author);
        result.put("title", title);
        result.put("body", body);
        result.put("starCount", starCount);
        result.put("stars", stars);

        return result;
    }
}

Kotlin+KTX

@IgnoreExtraProperties
data class Post(
    var uid: String? = "",
    var author: String? = "",
    var title: String? = "",
    var body: String? = "",
    var starCount: Int = 0,
    var stars: MutableMap<String, Boolean> = HashMap()
) {

    @Exclude
    fun toMap(): Map<String, Any?> {
        return mapOf(
                "uid" to uid,
                "author" to author,
                "title" to title,
                "body" to body,
                "starCount" to starCount,
                "stars" to stars
        )
    }
}

Pour créer une publication et la mettre à jour simultanément avec le flux d'activité récent et le flux d'activité de l'utilisateur publiant, l'application de blog utilise un code comme celui-ci :

Java

private void writeNewPost(String userId, String username, String title, String body) {
    // Create new post at /user-posts/$userid/$postid and at
    // /posts/$postid simultaneously
    String key = mDatabase.child("posts").push().getKey();
    Post post = new Post(userId, username, title, body);
    Map<String, Object> postValues = post.toMap();

    Map<String, Object> childUpdates = new HashMap<>();
    childUpdates.put("/posts/" + key, postValues);
    childUpdates.put("/user-posts/" + userId + "/" + key, postValues);

    mDatabase.updateChildren(childUpdates);
}

Kotlin+KTX

private fun writeNewPost(userId: String, username: String, title: String, body: String) {
    // Create new post at /user-posts/$userid/$postid and at
    // /posts/$postid simultaneously
    val key = database.child("posts").push().key
    if (key == null) {
        Log.w(TAG, "Couldn't get push key for posts")
        return
    }

    val post = Post(userId, username, title, body)
    val postValues = post.toMap()

    val childUpdates = hashMapOf<String, Any>(
            "/posts/$key" to postValues,
            "/user-posts/$userId/$key" to postValues
    )

    database.updateChildren(childUpdates)
}

Cet exemple utilise push() pour créer un poste dans le nœud contenant les messages pour tous les utilisateurs à /posts/$postid et récupérer en même temps la clé avec getKey() . La clé peut être utilisée pour créer une deuxième entrée dans les messages de l'utilisateur à /user-posts/$userid/$postid .

L' utilisation de ces chemins, vous pouvez effectuer des mises à jour simultanées à plusieurs endroits dans l'arborescence JSON avec un seul appel à updateChildren() , comme la façon dont cet exemple crée le nouveau poste dans les deux endroits. 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 rappel d'achèvement

Si vous voulez savoir quand vos données ont été validées, vous pouvez ajouter un écouteur d'achèvement. Les deux setValue() et updateChildren() prennent un écouteur d'achèvement en option qui est appelée lorsque l'écriture a été commise avec succès à la base de données. Si l'appel a échoué, l'auditeur reçoit un objet d'erreur indiquant pourquoi l'échec s'est produit.

Java

mDatabase.child("users").child(userId).setValue(user)
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(Void aVoid) {
                // Write was successful!
                // ...
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Write failed
                // ...
            }
        });

Kotlin+KTX

database.child("users").child(userId).setValue(user)
        .addOnSuccessListener {
            // Write was successful!
            // ...
        }
        .addOnFailureListener {
            // Write failed
            // ...
        }

Suprimmer les données

La façon la plus simple de suppression de données est d'appeler removeValue() sur une référence à l'emplacement de ces données.

Vous pouvez également supprimer en spécifiant null comme valeur pour une autre opération d'écriture tels que setValue() ou updateChildren() . Vous pouvez utiliser cette technique avec updateChildren() pour supprimer plusieurs enfants dans un seul appel API.

Détacher les auditeurs

Callbacks sont supprimés en appelant le removeEventListener() méthode sur la référence de votre base de données Firebase.

Si un écouteur a été ajouté plusieurs fois à un emplacement de données, il est appelé plusieurs fois pour chaque événement et vous devez le détacher le même nombre de fois pour le supprimer complètement.

Appel removeEventListener() sur un écouteur parent ne supprime pas automatiquement les écouteurs enregistrés sur ses nœuds enfants; removeEventListener() doit également être appelé écouteurs d'enfant pour enlever le rappel.

Enregistrer les données en tant que transactions

Lorsque vous travaillez avec des données qui pourraient être corrompues par des modifications simultanées telles que les compteurs supplémentaires, 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. Si un autre client écrit à l'emplacement avant que votre nouvelle valeur ne soit écrite avec succès, votre fonction de mise à jour est à nouveau appelée avec la nouvelle valeur actuelle et l'écriture est retentée.

Par exemple, dans l'exemple d'application de blogs sociaux, vous pouvez autoriser les utilisateurs à afficher et à supprimer des articles et à suivre le nombre d'étoiles reçues par un article comme suit :

Java

private void onStarClicked(DatabaseReference postRef) {
    postRef.runTransaction(new Transaction.Handler() {
        @Override
        public Transaction.Result doTransaction(MutableData mutableData) {
            Post p = mutableData.getValue(Post.class);
            if (p == null) {
                return Transaction.success(mutableData);
            }

            if (p.stars.containsKey(getUid())) {
                // Unstar the post and remove self from stars
                p.starCount = p.starCount - 1;
                p.stars.remove(getUid());
            } else {
                // Star the post and add self to stars
                p.starCount = p.starCount + 1;
                p.stars.put(getUid(), true);
            }

            // Set value and report transaction success
            mutableData.setValue(p);
            return Transaction.success(mutableData);
        }

        @Override
        public void onComplete(DatabaseError databaseError, boolean committed,
                               DataSnapshot currentData) {
            // Transaction completed
            Log.d(TAG, "postTransaction:onComplete:" + databaseError);
        }
    });
}

Kotlin+KTX

private fun onStarClicked(postRef: DatabaseReference) {
    // ...
    postRef.runTransaction(object : Transaction.Handler {
        override fun doTransaction(mutableData: MutableData): Transaction.Result {
            val p = mutableData.getValue(Post::class.java)
                    ?: return Transaction.success(mutableData)

            if (p.stars.containsKey(uid)) {
                // Unstar the post and remove self from stars
                p.starCount = p.starCount - 1
                p.stars.remove(uid)
            } else {
                // Star the post and add self to stars
                p.starCount = p.starCount + 1
                p.stars[uid] = true
            }

            // Set value and report transaction success
            mutableData.value = p
            return Transaction.success(mutableData)
        }

        override fun onComplete(
                databaseError: DatabaseError?,
                committed: Boolean,
                currentData: DataSnapshot?
        ) {
            // Transaction completed
            Log.d(TAG, "postTransaction:onComplete:" + databaseError!!)
        }
    })
}

L'utilisation d'une transaction empêche le nombre d'étoiles d'être incorrect si plusieurs utilisateurs affichent le même message en même temps ou si le client avait des données périmées. 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 côté serveur atomiques

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

Java

private void onStarClicked(String uid, String key) {
    Map<String, Object> updates = new HashMap<>();
    updates.put("posts/"+key+"/stars/"+uid, true);
    updates.put("posts/"+key+"/starCount", ServerValue.increment(1));
    updates.put("user-posts/"+uid+"/"+key+"/stars/"+uid, true);
    updates.put("user-posts/"+uid+"/"+key+"/starCount", ServerValue.increment(1));
    mDatabase.updateChildren(updates);
}

Kotlin+KTX

private fun onStarClicked(uid: String, key: String) {
    val updates: MutableMap<String, Any> = HashMap()
    updates["posts/$key/stars/$uid"] = true
    updates["posts/$key/starCount"] = ServerValue.increment(1)
    updates["user-posts/$uid/$key/stars/$uid"] = true
    updates["user-posts/$uid/$key/starCount"] = ServerValue.increment(1)
    database.updateChildren(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 se produit 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à publiée 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 sur lesquelles les écouteurs sont utilisés ou qui sont signalées comme étant synchronisées avec le serveur. Lorsque les données sont lues ou écrites, cette version locale des données est utilisée en premier. Le client Firebase synchronise ensuite ces données avec les serveurs de base de données distants et avec d'autres clients au mieux.

Par conséquent, toutes les écritures dans la base de données déclenchent des événements locaux immédiatement, avant toute interaction avec 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 allons parler plus sur le comportement en ligne En savoir plus sur les capacités en ligne et hors ligne .

Prochaines étapes