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

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

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

ملاحظة: يسمح كلّ من Realtime Database وCloud Storage بإنشاء مثيلات ومجموعات بيانات متعددة في قاعدة بيانات واحدة على 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، احرص على تدوين ما يفيد بأنّ إضافة Chrome تستخدم Cloud Secret Manager فيملف PREINSTALL. في حال حذف هذا الحقل، يتم ضبط المَعلمة تلقائيًا على type من string.
options (مطلوب إذا كانت المَعلمة type هي select أو multiSelect)	القائمة	قائمة بالقيم التي يمكن للمستخدم الاختيار من بينها أدرِج الحقلين label وvalue ضمن الحقل options: label (string): وصف موجز لل خيار قابل للاختيار value (سلسلة): القيمة الفعلية لخيار قابل للاختيار احرص على وضع علامات اقتباس حول هذه السلاسل لمنع تحويلات النوع غير المقصودة. حقل value مطلوب لحقل options. في حال حذف label، يتم ضبط خيار القائمة تلقائيًا لعرض value. مثال على البنية options: - label: value: - label: value: - 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 من ما يلي عند إدخال قيمة المَعلمة:

• ما إذا تم إعداد قاعدة البيانات أو حزمة 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	التصنيفات التي سيتم تطبيقها على جميع الموارد في الإضافة