Cloud Firestore tetikleyicileri

Cloud Functions ile, istemci kodunu güncellemeye gerek kalmadan Cloud Firestore'daki olayları işleyebilirsiniz. Cloud Firestore değişikliklerini DocumentSnapshot arabirimi veya Yönetici SDK'sı aracılığıyla yapabilirsiniz.

Tipik bir yaşam döngüsünde bir Cloud Firestore işlevi aşağıdakileri yapar:

  1. Belirli bir belgedeki değişiklikleri bekler.
  2. Bir olay meydana geldiğinde ve görevlerini yerine getirdiğinde tetiklenir (kullanım örnekleri için Cloud Functions ile neler yapabilirim? bölümüne bakın).
  3. Belirtilen belgede depolanan verilerin anlık görüntüsünü içeren bir veri nesnesi alır. onWrite veya onUpdate olayları için, veri nesnesi, tetikleyici olaydan önceki ve sonraki veri durumunu temsil eden iki anlık görüntü içerir.

Firestore örneğinin konumu ile işlevin konumu arasındaki mesafe, önemli ağ gecikmesi oluşturabilir. Performansı optimize etmek için, uygun olduğunda işlev konumunu belirtmeyi düşünün.

Cloud Firestore işlevi tetikleyicileri

Firebase SDK için Bulut İşlevleri, belirli Cloud Firestore olaylarına bağlı işleyiciler oluşturmanıza olanak tanıyan bir functions.firestore nesnesini dışa aktarır.

Etkinlik tipi Tetiklemek
onCreate Bir belgeye ilk kez yazıldığında tetiklenir.
onUpdate Bir belge zaten mevcut olduğunda ve herhangi bir değeri değiştiğinde tetiklenir.
onDelete Veri içeren bir belge silindiğinde tetiklenir.
onWrite onCreate , onUpdate veya onDelete tetiklendiğinde tetiklenir.

Henüz Cloud Functions for Firebase için etkinleştirilmiş bir projeniz yoksa, Firebase için Cloud Functions projenizi yapılandırmak ve ayarlamak için Başlayın: İlk İşlevlerinizi Yazın ve Dağıtın başlıklı makaleyi okuyun.

Cloud Firestore tarafından tetiklenen işlevleri yazma

Bir işlev tetikleyici tanımlayın

Bir Cloud Firestore tetikleyicisi tanımlamak için bir belge yolu ve bir olay türü belirtin:

Node.js

const functions = require('firebase-functions');

exports.myFunction = functions.firestore
  .document('my-collection/{docId}')
  .onWrite((change, context) => { /* ... */ });

Belge yolları, belirli bir belgeye veya bir joker karakter kalıbına başvurabilir.

Tek bir belge belirtin

Belirli bir belgedeki herhangi bir değişiklik için bir olayı tetiklemek istiyorsanız, aşağıdaki işlevi kullanabilirsiniz.

Node.js

// Listen for any change on document `marie` in collection `users`
exports.myFunctionName = functions.firestore
    .document('users/marie').onWrite((change, context) => {
      // ... Your code here
    });

Joker karakterler kullanarak bir grup belge belirtin

Belirli bir koleksiyondaki herhangi bir belge gibi bir grup belgeye bir tetikleyici eklemek istiyorsanız, belge kimliği yerine bir {wildcard} kullanın:

Node.js

// Listen for changes in all documents in the 'users' collection
exports.useWildcard = functions.firestore
    .document('users/{userId}')
    .onWrite((change, context) => {
      // If we set `/users/marie` to {name: "Marie"} then
      // context.params.userId == "marie"
      // ... and ...
      // change.after.data() == {name: "Marie"}
    });

Bu örnekte, users herhangi bir belgedeki herhangi bir alan değiştirildiğinde, userId adlı bir joker karakterle eşleşir.

users bir belgenin alt koleksiyonları varsa ve bu alt koleksiyonların belgelerindeki bir alan değiştirilirse, userId joker karakteri tetiklenmez.

Joker karakter eşleşmeleri belge yolundan çıkarılır ve context.params içinde saklanır. Açık koleksiyon veya belge kimliklerini değiştirmek için istediğiniz kadar joker karakter tanımlayabilirsiniz, örneğin:

Node.js

// Listen for changes in all documents in the 'users' collection and all subcollections
exports.useMultipleWildcards = functions.firestore
    .document('users/{userId}/{messageCollectionId}/{messageId}')
    .onWrite((change, context) => {
      // If we set `/users/marie/incoming_messages/134` to {body: "Hello"} then
      // context.params.userId == "marie";
      // context.params.messageCollectionId == "incoming_messages";
      // context.params.messageId == "134";
      // ... and ...
      // change.after.data() == {body: "Hello"}
    });

Olay Tetikleyicileri

Yeni bir belge oluşturulduğunda bir işlevi tetikleyin

Joker karakterli bir onCreate() işleyicisi kullanarak bir koleksiyonda her yeni belge oluşturulduğunda bir işlevi tetiklemek için tetikleyebilirsiniz. Bu örnek işlev, her yeni kullanıcı profili eklendiğinde createUser çağırır:

Node.js

exports.createUser = functions.firestore
    .document('users/{userId}')
    .onCreate((snap, context) => {
      // Get an object representing the document
      // e.g. {'name': 'Marie', 'age': 66}
      const newValue = snap.data();

      // access a particular field as you would any JS property
      const name = newValue.name;

      // perform desired operations ...
    });

Bir belge güncellendiğinde bir işlevi tetikleyin

Ayrıca, bir joker karakterle onUpdate() işlevi kullanılarak bir belge güncellendiğinde tetiklenecek bir işlevi tetikleyebilirsiniz. Bu örnek işlev, bir kullanıcı profilini değiştirirse updateUser çağırır:

Node.js

exports.updateUser = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Get an object representing the document
      // e.g. {'name': 'Marie', 'age': 66}
      const newValue = change.after.data();

      // ...or the previous value before this update
      const previousValue = change.before.data();

      // access a particular field as you would any JS property
      const name = newValue.name;

      // perform desired operations ...
    });

Bir belge silindiğinde bir işlevi tetikleyin

Ayrıca, bir joker karakterle onDelete() işlevi kullanılarak bir belge silindiğinde bir işlevi tetikleyebilirsiniz. Bu örnek işlev, bir kullanıcı kendi kullanıcı profilini sildiğinde deleteUser çağırır:

Node.js

exports.deleteUser = functions.firestore
    .document('users/{userID}')
    .onDelete((snap, context) => {
      // Get an object representing the document prior to deletion
      // e.g. {'name': 'Marie', 'age': 66}
      const deletedValue = snap.data();

      // perform desired operations ...
    });

Bir belgedeki tüm değişiklikler için bir işlevi tetikleyin

Tetiklenen olayın türünü umursamıyorsanız, bir joker karakterle onWrite() işlevini kullanarak bir Cloud Firestore belgesindeki tüm değişiklikleri dinleyebilirsiniz. Bu örnek işlev, bir kullanıcı oluşturulur, güncellenir veya silinirse modifyUser çağırır:

Node.js

exports.modifyUser = functions.firestore
    .document('users/{userID}')
    .onWrite((change, context) => {
      // Get an object with the current document value.
      // If the document does not exist, it has been deleted.
      const document = change.after.exists ? change.after.data() : null;

      // Get an object with the previous document value (for update or delete)
      const oldDocument = change.before.data();

      // perform desired operations ...
    });

Veri Okuma ve Yazma

Bir işlev tetiklendiğinde, olayla ilgili verilerin anlık görüntüsünü sağlar. Olayı tetikleyen belgeden okumak veya belgeye yazmak için bu anlık görüntüyü kullanabilir veya veritabanınızın diğer bölümlerine erişmek için Firebase Admin SDK'sını kullanabilirsiniz.

Olay Verileri

Veri Okuma

Bir işlev tetiklendiğinde, güncellenmiş bir belgeden veri almak veya verileri güncellemeden önce almak isteyebilirsiniz. Güncellemeden önceki belge anlık görüntüsünü içeren change.before.data() kullanarak önceki verileri alabilirsiniz. Benzer şekilde, change.after.data() , güncellemeden sonraki belge anlık görüntüsünü içerir.

Node.js

exports.updateUser2 = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Get an object representing the current document
      const newValue = change.after.data();

      // ...or the previous value before this update
      const previousValue = change.before.data();
    });

Diğer nesnelerde olduğu gibi özelliklere erişebilirsiniz. Alternatif olarak, belirli alanlara erişmek için get işlevini kullanabilirsiniz:

Node.js

// Fetch data using standard accessors
const age = snap.data().age;
const name = snap.data()['name'];

// Fetch data using built in accessor
const experience = snap.get('experience');

Veri Yazma

Her işlev çağrısı, Cloud Firestore veritabanınızdaki belirli bir belgeyle ilişkilendirilir. Bu belgeye, işlevinize döndürülen anlık ref özelliğinde DocumentReference olarak erişebilirsiniz.

Bu DocumentReference , Cloud Firestore Node.js SDK'dan gelir ve update() , set() ve remove() gibi yöntemleri içerir, böylece işlevi tetikleyen belgeyi kolayca değiştirebilirsiniz.

Node.js

// Listen for updates to any `user` document.
exports.countNameChanges = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Retrieve the current and previous value
      const data = change.after.data();
      const previousData = change.before.data();

      // We'll only update if the name has changed.
      // This is crucial to prevent infinite loops.
      if (data.name == previousData.name) {
        return null;
      }

      // Retrieve the current count of name changes
      let count = data.name_change_count;
      if (!count) {
        count = 0;
      }

      // Then return a promise of a set operation to update the count
      return change.after.ref.set({
        name_change_count: count + 1
      }, {merge: true});
    });

Tetikleyici olayın dışındaki veriler

Bulut İşlevleri, güvenilir bir ortamda yürütülür; bu, projenizde hizmet hesabı olarak yetkilendirildikleri anlamına gelir. Firebase Admin SDK'sını kullanarak okuma ve yazma işlemleri gerçekleştirebilirsiniz:

Node.js

const admin = require('firebase-admin');
admin.initializeApp();

const db = admin.firestore();

exports.writeToFirestore = functions.firestore
  .document('some/doc')
  .onWrite((change, context) => {
    db.doc('some/otherdoc').set({ ... });
  });

sınırlamalar

Cloud Functions için Cloud Firestore tetikleyicileri için aşağıdaki sınırlamalara dikkat edin:

  • Sipariş garanti edilmez. Hızlı değişiklikler, beklenmeyen bir sırada işlev çağrılarını tetikleyebilir.
  • Olaylar en az bir kez teslim edilir, ancak tek bir olay birden çok işlev çağrısına neden olabilir. Tam bir kez mekaniğine bağlı kalmaktan kaçının ve idempotent işlevler yazın.
  • Cloud Functions için Cloud Firestore tetikleyicileri, yalnızca Yerel modda Cloud Firestore için kullanılabilir. Datastore modunda Cloud Firestore için kullanılamaz.