عوامل تشغيل مصادقة Firebase

يمكنك تشغيل دوال استجابةً لعمليات إنشاء حسابات المستخدمين وحذفها. Firebase Authentication على سبيل المثال، يمكنك إرسال رسالة إلكترونية ترحيبية إلى مستخدم أنشأ حسابًا في تطبيقك. تستند الأمثلة الواردة في هذه الصفحة إلى نموذج يفعل ذلك بالضبط، أي يرسل رسائل إلكترونية ترحيبية وتوديعية عند إنشاء الحساب وحذفه.

للاطّلاع على المزيد من الأمثلة حول حالات الاستخدام، راجِع المقالة ما هي الإجراءات التي يمكنني اتّخاذها باستخدام Cloud Functions؟.

تشغيل دالة عند إنشاء مستخدم

يمكنك إنشاء دالة يتم تشغيلها عند إنشاء مستخدم Authentication باستخدام معالج الأحداث onUserCreated من الحزمة الفرعية firebase-functions/v2/identity:

const { onUserCreated } = require("firebase-functions/identity");
const { defineSecret } = require("firebase-functions/params");
const { logger } = require("firebase-functions");
const { sendWelcomeEmail } = require("./utils/myEmailService");

const emailApiKey = defineSecret("EMAIL_API_KEY");

exports.newUserWelcome = onUserCreated(
  { secrets: [emailApiKey] },
  async (event) => {
    const { uid, email, displayName } = event.data;

    if (!email) {
      logger.log(`User ${uid} does not have an email address.`);
      return;
    }

    await sendWelcomeEmail(email, displayName);
  },
);

ستؤدي حسابات Authentication إلى تشغيل أحداث إنشاء المستخدمين في Cloud Functions في الحالات التالية:

  • ينشئ المستخدم حسابًا على البريد الإلكتروني وكلمة مرور.
  • يسجِّل المستخدم الدخول لأول مرة باستخدام موفِّر هوية موحَّدة.
  • ينشئ المطوّر حسابًا باستخدام Admin SDK.
  • يسجِّل المستخدم الدخول إلى جلسة مصادقة مجهولة جديدة للمرة الأولى.

لا يتم تشغيل حدث Cloud Functions عندما يسجّل المستخدم الدخول للمرة الأولى باستخدام رمز مميّز مخصّص.

ضبط خيارات المشغّل وإعدادات المستأجرين المتعدّدين

يمكنك ضبط وظيفتك من خلال تمرير عنصر خيارات (AuthOptions) كالمَعلمة الأولى إلى onUserCreated:

/**
 * Sends a welcome email scoped to a specific tenant in Identity Platform.
 */
exports.sendWelcomeEmailToTenant = onUserCreated(
  {
    secrets: [emailApiKey],
    // Only trigger when a user is a member of this tenant
    tenantId: "my-tenant-id",
  },
  async (event) => {
    const { uid, email, displayName } = event.data;
    // Customize the email for this tenant
    await sendWelcomeEmail(email, displayName, event.tenantId);
  },
);
  /**
 * Sends a welcome email only to users not associated with any tenant.
 */
exports.sendWelcomeEmailNoTenant = onUserCreated(
  {
    secrets: [emailApiKey],
    // Only trigger when a user is NOT a member of a tenant
    tenantId: IS_NOT_TENANT,
  },
  async (event) => {
    const { email, displayName } = event.data;

    // Send a generic welcome email
    await sendWelcomeEmail(email, displayName);
  },
);

إذا كان مشروعك يستخدم ميزة "تعدد المستأجرين" في Identity Platform، يمكنك تحديد نطاق المشغّل على النحو التالي:

  • المشروع التلقائي (بدون مستأجر): اضبط tenantId على IS_NOT_TENANT للاستماع إلى المستخدمين الذين تم إنشاؤهم في المشروع التلقائي فقط.
  • مستأجر محدّد: أدخِل رقم تعريف السلسلة للمستأجر (على سبيل المثال، { tenantId: "tenant-id-1" }) للاستماع إلى المستخدمين الذين تم إنشاؤهم في هذا المستأجر فقط.
  • جميع المستأجرين والمستخدمين: إذا تم حذف tenantId، سيتم تشغيل الدالة عند وقوع أحداث إنشاء المستخدمين في جميع المستأجرين ومستخدمي المشروع التلقائيين في المشروع.

بالإضافة إلى tenantId، يمكنك تحديد خيارات الضبط العادي من الجيل الثاني، بما في ذلك region وconcurrency وcpu وmemory وtimeoutSeconds وminInstances وmaxInstances وsecrets.

الوصول إلى سمات المستخدم

من بيانات المستخدم التي تم إرجاعها إلى الدالة، يمكنك الوصول إلى قائمة سمات المستخدم المتوفّرة في عنصر UserRecord الخاص بالمستخدم الذي تم إنشاؤه حديثًا من خلال event.data. على سبيل المثال، يمكنك الحصول على البريد الإلكتروني للمستخدم واسمه المعروض كما هو موضّح أدناه:

const { uid, email, displayName } = event.data;

تتلقّى مشغّلات المصادقة في الجيل الثاني عنصر AuthEvent. بالإضافة إلى event.data، يمكنك الوصول إلى البيانات الوصفية للأحداث، مثل:

  • event.id: معرّف فريد للحدث.
  • event.type: نوع الحدث (google.firebase.auth.user.v2.created)
  • ‫event.time: طابع زمني بتنسيق ISO 8601 يمثّل وقت وقوع الحدث.
  • event.project: معرّف مشروع Google Cloud
  • ‫event.tenantId: رقم تعريف المستأجر في Identity Platform المرتبط بالمستخدم، إذا كان ذلك منطبقًا.

تفعيل دالة عند حذف مستخدم

وكما يمكنك تشغيل دالة عند إنشاء مستخدم، يمكنك الاستجابة لأحداث حذف المستخدم. استخدِم معالج الأحداث onUserDeleted من firebase-functions/v2/identity كما هو موضّح:

const { onUserDeleted } = require("firebase-functions/identity");
const { defineSecret } = require("firebase-functions/params");
const { logger } = require("firebase-functions");
const { sendGoodbyeEmail } = require("./utils/myEmailService");

const emailApiKey = defineSecret("EMAIL_API_KEY");

exports.deletedUserFarewell = onUserDeleted(
  { secrets: [emailApiKey] },
  async (event) => {
    const { uid, email, displayName } = event.data;
    if (!email) {
      logger.log(`User ${uid} does not have an email address.`);
      return;
    }

    await sendGoodbyeEmail(email, displayName);
  },
);

كما هو الحال مع onUserCreated، يمكنك ضبط onUserDeleted باستخدام خيارات مثل { tenantId: IS_NOT_TENANT } لحصر المشغّلات على المستخدمين في المشروع التلقائي.

وظائف حظر المشغّلات

إذا تمت الترقية إلى Firebase Authentication with Identity Platform، يمكنك تمديد Firebase Authentication باستخدام الدوال الحظر.

تتيح لك الدوال الحظر تنفيذ رمز مخصّص بشكل متزامن لتعديل نتيجة تسجيل مستخدم أو تسجيل الدخول إلى تطبيقك. وخلافًا لمشغّلات الخلفية التي يتم تشغيلها بشكل غير متزامن بعد انتهاء حدث ما، تتيح لك دوال الحظر منع المستخدم من إثبات الهوية إذا لم يستوفِ معايير معيّنة، أو تعديل معلومات المستخدم ومطالباته قبل إرجاعها إلى تطبيق العميل.

أفضل الممارسات المتعلقة بمشغّلات الجيل الثاني

عند تنفيذ مشغّلات المصادقة من الجيل الثاني، يُرجى مراعاة أفضل الممارسات التالية:

  • مراعاة التزامن: تعالج مثيلات Cloud Functions (الجيل الثاني) الطلبات المتزامنة (يتم تلقائيًا ضبط 80 طلبًا متزامنًا عندما تكون وحدة المعالجة المركزية ≥ 1). تأكَّد من أنّ وظيفتك لا تعتمد على حالة متغيرة عامة بين عمليات التنفيذ المتزامنة.
  • التصميم لضمان عدم تكرار العمليات: يتم تسليم الأحداث في الجيل الثاني مرة واحدة على الأقل من خلال Eventarc. تأكَّد من أنّ الدوال متكرّرة، على سبيل المثال، تحقَّق من أنّه لم يتم إرسال رسالة ترحيب إلكترونية أو تهيئة إدخال قاعدة بيانات من قبل، وذلك قبل تنفيذ أي آثار جانبية.
  • تحديد نطاق وظائف المستأجرين المتعدّدين: إذا كان تطبيقك يستخدم ميزة المستأجرين المتعدّدين في Identity Platform، تحقَّق مما إذا كان يجب أن تتعامل الدوال مع الأحداث على مستوى جميع المستأجرين أو مستأجرين معيّنين فقط. استخدِم tenantId: IS_NOT_TENANT لمنع مستخدمي المستأجر من تشغيل الدوال المخصّصة للمشروع الأساسي فقط.
  • إدارة المناطق وتخصيص الموارد: حدِّد موقع الدالة (region) لتقليل وقت استجابة الشبكة إلى أدنى حد بين موفّر المصادقة وبيئة تنفيذ الدالة.