Cloud Functions ile SQL Connect'in kapsamını genişletme

Cloud Functions for Firebase ile Firebase SQL Connect içindeki etkinlikleri yönetebilirsiniz. Cloud Functions, SQL Connect hizmetinizde bir mutasyonun yürütülmesi gibi etkinliklere yanıt olarak sunucu tarafı kod çalıştırmanıza olanak tanır. Bu sayede kendi sunucularınızı dağıtmadan özel mantık ekleyebilirsiniz.

Yaygın kullanım alanları

  • Veri senkronizasyonu: Bir mutasyon gerçekleştikten sonra verileri diğer sistemlerle (Cloud Firestore, BigQuery veya harici API'ler gibi) kopyalayın veya senkronize edin.

  • Eşzamansız iş akışları: Veritabanı değişikliğinden sonra görüntü işleme veya veri toplama gibi uzun süren işlemleri başlatın.

  • Kullanıcı etkileşimi: Uygulamanızda hesap oluşturma gibi belirli bir değişiklik etkinliğinden sonra kullanıcılara e-posta veya Cloud Messaging bildirimleri gönderin.

SQL Connect mutasyonunda bir işlevi tetikleme

onMutationExecuted etkinlik işleyiciyi kullanarak bir SQL Connect mutasyonu yürütüldüğünde bir işlevi tetikleyebilirsiniz. Bu tetikleyici, bir mutasyon yürütüldüğünde gerçekleşir.

Temel bir değişiklik etkinliği işlevi

Aşağıdaki temel örnek, SQL Connect hizmetinizde yürütülen tüm mutasyonların ayrıntılarını günlüğe kaydeden bir işlevdir:

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";
import { logger } from "firebase-functions";

export const logMutation = onMutationExecuted(
  {
    /* Trigger on all mutations, spanning all services and connectors
       in us-central1 */
  },
  (event) => {
    logger.info("A mutation was executed!", {
      data: event.data,
    });
  }
);

Python

from firebase_functions import dataconnect_fn, logger

@dataconnect_fn.on_mutation_executed()
def log_mutation(event: dataconnect_fn.Event):
  logger.info("A mutation was executed!", event.data)

Projenizdeki tüm mutasyonları tetiklerken tetikleyici işleyicide herhangi bir mutasyon gerçekleştirmemeniz gerekir. Aksi takdirde sonsuz döngüye neden olursunuz. Bir etkinlik tetikleyicide mutasyon gerçekleştirmek istiyorsanız aşağıda açıklanan filtreleme seçeneklerini kullanın ve mutasyonun kendisini tetiklemediğinden emin olun.

İşlev konumunu ayarlama

Etkinliklerin işlevi tetiklemesi için işlev konumu, SQL Connect hizmet konumu ile eşleşmelidir. Varsayılan olarak işlev bölgesi us-central1 şeklindedir.

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";

export const onMutationRegionOption = onMutationExecuted(
  {
    region: "europe-west1"  // Set if SQL Connect service location is not us-central1
  },
  (event) => { /* ... */ }
);

Python

@dataconnect_fn.on_mutation_executed(
  region="europe-west1"  # Set if SQL Connect service location is not us-central1
)
def mutation_executed_handler_region_option(event: dataconnect_fn.Event):
  pass

Etkinlikleri filtrele

onMutationExecuted işleyicisi, etkinlikleri belirli özelliklere göre filtreleyecek seçeneklerle yapılandırılabilir. Bu, işlevinizi yalnızca belirli mutasyonlar için tetiklemek istediğinizde kullanışlıdır.

service, connector ve operation'ye göre filtreleme yapabilirsiniz:

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";
import { logger } from "firebase-functions";

// Trigger this function only for the CreateUser mutation
// in the users connector of the myAppService service.
export const onUserCreate = onMutationExecuted(
  {
    service: "myAppService",
    connector: "users",
    operation: "CreateUser",
  },
  (event) => {
    logger.info("A new user was created!", event.data);
    // Add logic here: for example, sending a welcome email.
  }
);

Python

from firebase_functions import dataconnect_fn, logger

@dataconnect_fn.on_mutation_executed(
  service="myAppService",
  connector="users",
  operation="CreateUser"
):
def on_user_create(event: dataconnect_fn.Event):
  logger.info("A new user was created!", event.data)

Joker karakterler ve yakalama grupları

Tetikleyicilerinizi birden fazla değere göre filtrelemek için joker karakterler ve yakalama grupları kullanabilirsiniz. Yakalanan tüm gruplar event.params uygulamasında kullanılabilir. Daha fazla bilgi için Yol kalıplarını anlama bölümüne bakın.

Örnekler:

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";

// Trigger on all operations that match the pattern `User*`, on any service and
// connector.
export const onMutationWildcards = onMutationExecuted(
  {
    operation: "User*",
  },
  (event) => {}
);

// Trigger on all operations that match the pattern `User*`, on any service and
// connector. Capture the operation name in the variable `op`.
export const onMutationCaptureWildcards = onMutationExecuted(
  {
    operation: "{op=User*}",
  },
  (event) => {
    // `event.params.op` contains the operation name.
  }
);

// Trigger on all operations on the service `myAppService`. Capture the
// operation name in the variable `operation`.
export const onMutationCaptures = onMutationExecuted(
  {
    service: "myAppService",
    operation: "{operation}",
  },
  (event) => {
    // `event.params.operation` contains the operation name.
  }
);

Python

from firebase_functions import dataconnect_fn

# Trigger on all operations that match the pattern `User*`, on any service and
# connector.
@dataconnect_fn.on_mutation_executed(
  operation="User*"
)
def on_mutation_wildcards(event: dataconnect_fn.Event):
  pass

# Trigger on all operations that match the pattern `User*`, on any service and
# connector. Capture the operation name in the variable `op`.
@dataconnect_fn.on_mutation_executed(
  operation="{op=User*}"
)
def on_mutation_capture_wildcards(event: dataconnect_fn.Event):
  # `event.params["op"]` contains the operation name.
  pass

# Trigger on all operations on the service `myAppService`. Capture the
# operation name in the variable `operation`.
@dataconnect_fn.on_mutation_executed(
  service="myAppService",
  operation="{operation}"
)
def on_mutation_captures(event: dataconnect_fn.Event):
  # `event.params["operation"]` contains the operation name.
  pass

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

Etkinliği tetikleyen asıl kullanıcıyla ilgili kullanıcı kimlik doğrulama bilgilerine erişebilirsiniz. Kimlik doğrulama bağlamında bulunan veriler hakkında daha fazla bilgi için Kimlik Doğrulama Bağlamı başlıklı makaleyi inceleyin.

Aşağıdaki örnekte, kimlik doğrulama bilgilerinin nasıl alınacağı gösterilmektedir:

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";

export const onMutation = onMutationExecuted(
  { operation: "MyMutation" },
  (event) => {
    // mutationExecuted event provides authType and authId:
    // event.authType
    // event.authId
  }
);

Python

from firebase_functions import dataconnect_fn

@dataconnect_fn.on_mutation_executed(operation="MyMutation")
def mutation_executed_handler(event: dataconnect_fn.Event):
  # mutationExecuted event provides auth_type and auth_id, which are accessed as follows
  # event.auth_type
  # event.auth_id
  pass

Yetkilendirme türü ve yetkilendirme kimliği şu şekilde doldurulur:

Değişikliği başlatan authtype authid
Kimliği doğrulanmış son kullanıcı app_user Firebase Auth jetonu UID'si
Kimliği doğrulanmamış son kullanıcı unauthenticated boş
Admin SDK'nın bir son kullanıcının kimliğine bürünmesi app_user Kimliğine bürünülen kullanıcının Firebase Auth jetonunun kullanıcı kimliği
Admin SDK, kimliği doğrulanmamış bir isteğin kimliğine bürünüyor unauthenticated boş
Tüm izinlere sahip Admin SDK admin boş

Etkinlik verilerine erişme

İşlevinize iletilen CloudEvent nesnesi, işlevi tetikleyen etkinlikle ilgili bilgiler içerir.

Etkinlik özellikleri

Özellik Tür Açıklama
id string Etkinliğin benzersiz tanımlayıcısı.
source string Etkinliği oluşturan bağlayıcı kaynağı (ör. //firebasedataconnect.googleapis.com/projects/*/locations/*/services/*/connectors/*).
specversion string CloudEvents spesifikasyon sürümü (ör. "1.0").
type string Etkinliğin türü: google.firebase.dataconnect.connector.v1.mutationExecuted.
time string Etkinliğin oluşturulduğu zaman damgası (ISO 8601 biçimi).
subject string İsteğe bağlı. Etkinlik bağlamıyla ilgili ek bilgiler (ör. işlem adı).
params object Yakalanan yol kalıplarının haritası.
authType string Etkinliği tetikleyen asıl öğenin türünü temsil eden bir enum.
authId string Etkinliği tetikleyen asıl öğenin benzersiz tanımlayıcısı.
data MutationEventData SQL Connect etkinliğinin yükü. Sonraki bölüme bakın.

Veri yükü

MutationEventData nesnesi, SQL Connect etkinliğinin yükünü içerir:

{
  // ...
  "authType": // ...
  "data": {
    "payload": {
      "variables": {
        "userId": "user123",
        "updateData": {
          "displayName": "New Name"
        }
      },
      "data": {
        "updateUser": {
          "id": "user123",
          "displayName": "New Name",
          "email": "user@example.com"
        }
      },
      "errors": []
    }
  }
}
  • payload.variables: Değişikliğe iletilen değişkenleri içeren bir nesne.
  • payload.data: Değişiklik tarafından döndürülen verileri içeren bir nesne.
  • payload.errors: Değişikliğin yürütülmesi sırasında oluşan hataların dizisi. Değişiklik başarılı olduysa bu dizi boş olur.

Örnek

Değişiklik değişkenlerine ve döndürülen verilere şu şekilde erişebilirsiniz:

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";
import { logger } from "firebase-functions";

export const processNewUserData = onMutationExecuted(
  {
    "service": "myAppService",
    "connector": "users",
    "operation": "CreateUser",
  },
  (event) => {
    // The variables passed to the mutation
    const mutationVariables = event.data.payload.variables;

    // The data returned by the mutation
    const returnedData = event.data.payload.data;

    logger.info("Processing mutation with variables:", mutationVariables);
    logger.info("Mutation returned:", returnedData);

    // ... your custom logic here
  }
);

Python

from firebase_functions import dataconnect_fn, logger

@dataconnect_fn.on_mutation_executed(
  service="myAppService",
  connector="users",
  operation="CreateUser"
):
def process_new_user_data(event: dataconnect_fn.Event):
  # The variables passed to the mutation
  mutation_vars = event.data.payload.variables
  # The data returned by the mutation
  returned_data = event.data.payload.data

  logger.info("Processing mutation with variables:", mutationVariables)
  logger.info("Mutation returned", returnedData)

  # ... your custom logic here

Cloud Firestore veya Realtime Database gibi diğer veritabanı tetikleyicilerinin aksine, SQL Connect etkinliğinin verilerin "önceki" anlık görüntüsünü sağlamadığını unutmayın. SQL Connect, istekleri temel veritabanına proxy üzerinden ilettiğinden verilerin "önceki" anlık görüntüsü işlemsel olarak alınamaz. Bunun yerine, mutasyona gönderilen bağımsız değişkenlere ve mutasyon tarafından döndürülen verilere erişebilirsiniz.

Bunun bir sonucu olarak, bir etkinlik tetikleyicisinin aynı etkinliği tetiklediği sonsuz döngüleri önlemek için "önceki" ve "sonraki" anlık görüntüleri karşılaştırma stratejisini kullanamazsınız. Bir değişiklik etkinliği tarafından tetiklenen bir işlevden değişiklik yapmanız gerekiyorsa etkinlik filtrelerini kullanın ve hiçbir değişikliğin dolaylı olarak bile olsa kendisini tetikleyemeyeceğinden emin olun.