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

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

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

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

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

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

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

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

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

على الرغم من أنّ 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.appspot.com

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

المَعلمة ذات القيمة التلقائية من تثبيت الإضافة
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، احرص على تدوين ما يلي فيملف PREINSTALL : تستخدم الإضافة أداة Cloud Secret Manager.

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

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

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

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

  • label (string): وصف موجز لل خيار قابل للاختيار
  • value (سلسلة): القيمة الفعلية لخيار قابل للاختيار

حقل 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 في التمديد Resize Images).

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

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

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

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

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

في حال حذف immutable، تكون القيمة التلقائية هي false.

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

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

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

بالإضافة إلى ذلك، في العديد من الإضافات، تكون قيمة المَعلمة المطلوبة بشكل شائع هي ملف تعريف قاعدة بيانات أو حزمة Cloud Storage. تجدر الإشارة إلى أنّه أثناء التثبيت أو إعادة الضبط أو التحديث، Extensions لا لا تتحقق من صحة ما يلي في وقت إدخال قيمة المعلمة entry::<br class="

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

ومع ذلك، عندما تنشر الإضافة مواردها، ستعرض Firebase console أو Firebase CLI رسالة خطأ في حال عدم إعداد قاعدة البيانات المُشار إليها أو حزمة 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 التصنيفات التي سيتم تطبيقها على جميع الموارد في الإضافة