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

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

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

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

पहले इंस्टॉल किए गए इंस्टेंस के लिए सामान्य फ़ॉर्मैट (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 है) 		सूची

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

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

  • label (स्ट्रिंग): चुने जा सकने वाले विकल्प के बारे में, कम शब्दों में जानकारी

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

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

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

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

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

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

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

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

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

अगर validationRegex काम नहीं करता है, तो गड़बड़ी का मैसेज दिखाया जाता है

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

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

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

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

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

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

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

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

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

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

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

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

जब 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 एक्सटेंशन में मौजूद सभी रिसॉर्स पर लागू किए जाने वाले लेबल