Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Déclencheurs de base de données en temps réel

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Dans un cycle de vie typique, une fonction Firebase Realtime Database effectue les opérations suivantes :

  1. Attend les modifications apportées à un chemin d'accès à la base de données en temps réel particulier.
  2. Se déclenche lorsqu'un événement se produit et exécute ses tâches.
  3. Reçoit un objet de données qui contient un instantané des données stockées dans ce chemin.

Vous pouvez déclencher une fonction en réponse à l'écriture, la création, la mise à jour ou la suppression de nœuds de base de données dans Firebase Realtime Database.

Déclencher une fonction sur les modifications de la base de données en temps réel Firebase

Utilisez le firebase-functions/v2/database pour créer une fonction qui gère les événements Firebase Realtime Database. Pour contrôler le moment où la fonction se déclenche, spécifiez l'un des gestionnaires d'événements et spécifiez le chemin de la base de données en temps réel où elle écoutera les événements.

Réglage de l'emplacement de la fonction

La distance entre l'emplacement d'une instance Realtime Database et l'emplacement de la fonction peut créer une latence réseau importante. En outre, une incompatibilité entre les régions peut entraîner un échec du déploiement. Pour éviter ces situations, spécifiez l' emplacement de la fonction afin qu'il corresponde à l' emplacement de l'instance de base de données .

Gestion des événements de la base de données en temps réel

Les fonctions vous permettent de gérer les événements de la base de données en temps réel à deux niveaux de spécificité ; vous pouvez écouter spécifiquement uniquement les événements d'écriture, de création, de mise à jour ou de suppression, ou vous pouvez écouter tout changement de quelque nature que ce soit apporté à une référence.

Ces gestionnaires pour répondre aux événements de la base de données en temps réel sont disponibles :

  • onValueWritten() Uniquement déclenché lorsque les données sont écrites dans la base de données en temps réel.
  • onValueCreated() Uniquement déclenché lorsque les données sont créées dans la base de données en temps réel.
  • onValueUpdated() Uniquement déclenché lorsque les données sont mises à jour dans la base de données en temps réel.
  • onValueDeleted() Uniquement déclenché lorsque les données sont supprimées dans la base de données en temps réel.

Spécifier l'instance et le chemin

Pour contrôler quand et où votre fonction doit se déclencher, configurez votre fonction avec un chemin et éventuellement une instance de base de données en temps réel. Si vous ne spécifiez pas d'instance, la fonction se déploie sur toutes les instances de la base de données en temps réel dans la région de la fonction. Vous pouvez également spécifier un modèle d'instance de base de données en temps réel à déployer sur un sous-ensemble sélectif d'instances dans la même région.

Par exemple, en utilisant onValueWritten() pour illustration :

# All Realtime Database instances in default function region us-central1 at path "/user/{uid}"
# There must be at least one Realtime Database present in us-central1.
const onwrittenfunctiondefault = onValueWritten("/user/{uid}", (event) => {
  // …
});

# Instance named "my-app-db-2", at path "/user/{uid}".
# The "my-app-db-2" instance must exist in this region.
const onwrittenfunctioninstance = onValueWritten(
  {
    ref: "/user/{uid}",
    instance: "my-app-db-2"
    // This example assumes us-central1, but to set location:
    // region: "europe-west1"
  },
  (event) => {
    // …
  }
);

# Instance with "my-app-db-" prefix, at path "/user/{uid}", where uid ends with @gmail.com.
# There must be at least one Realtime Database with "my-app-db-*" prefix in this region.
const onwrittenfunctioninstance = onValueWritten(
  {
    ref: "/user/{uid=*@gmail.com}",
    instance: "my-app-db-*"
    // This example assumes us-central1, but to set location:
    // region: "europe-west1"
  },
  (event) => {
    // …
  }
);

Ces paramètres indiquent à votre fonction de gérer les écritures sur un certain chemin dans l'instance de la base de données en temps réel.

Les spécifications de chemin correspondent à toutes les écritures qui touchent un chemin, y compris les écritures qui se produisent n'importe où en dessous. Si vous définissez le chemin de votre fonction comme /foo/bar , il correspond aux événements à ces deux emplacements :

 /foo/bar
 /foo/bar/baz/really/deep/path

Dans les deux cas, Firebase interprète que l'événement se produit à /foo/bar , et les données d'événement incluent les anciennes et les nouvelles données à /foo/bar . Si les données d'événement peuvent être volumineuses, envisagez d'utiliser plusieurs fonctions sur des chemins plus profonds au lieu d'une seule fonction près de la racine de votre base de données. Pour des performances optimales, demandez uniquement des données au niveau le plus profond possible.

Caractères génériques et capture

Vous pouvez utiliser {key} , {key=*} , {key=prefix*} , {key=*suffix} pour la capture. * , prefix* , *suffix pour le caractère générique à un seul segment. Remarque : ** représente le caractère générique multi-segments, que RTDB ne prend pas en charge. Voir Comprendre les modèles de chemin .

Caractère générique de chemin. Vous pouvez spécifier un composant de chemin comme caractère générique :

  • En utilisant l'astérisque, * . Par exemple, foo/* correspond à tous les enfants situés à un niveau de la hiérarchie des nœuds sous foo/ .
  • En utilisant un segment contenant exactement un astérisque, * . Par exemple, foo/app*-us correspond à tous les segments enfants sous foo/ avec le préfixe app et le suffixe -us .

Les chemins avec des caractères génériques peuvent correspondre à plusieurs événements à partir, par exemple, d'une seule écriture. Un insert de

{
  "foo": {
    "hello": "world",
    "firebase": "functions"
  }
}

correspond au chemin "/foo/*" deux fois : une fois avec "hello": "world" et une autre fois avec "firebase": "functions" .

Capture de chemin. Vous pouvez capturer des correspondances de chemin dans des variables nommées à utiliser dans votre code de fonction (par exemple /user/{uid} , /user/{uid=*-us} ).

Les valeurs des variables de capture sont disponibles dans l'objet database.DatabaseEvent.params de votre fonction.

Caractère générique d'instance. Vous pouvez également spécifier un composant d'instance à l'aide de caractères génériques. Un caractère générique d'instance peut avoir un préfixe, un suffixe ou les deux (par exemple my-app-*-prod ).

Caractère générique et référence de capture

Avec Cloud Functions (2e génération) et Realtime Database, un modèle peut être utilisé lors de la spécification de ref et instance . Chaque interface de déclencheur aura les options suivantes pour définir la portée d'une fonction :

Spécification de la ref Spécification de l' instance Comportement
Célibataire ( /foo/bar ) Ne pas spécifier Gestionnaire de portées à toutes les instances de la région de fonction.
Célibataire ( /foo/bar ) Unique ( 'my-new-db' ) Gestionnaire de portées à l'instance spécifique dans la région de fonction.
Célibataire ( /foo/bar ) Modèle ( 'inst-prefix*' ) Étend le gestionnaire à toutes les instances qui correspondent au modèle dans la région de la fonction.
Modèle ( /foo/{bar} ) Ne pas spécifier Gestionnaire de portées à toutes les instances de la région de fonction.
Modèle ( /foo/{bar} ) Unique ( 'my-new-db' ) Gestionnaire de portées à l'instance spécifique dans la région de fonction.
Modèle ( /foo/{bar} ) Modèle ( 'inst-prefix*' ) Étend le gestionnaire à toutes les instances qui correspondent au modèle dans la région de la fonction.

Gérer les données d'événement

Lors de la gestion d'un événement Realtime Database, l'objet de données renvoyé est un DataSnapshot .

Pour les événements onValueWritten ou onValueUpdated , le premier paramètre est un objet Change qui contient deux instantanés qui représentent l'état des données avant et après l'événement déclencheur.

Pour les événements onValueCreated et onValueDeleted , l'objet de données renvoyé est un instantané des données créées ou supprimées.

Dans cet exemple, la fonction récupère l'instantané pour le chemin spécifié foo/bar en tant que snap , convertit la chaîne à cet emplacement en majuscules et écrit cette chaîne modifiée dans la base de données :

// Listens for new messages added to /messages/:pushId/original and creates an
// uppercase version of the message to /messages/:pushId/uppercase
export makeuppercase = onValueCreated("foo/bar", (event) => {
      // Grab the current value of what was written to the Realtime Database.
      const original = event.data.val();
      functions.logger.log('Uppercasing', event.params.pushId, original);
      const uppercase = original.toUpperCase();
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to the Firebase Realtime Database.
      // Setting an "uppercase" sibling in the Realtime Database returns a Promise.
      return event.data.ref.parent.child('uppercase').set(uppercase);
    });

Lecture de la valeur précédente

L'objet Change a une propriété before qui vous permet d'inspecter ce qui a été enregistré dans la base de données en temps réel avant l'événement. La propriété before renvoie un DataSnapshot où toutes les méthodes (par exemple, val() et exists() ) font référence à la valeur précédente. Vous pouvez relire la nouvelle valeur en utilisant le DataSnapshot d'origine ou en lisant la propriété after . Cette propriété sur tout Change est un autre DataSnapshot représentant l'état des données après que l'événement se soit produit.

Par exemple, la propriété before peut être utilisée pour s'assurer que la fonction ne met que du texte en majuscule lors de sa première création :

    exports makeuppercase = onValueWritten("/messages/{pushId}/original", (event) => {
          // Only edit data when it is first created.
          if (event.data.before.exists()) {
            return null;
          }
          // Exit when the data is deleted.
          if (!event.data.after.exists()) {
            return null;
          }
          // Grab the current value of what was written to the Realtime Database.
          const original = event.data.after.val();
          console.log('Uppercasing', event.params.pushId, original);
          const uppercase = original.toUpperCase();
          // You must return a Promise when performing asynchronous tasks inside a Functions such as
          // writing to the Firebase Realtime Database.
          // Setting an "uppercase" sibling in the Realtime Database returns a Promise.
          return event.data.after.ref.parent.child('uppercase').set(uppercase);
        });