قم بإعداد المعلمات واستخدامها في ملحقك

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

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

على الرغم من أن Firebase يقوم تلقائيًا بملء قيم المعلمات هذه للامتداد، إلا أن Firebase لا يوفر تلقائيًا المنتجات المرتبطة للمستخدم أثناء التثبيت . يجب على المستخدم الذي يقوم بتثبيت الامتداد تمكين المنتج (المنتجات) المرتبط والقابل للتطبيق في مشروعه قبل التثبيت. على سبيل المثال، إذا كان ملحقك يشتمل على Cloud Firestore، فيجب على المستخدم إعداد Cloud Firestore في مشروعه. نوصي بإعلام المستخدمين بهذه المتطلبات في ملف PREINSTALL.md .

المعلمات التي قام المستخدم بتكوينها

لتمكين المستخدم من تخصيص كل مثيل مثبت للامتداد، يمكنك أن تطلب من المستخدم تحديد قيم المعلمات أثناء التثبيت. لطلب هذه القيم، عليك إعداد المطالبات في قسم 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 الخاص بك، استخدم الحقول التالية لتحديد معلمة تم تكوينها بواسطة المستخدم:

options:
  - label:
    value:
  - label:
    value:
  - label:
    value:

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

عندما تقوم بإعداد معلمة type string ، فإنك تحتاج إلى تحديد التحقق المناسب من صحة التعبير العادي عبر حقل validationRegex المعلمة.

أيضًا، بالنسبة للعديد من الملحقات، فإن قيمة المعلمة المطلوبة بشكل شائع هي مسار قاعدة البيانات أو مجموعة التخزين السحابي. انتبه إلى أنه أثناء التثبيت أو إعادة التكوين أو التحديث، لا تتحقق خدمة الملحقات من صحة ما يلي في وقت إدخال قيمة المعلمة:

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

ومع ذلك، عندما يقوم الامتداد بنشر موارده فعليًا، ستعرض وحدة تحكم Firebase أو واجهة سطر أوامر Firebase رسالة خطأ إذا لم يتم إعداد قاعدة البيانات المرجعية أو مجموعة التخزين السحابي في المشروع بعد.

نوصي بشدة بإعلام المستخدمين في ملف 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

معلمات النظام المتاحة هي: