Pemicu Cloud Firestore

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

Dalam siklus proses yang umum, fungsi Cloud Firestore melakukan hal berikut:

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

Jarak antara lokasi instance Firestore dan lokasi fungsi dapat menghasilkan latensi jaringan yang signifikan. Untuk mengoptimalkan performa, pertimbangkan untuk menentukan lokasi fungsi, jika ada.

Memicu fungsi Cloud Firestore

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

Cloud Firestore mendukung peristiwa create, update, delete, dan write:

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

Jika Anda belum memiliki project yang diaktifkan untuk Cloud Functions for Firebase, baca Memulai: Menulis dan Menerapkan Fungsi Pertama Anda untuk mengonfigurasi dan menyiapkan project Cloud Functions for Firebase.

Memicu fungsi saat dokumen tertentu berubah

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

Memicu fungsi saat dokumen baru dibuat

Anda dapat memicu fungsi agar aktif setiap kali ada dokumen baru yang dibuat dalam koleksi, menggunakan pengendali onCreate() dengan karakter pengganti. Fungsi contoh ini akan 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 agar aktif saat dokumen diperbarui, menggunakan fungsi onUpdate() dengan karakter pengganti. Fungsi contoh ini memanggil updateUser jika pengguna mengubah profil mereka:

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 ketika pengguna menghapus profilnya:

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 perubahan pada dokumen

Jika jenis peristiwa yang diaktifkan tidak penting bagi Anda, Anda dapat mendeteksi semua perubahan dalam dokumen Cloud Firestore menggunakan fungsi onWrite() dengan karakter pengganti. Fungsi contoh ini akan 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 ...
    });

Menangani Data Peristiwa

Membaca Data

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

Node.js

exports.updateUser = 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 sebagaimana Anda mengakses objek lainnya. Atau, Anda dapat menggunakan fungsi get untuk mengakses kolom 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 dalam database Cloud Firestore. Anda dapat mengakses dokumen tersebut sebagai DocumentReference di properti ref dari snapshot yang ditampilkan ke fungsi.

DocumentReference ini berasal dari Cloud Firestore Node.js SDK dan mencakup berbagai metode seperti update(), set(), dan remove(), sehingga Anda dapat dengan mudah mengubah 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});
    });

Menggunakan karakter pengganti dan parameter

Jika Anda tidak mengetahui dokumen tertentu yang ingin Anda tambahi pemicu peristiwa, Anda dapat menggunakan {wildcard} sebagai pengganti 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, saat kolom dalam dokumen pada users diubah, sistem akan mencocokkan karakter pengganti yang disebut userId.

Jika dokumen pada users memiliki subkoleksi, dan kolom di salah satu dokumen subkoleksi tersebut diubah, karakter pengganti userId tidak akan dipicu.

Kecocokan karakter pengganti diekstrak dari lokasi dokumen dan disimpan ke dalam event.params. Anda dapat menentukan karakter pengganti sebanyak yang Anda inginkan untuk mengganti koleksi eksplisit atau ID dokumen.

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

Keterbatasan dan jaminan

Saat mengembangkan aplikasi, ingatlah bahwa Cloud Firestore saat ini masih dalam versi beta, yang berarti perilaku tak terduga mungkin terjadi.

Beberapa keterbatasan yang telah diketahui antara lain:

  • Diperlukan waktu hingga 10 detik sampai fungsi dipicu setelah ada perubahan pada data Cloud Firestore.
  • Seperti halnya semua fungsi latar belakang, pengurutan peristiwa juga tidak dijamin. Selain itu, peristiwa tunggal dapat mengakibatkan beberapa pemanggilan Cloud Functions. Oleh sebab itu, untuk mendapatkan kualitas terbaik, pastikan fungsi tersebut ditulis menjadi idempoten.

Kirim masukan tentang...

Butuh bantuan? Kunjungi halaman dukungan kami.