إعداد المعلمات واستخدامها في الإضافة

المَعلمات هي الآلية التي يخصّص من خلالها المستخدم كل نسخة مثبّتة من الإضافة. المَعلمات تشبه متغيّرات البيئة للإضافة. يمكن أن تكون قيم المَعلمات إما تتم تعبئتها تلقائيًا (يوفّرها Firebase بعد التثبيت) أو يضبطها المستخدم (يحدّدها المستخدم أثناء التثبيت).

تتوفّر هذه المَعلمات لتتمكّن من الرجوع إليها في الرمز المصدر لدوال الإضافة وملف extension.yaml وملف POSTINSTALL.md. في ما يلي البنية التي توضّح كيفية الإشارة إلى مَعلمة باسم PARAMETER_NAME:

  • ضمن الرمز المصدر للدوال، استخدِم وحدة params (على سبيل المثال، params.defineInt("PARAMETER_NAME")) أو process.env.PARAMETER_NAME.

  • في extension.yaml وPOSTINSTALL.md، استخدِم ${param:PARAMETER_NAME}.

    بعد التثبيت، تعرض وحدة تحكّم Firebase محتوى ملف POSTINSTALL.md وتملأ أي مراجع للمَعلمات بالقيم الفعلية للنسخة المثبَّتة.

المَعلمات التي تتم تعبئتها تلقائيًا

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

جميع قيم المَعلمات التي تتم تعبئتها تلقائيًا غير قابلة للتغيير. ويتم ضبطها في وقت إنشاء المشروع أو تثبيت الإضافة.

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

مرجع للمَعلمة التي تتم تعبئتها تلقائيًا الوصف قيمة المَعلمة (التي توفّرها Firebase)
المَعلمات ذات القيم التلقائية من مشروع Firebase
PROJECT_ID المعرّف الفريد لمشروع Firebase الذي تم تثبيت الإضافة فيه

التنسيق العام:
project-id

مثال على القيمة:
project-123

DATABASE_URL عنوان URL التلقائي لمثيل Realtime Database في مشروع Firebase

التنسيق العام:
https://project-id-default-rtdb.firebaseio.com
(المثيلات في الولايات المتحدة)
أو
https://project-id-default-rtdb.region-code.firebasedatabase.app
(المثيلات خارج الولايات المتحدة)

مثال على القيمة:
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

اسم مثيل Realtime Database التلقائي لمشروع Firebase

عادةً ما تكون هذه القيمة مماثلة لرقم تعريف المشروع أو تنتهي بـ -default-rtdb.

التنسيق العام:
project-id

مثال على القيمة:
project-123

STORAGE_BUCKET اسم حزمة Cloud Storage التلقائية لمشروع Firebase

التنسيق العام:
PROJECT_ID.firebasestorage.app

مثال على القيمة:
project-123.firebasestorage.app

مَعلمة ذات قيمة تلقائية من عملية تثبيت الإضافة
EXT_INSTANCE_ID

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

يتم إنشاء هذه القيمة من الحقل name المحدّد في ملف extension.yaml.

التنسيق العام لأول نسخة مثبَّتة (يتم تخصيصه تلقائيًا من خلال Firebase، ولا يمكن للمستخدم تعديله أثناء التثبيت):
name-from-extension.yaml

مثال على القيمة:
my-awesome-extension


التنسيق العام للنسخة الثانية المثبَّتة وما فوقها (يتم تخصيصه تلقائيًا من خلال Firebase، ويمكن للمستخدم تعديله أثناء التثبيت):
name-from-extension.yaml-4-digit-alphanumeric-hash

مثال على القيمة:
my-awesome-extension-6m31

المَعلمات التي يضبطها المستخدم

للسماح للمستخدم بتخصيص كل نسخة مثبَّتة من الإضافة، يمكنك طلب تحديد قيم المَعلمات من المستخدم أثناء التثبيت. لطلب هذه القيم، يمكنك إعداد الطلبات في قسم params من ملف extension.yaml.

في ما يلي مثال على قسم params، يليه جدول يصف جميع حقول المَعلمات المتاحة.

# extension.yaml
...

# Parameters (environment variables) for which the user specifies values during installation
params:
  - param: DB_PATH
    label: Realtime Database path
    description: >-
      What is the Realtime Database path where you will write new text
      for sentiment analysis?
    type: string
    validationRegex: ^\S+$
    validationErrorMessage: Realtime Database path cannot contain spaces.
    example: path/to/posts
    required: true

  - param: TEXT_KEY
    label: Key for text
    description: What is the name of the key that will contain text to be analyzed?
    type: string
    default: textToAnalyze
    required: true

في قسم params من ملف extension.yaml، استخدِم الحقول التالية لتحديد مَعلمة يضبطها المستخدم:

الحقل النوع الوصف
param
(مطلوب)
سلسلة اسم المَعلمة
label
(مطلوب)
سلسلة

وصف موجز للمَعلمة

يتم عرضها للمستخدم عندما يُطلب منه إدخال قيمة المَعلمة

description
(اختياري)
سلسلة

وصف تفصيلي للمَعلمة

يتم عرضها للمستخدم عندما يُطلب منه إدخال قيمة المَعلمة

يتيح تنسيق Markdown

type
(اختياري)
سلسلة

آلية الإدخال التي يحدّد المستخدم من خلالها قيمة المَعلمة (على سبيل المثال، إدخال النص مباشرةً أو الاختيار من قائمة منسدلة)

تشمل القيم الصالحة ما يلي:

  • ‫string: يسمح بإدخال نص بتصميم مرن (وفقًا للقيود التي يفرضها validationRegex)
  • ‫select: تتيح اختيار إدخال واحد من قائمة خيارات محدّدة مسبقًا. إذا حدّدت هذه القيمة، يجب أيضًا تحديد الحقل options.
  • ‫multiSelect: يسمح باختيار إدخال واحد أو أكثر من قائمة خيارات محدّدة مسبقًا. إذا حدّدت هذه القيمة، يجب أيضًا تحديد الحقل options.
  • ‫selectResource: يسمح باختيار نوع معيّن من موارد Firebase (مثل حزمة Cloud Storage) من مشروع المستخدم.

    عند تحديد مَعلمة من هذا النوع، سيحصل المستخدمون على تطبيق مصغّر للاختيار أكثر سهولة في الاستخدام في واجهة مستخدم التثبيت، ولهذا السبب، استخدِم مَعلمات selectResource كلما أمكن ذلك.

    في حال تحديد هذه القيمة، يجب أيضًا تحديد الحقل resourceType.

  • ‫secret: يسمح بتخزين السلاسل الحسّاسة، مثل مفاتيح واجهة برمجة التطبيقات للخدمات التابعة لجهات خارجية. سيتم تخزين هذه القيم في Cloud Secret Manager.

    ‫Cloud Secret Manager هي خدمة مدفوعة، وقد يؤدي استخدامها إلى فرض رسوم على المستخدمين الذين يثبّتون الإضافة. إذا كنت تستخدم نوع المَعلمة secret، احرص على توثيق استخدام الإضافة لخدمة Cloud Secret Manager في ملف PREINSTALL.

في حال حذف هذا الحقل، يتم ضبط المَعلمة تلقائيًا على type من string.

options
(مطلوبة إذا كانت المَعلمة type هي select أو multiSelect)
القائمة

قائمة بالقيم التي يمكن للمستخدم الاختيار من بينها

أدرِج الحقلَين label وvalue ضمن الحقل options:

  • ‫label (string): وصف مختصر للخيار الذي يمكن تحديده
  • ‫value (string): القيمة الفعلية للخيار الذي يمكن تحديده

يجب ملء حقل value لحقل options.
في حال حذف label، يتم ضبط خيار القائمة تلقائيًا على عرض value.

resourceType
(مطلوبة إذا كانت المَعلمة type هي selectResource)
سلسلة

نوع مورد Firebase الذي سيُطلب من المستخدم اختياره. في الوقت الحالي، لا تتيح سوى حِزم Cloud Storage استخدام أدوات اختيار الموارد:

نوع المورد رقم تعريف النوع
حزمة واحدة (Cloud Storage) storage.googleapis.com/Bucket

سيتم تجاهل قيم resourceType غير المعروفة وستعرض واجهة المستخدم المَعلمة كحقل إدخال string بتصميم مرن.

example
(اختياري)
سلسلة

مثال على قيمة المَعلمة

validationRegex
(اختياري)
(ينطبق فقط عندما تكون المَعلمة type string)
سلسلة

سلسلة تعبير نمطي للتحقّق من صحة القيمة التي ضبطها المستخدم للمَعلمة

يتم تجميع التعبير النمطي باستخدام مكتبة go: RE2

للاطّلاع على تفاصيل حول التحقّق من الصحة، يُرجى الرجوع إلى قسم التحقّق من الصحة ورسائل الخطأ أدناه.

validationErrorMessage
(اختياري)
سلسلة

رسالة الخطأ التي تظهر في حال تعذُّر validationRegex

للحصول على تفاصيل حول رسائل الخطأ، يُرجى الرجوع إلى قسم التحقّق من الصحة ورسائل الخطأ أدناه.

default
(اختياري)
سلسلة

القيمة التلقائية للمَعلمة إذا ترك المستخدم قيمة المَعلمة فارغة

يمكنك تحديد قيمة مَعلمة تتم تعبئتها تلقائيًا للقيمة default، إذا كان ذلك منطبقًا (للاطّلاع على مثال، يُرجى الرجوع إلى المَعلمة IMG_BUCKET في إضافة تغيير حجم الصور).

required
(اختياري)
قيمة منطقية

تحدّد ما إذا كان بإمكان المستخدم إرسال سلسلة فارغة عندما يُطلب منه إدخال قيمة المَعلمة

في حال حذف السمة required، يتم ضبط هذه القيمة تلقائيًا على true (أي مَعلمة مطلوبة).

immutable
(اختياري)
قيمة منطقية

تحدّد ما إذا كان بإمكان المستخدم تغيير قيمة المَعلمة بعد التثبيت (على سبيل المثال، في حال إعادة ضبط الإضافة)

في حال حذف السمة immutable، يتم ضبط هذه القيمة تلقائيًا على false.

ملاحظة: إذا حدّدت مَعلمة "location" للدوال المنشورة في إضافتك، عليك تضمين حقل immutable هذا في كائن المَعلمة.

التحقّق من صحة القيم التي ضبطها المستخدم ورسائل الخطأ

عند إعداد مَعلمة باستخدام type من string، عليك تحديد عملية التحقّق المناسبة من التعبير النمطي من خلال حقل validationRegex الخاص بالمَعلمة.

بالنسبة إلى العديد من الإضافات، تكون قيمة المَعلمة المطلوبة عادةً هي مسار قاعدة البيانات أو حزمة Cloud Storage. يُرجى العِلم أنّه أثناء التثبيت أو إعادة الضبط أو التحديث، لا تتحقّق خدمة Extensions من صحة ما يلي في وقت إدخال قيمة المَعلمة:

  • ما إذا تم إعداد قاعدة البيانات المحدّدة أو حزمة Cloud Storage ضمن مشروع Firebase الخاص بالمستخدم
  • ما إذا كان مسار قاعدة البيانات المحدّد متوفّرًا في قاعدة بيانات المستخدم

ومع ذلك، عندما تنشر الإضافة مواردها، ستعرض وحدة تحكّم Firebase أو واجهة سطر أوامر Firebase رسالة خطأ إذا لم يتم إعداد قاعدة البيانات المُشار إليها أو حزمة Cloud Storage في المشروع بعد.

ننصحك بشدة بإبلاغ المستخدمين في ملف PREINSTALL بهذه المتطلبات حتى يتم تثبيت الإضافة بنجاح وتعمل على النحو المتوقع عند تثبيتها.

مَعلمات النظام

تتحكّم معلَمات النظام في الإعدادات الأساسية لموارد الإضافة. بما أنّها تهدف إلى التحكّم في إعدادات الموارد، لا يمكن الوصول إليها كمتغيّرات بيئة من داخل رمز الدالة.

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

ومع ذلك، إذا كانت الإضافة تتطلّب موارد خاصة، يمكنك ضبط قيم محدّدة على مستوى كل مورد في extension.yaml. ستلغي إعدادات الضبط هذه لكل مورد إعدادات الإضافة على مستوى المثيل لدى المستخدم. على سبيل المثال:

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    availableMemoryMb: 1024
- name: normal_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function has no special memory requirements. It will use the
    default value, or the value of `firebaseextension.v1beta.function/memory`
  properties:
    httpsTrigger: {}
    runtime: nodejs18

في ما يلي مَعلمات النظام المتاحة:

الاسم التصنيف (مناسب للمستخدمين) الحقل المقابل في properties الوصف
firebaseextensions.v1beta.function/location الموقع الجغرافي location ما هي المنطقة التي يجب نشر Cloud Functions فيها؟
firebaseextensions.v1beta.function/memory ذاكرة الدالة memory كم عدد الميغابايت من الذاكرة التي يجب تخصيصها لكل دالة؟
firebaseextensions.v1beta.function/timeoutSeconds مهلة الدالة timeout كم عدد الثواني التي يجب أن تعمل فيها الدوال قبل انتهاء المهلة؟
firebaseextensions.v1beta.function/vpcConnectorEgressSettings البيانات الصادرة من موصِّل VPC vpcConnectorEgressSettings تتحكّم في حركة البيانات الصادرة عند ضبط موصِّل VPC
firebaseextensions.v1beta.function/vpcConnector موصل VPC vpcConnector يربط Cloud Functions بموصِّل VPC محدّد.
firebaseextensions.v1beta.function/minInstances الحد الأدنى لعدد مثيلات الدوال minInstances الحدّ الأدنى لعدد نُسخ هذه الدالة التي يتم تشغيلها في آنٍ واحد
firebaseextensions.v1beta.function/maxInstances الحد الأقصى لعدد نُسخ الدالة maxInstances الحدّ الأقصى لعدد نُسخ هذه الدالة التي يمكن تشغيلها في الوقت نفسه
firebaseextensions.v1beta.function/ingressSettings إعدادات الدخول ingressSettings يتحكّم في مصادر الزيارات الواردة التي يتم قبولها
firebaseextensions.v1beta.function/labels التصنيفات labels التصنيفات التي سيتم تطبيقها على جميع الموارد في الإضافة