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

المَعلمات هي الآلية التي يخصّص المستخدم من خلالها كل نسخة مثبَّتة من إحدى الإضافات. تشبه المَعلمات متغيّرات البيئة لإحدى الإضافات. يمكن أن تتم تعبئة قيم المَعلمات تلقائيًا (توفّرها 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 (سلسلة): وصف قصير للخيار القابل للاختيار

حقل value مطلوب لحقل options.إذا تم إسقاط label، يتم ضبط خيار القائمة تلقائيًا على عرض value.
resourceType
(مطلوب إذا كان المَعلمة type هو selectResource) 		سلسلة

نوع مورد Firebase الذي يُطلب من المستخدم اختياره في الوقت الحالي، لا تتيح أداة اختيار الموارد سوى حِزم Cloud Storage 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.

ملاحظة: إذا حدّدت مَعلمة "الموقع الجغرافي" للدوال المنشورة في إضافتك، عليك تضمين حقل 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 التصنيفات التي يجب تطبيقها على جميع الموارد في الإضافة