تثبيت إضافة Firebase

يمكنك تثبيت (وإدارة) أيٍّ من إضافات Firebase الرسمية باستخدام وحدة تحكّم Firebase أو Firebase CLI (واجهة سطر الأوامر) أو باستخدام حزمة SDK تم إنشاؤها تلقائيًا.

احرص على مراجعة الاختلافات في الإجراءات المتوافقة لكل طريقة تثبيت.


يُعدّ التثبيت باستخدام حزمة تطوير برامج (SDK) تم إنشاؤها تلقائيًا خيارًا جديدًا لتثبيت وإدارة الإضافات. باستخدام هذا الخيار، يمكنك استخدام سطر الأوامر لإنشاء حزمة تطوير برامج Node SDK تلقائيًا لإصدار معيّن من الإضافة، ويمكنك استيرادها كأحد الموارد المعتمدة العادية في وظائف Cloud المستندة إلى JavaScript أو TypeScript.

تحتوي حزمة تطوير البرامج (SDK) هذه التي تم إنشاؤها تلقائيًا على ما يلي:

  • واجهة تمثّل مَعلمات الإضافة وإعلانات الأنواع لمعظم أنواع المَعلمات غير الأساسية
  • دالة تنشئ مثيلًا للإضافة
  • فئة إضافة تحتوي على عوامل تشغيل Eventarc لجميع الأحداث التي تطلقها الإضافة

بعد إنشاء حزمة SDK للإضافة، تتم جميع عمليات ضبط الإضافة في الرمز البرمجي.

يمكن أن يؤدي استخدام خيار التثبيت هذا إلى تبسيط إدارة مثيلات الإضافات المتعدّدة بشكل كبير، لا سيما في المشاريع التي تحتوي على وظائف Cloud محددة خارج الإضافات.


لتثبيت الإضافات أو إدارتها، يجب أن يكون لديك أحد الدورَين التاليَين: المالك أو المحرِّر أو مشرف Firebase.

لتثبيت إضافة، يجب أن يكون مشروعك مُدرَجًا في خطة Blaze (الدفع أثناء الاستفادة). على الرغم من أنّه لا يتم تحصيل رسوم مقابل تثبيت إضافة، قد يتم تحصيل رسوم منك مقابل استخدامك لخدمات Firebase أو خدمات Cloud، مثل Cloud Secret Manager، إذا تجاوز استخدامك الخطط المجانيّة للخدمات.

قبل البدء

  1. أضِف Firebase إلى مشروعك، إذا لم يسبق لك إجراء ذلك.

  2. إذا لم يسبق لك ذلك، عليك ترقية مشروعك إلى خطة Blaze (الدفع عند استخدام الخدمة).

  3. ثبِّت أحدث إصدار من واجهة برمجة التطبيقات Firebase أو حدِّثه.

  4. سجِّل رقم تعريف مشروعك على Firebase أواسمه المستعار الذي تم ضبطه سابقًا.

    Firebase directory.

الخطوة 1: عرض معلومات تفصيلية عن إضافة

هذه الخطوة اختيارية، ولكنّنا ننصح بها بشدة.

قبل تثبيت Firebase Extension، ننصحك بمراجعة المعلومات التفصيلية عن الإضافة، بما في ذلك:

  • آلية عمل الإضافة وأي مهام قبل التثبيت وتفاصيل عن الإضافة
  • المعلومات العامة التي تحدّد الهوية والوصف
  • ما إذا كانت مهام الإضافة تتطلّب حساب فوترة
  • خدمات Google (واجهات برمجة التطبيقات) و أدوار الوصول المطلوبة ل العمل
  • الموارد التي تم إنشاؤها للإضافة (مثل الدوال)
  • أوصاف المَعلمات التي يمكن للمستخدم ضبطها

لعرض المعلومات التفصيلية عن إضافة:

  1. تأكَّد من أنّك أعددت بيئتك و اخترت إضافة.

  2. يمكنك تنفيذ الأمر extension-info من أي مكان على جهاز الكمبيوتر:

    firebase ext:info publisher-id/extension-id

    يجب استخدام وسيطَي publisher-id وextension-id ، ويمكن العثور عليهما في صفحة تفاصيل التثبيت المُسبَق للملحق.

الخطوة 2: تثبيت إضافة

قبل التثبيت، راجِع المواصفات الأساسية للإضافة (مثل واجهات برمجة التطبيقات المفعّلة، الموارد التي تم إنشاؤها، الإذن بالوصول الممنوح، وما إلى ذلك) ومتطلّبات الفوترة.

قبل المتابعة، تأكّد من إعداد بيئتك واختيار إضافة.

إعداد وظائف السحابة الإلكترونية لبرنامج Firebase

إذا كنت بصدد بدء مشروع جديد أو إذا كان مشروعك لا يستخدم Cloud Functions في Firebase، نفِّذ init functions:

cd your-project
firebase init functions

اختَر TypeScript أو JavaScript كلغة للدوالّ.

إذا سبق أن تمّت بدء Cloud Functions في مشروعك، تأكَّد من استخدام الإصدار 5.1.0 أو إصدار أحدث من حزمة firebase-functions:

cd your-project/functions
npm upgrade --save firebase-functions

إذا كنت تستخدم ESLint، قد تحتاج أيضًا إلى استبعاد حِزم SDK التي تم إنشاؤها من الإعدادات (.eslintrc.js):

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

إنشاء حزمة تطوير برامج (SDK) للإضافات

من دليل Firebase على الجهاز، نفِّذ الأمر ext:sdk:install.

firebase ext:sdk:install publisher-id/extension-id@version

على سبيل المثال، لتثبيت الإصدار 0.1.34 من إضافة firestore-send-email:

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

يجب توفير publisher-id وextension-id ، ويمكن العثور عليهما في صفحة تفاصيل التثبيت المُسبَق للإضافة على extensions.dev. ويكون الجزء @version اختياريًا، وإذا حذفته، سثبِّت الأدوات أحدث إصدار.

هناك خياران يمكنك تحديدهما:

  • --force: عليك تنفيذ كل ما يلي بدون تأكيد إضافي:

    • إنشاء حزمة SDK تلقائيًا حتى إذا سبق أن تم إنشاء حزمة SDK لإضافة الإصدار نفسه
    • ثبِّت حزمة SDK المُنشأة تلقائيًا في مشروع Node في Cloud Functions.

  • --codebase: اسم قاعدة البيانات التي ستتم إضافة حزمة SDK إليها. في حال عدم تحديد قاعدة بيانات، يضيف الأمر حزمة تطوير البرامج (SDK) إلى قاعدة البيانات التلقائية functions.

ينشئ هذا الأمر حزمة Node تحتوي على حزمة تطوير برامج (SDK) يتم إنشاؤها تلقائيًا للإضافات، ويضيفها إلى أحد قواعد رمز برمجي في Cloud Functions في مشروعك. في قاعدة البيانات التلقائية (functions)، يتم حفظ حزمة تطوير البرامج (SDK) في الموقع التالي: 

functions/generated/extensions/publisher-id/extension-id/version

بعد إنشاء حزمة SDK، سيطلب منك الأمر تحديد ما إذا كنت تريد أيضًا تثبيت حزمة SDK في مشروع Node في Cloud Functions. يجب الردّ بنعم على هذا الطلب.

ضبط نُسخ الإضافة

لضبط الإضافة، استورِد حزمة تطوير البرامج (SDK)، ولكل مثيل إضافة تريد تثبيته، استخدِم دالة الإنشاء، مع تضمين معرّف مثيل فريد للمشروع ومَعلمات الضبط التي تتطلّبها الإضافة.

  1. في مصدر Cloud Functions، استورِد أداة الإنشاء باستخدام statement المُطبَّعة بواسطة الأمر ext:sdk:install.

    TypeScript

    على سبيل المثال، إذا أنشأت حزمة SDK لإضافات firestore-send-email ، سيظهر بيان import بالشكل التالي:

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    إذا كانت الإضافة تتطلّب أي قيم سرية، مثل كلمات المرور، تحتاج أيضًا إلى دالة defineSecret من حزمة تطوير البرامج (SDK) لخدمة Cloud Functions:

    import { defineSecret } from "firebase-functions/params";

    JavaScript

    على سبيل المثال، إذا أنشأت حزمة SDK لإضافات firestore-send-email ، سيظهر بيان require على النحو التالي:

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    إذا كانت الإضافة تتطلّب أي قيم سرية، مثل كلمات المرور، تحتاج أيضًا إلى دالة defineSecret من حزمة تطوير البرامج (SDK) لخدمة Cloud Functions:

    const { defineSecret } = require('firebase-functions/params');

  2. لكل مثيل تريد ضبطه، استخدِم دالة المنشئ و صدِّر النتيجة.

    امنح كل مثيل معرّفًا فريدًا يحتوي على أحرف أبجدية صغيرة وأرقام وواصلات فقط.

    TypeScript

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    JavaScript

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    يُرجى العِلم أنّه يجب تحديد القيم السرية باستخدام الدالة defineSecret.

  3. بعد ذلك، لنشر الإضافات التي أعددتها، شغِّل: 

    firebase deploy --only functions --project=projectId-or-alias

    تنطبق جميع خيارات نشر وظائف السحابة الإلكترونية المعروفة. على سبيل المثال، لنشر مثيل إضافة واحد من قاعدة رموز برمجية معيّنة: 

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

الخطوة 3: إكمال عملية الإعداد بعد التثبيت

تتطلّب بعض الإضافات إكمال خطوات مطلوبة أو اختيارية قبل استخدامها. يمكنك العثور على هذه التعليمات في صفحة تفاصيل ما بعد التثبيت الخاصة بامتداداتك في لوحة بيانات Extensions في وحدة تحكّم Firebase (يتم عرض الرابط المحدّد ل لوحة البيانات في المحطة الطرفية بعد التثبيت).

يمكنك أيضًا العثور على هذه التعليمات في ملف POSTINSTALL.md المضمّن في دليل مصدر الإضافة.

إنشاء موارد Firebase

إذا أعددت الإضافة لاستخدام موارد Firebase (Cloud Firestore المجموعات وRealtime Database المسارات وCloud Storage الحِزم) غير المتوفّرة، أنشئها قبل استخدام الإضافة.

إنشاء معالِجات أحداث Eventarc

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

إذا كنت تريد تحديد معالجات لأيّ من الأحداث التي تطلقها الإضافة، يمكنك إجراء ذلك باستخدام طرق التفعيل لكلّ مثيل:

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

يجب تصدير معالِج الحدث مع مثيل الإضافة.

بعد تحديد معالِج أحداث، وبعد كل مرة تُجري فيها تغييرات على أحدها، أعِد نشر كلّ من الإضافة والمعالِج.

تثبيت عدّة نُسخ من الإضافة

يمكنك تثبيت الإضافة نفسها أكثر من مرة في المشروع نفسه. يمكن أن تتضمّن كل نسخة مثبّتة إعدادات مخصّصة وموارد ملف التمديد الخاصة بها. يمكنك تحديد كلّ نسخة مثبّتة والإشارة إليها باستخدام معرّف النسخة، وهو معرّف فريد ضمن مشروعك.

استخدِم دالة إنشاء حزمة SDK المُنشأة تلقائيًا مرة واحدة لكل مثيل تريد تثبيته وضبطه.

الخطوات التالية