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

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

مرجع للمَعلمة التي تتم تعبئتها تلقائيًا الوصف قيمة المَعلمة (التي يوفّرها Firebase)
المَعلمات ذات القيم التلقائية من مشروع Firebase
PROJECT_ID المعرّف الفريد لمشروع Firebase الذي تظهر فيه الإضافة تم التثبيت

تنسيق عام:
project-id

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

DATABASE_URL عنوان URL لمثيل قاعدة البيانات في الوقت الفعلي التلقائي لمشروع 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

اسم مثيل قاعدة البيانات التلقائية لقاعدة البيانات في الوقت الفعلي لمشروع 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
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

ملاحظة: إذا حددت "الموقع الجغرافي" للدوال المنشورة لإضافتك، يجب تضمين الحقل immutable هذا في مَعلمته الخاص بك.

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

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

وبالنسبة إلى العديد من الإضافات، غالبًا ما تكون قيمة المعلَمة، وهي قاعدة بيانات. أو حزمة Cloud Storage. اعلم أنه أثناء التثبيت أو إعادة الضبط أو ، فإن خدمة "الإضافات" لا تتحقَّق مما يلي في وقت إدخال قيمة المَعلمة:

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