Catch up on highlights from Firebase at Google I/O 2023. Learn more

Cloud Firestore'u Cloud Functions ile Genişletin

Cloud Functions ile, Cloud Firestore veritabanınızdaki değişiklikler tarafından tetiklenen olayları işlemek için Node.js kodunu dağıtabilirsiniz. Bu, kendi sunucularınızı çalıştırmadan uygulamanıza kolayca sunucu tarafı işlevselliği eklemenizi sağlar.

Kullanım örnekleri için bkz. Cloud Functions ile Ne Yapabilirim? veya Functions Samples GitHub deposu.

Cloud Firestore işlevi tetikleyicileri

Cloud Functions for Firebase SDK, 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ştirilen bir projeniz yoksa Cloud Functions for Firebase projenizi yapılandırmak ve kurmak için Başlarken: İlk İşlevlerinizi Yazma ve Dağıtma bölümünü okuyun.

Cloud Firestore tarafından tetiklenen işlevleri yazma

Bir işlev tetikleyicisi 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 modeline 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 belge grubu belirtin

Belirli bir koleksiyondaki herhangi bir belge gibi bir belge grubuna 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 içindeki 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 dosyasında saklanır. Açık toplama 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 yeni bir belge oluşturulduğunda herhangi bir zamanda tetiklenecek bir işlevi tetikleyebilirsiniz. Bu örnek işlev, her yeni kullanıcı profili eklendiğinde createUser öğesini ç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

Bir joker karakterle onUpdate() işlevi kullanılarak bir belge güncellendiğinde tetiklenecek bir işlevi de tetikleyebilirsiniz. Bu örnek işlev, bir kullanıcı profilini değiştirirse updateUser öğesini ç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

Bir joker karakterle onDelete() işlevi kullanılarak bir belge silindiğinde de bir işlevi tetikleyebilirsiniz. Bu örnek işlev, bir kullanıcı kendi kullanıcı profilini sildiğinde deleteUser öğesini ç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

Başlatılan 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 belgeyi 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'yı kullanabilirsiniz.

Etkinlik Verileri

Veri Okuma

Bir fonksiyon tetiklendiğinde, güncellenmiş bir belgeden veri almak veya güncellemeden önce veri 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 sonra belgenin anlık görüntü durumunu 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();
    });

Özelliklere herhangi başka bir nesnede olduğu gibi 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 görüntünün ref özelliğinde bir DocumentReference olarak erişebilirsiniz.

Bu DocumentReference Cloud Firestore Node.js SDK'sından gelir ve işlevi tetikleyen belgeyi kolayca değiştirebilmeniz için update() , set() ve remove() gibi yöntemleri içerir.

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

Cloud Functions, güvenilir bir ortamda yürütülür; bu, projenizde bir hizmet hesabı olarak yetkilendirildiği anlamına gelir. Firebase Admin SDK'yı 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, işlev çağrılarını beklenmedik bir sırada tetikleyebilir.
  • Olaylar en az bir kez iletilir, ancak tek bir olay birden çok işlev çağrısına neden olabilir. Tam olarak bir kere mekaniğine bağlı kalmaktan kaçının ve idempotent fonksiyonlar 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.