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

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

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

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

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

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

  • label (string): चुने जा सकने वाले विकल्प का छोटा ब्यौरा
  • value (string): चुनने लायक विकल्प की असल वैल्यू

options फ़ील्ड के लिए value फ़ील्ड की वैल्यू डालना ज़रूरी है.
अगर label को शामिल नहीं किया जाता है, तो सूची का विकल्प डिफ़ॉल्ट रूप से value के तौर पर दिखता है.
resourceType
(required if parameter type is selectResource) 		स्ट्रिंग

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

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

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

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

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

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

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

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

validationRegex के फ़ेल होने पर दिखने वाला गड़बड़ी का मैसेज

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

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

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

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

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

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

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

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

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

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

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

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

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