راه‌اندازی و استفاده از پارامترها در افزونه

پارامترها سازوکاری هستند که کاربر ازطریق آن هر نمونه نصب‌شده از افزونه را سفارشی‌سازی می‌کند. پارامترها مانند متغیرهای محیطی برای یک افزونه هستند. مقادیر پارامترها می‌تواند خودکار درج شود (توسط 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	نشانی وب نمونه 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 استفاده می‌کنید، حتماً در فایل PREINSTALL خود مستند کنید که افزونه شما از Cloud Secret Manager استفاده می‌کند. اگر این فیلد حذف شود، پارامتر به‌طور پیش‌فرض روی type از string قرار می‌گیرد.
options (اگر پارامتر type select یا multiSelect باشد، الزامی است)	فهرست کردن	فهرست مقادیری که کاربر می‌تواند از بین آن‌ها انتخاب کند فیلدهای label و value را در فیلد options اضافه کنید: ‫label (رشته): شرح کوتاهی از گزینه قابل‌انتخاب ‫value (رشته): مقدار واقعی گزینه قابل‌انتخاب حتماً این رشته‌ها را در گیومه قرار دهید تا از تبدیل نوع ناخواسته جلوگیری شود. فیلد 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 تغییر می‌کند. توجه: اگر پارامتر «مکان» را برای عملکردهای مستقرشده افزونه‌تان تعریف کنید، باید این فیلد immutable را در شیء پارامتر آن بگنجانید.

اعتبارسنجی و پیام‌رسانی خطا برای مقادیر پیکربندی‌شده توسط کاربر

وقتی پارامتری را با type از string راه‌اندازی می‌کنید، باید اعتبارسنجی عبارت باقاعده مناسب را ازطریق فیلد validationRegex پارامتر تعریف کنید.

همچنین، برای بسیاری‌از افزونه‌ها، مقدار پارامتر درخواستی معمولاً مسیر پایگاه داده یا دسته Cloud Storage است. توجه داشته باشید که درطول نصب، پیکربندی مجدد، یا به‌روزرسانی، سرویس Extensions در زمان ورود مقدار پارامتر، موارد زیر را اعتبارسنجی نمی‌کند:

• اینکه پایگاه داده یا دسته Cloud Storage مشخص‌شده در پروژه Firebase کاربر راه‌اندازی شده است یا نه
• آیا مسیر پایگاه داده مشخص‌شده در پایگاه داده کاربر وجود دارد یا نه

بااین‌حال، وقتی افزونه درحال استقرار منابع خود است، اگر پایگاه داده یا دسته Cloud Storage ارجاع‌شده هنوز در پروژه راه‌اندازی نشده باشد، کنسول Firebase یا CLI 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

پارامترهای سیستم دردسترس عبارت‌اند از:

نام	برچسب (قابل‌فهم برای انسان)	فیلد مربوطه در properties	شرح
firebaseextensions.v1beta.function/location	مکان	location	Cloud Functions باید در کدام منطقه پیاده‌سازی شود؟
firebaseextensions.v1beta.function/memory	حافظه «تابع»	memory	چند مگابایت حافظه باید به هر تابع اختصاص داده شود؟
firebaseextensions.v1beta.function/timeoutSeconds	درنگ تابع سر رسید	timeout	توابع چند ثانیه باید اجرا شوند تا مهلتشان تمام شود؟
firebaseextensions.v1beta.function/vpcConnectorEgressSettings	VPC Connector Egress	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	برچسب‌هایی که باید روی همه منابع در افزونه اعمال شود