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

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

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

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

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

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