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

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

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

एक्सटेंशन इंस्टॉलेशन से मिली डिफ़ॉल्ट वैल्यू वाला पैरामीटर
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 (स्ट्रिंग): चुने जा सकने वाले विकल्प के बारे में कम शब्दों में जानकारी
  • value (स्ट्रिंग): चुने जा सकने वाले विकल्प की असल वैल्यू

options फ़ील्ड के लिए 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 पर सेट हो जाती है.

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

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

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

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

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

हालांकि, जब एक्सटेंशन अपने संसाधनों को डिप्लॉय कर रहा होता है, तो अगर प्रोजेक्ट में रेफ़रंस वाला डेटाबेस या Cloud Storage बकेट अब तक सेट अप नहीं किया गया है, तो Firebase कंसोल या Firebase CLI गड़बड़ी का मैसेज दिखाएगा.

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