Cloud Functions'ı (2. nesil) kullanarak Cloud Firestore'u genişletin

Cloud Functions ile Cloud Firestore veritabanınızdaki değişikliklerin tetiklediği etkinlikleri işlemek için kod dağıtabilirsiniz. Bu, kendi sunucularınızı çalıştırmadan uygulamanıza kolayca sunucu tarafı işlevleri eklemenize olanak tanır.

Cloud Functions (2. nesil)

Cloud Run ve Eventarc destekli Cloud Functions for Firebase (2. nesil) size daha güçlü bir altyapı, performans ve ölçeklenebilirlik üzerinde gelişmiş kontrol ve işlevlerin çalışma zamanı üzerinde daha fazla kontrol sağlar. 2. nesil hakkında daha fazla bilgi için Cloud Functions for Firebase (2. nesil) sayfasını inceleyin. 1. nesil hakkında daha fazla bilgi için Cloud Functions ile Cloud Firestore'u Genişletme başlıklı makaleyi inceleyin.

Cloud Firestore işlev tetikleyicileri

Cloud Functions for Firebase SDK'sı, belirli Cloud Firestore etkinliklerine bağlı işleyiciler oluşturabilmeniz için aşağıdaki Cloud Firestore etkinlik tetikleyicilerini dışa aktarır:

Node.js

Etkinlik Türü	Tetikleyici
onDocumentCreated	Bir doküman ilk kez yazıldığında tetiklenir.
onDocumentUpdated	Zaten bir doküman varsa ve herhangi bir değeri değiştirildiğinde tetiklenir.
onDocumentDeleted	Doküman silindiğinde tetiklenir.
onDocumentWritten	onDocumentCreated, onDocumentUpdated veya onDocumentDeleted tetiklendiğinde tetiklenir.
onDocumentCreatedWithAuthContext	Ek kimlik doğrulama bilgileriyle onDocumentCreated
onDocumentWrittenWithAuthContext	Ek kimlik doğrulama bilgileriyle onDocumentWritten
onDocumentDeletedWithAuthContext	Ek kimlik doğrulama bilgileriyle onDocumentDeleted
onDocumentUpdatedWithAuthContext	Ek kimlik doğrulama bilgileriyle onDocumentUpdated

Python (önizleme)

Etkinlik Türü	Tetikleyici
on_document_created	Bir doküman ilk kez yazıldığında tetiklenir.
on_document_updated	Zaten bir doküman varsa ve herhangi bir değeri değiştirildiğinde tetiklenir.
on_document_deleted	Doküman silindiğinde tetiklenir.
on_document_written	on_document_created, on_document_updated veya on_document_deleted tetiklendiğinde tetiklenir.
on_document_created_with_auth_context	Ek kimlik doğrulama bilgileriyle on_document_created
on_document_updated_with_auth_context	Ek kimlik doğrulama bilgileriyle on_document_updated
on_document_deleted_with_auth_context	Ek kimlik doğrulama bilgileriyle on_document_deleted
on_document_written_with_auth_context	Ek kimlik doğrulama bilgileriyle on_document_written

Cloud Firestore etkinlikleri yalnızca belge değişikliklerinde tetiklenir. Verilerin değişmediği (işlemsiz yazma) güncelleme veya yazma etkinliği oluşturmadığı bir Cloud Firestore belgesi güncellemesi. Belirli alanlara etkinlik eklemek mümkün değildir.

Henüz Cloud Functions for Firebase için etkinleştirilmiş bir projeniz yoksa Cloud Functions for Firebase projenizi yapılandırmak ve ayarlamak üzere Firebase için Cloud Functions'ı (2. nesil) kullanmaya başlama başlıklı makaleyi okuyun.

Cloud Firestore tarafından tetiklenen işlevler yazma

İşlev tetikleyicisi tanımlayın

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

Node.js

import {
  onDocumentWritten,
  onDocumentCreated,
  onDocumentUpdated,
  onDocumentDeleted,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.myfunction = onDocumentWritten("my-collection/{docId}", (event) => {
   /* ... */ 
});

Python (önizleme)

from firebase_functions.firestore_fn import (
  on_document_created,
  on_document_deleted,
  on_document_updated,
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_created(document="users/{userId}")
def myfunction(event: Event[DocumentSnapshot]) -> None:

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

Tek bir doküman belirtin

Belirli bir dokümanda yapılan herhangi bir değişiklik için etkinlik tetiklemek istiyorsanız aşağıdaki işlevi kullanabilirsiniz.

Node.js

import {
  onDocumentWritten,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.myfunction = onDocumentWritten("users/marie", (event) => {
  // Your code here
});

Python (önizleme)

from firebase_functions.firestore_fn import (
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_written(document="users/marie")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:

Joker karakter kullanarak bir doküman grubu belirtin

Bir belge grubuna (ör. belirli bir koleksiyondaki herhangi bir belge) tetikleyici eklemek istiyorsanız belge kimliği yerine {wildcard} kullanın:

Node.js

import {
  onDocumentWritten,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.myfunction = onDocumentWritten("users/{userId}", (event) => {
  // If we set `/users/marie` to {name: "Marie"} then
  // event.params.userId == "marie"
  // ... and ...
  // event.data.after.data() == {name: "Marie"}
});

Python (önizleme)

from firebase_functions.firestore_fn import (
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_written(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # If we set `/users/marie` to {name: "Marie"} then
  event.params["userId"] == "marie"  # True
  # ... and ...
  event.data.after.to_dict() == {"name": "Marie"}  # True

Bu örnekte, users kapsamındaki herhangi bir dokümandaki herhangi bir alan değiştirildiğinde, userId adlı bir joker karakterle eşleşir.

users alanındaki bir dokümanda alt koleksiyonlar varsa ve bu alt koleksiyonların dokümanlarından birindeki bir alan değiştirilirse userId joker karakteri tetiklenmez.

Joker karakter eşleşmeleri belge yolundan ayıklanır ve event.params içinde depolanır. Açık koleksiyon veya doküman kimliklerinin yerine istediğiniz kadar joker karakter tanımlayabilirsiniz. Örneğin:

Node.js

import {
  onDocumentWritten,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.myfunction = onDocumentWritten("users/{userId}/{messageCollectionId}/{messageId}", (event) => {
    // If we set `/users/marie/incoming_messages/134` to {body: "Hello"} then
    // event.params.userId == "marie";
    // event.params.messageCollectionId == "incoming_messages";
    // event.params.messageId == "134";
    // ... and ...
    // event.data.after.data() == {body: "Hello"}
});

Python (önizleme)

from firebase_functions.firestore_fn import (
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_written(document="users/{userId}/{messageCollectionId}/{messageId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # If we set `/users/marie/incoming_messages/134` to {body: "Hello"} then
  event.params["userId"] == "marie"  # True
  event.params["messageCollectionId"] == "incoming_messages"  # True
  event.params["messageId"] == "134"  # True
  # ... and ...
  event.data.after.to_dict() == {"body": "Hello"}

Joker karakter kullansanız bile tetikleyiciniz her zaman bir dokümana işaret etmelidir. Örneğin, {messageCollectionId} bir koleksiyon olduğundan users/{userId}/{messageCollectionId} geçerli değildir. Ancak {messageId} her zaman bir dokümana işaret ettiğinden users/{userId}/{messageCollectionId}/{messageId} geçerlidir.

Etkinlik Tetikleyicileri

Yeni doküman oluşturulduğunda bir işlevi tetikle

Koleksiyonda yeni bir doküman oluşturulduğunda bir işlevin tetiklenmesini sağlayabilirsiniz. Bu örnek işlev her yeni kullanıcı profili eklendiğinde tetiklenir:

Node.js

import {
  onDocumentCreated,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.createuser = onDocumentCreated("users/{userId}", (event) => {
    // Get an object representing the document
    // e.g. {'name': 'Marie', 'age': 66}
    const snapshot = event.data;
    if (!snapshot) {
        console.log("No data associated with the event");
        return;
    }
    const data = snapshot.data();

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

    // perform more operations ...
});

Ek kimlik doğrulama bilgileri için onDocumentCreatedWithAuthContext kullanın.

Python (önizleme)

from firebase_functions.firestore_fn import (
  on_document_created,
  Event,
  DocumentSnapshot,
)

@on_document_created(document="users/{userId}")
def myfunction(event: Event[DocumentSnapshot]) -> None:
  # Get a dictionary representing the document
  # e.g. {'name': 'Marie', 'age': 66}
  new_value = event.data.to_dict()

  # Access a particular field as you would any dictionary
  name = new_value["name"]

  # Perform more operations ...

Doküman güncellendiğinde bir işlevi tetikleyin

Ayrıca, bir doküman güncellendiğinde de etkinleşecek bir işlev tetikleyebilirsiniz. Bu örnek işlev, bir kullanıcı profilini değiştirirse tetiklenir:

Node.js

import {
  onDocumentUpdated,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.updateuser = onDocumentUpdated("users/{userId}", (event) => {
    // Get an object representing the document
    // e.g. {'name': 'Marie', 'age': 66}
    const newValue = event.data.after.data();

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

    // perform more operations ...
});

Ek kimlik doğrulama bilgileri için onDocumentUpdatedWithAuthContext kullanın.

Python (önizleme)

from firebase_functions.firestore_fn import (
  on_document_updated,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_updated(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # Get a dictionary representing the document
  # e.g. {'name': 'Marie', 'age': 66}
  new_value = event.data.after.to_dict()

  # Access a particular field as you would any dictionary
  name = new_value["name"]

  # Perform more operations ...

Doküman silindiğinde bir işlevi tetikle

Doküman silindiğinde de bir işlevi tetikleyebilirsiniz. Bu örnek işlev, bir kullanıcı kendi kullanıcı profilini sildiğinde etkinleşir:

Node.js

import {
  onDocumentDeleted,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.deleteuser = onDocumentDeleted("users/{userId}", (event) => {
    // Get an object representing the document
    // e.g. {'name': 'Marie', 'age': 66}
    const snap =  event.data;
    const data =  snap.data();

    // perform more operations ...
});

Ek kimlik doğrulama bilgileri için onDocumentDeletedWithAuthContext kullanın.

Python (önizleme)

from firebase_functions.firestore_fn import (
  on_document_deleted,
  Event,
  DocumentSnapshot,
)

@on_document_deleted(document="users/{userId}")
def myfunction(event: Event[DocumentSnapshot|None]) -> None:
  # Perform more operations ...

Dokümanda yapılan tüm değişikliklerde bir işlevi tetikleme

Tetiklenen etkinlik türü sizin için önemli değilse "belge yazıldı" etkinlik tetikleyicisini kullanarak Cloud Firestore belgesindeki tüm değişiklikleri dinleyebilirsiniz. Bu örnek işlev, bir kullanıcı oluşturulduğunda, güncellendiğinde veya silindiğinde etkinleşir:

Node.js

import {
  onDocumentWritten,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.modifyuser = onDocumentWritten("users/{userId}", (event) => {
    // Get an object with the current document values.
    // If the document does not exist, it was deleted
    const document =  event.data.after.data();

    // Get an object with the previous document values
    const previousValues =  event.data.before.data();

    // perform more operations ...
});

Ek kimlik doğrulama bilgileri için onDocumentWrittenWithAuthContext kullanın.

Python (önizleme)

from firebase_functions.firestore_fn import (
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_written(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot | None]]) -> None:
  # Get an object with the current document values.
  # If the document does not exist, it was deleted.
  document = (event.data.after.to_dict()
              if event.data.after is not None else None)

  # Get an object with the previous document values.
  # If the document does not exist, it was newly created.
  previous_values = (event.data.before.to_dict()
                     if event.data.before is not None else None)

  # Perform more operations ...

Verileri Okuma ve Yazma

Bir işlev tetiklendiğinde, etkinlikle ilgili verilerin anlık görüntüsünü sağlar. Etkinliği tetikleyen belgeden okuma veya yazma işlemi yapmak için bu anlık görüntüyü ya da veritabanınızın diğer bölümlerine erişmek için Firebase Admin SDK'yı kullanabilirsiniz.

Etkinlik Verileri

Verileri Okuma

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

Node.js

exports.updateuser2 = onDocumentUpdated("users/{userId}", (event) => {
    // Get an object with the current document values.
    // If the document does not exist, it was deleted
    const newValues =  event.data.after.data();

    // Get an object with the previous document values
    const previousValues =  event.data.before.data();
});

Python (önizleme)

@on_document_updated(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # Get an object with the current document values.
  new_value = event.data.after.to_dict()

  # Get an object with the previous document values.
  prev_value = event.data.before.to_dict()

Mülklere, diğer herhangi bir nesnede olduğu gibi erişebilirsiniz. Alternatif olarak, belirli alanlara erişmek için get işlevini de kullanabilirsiniz:

Node.js

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

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

Python (önizleme)

# Get the value of a single document field.
age = event.data.after.get("age")

# Convert the document to a dictionary.
age = event.data.after.to_dict()["age"]

Veri Yazma

Her işlev çağrısı, Cloud Firestore veritabanınızdaki belirli bir belgeyle ilişkilendirilir. Bu dokümana, işlevinize döndürülen anlık görüntüden erişebilirsiniz.

Doküman referansı, işlevi tetikleyen dokümanı değiştirebilmeniz için update(), set() ve remove() gibi yöntemleri içerir.

Node.js

import { onDocumentUpdated } from "firebase-functions/v2/firestore";

exports.countnamechanges = onDocumentUpdated('users/{userId}', (event) => {
  // Retrieve the current and previous value
  const data = event.data.after.data();
  const previousData = event.data.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 data.after.ref.set({
    name_change_count: count + 1
  }, {merge: true});

});

Python (önizleme)

@on_document_updated(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # Get the current and previous document values.
  new_value = event.data.after
  prev_value = event.data.before

  # We'll only update if the name has changed.
  # This is crucial to prevent infinite loops.
  if new_value.get("name") == prev_value.get("name"):
      return

  # Retrieve the current count of name changes
  count = new_value.to_dict().get("name_change_count", 0)

  # Update the count
  new_value.reference.update({"name_change_count": count + 1})

Uyarı: Bir işlevi tetikleyen aynı dokümana her yazdığınızda sonsuz döngü oluşturma riskiyle karşı karşıyasınızdır. Dikkatli olun ve herhangi bir değişiklik gerekmediğinde işlevden güvenli bir şekilde çıktığınızdan emin olun.

Kullanıcı kimlik doğrulama bilgilerine erişme

Aşağıdaki etkinlik türlerinden birini kullanırsanız etkinliği tetikleyen ana hesapla ilgili kullanıcı kimlik doğrulama bilgilerine erişebilirsiniz. Bu bilgiler, temel etkinlikte döndürülen bilgilere ek olarak sunulur.

Node.js

• onDocumentCreatedWithAuthContext
• onDocumentWrittenWithAuthContext
• onDocumentDeletedWithAuthContext
• onDocumentUpdatedWithAuthContext

Python (önizleme)

• on_document_created_with_auth_context
• on_document_updated_with_auth_context
• on_document_deleted_with_auth_context
• on_document_written_with_auth_context

Kimlik doğrulama bağlamında sunulan veriler hakkında bilgi için Kimlik Doğrulama Bağlamı bölümüne bakın. Aşağıdaki örnekte, kimlik doğrulama bilgilerinin nasıl alınacağı gösterilmektedir:

Node.js

import { onDocumentWrittenWithAuthContext } from "firebase-functions/v2/firestore"

exports.syncUser = onDocumentWrittenWithAuthContext("users/{userId}", (event) => {
    const snapshot = event.data.after;
    if (!snapshot) {
        console.log("No data associated with the event");
        return;
    }
    const data = snapshot.data();

    // retrieve auth context from event
    const { authType, authId } = event;

    let verified = false;
    if (authType === "system") {
      // system-generated users are automatically verified
      verified = true;
    } else if (authType === "unknown" || authType === "unauthenticated") {
      // admin users from a specific domain are verified
      if (authId.endsWith("@example.com")) {
        verified = true;
      }
    }

    return data.after.ref.set({
        created_by: authId,
        verified,
    }, {merge: true}); 
}); 

Python (önizleme)

@on_document_updated_with_auth_context(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:

  # Get the current and previous document values.
  new_value = event.data.after
  prev_value = event.data.before

  # Get the auth context from the event
  user_auth_type = event.auth_type
  user_auth_id = event.auth_id

Tetikleyici etkinliğin dışındaki veriler

Cloud Functions, güvenilir bir ortamda yürütülür. Projenizde hizmet hesabı olarak yetkilendirilirler ve Firebase Admin SDK'sını kullanarak okuma ve yazma işlemleri gerçekleştirebilirsiniz:

Node.js

const { initializeApp } = require('firebase-admin/app');
const { getFirestore, Timestamp, FieldValue } = require('firebase-admin/firestore');

initializeApp();
const db = getFirestore();

exports.writetofirestore = onDocumentWritten("some/doc", (event) => {
    db.doc('some/otherdoc').set({ ... });
  });

  exports.writetofirestore = onDocumentWritten('users/{userId}', (event) => {
    db.doc('some/otherdoc').set({
      // Update otherdoc
    });
  });

Python (önizleme)

from firebase_admin import firestore, initialize_app
import google.cloud.firestore

initialize_app()

@on_document_written(document="some/doc")
def myfunction(event: Event[Change[DocumentSnapshot | None]]) -> None:
  firestore_client: google.cloud.firestore.Client = firestore.client()
  firestore_client.document("another/doc").set({
      # ...
  })

Not: Cloud Functions'da gerçekleştirilen okuma ve yazma işlemleri güvenlik kurallarınız tarafından kontrol edilmez. Veritabanınızın herhangi bir bölümüne erişebilirler.

Sınırlamalar

Cloud Functions için Cloud Firestore tetikleyicileriyle ilgili aşağıdaki sınırlamaları göz önünde bulundurun:

• Cloud Functions (1. nesil), Firestore yerel modunda mevcut bir "(varsayılan)" veritabanını ön koşullandırır. Cloud Firestore tarafından adlandırılmış veritabanlarını veya Datastore modunu desteklemez. Bu tür durumlarda etkinlikleri yapılandırmak için lütfen Cloud Functions'ı (2. nesil) kullanın.
• Sipariş verme garantisi verilmez. Hızlı değişiklikler, işlev çağrılarını beklenmedik bir sırada tetikleyebilir.
• Etkinlikler en az bir kez teslim edilir ancak tek bir etkinlik, birden fazla işlev çağrısına neden olabilir. Tam olarak bir kez gerçekleşen mekaniklere bağlı kalmaktan kaçının ve ihtiyatlı işlevler yazın.
• Datastore modunda Cloud Firestore, Cloud Functions (2. nesil) gerektirir. Cloud Functions (1. nesil) Datastore modunu desteklemez.
• Tetikleyici, tek bir veritabanıyla ilişkilendirilir. Birden çok veritabanıyla eşleşen bir tetikleyici oluşturamazsınız.
• Veritabanının silinmesi, o veritabanına ait tetikleyicilerin otomatik olarak silinmesine neden olmaz. Tetikleyici, etkinlikleri yayınlamayı durdurur ancak siz tetikleyici silene kadar var olmaya devam eder.
• Eşleşen bir etkinlik maksimum istek boyutunu aşarsa bu etkinlik Cloud Functions'a (1. nesil) teslim edilmeyebilir.
  • İstek boyutu nedeniyle teslim edilmeyen etkinlikler platform günlüklerine kaydedilir ve projenin günlük kullanımına dahil edilir.
  • Bu günlükleri Günlük Gezgini'nde "Boyut, error önem derecesi olan 1. nesil için sınırı aştığı için etkinlik, Cloud Functions işlevine teslim edilemiyor..." mesajıyla bulabilirsiniz. İşlev adını functionName alanının altında bulabilirsiniz. receiveTimestamp alanı şu andan itibaren bir saat sonra hâlâ görünüyorsa söz konusu dokümanı zaman damgasından önce ve sonra bir anlık görüntü ile okuyarak gerçek etkinlik içeriğini tahmin edebilirsiniz.
  • Bu sıklığı önlemek için şunları yapabilirsiniz:
    • Cloud Functions'ı (2. nesil) taşıyın ve yükseltin
    • Dokümanın boyutunu küçült
    • İlgili Cloud Functions işlevlerini silin
  • Hariç tutma özelliğini kullanarak günlüğe kaydetme işlemini kapatabilirsiniz ancak rahatsız edici etkinliklerin yine de teslim edilmeyeceğini unutmayın.