گسترش اتصال داده با توابع ابری

با استفاده Cloud Functions for Firebase ، می‌توانید رویدادها را در Firebase Data Connect مدیریت کنید. Cloud Functions به شما امکان می‌دهد کد سمت سرور را در پاسخ به رویدادها، مانند اجرای یک جهش در سرویس Data Connect خود، اجرا کنید. این به شما امکان می‌دهد بدون استقرار سرورهای خود، منطق سفارشی اضافه کنید.

موارد استفاده رایج

  • همگام‌سازی داده‌ها: پس از وقوع یک جهش، داده‌ها را با سیستم‌های دیگر (مانند Cloud Firestore ، BigQuery یا APIهای خارجی) تکثیر یا همگام‌سازی کنید.

  • گردش‌های کاری ناهمزمان: فرآیندهای طولانی‌مدت، مانند پردازش تصویر یا جمع‌آوری داده‌ها، را پس از تغییر پایگاه داده آغاز کنید.

  • تعامل با کاربر: پس از یک رویداد جهش خاص در برنامه شما، مانند ایجاد حساب کاربری، ایمیل یا اعلان‌های Cloud Messaging را برای کاربران ارسال کنید.

یک تابع را روی یک جهش Data Connect فعال می‌کند.

شما می‌توانید هر زمان که یک جهش Data Connect با استفاده از رویداد onMutationExecuted اجرا می‌شود، یک تابع را فعال کنید. این فعال‌سازی پس از اجرای یک جهش رخ می‌دهد.

یک تابع رویداد جهش پایه

مثال پایه زیر تابعی است که جزئیات هر جهشی که در سرویس Data Connect شما اجرا می‌شود را ثبت می‌کند:

نود جی اس 

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

پایتون 

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)

هنگام فعال کردن همه جهش‌ها در پروژه خود، نباید هیچ جهشی را در کنترل‌کننده‌ی ماشه انجام دهید، در غیر این صورت باعث ایجاد یک حلقه‌ی بی‌نهایت خواهید شد. اگر می‌خواهید جهش‌ها را در یک ماشه رویداد انجام دهید، از گزینه‌های فیلترینگ شرح داده شده در زیر استفاده کنید و مراقب باشید که جهش خودش فعال نشود.

محل تابع را تنظیم کنید

برای اینکه رویدادها بتوانند تابع را فعال کنند، مکان تابع باید با مکان سرویس Data Connect مطابقت داشته باشد. به طور پیش‌فرض، ناحیه تابع us-central1 است.

نود جی اس 

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

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

پایتون 

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

فیلتر کردن رویدادها

هندلر onMutationExecuted را می‌توان با گزینه‌هایی برای فیلتر کردن رویدادها بر اساس ویژگی‌های خاص پیکربندی کرد. این قابلیت زمانی مفید است که فقط می‌خواهید تابع خود را برای جهش‌های خاصی فعال کنید.

می‌توانید بر اساس service ، connector و operation فیلتر کنید:

نود جی اس 

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

پایتون 

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)

وایلدکاردها و گروه‌های تسخیر شده

شما می‌توانید از wildcardها و گروه‌های capture برای فیلتر کردن triggerهای خود بر روی چندین مقدار استفاده کنید. هر گروه capture شده در event.params برای استفاده در دسترس است. برای اطلاعات بیشتر به Understanding path patterns مراجعه کنید.

مثال‌ها:

نود جی اس 

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

پایتون 

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

دسترسی به اطلاعات احراز هویت کاربر

شما می‌توانید به اطلاعات احراز هویت کاربر در مورد مدیری که رویداد را آغاز کرده است، دسترسی داشته باشید. برای اطلاعات بیشتر در مورد داده‌های موجود در زمینه احراز هویت، به Auth Context مراجعه کنید.

مثال زیر نحوه بازیابی اطلاعات احراز هویت را نشان می‌دهد:

نود جی اس 

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

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

پایتون 

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

نوع و شناسه‌ی احراز هویت به این صورت وارد می‌شوند:

جهش آغاز شده توسط نوع اعتبار معتبر
کاربر نهایی احراز هویت شده app_user شناسه کاربری توکن فایربیس Auth
کاربر نهایی احراز هویت نشده unauthenticated خالی
SDK ادمین که هویت یک کاربر نهایی را جعل می‌کند app_user شناسه کاربری توکن احراز هویت فایربیس مربوط به کاربر جعل هویت شده
SDK ادمین، یک درخواست احراز هویت نشده را جعل هویت می‌کند unauthenticated خالی
SDK مدیریتی با مجوزهای کامل admin خالی

دسترسی به داده‌های رویداد

شیء CloudEvent که به تابع شما ارسال می‌شود، حاوی اطلاعاتی در مورد رویدادی است که آن را فعال کرده است.

ویژگی‌های رویداد

ویژگی نوع توضیحات
id string یک شناسه منحصر به فرد برای رویداد.
source string منبع رابطی که رویداد را ایجاد کرده است (برای مثال، //firebasedataconnect.googleapis.com/projects/*/locations/*/services/*/connectors/* ).
specversion string نسخه مشخصات CloudEvents (مثلاً "1.0").
type string نوع رویداد: google.firebase.dataconnect.connector.v1.mutationExecuted .
time string مهر زمانی (با فرمت ISO 8601) برای زمان تولید رویداد.
subject string اختیاری. اطلاعات اضافی در مورد زمینه رویداد، مانند نام عملیات.
params object نقشه‌ای از الگوهای مسیر ثبت‌شده.
authType string یک enum که نوع principal ای که رویداد را آغاز کرده است را نشان می‌دهد.
authId string یک شناسه منحصر به فرد از اصلی که باعث ایجاد رویداد شده است.
data MutationEventData بار مفید رویداد Data Connect . به بخش بعدی مراجعه کنید.

بار داده

شیء MutationEventData شامل محتوای رویداد Data Connect است: 

{
  // ...
  "authType": // ...
  "data": {
    "payload": {
      "variables": {
        "userId": "user123",
        "updateData": {
          "displayName": "New Name"
        }
      },
      "data": {
        "updateUser": {
          "id": "user123",
          "displayName": "New Name",
          "email": "user@example.com"
        }
      },
      "errors": []
    }
  }
}
  • payload.variables : یک شیء حاوی متغیرهایی که به mutation ارسال شده‌اند.
  • payload.data : شیء حاوی داده‌هایی که توسط جهش بازگردانده شده‌اند.
  • payload.errors : آرایه‌ای از هرگونه خطایی که در طول اجرای جهش رخ داده است. اگر جهش موفقیت‌آمیز باشد، این آرایه خالی خواهد بود.

مثال

در اینجا نحوه دسترسی به متغیرهای جهش و داده‌های برگشتی آورده شده است:

نود جی اس 

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

پایتون 

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 یا Realtime Database ، رویداد Data Connect یک تصویر لحظه‌ای "قبل" از داده‌ها ارائه نمی‌دهد. از آنجا که Data Connect درخواست‌ها را به پایگاه داده اصلی پروکسی می‌کند، تصویر لحظه‌ای "قبل" از داده‌ها را نمی‌توان به صورت تراکنشی به دست آورد. در عوض، شما به آرگومان‌های ارسال شده به جهش و داده‌هایی که توسط آن بازگردانده شده است، دسترسی دارید.

یکی از پیامدهای این امر این است که شما نمی‌توانید از استراتژی مقایسه اسنپ‌شات‌های «قبل» و «بعد» برای جلوگیری از حلقه‌های بی‌نهایت استفاده کنید، که در آن یک رویداد، همان رویداد را فعال می‌کند. اگر باید جهشی را از تابعی که توسط یک رویداد جهش فعال شده است، انجام دهید، از فیلترهای رویداد استفاده کنید و مراقب باشید که هیچ جهشی نتواند خودش را فعال کند، حتی به طور غیرمستقیم.