अपने एक्सटेंशन में पैरामीटर सेट अप और उनका इस्तेमाल करना

पैरामीटर एक ऐसा तरीका है जिससे उपयोगकर्ता, इंस्टॉल किए गए एक्सटेंशन के हर इंस्टेंस को अपनी ज़रूरत के मुताबिक बना सकता है. पैरामीटर, किसी एक्सटेंशन के लिए एनवायरमेंट वैरिएबल की तरह होते हैं. पैरामीटर की वैल्यू, अपने-आप भरी जा सकती हैं (इंस्टॉल करने के बाद, 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 Firebase प्रोजेक्ट का डिफ़ॉल्ट Realtime Database इंस्टेंस यूआरएल

सामान्य फ़ॉर्मैट:
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 प्रोजेक्ट के डिफ़ॉल्ट Realtime Database इंस्टेंस का नाम

आम तौर पर, यह वैल्यू प्रोजेक्ट आईडी जैसी ही होती है या -default-rtdb पर खत्म होती है.

सामान्य फ़ॉर्मैट:
project-id

वैल्यू का उदाहरण:
project-123

STORAGE_BUCKET Firebase प्रोजेक्ट के डिफ़ॉल्ट Cloud Storage बकेट का नाम

सामान्य फ़ॉर्मैट:
PROJECT_ID.firebasestorage.app

वैल्यू का उदाहरण:
project-123.firebasestorage.app

एक्सटेंशन इंस्टॉल करने के बाद, डिफ़ॉल्ट वैल्यू वाला पैरामीटर
EXT_INSTANCE_ID

इंस्टॉल किए गए एक्सटेंशन इंस्टेंस के लिए यूनीक आइडेंटिफ़ायर

यह वैल्यू, extension.yaml फ़ाइल में दिए गए name फ़ील्ड से जनरेट होती है.

पहली बार इंस्टॉल किए गए इंस्टेंस के लिए सामान्य फ़ॉर्मैट (Firebase इसे अपने-आप असाइन करता है. इंस्टॉल करने के दौरान, उपयोगकर्ता इसमें बदलाव नहीं कर सकता):
name-from-extension.yaml

वैल्यू का उदाहरण:
my-awesome-extension


दूसरी बार इंस्टॉल किए गए इंस्टेंस और उसके बाद के इंस्टेंस के लिए सामान्य फ़ॉर्मैट (Firebase अपने-आप असाइन करता है; इंस्टॉलेशन के दौरान उपयोगकर्ता इसमें बदलाव कर सकते हैं):
name-from-extension.yaml-4-digit-alphanumeric-hash

वैल्यू का उदाहरण:
my-awesome-extension-6m31

उपयोगकर्ता के कॉन्फ़िगर किए गए पैरामीटर

अगर आपको किसी उपयोगकर्ता को इंस्टॉल किए गए एक्सटेंशन के हर इंस्टेंस को पसंद के मुताबिक बनाने की सुविधा देनी है, तो इंस्टॉलेशन के दौरान उपयोगकर्ता से पैरामीटर वैल्यू तय करने के लिए कहें. इन वैल्यू का अनुरोध करने के लिए, अपनी extension.yaml फ़ाइल के params सेक्शन में प्रॉम्प्ट सेट अप करें.

यहां उदाहरण के तौर पर 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

अपनी extension.yaml फ़ाइल के params सेक्शन में, उपयोगकर्ता के कॉन्फ़िगर किए गए पैरामीटर को तय करने के लिए, इन फ़ील्ड का इस्तेमाल करें:

फ़ील्ड टाइप ब्यौरा
param
(ज़रूरी है)
स्ट्रिंग पैरामीटर का नाम
label
(ज़रूरी है)
स्ट्रिंग

पैरामीटर के बारे में कम शब्दों में जानकारी

यह उपयोगकर्ता को तब दिखता है, जब उससे पैरामीटर की वैल्यू मांगी जाती है

description
(ज़रूरी नहीं)
स्ट्रिंग

पैरामीटर की पूरी जानकारी

यह उपयोगकर्ता को तब दिखता है, जब उससे पैरामीटर की वैल्यू मांगी जाती है

मार्कडाउन का इस्तेमाल किया जा सकता है

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 का इस्तेमाल करता है.

अगर इस फ़ील्ड को शामिल नहीं किया जाता है, तो पैरामीटर डिफ़ॉल्ट रूप से string के type पर सेट हो जाता है.

options
(अगर पैरामीटर type select या multiSelect है, तो ज़रूरी है)
सूची

वैल्यू की सूची, जिसमें से उपयोगकर्ता चुन सकता है

options फ़ील्ड में, label और value फ़ील्ड शामिल करें:

  • label (string): चुने जा सकने वाले विकल्प के बारे में कम शब्दों में जानकारी
  • value (string): चुने जा सकने वाले विकल्प की असल वैल्यू.

options फ़ील्ड के लिए, value फ़ील्ड भरना ज़रूरी है.
अगर label को शामिल नहीं किया जाता है, तो सूची का विकल्प डिफ़ॉल्ट रूप से value को दिखाता है.

resourceType
(अगर पैरामीटर type selectResource है, तो ज़रूरी है)
स्ट्रिंग

Firebase के उस संसाधन का टाइप जिसे चुनने के लिए उपयोगकर्ता को कहा जाएगा. फ़िलहाल, सिर्फ़ Cloud Storage बकेट में संसाधन सिलेक्टर काम करते हैं:

रिसॉर्स के टाइप आईडी टाइप करें
Cloud Storage बकेट storage.googleapis.com/Bucket

resourceType की ऐसी वैल्यू को अनदेखा कर दिया जाएगा जिनकी जानकारी नहीं है. साथ ही, यूज़र इंटरफ़ेस (यूआई) पैरामीटर को फ़्री-फ़ॉर्म string इनपुट फ़ील्ड के तौर पर रेंडर करेगा.

example
(ज़रूरी नहीं)
स्ट्रिंग

पैरामीटर के लिए वैल्यू का उदाहरण

validationRegex
(ज़रूरी नहीं)
(सिर्फ़ तब लागू होता है, जब पैरामीटर type की वैल्यू string हो)
स्ट्रिंग

पैरामीटर की उपयोगकर्ता की ओर से कॉन्फ़िगर की गई वैल्यू की पुष्टि करने के लिए, रेगुलर एक्सप्रेशन स्ट्रिंग

Regex को go लाइब्रेरी: RE2 का इस्तेमाल करके कंपाइल किया जाता है

पुष्टि करने के बारे में ज़्यादा जानने के लिए, यहां दिए गए पुष्टि करना और गड़बड़ी का मैसेज सेक्शन देखें.

validationErrorMessage
(ज़रूरी नहीं)
स्ट्रिंग

validationRegex के काम न करने पर, गड़बड़ी का मैसेज दिखेगा

गड़बड़ी के मैसेज के बारे में ज़्यादा जानने के लिए, यहां दिए गए पुष्टि और गड़बड़ी के मैसेज सेक्शन को देखें.

default
(ज़रूरी नहीं)
स्ट्रिंग

अगर उपयोगकर्ता पैरामीटर की वैल्यू को खाली छोड़ देता है, तो पैरामीटर के लिए डिफ़ॉल्ट वैल्यू

अगर लागू हो, तो default वैल्यू के लिए, अपने-आप भरी जाने वाली पैरामीटर वैल्यू तय की जा सकती है. उदाहरण के लिए, इमेज का साइज़ बदलें एक्सटेंशन का IMG_BUCKET पैरामीटर देखें.

required
(ज़रूरी नहीं)
बूलियन

इससे यह तय होता है कि पैरामीटर की वैल्यू के लिए प्रॉम्प्ट मिलने पर, उपयोगकर्ता खाली स्ट्रिंग सबमिट कर सकता है या नहीं

अगर required को शामिल नहीं किया जाता है, तो यह वैल्यू डिफ़ॉल्ट रूप से true (यानी कि ज़रूरी पैरामीटर) पर सेट हो जाती है.

immutable
(ज़रूरी नहीं)
बूलियन

इससे यह तय होता है कि उपयोगकर्ता, एक्सटेंशन इंस्टॉल करने के बाद पैरामीटर की वैल्यू बदल सकता है या नहीं. उदाहरण के लिए, अगर वह एक्सटेंशन को फिर से कॉन्फ़िगर करता है

अगर immutable को शामिल नहीं किया जाता है, तो यह वैल्यू डिफ़ॉल्ट रूप से false पर सेट हो जाती है.

ध्यान दें: अगर आपने एक्सटेंशन के डिप्लॉय किए गए फ़ंक्शन के लिए, "location" पैरामीटर तय किया है, तो आपको इस immutable फ़ील्ड को इसके param ऑब्जेक्ट में शामिल करना चाहिए.

उपयोगकर्ता की ओर से कॉन्फ़िगर की गई वैल्यू के लिए, पुष्टि और गड़बड़ी का मैसेज

string के type के साथ पैरामीटर सेट अप करते समय, आपको पैरामीटर के validationRegex फ़ील्ड की मदद से, सही रेगुलर एक्सप्रेशन की पुष्टि करनी होगी.

इसके अलावा, कई एक्सटेंशन के लिए, आम तौर पर अनुरोध की जाने वाली पैरामीटर वैल्यू, डेटाबेस पाथ या Cloud Storage बकेट होती है. ध्यान रखें कि इंस्टॉल, फिर से कॉन्फ़िगर या अपडेट करने के दौरान, Extensions सेवा, पैरामीटर वैल्यू डालते समय इनकी पुष्टि नहीं करती:

  • क्या उपयोगकर्ता के Firebase प्रोजेक्ट में, तय किया गया डेटाबेस या Cloud Storage बकेट सेट अप किया गया है
  • क्या उपयोगकर्ता के डेटाबेस में, बताया गया डेटाबेस पाथ मौजूद है

हालांकि, जब एक्सटेंशन अपने संसाधनों को डिप्लॉय कर रहा होता है, तब 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 वीपीसी कनेक्टर इग्रेस vpcConnectorEgressSettings वीपीसी कनेक्टर कॉन्फ़िगर होने पर, आउटगोइंग ट्रैफ़िक को कंट्रोल करता है
firebaseextensions.v1beta.function/vpcConnector वीपीसी कनेक्टर vpcConnector यह Cloud Functions को तय किए गए वीपीसी कनेक्टर से कनेक्ट करता है.
firebaseextensions.v1beta.function/minInstances फ़ंक्शन के कम से कम इंस्टेंस minInstances एक बार में इस फ़ंक्शन के इंस्टेंस की कम से कम संख्या
firebaseextensions.v1beta.function/maxInstances फ़ंक्शन के ज़्यादा से ज़्यादा इंस्टेंस maxInstances इस फ़ंक्शन के इंस्टेंस की ज़्यादा से ज़्यादा संख्या, जिन्हें एक साथ चलाया जा सकता है
firebaseextensions.v1beta.function/ingressSettings इन्ग्रेस डेटा ट्रैफ़िक की सेटिंग ingressSettings इससे यह कंट्रोल होता है कि इनकमिंग ट्रैफ़िक कहां से स्वीकार किया जाए
firebaseextensions.v1beta.function/labels लेबल labels एक्सटेंशन में मौजूद सभी संसाधनों पर लागू किए जाने वाले लेबल