پارامترها را در برنامه افزودنی خود تنظیم و استفاده کنید

پارامترها مکانیزمی هستند که از طریق آن کاربر هر نمونه نصب شده یک برنامه افزودنی را سفارشی می کند. پارامترها مانند متغیرهای محیطی برای یک برنامه افزودنی هستند. مقادیر پارامترها می‌توانند به صورت خودکار (پس از نصب توسط 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 نشانی اینترنتی نمونه 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

معمولاً این مقدار همان ID پروژه است یا به -default-rtdb ختم می شود.

قالب تعمیم یافته:
project-id

مقدار مثال:
project-123

STORAGE_BUCKET نام پیش‌فرض سطل فضای ذخیره‌سازی ابری پروژه 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
(اختیاری)
رشته

توضیحات دقیق برای پارامتر

هنگامی که از کاربر برای مقدار پارامتر خواسته می شود به کاربر نمایش داده می شود

از نشانه گذاری پشتیبانی می کند

type
(اختیاری)
رشته

مکانیزم ورودی برای نحوه تنظیم مقدار پارامتر توسط کاربر (به عنوان مثال، متن را مستقیما وارد کنید یا از لیست کشویی انتخاب کنید)

مقادیر معتبر شامل موارد زیر است:

  • string : اجازه ورود متن آزاد را می دهد (که توسط validationRegex شما محدود شده است)
  • select : امکان انتخاب یک ورودی از لیست از پیش تعریف شده گزینه ها را فراهم می کند. اگر این مقدار را مشخص کنید، باید فیلد options را نیز تعریف کنید.
  • multiSelect : امکان انتخاب یک یا چند ورودی را از یک لیست از پیش تعریف شده از گزینه ها فراهم می کند. اگر این مقدار را مشخص کنید، باید فیلد options را نیز تعریف کنید.
  • selectResource : امکان انتخاب نوع خاصی از منبع Firebase (مانند سطل Cloud Storage ) از پروژه کاربر را فراهم می کند.

    هنگامی که پارامتری از این نوع را مشخص می کنید، کاربران ویجت انتخاب کاربر پسندتری را در رابط کاربری نصب دریافت می کنند. به همین دلیل، در صورت امکان از پارامترهای selectResource استفاده کنید.

    اگر این مقدار را مشخص کنید، باید قسمت resourceType را نیز تعریف کنید.

  • secret : امکان ذخیره رشته های حساس مانند کلیدهای API برای سرویس های شخص ثالث را فراهم می کند. این مقادیر در Cloud Secret Manager ذخیره خواهند شد.

    Cloud Secret Manager یک سرویس پولی است که استفاده از آن ممکن است برای کاربرانی که برنامه افزودنی شما را نصب می‌کنند هزینه‌هایی ایجاد کند. اگر از نوع پارامتر secret استفاده می‌کنید، حتماً در فایل PREINSTALL خود مستند کنید که پسوند شما از Cloud Secret Manager استفاده می‌کند.

اگر این فیلد حذف شود، پارامتر به طور پیش‌فرض روی type string تنظیم می‌شود.

options
(الزامی است اگر type پارامتر select یا multiSelect باشد)
فهرست

لیست مقادیری که کاربر می تواند از بین آنها انتخاب کند

فیلدهای label و value را در فیلد options قرار دهید:

  • label (string) : شرح کوتاهی از گزینه قابل انتخاب
  • value (رشته) : مقدار واقعی گزینه قابل انتخاب

فیلد value برای فیلد options لازم است.
اگر label حذف شود، گزینه لیست به طور پیش فرض value را نمایش می دهد.

resourceType
(اگر type پارامتر selectResource باشد، لازم است)
رشته

نوع منبع Firebase که کاربر را وادار به انتخاب می کند. در حال حاضر، فقط سطل‌های Cloud Storage از انتخابگرهای منبع پشتیبانی می‌کنند:

نوع منبع شناسه را تایپ کنید
سطل Cloud Storage storage.googleapis.com/Bucket

مقادیر ناشناخته resourceType نادیده گرفته می شود و UI پارامتر را به عنوان یک فیلد ورودی string آزاد ارائه می کند.

example
(اختیاری)
رشته

مقدار مثال برای پارامتر

validationRegex
(اختیاری)
(فقط زمانی قابل اجراست که type پارامتر string باشد)
رشته

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

Regex با استفاده از کتابخانه go کامپایل شده است: RE2

برای جزئیات در مورد اعتبارسنجی، به اعتبارسنجی و پیام خطا در زیر مراجعه کنید.

validationErrorMessage
(اختیاری)
رشته

پیام خطا برای نمایش در صورت عدم موفقیت validationRegex

برای جزئیات بیشتر در مورد پیام‌رسانی خطا، به اعتبارسنجی و پیام‌رسانی خطا در زیر مراجعه کنید.

default
(اختیاری)
رشته

اگر کاربر مقدار پارامتر را خالی بگذارد، مقدار پیش‌فرض برای پارامتر

در صورت امکان، می‌توانید یک مقدار پارامتری که به صورت خودکار تکمیل می‌شود را برای مقدار default تعیین کنید (به عنوان مثال، به پارامتر IMG_BUCKET در پسوند تغییر اندازه تصاویر مراجعه کنید).

required
(اختیاری)
بولی

تعیین می کند که آیا کاربر می تواند یک رشته خالی را زمانی که از او برای مقدار پارامتر خواسته می شود ارسال کند یا خیر

اگر required حذف شود، این مقدار به طور پیش‌فرض روی true می‌شود (یعنی یک پارامتر ضروری).

immutable
(اختیاری)
بولی

تعیین می کند که آیا کاربر می تواند مقدار پارامتر را پس از نصب تغییر دهد (به عنوان مثال، اگر برنامه افزودنی را دوباره پیکربندی کند )

اگر immutable حذف شود، این مقدار به طور پیش فرض روی false قرار می گیرد.

توجه: اگر یک پارامتر "مکان" را برای توابع مستقر در برنامه افزودنی خود تعریف کنید، باید این فیلد immutable را در شی param آن قرار دهید.

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

هنگامی که پارامتری را با type string تنظیم می کنید، باید اعتبار سنجی regex مناسب را از طریق قسمت validationRegex پارامتر تعریف کنید.

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

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

با این حال، هنگامی که برنامه افزودنی واقعاً منابع خود را مستقر می کند، کنسول Firebase یا 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 توابع ابری باید در چه منطقه ای مستقر شوند؟
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 برچسب هایی برای اعمال به همه منابع موجود در برنامه افزودنی