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

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

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

ملاحظة: يتيح كلّ من 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.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. مثال على البنية 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 الخاصة بالإضافة تغيير حجم الصور).
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 Connector	vpcConnector	يربط هذا الإعداد Cloud Functions بموصل VPC محدّد.
firebaseextensions.v1beta.function/minInstances	الحد الأدنى لعدد مثيلات الدوال	minInstances	الحد الأدنى لعدد مثيلات هذه الدالة التي سيتم تشغيلها في المرة الواحدة
firebaseextensions.v1beta.function/maxInstances	الحد الأقصى لعدد مثيلات الدوال	maxInstances	الحدّ الأقصى لعدد مثيلات هذه الدالة التي يمكن تشغيلها في الوقت نفسه
firebaseextensions.v1beta.function/ingressSettings	إعدادات الدخول	ingressSettings	تتحكّم في الأماكن التي يتم قبول الزيارات الواردة منها
firebaseextensions.v1beta.function/labels	التصنيفات	labels	التصنيفات التي سيتم تطبيقها على جميع الموارد في الإضافة