المَعلمات هي الآلية التي يخصّص من خلالها المستخدم كل نسخة مثبّتة من الإضافة. المَعلمات تشبه متغيّرات البيئة للإضافة. يمكن أن تكون قيم المَعلمات إما تتم تعبئتها تلقائيًا (يوفّرها 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 التلقائية) أو تكون خاصة بالإضافة (مثل رقم تعريف مثيل الإضافة).
جميع قيم المَعلمات التي تتم تعبئتها تلقائيًا غير قابلة للتغيير. ويتم ضبطها في وقت إنشاء المشروع أو تثبيت الإضافة.
على الرغم من أنّ Firebase يملأ قيم المَعلمات هذه تلقائيًا للإضافة،
لا يوفّر Firebase المنتجات المرتبطة تلقائيًا للمستخدم أثناء
التثبيت. على المستخدم الذي يثبّت الإضافة تفعيل المنتجات المرتبطة
والمطبَّقة في مشروعه قبل التثبيت. على سبيل المثال، إذا كانت الإضافة تتضمّن Cloud Firestore، على المستخدم إعداد Cloud Firestore في مشروعه. ننصحك بإعلام المستخدمين بهذه المتطلبات في ملف PREINSTALL.md.
| مرجع للمَعلمة التي تتم تعبئتها تلقائيًا | الوصف | قيمة المَعلمة (التي توفّرها Firebase) |
|---|---|---|
| المَعلمات ذات القيم التلقائية من مشروع Firebase | ||
PROJECT_ID |
المعرّف الفريد لمشروع Firebase الذي تم تثبيت الإضافة فيه |
التنسيق العام:
مثال على القيمة: |
DATABASE_URL |
عنوان URL التلقائي لمثيل Realtime Database في مشروع Firebase |
التنسيق العام:
مثال على القيمة: |
DATABASE_INSTANCE |
اسم مثيل Realtime Database التلقائي لمشروع Firebase عادةً ما تكون هذه القيمة مماثلة لرقم تعريف المشروع أو تنتهي بـ |
التنسيق العام:
مثال على القيمة: |
STORAGE_BUCKET |
اسم حزمة Cloud Storage التلقائية لمشروع Firebase |
التنسيق العام:
مثال على القيمة: |
| مَعلمة ذات قيمة تلقائية من عملية تثبيت الإضافة | ||
EXT_INSTANCE_ID |
المعرّف الفريد لنسخة الإضافة المثبّتة يتم إنشاء هذه القيمة من الحقل
|
التنسيق العام لأول نسخة مثبَّتة (يتم تخصيصه تلقائيًا
من خلال Firebase، ولا يمكن للمستخدم تعديله أثناء التثبيت):
مثال على القيمة: التنسيق العام للنسخة الثانية المثبَّتة وما فوقها
(يتم تخصيصه تلقائيًا من خلال Firebase، ويمكن للمستخدم تعديله
أثناء التثبيت):
مثال على القيمة: |
المَعلمات التي يضبطها المستخدم
للسماح للمستخدم بتخصيص كل نسخة مثبَّتة من الإضافة، يمكنك
طلب تحديد قيم المَعلمات من المستخدم أثناء التثبيت. لطلب هذه القيم، يمكنك إعداد الطلبات في قسم 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(اختياري) |
سلسلة |
آلية الإدخال التي يحدّد المستخدم من خلالها قيمة المَعلمة (على سبيل المثال، إدخال النص مباشرةً أو الاختيار من قائمة منسدلة) تشمل القيم الصالحة ما يلي:
في حال حذف هذا الحقل، يتم ضبط المَعلمة تلقائيًا على |
||||
options(مطلوبة إذا كانت المَعلمة type
هي select أو multiSelect)
|
القائمة |
قائمة بالقيم التي يمكن للمستخدم الاختيار من بينها أدرِج الحقلَين
يجب ملء حقل |
||||
resourceType(مطلوبة إذا كانت المَعلمة type
هي selectResource)
|
سلسلة |
نوع مورد Firebase الذي سيُطلب من المستخدم اختياره. في الوقت الحالي، لا تتيح سوى حِزم Cloud Storage استخدام أدوات اختيار الموارد:
سيتم تجاهل قيم |
||||
example(اختياري) |
سلسلة |
مثال على قيمة المَعلمة |
||||
validationRegex(اختياري) (ينطبق فقط عندما تكون المَعلمة type
string)
|
سلسلة |
سلسلة تعبير نمطي للتحقّق من صحة القيمة التي ضبطها المستخدم للمَعلمة يتم تجميع التعبير النمطي باستخدام مكتبة go: RE2 للاطّلاع على تفاصيل حول التحقّق من الصحة، يُرجى الرجوع إلى قسم التحقّق من الصحة ورسائل الخطأ أدناه. |
||||
validationErrorMessage(اختياري) |
سلسلة |
رسالة الخطأ التي تظهر في حال تعذُّر
للحصول على تفاصيل حول رسائل الخطأ، يُرجى الرجوع إلى قسم التحقّق من الصحة ورسائل الخطأ أدناه. |
||||
default(اختياري) |
سلسلة |
القيمة التلقائية للمَعلمة إذا ترك المستخدم قيمة المَعلمة فارغة يمكنك تحديد قيمة مَعلمة تتم تعبئتها تلقائيًا للقيمة |
||||
required(اختياري) |
قيمة منطقية |
تحدّد ما إذا كان بإمكان المستخدم إرسال سلسلة فارغة عندما يُطلب منه إدخال قيمة المَعلمة في حال حذف السمة |
||||
immutable(اختياري) |
قيمة منطقية |
تحدّد ما إذا كان بإمكان المستخدم تغيير قيمة المَعلمة بعد التثبيت (على سبيل المثال، في حال إعادة ضبط الإضافة) في حال حذف السمة
ملاحظة: إذا حدّدت
مَعلمة "location"
للدوال المنشورة في إضافتك،
عليك تضمين حقل |
التحقّق من صحة القيم التي ضبطها المستخدم ورسائل الخطأ
عند إعداد مَعلمة باستخدام 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 | vpcConnector |
يربط Cloud Functions بموصِّل VPC محدّد. |
| firebaseextensions.v1beta.function/minInstances | الحد الأدنى لعدد مثيلات الدوال | minInstances |
الحدّ الأدنى لعدد نُسخ هذه الدالة التي يتم تشغيلها في آنٍ واحد |
| firebaseextensions.v1beta.function/maxInstances | الحد الأقصى لعدد نُسخ الدالة | maxInstances |
الحدّ الأقصى لعدد نُسخ هذه الدالة التي يمكن تشغيلها في الوقت نفسه |
| firebaseextensions.v1beta.function/ingressSettings | إعدادات الدخول | ingressSettings |
يتحكّم في مصادر الزيارات الواردة التي يتم قبولها |
| firebaseextensions.v1beta.function/labels | التصنيفات | labels |
التصنيفات التي سيتم تطبيقها على جميع الموارد في الإضافة |