تثبيت إضافة Firebase

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

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

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

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

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

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

قبل البدء

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

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

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

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

   • رقم تعريف المشروع: شغِّل firebase projects:list من أي مكان على جهاز الكمبيوتر.
   • اسم مستعار للمشروع: شغِّل firebase use من دليل التطبيق المحلي.

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

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

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

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

لعرض معلومات مفصّلة عن إضافة، اتّبِع الخطوات التالية:

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

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

   firebase ext:info publisher-id/extension-id

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

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

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

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

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

إذا كنت بصدد بدء مشروع جديد أو إذا كان مشروعك لا يستخدم Cloud Functions for 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 التي تم إنشاؤها تلقائيًا في مشروع Cloud Functions Node.

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

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

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

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

ضبط مثيلات الإضافة

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

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

   TypeScriptJavaScript المزيد

   على سبيل المثال، إذا أنشأت حزمة 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";
   

   على سبيل المثال، إذا أنشأت حزمة 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. لكل مثيل تريد إعداده، استدعِ دالة الإنشاء واعرض النتيجة.

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

   TypeScriptJavaScript المزيد
   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",
   });
   

   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

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

   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 عند وقوع أحداث مهمة أثناء التنفيذ. إذا كان أحد الإضافات ينشر أحداثًا، يمكنك كتابة دوال تتفاعل مع هذه الأحداث باستخدام منطق مخصّص. يمكن أن يكون ذلك مفيدًا، على سبيل المثال، لإعلام المستخدمين عند اكتمال المهام التي تستغرق وقتًا طويلاً، أو لمعالجة ناتج دالة إضافة.

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

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

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

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

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

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

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

تثبيت عدة مثيلات للإضافة

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

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

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

• اطّلِع على التفاصيل والإعدادات الخاصة بالإضافة المثبَّتة في وحدة تحكّم Firebase.

• مراقبة نشاط الإضافة المثبَّتة، بما في ذلك عمليات التحقّق من سلامتها واستخدامها وسجلّاتها

• استخدِم وحدة تحكّم Firebase لإدارة الإضافة المثبَّتة. بالنسبة إلى إضافات Firebase الرسمية، يمكنك إعادة ضبط إعدادات الإضافة أو إلغاء تثبيتها، بالإضافة إلى تحديثها إلى أحدث إصدار.

• كأفضل ممارسة لجميع المشاريع، احرص على إعداد تنبيهات الميزانية لمشروعك ومراقبة لوحة بيانات الاستخدام والفوترة في وحدة تحكّم Firebase.