Ikuti semua informasi yang diumumkan di Firebase Summit, dan pelajari bagaimana Firebase dapat membantu Anda mempercepat pengembangan aplikasi dan menjalankan aplikasi dengan percaya diri. Pelajari Lebih Lanjut

Pemicu Cloud Firestore

Dengan Cloud Functions, Anda dapat menangani peristiwa di Cloud Firestore tanpa perlu memperbarui kode klien. Anda dapat membuat perubahan Cloud Firestore melalui antarmuka DocumentSnapshot atau melalui Admin SDK .

Dalam siklus proses biasa, fungsi Cloud Firestore melakukan hal berikut:

  1. Menunggu perubahan pada dokumen tertentu.
  2. Dipicu saat suatu peristiwa terjadi dan menjalankan tugasnya (lihat Apa yang dapat saya lakukan dengan Cloud Functions? untuk contoh kasus penggunaan).
  3. Menerima objek data yang berisi snapshot dari data yang disimpan dalam dokumen tertentu. Untuk peristiwa onWrite atau onUpdate , objek data berisi dua snapshot yang mewakili status data sebelum dan sesudah peristiwa pemicu.

Jarak antara lokasi instance Firestore dan lokasi fungsi dapat membuat latensi jaringan yang signifikan. Untuk mengoptimalkan kinerja, pertimbangkan untuk menentukan lokasi fungsi jika berlaku.

Pemicu fungsi Cloud Firestore

Cloud Functions for Firebase SDK mengekspor objek functions.firestore yang memungkinkan Anda membuat penangan yang terkait dengan peristiwa Cloud Firestore tertentu.

Jenis Acara Pemicu
onCreate Dipicu saat dokumen ditulis untuk pertama kalinya.
onUpdate Dipicu saat dokumen sudah ada dan nilainya berubah.
onDelete Dipicu saat dokumen dengan data dihapus.
onWrite Dipicu saat onCreate , onUpdate atau onDelete dipicu.

Jika Anda belum mengaktifkan proyek untuk Cloud Functions for Firebase, baca Memulai: Menulis dan Menerapkan Fungsi Pertama Anda untuk mengonfigurasi dan menyiapkan proyek Cloud Functions for Firebase Anda.

Menulis fungsi yang dipicu Cloud Firestore

Tentukan pemicu fungsi

Untuk menentukan pemicu Cloud Firestore, tentukan jalur dokumen dan jenis peristiwa:

Node.js

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

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

Jalur dokumen dapat mereferensikan dokumen tertentu atau pola wildcard .

Tentukan satu dokumen

Jika Anda ingin memicu suatu peristiwa untuk perubahan apa pun pada dokumen tertentu, maka Anda dapat menggunakan fungsi berikut.

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
    });

Tentukan sekelompok dokumen menggunakan wildcard

Jika Anda ingin melampirkan pemicu ke sekelompok dokumen, seperti dokumen apa pun dalam koleksi tertentu, gunakan {wildcard} sebagai ganti ID dokumen:

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"}
    });

Dalam contoh ini, ketika bidang apa pun pada dokumen apa pun di users diubah, itu cocok dengan wildcard yang disebut userId .

Jika dokumen di users memiliki subkoleksi, dan bidang di salah satu dokumen subkoleksi tersebut diubah, wildcard userId tidak dipicu.

Kecocokan karakter pengganti diekstraksi dari jalur dokumen dan disimpan ke dalam context.params . Anda dapat menentukan sebanyak mungkin wildcard untuk menggantikan koleksi eksplisit atau ID dokumen, misalnya:

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"}
    });

Pemicu Acara

Memicu fungsi saat dokumen baru dibuat

Anda dapat memicu fungsi untuk diaktifkan setiap kali dokumen baru dibuat dalam koleksi dengan menggunakan handler onCreate() dengan wildcard . Fungsi contoh ini memanggil createUser setiap kali profil pengguna baru ditambahkan:

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 ...
    });

Memicu fungsi saat dokumen diperbarui

Anda juga dapat memicu fungsi untuk diaktifkan saat dokumen diperbarui menggunakan fungsi onUpdate() dengan karakter pengganti . Contoh fungsi ini memanggil updateUser jika pengguna mengubah profilnya:

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 ...
    });

Memicu fungsi saat dokumen dihapus

Anda juga dapat memicu fungsi saat dokumen dihapus menggunakan fungsi onDelete() dengan karakter pengganti . Fungsi contoh ini memanggil deleteUser saat pengguna menghapus profil pengguna mereka:

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 ...
    });

Memicu fungsi untuk semua perubahan pada dokumen

Jika Anda tidak peduli dengan jenis peristiwa yang dipicu, Anda dapat mendengarkan semua perubahan dalam dokumen Cloud Firestore menggunakan fungsi onWrite() dengan karakter pengganti . Fungsi contoh ini memanggil modifyUser jika pengguna dibuat, diperbarui, atau dihapus:

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 ...
    });

Membaca dan Menulis Data

Ketika suatu fungsi dipicu, itu memberikan snapshot data yang terkait dengan acara tersebut. Anda dapat menggunakan snapshot ini untuk membaca atau menulis ke dokumen yang memicu peristiwa, atau menggunakan Firebase Admin SDK untuk mengakses bagian lain dari database Anda.

Data Acara

Membaca Data

Saat suatu fungsi dipicu, Anda mungkin ingin mendapatkan data dari dokumen yang diperbarui, atau mendapatkan data sebelum pembaruan. Anda bisa mendapatkan data sebelumnya dengan menggunakan change.before.data() , yang berisi snapshot dokumen sebelum pembaruan. Demikian pula, change.after.data() berisi status snapshot dokumen setelah pembaruan.

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();
    });

Anda dapat mengakses properti seperti yang Anda lakukan di objek lain. Atau, Anda dapat menggunakan fungsi get untuk mengakses bidang tertentu:

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');

Menulis Data

Setiap pemanggilan fungsi dikaitkan dengan dokumen tertentu di database Cloud Firestore Anda. Anda dapat mengakses dokumen itu sebagai DocumentReference di properti ref dari snapshot yang dikembalikan ke fungsi Anda.

DocumentReference ini berasal dari Cloud Firestore Node.js SDK dan menyertakan metode seperti update() , set() , dan remove() sehingga Anda dapat dengan mudah memodifikasi dokumen yang memicu fungsi tersebut.

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});
    });

Data di luar peristiwa pemicu

Cloud Functions dijalankan di lingkungan tepercaya, yang berarti mereka diotorisasi sebagai akun layanan di project Anda. Anda dapat melakukan pembacaan dan penulisan menggunakan Firebase Admin SDK :

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({ ... });
  });

Keterbatasan

Perhatikan batasan berikut untuk pemicu Cloud Firestore untuk Cloud Functions:

  • Pemesanan tidak dijamin. Perubahan cepat dapat memicu pemanggilan fungsi dalam urutan yang tidak terduga.
  • Acara dikirimkan setidaknya sekali, tetapi satu acara dapat menghasilkan beberapa pemanggilan fungsi. Hindari bergantung pada mekanik yang tepat sekali, dan tulis fungsi idempoten .
  • Pemicu Cloud Firestore untuk Cloud Functions hanya tersedia untuk Cloud Firestore dalam mode Native . Ini tidak tersedia untuk Cloud Firestore dalam mode Datastore.