عوامل تشغيل مصادقة 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) لتقليل وقت استجابة الشبكة بين موفّر المصادقة وبيئة تنفيذ الدالة.