https.onCall के लिए प्रोटोकॉल से जुड़ी ज़रूरी शर्तें

Cloud फ़ंक्शन के लिए https.onCall ट्रिगर, यह एक खास फ़ॉर्मैट है. इस सेक्शन में क्लाइंट SDK टूल में इस्तेमाल किए जाने वाले एचटीटीपीएस अनुरोध और रिस्पॉन्स फ़ॉर्मैट के लिए खास जानकारी एपीआई लागू करने के लिए. अगर ज़रूरी हो, तो यह जानकारी आपके काम की हो सकती है को Android, Apple प्लैटफ़ॉर्म या वेब SDK टूल का इस्तेमाल करके पूरा नहीं किया जा सकता.

अनुरोध का फ़ॉर्मैट: हेडर

कॉल किए जा सकने वाले ट्रिगर एंडपॉइंट के लिए एचटीटीपी अनुरोध, POST नीचे दिए गए हेडर:

• ज़रूरी है: Content-Type: application/json
  • एक वैकल्पिक ; charset=utf-8 की अनुमति है.
• ज़रूरी नहीं: Authorization: Bearer <token>
  • अनुरोध करने वाले लॉग इन किए हुए उपयोगकर्ता के लिए, Firebase Authentication यूज़र आईडी टोकन. बैकएंड अपने-आप इस टोकन की पुष्टि करता है और इसे हैंडलर के context में उपलब्ध कराता है. अगर टोकन मान्य नहीं है, तो अनुरोध अस्वीकार कर दिया जाता है.
• ज़रूरी नहीं: Firebase-Instance-ID-Token: <iid>
  • Firebase क्लाइंट SDK टूल से मिला FCM रजिस्ट्रेशन टोकन. यह एक स्ट्रिंग होनी चाहिए. यह हैंडलर के context में उपलब्ध है. इसका इस्तेमाल पुश नोटिफ़िकेशन को टारगेट करने के लिए किया जाता है.
• ज़रूरी नहीं: X-Firebase-AppCheck: <token>
  • Firebase ऐप्लिकेशन चेक टोकन, जो क्लाइंट ऐप्लिकेशन से मिला है अनुरोध. बैकएंड अपने-आप इस टोकन की पुष्टि करता है और इसे डिकोड करता है, हैंडलर के context में appId को इंजेक्ट करना. अगर टोकन पुष्टि के बाद, अनुरोध अस्वीकार कर दिया जाता है. (SDK टूल >=3.14.0 के लिए उपलब्ध)

अगर जवाब देने के लिए नीचे दिए गए दस्तावेज़ में कोई और हेडर शामिल किया जाता है, तो अनुरोध को अस्वीकार कर दिया जाता है.

ध्यान दें: JavaScript क्लाइंट में, ये अनुरोध सीओआरएस OPTIONS प्रीफ़्लाइट को ट्रिगर करते हैं, क्योंकि:

• application/json की अनुमति नहीं है. यह text/plain या application/x-www-form-urlencoded होना चाहिए.
• Authorization हेडर, सीओआरएस-सुरक्षित सूची में शामिल किए गए अनुरोध का हेडर नहीं है.
• दूसरे हेडर की भी अनुमति नहीं है.

कॉल करने लायक ट्रिगर इन OPTIONS अनुरोधों को अपने-आप मैनेज करता है.

अनुरोध का मुख्य भाग

एचटीटीपी अनुरोध का मुख्य हिस्सा एक JSON ऑब्जेक्ट होना चाहिए, जिसमें इनमें से कोई भी फ़ील्ड हो:

• ज़रूरी है: data - फ़ंक्शन को दिया गया आर्ग्युमेंट. यह कोई भी मान्य JSON वैल्यू हो सकती है. नीचे बताए गए सीरियलाइज़ेशन फ़ॉर्मैट के मुताबिक, यह अपने-आप नेटिव JavaScript टाइप में डिकोड हो जाता है.

अगर अनुरोध में कोई और फ़ील्ड मौजूद है, तो बैकएंड अनुरोध में गड़बड़ी के तौर पर पहचान करता है और इसे अस्वीकार कर दिया जाता है.

जवाब का फ़ॉर्मैट: स्टेटस कोड

ऐसे कई मामले हैं जिनकी वजह से अलग-अलग एचटीटीपी स्टेटस कोड दिख सकते हैं और गड़बड़ी के लिए स्ट्रिंग स्थिति कोड डालें.

1. अगर client ट्रिगर शुरू होने से पहले एचटीटीपी गड़बड़ी होती है, तो रिस्पॉन्स को क्लाइंट फ़ंक्शन के तौर पर हैंडल नहीं किया जाता. उदाहरण के लिए, अगर कोई क्लाइंट ऐसे फ़ंक्शन को शुरू करने की कोशिश करता है जो मौजूद नहीं है, तो उसे 404 Not Found रिस्पॉन्स मिलता है.

2. अगर क्लाइंट ट्रिगर को शुरू किया जाता है, लेकिन अनुरोध गलत फ़ॉर्मैट में है, जैसे कि JSON नहीं होना, अमान्य फ़ील्ड होना या data फ़ील्ड मौजूद न होना, तो अनुरोध को 400 Bad Request के गड़बड़ी कोड के साथ INVALID_ARGUMENT से अस्वीकार कर दिया जाता है.

3. अगर अनुरोध में दिया गया ऑथराइज़ेशन टोकन अमान्य है, तो 401 Unauthorized का अनुरोध अस्वीकार कर दिया जाता है. साथ ही, गड़बड़ी का कोड UNAUTHENTICATED दिखता है.

4. अगर अनुरोध में दिया गया FCM रजिस्ट्रेशन टोकन अमान्य है, तो व्यवहार के बारे में नहीं बताया जाता. टोकन की जांच हर अनुरोध पर नहीं की जाती है. हालांकि, FCM के साथ पुश नोटिफ़िकेशन भेजने के लिए इसका इस्तेमाल किया जाता है.

5. अगर कॉल किए जा सकने वाले ट्रिगर को शुरू किया जाता है, लेकिन वह किसी बिना कार्रवाई के अपवाद के साथ काम नहीं करता है या प्रॉमिस फ़ेल होता है, तो अनुरोध को INTERNAL के गड़बड़ी कोड के साथ 500 Internal Server Error से अस्वीकार कर दिया जाता है. इससे कोडिंग से जुड़ी गड़बड़ियां, असली उपयोगकर्ताओं को गलती से नहीं दिखेंगी.

6. अगर कॉल किए जा सकने वाले फ़ंक्शन को शुरू किया जाता है और कॉल करने लायक फ़ंक्शन के लिए दिए गए एपीआई का इस्तेमाल करके, गड़बड़ी की साफ़ तौर पर जानकारी देता है, तो अनुरोध पूरा नहीं होता. आपको जो एचटीटीपी स्टेटस कोड मिला है वह code.proto के मुताबिक, गड़बड़ी की स्थिति और एचटीटीपी स्थिति की आधिकारिक मैपिंग पर आधारित है. गड़बड़ी के खास कोड, मैसेज, और दी गई जानकारी को जवाब के मुख्य हिस्से में एन्कोड किया जाता है. इस बारे में यहां जानकारी दी गई है. इसका मतलब है कि अगर फ़ंक्शन, स्टेटस OK के साथ साफ़ तौर पर गड़बड़ी दिखाता है, तो रिस्पॉन्स की स्थिति 200 OK होती है, लेकिन रिस्पॉन्स में error फ़ील्ड सेट होता है.

7. अगर क्लाइंट ट्रिगर कामयाब होता है, तो रिस्पॉन्स का स्टेटस 200 OK होगा.

रिस्पॉन्स का फ़ॉर्मैट: हेडर

रिस्पॉन्स में ये हेडर होते हैं:

• Content-Type: application/json
• एक वैकल्पिक ; charset=utf-8 की अनुमति है.

जवाब का लेख

क्लाइंट एंडपॉइंट से मिलने वाला रिस्पॉन्स हमेशा एक JSON ऑब्जेक्ट होता है. कम से कम यह इसमें result या error और कोई भी वैकल्पिक फ़ील्ड शामिल होता है. अगर रिस्पॉन्स, JSON ऑब्जेक्ट नहीं है या उसमें data या error शामिल नहीं है, क्लाइंट SDK टूल को अनुरोध 'स्वीकार नहीं किया जा सका' के तौर पर मानना चाहिए Google गड़बड़ी कोड INTERNAL (13) है.

• error - अगर यह फ़ील्ड मौजूद है, तो एचटीटीपी स्टेटस कोड या data भी मौजूद है या नहीं, इस पर ध्यान दिए बिना अनुरोध को पूरा नहीं किया जा सकता. गड़बड़ियों के लिए इस फ़ील्ड की वैल्यू, स्टैंडर्ड Google Cloud एचटीटीपी मैपिंग फ़ॉर्मैट में एक JSON ऑब्जेक्ट होना चाहिए. इसमें status, message, और (ज़रूरी नहीं) details के लिए फ़ील्ड मौजूद होने चाहिए. code फ़ील्ड को शामिल नहीं किया जाएगा. अगर status फ़ील्ड सेट नहीं है या इसकी वैल्यू अमान्य है, तो क्लाइंट को स्थिति को code.proto के मुताबिक INTERNAL के तौर पर मानना चाहिए. अगर details मौजूद है, तो इसे क्लाइंट SDK टूल में गड़बड़ी के साथ अटैच की गई किसी भी उपयोगकर्ता की जानकारी में शामिल किया जाता है.
  अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है ध्यान दें: यहां details फ़ील्ड, उपयोगकर्ता से मिला वैल्यू है. यह ज़रूरी नहीं है कि यह उन वैल्यू की सूची हो जिन्हें प्रोटो टाइप के हिसाब से सेट किया गया है, जैसा कि Google Status फ़ॉर्मैट में किया जाता है.
• result - फ़ंक्शन से दिया गया मान. यह कोई भी मान्य JSON वैल्यू हो सकती है. firebase-Functions SDK टूल, उपयोगकर्ता से मिली वैल्यू को इस JSON फ़ॉर्मैट में अपने-आप कोड में बदल देता है. क्लाइंट SDK टूल, नीचे बताए गए सीरियलाइज़ेशन फ़ॉर्मैट के मुताबिक, इन पैरामीटर को नेटिव टाइप में अपने-आप डिकोड कर देते हैं.

अगर अन्य फ़ील्ड मौजूद हैं, तो उन्हें अनदेखा कर दिया जाना चाहिए.

क्रम से लगाना

आर्बिट्रेरी डेटा पेलोड को क्रम में लगाने का फ़ॉर्मैट, अनुरोध और रिस्पॉन्स, दोनों के लिए एक जैसा होता है.

प्लैटफ़ॉर्म के सही तरीके से काम करने के लिए, इन्हें JSON में इस तरह एन्कोड किया जाता है जैसे कि ये स्टैंडर्ड JSON मैपिंग का इस्तेमाल करके, Proto3 प्रोटोकॉल बफ़र में मौजूद Any फ़ील्ड की वैल्यू हों. null, int, double या string जैसे सामान्य टाइप की वैल्यू को सीधे तौर पर कोड में बदला जाता है. इनमें, अश्लील वैल्यू को शामिल नहीं किया जाता. इसलिए, float और double को एक ही तरह से कोड में बदला जाता है और हो सकता है कि आपको यह पता न चले कि कॉल के आखिर में कौनसा मिला. जो टाइप JSON में शामिल नहीं हैं उनके लिए, वैल्यू के लिए टाइप किए गए प्रोटो3 एन्कोडिंग का इस्तेमाल किया जाता है. ज़्यादा जानकारी के लिए, JSON को कोड में बदलने का तरीका बताने वाला दस्तावेज़ देखें.

इन टाइप के विज्ञापनों की अनुमति है:

• खाली - null
• int (हस्ताक्षरित या अनसाइन किया गया, 32 बिट तक) - जैसे 3 या -30.
• फ़्लोट - उदाहरण 3.14 अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है
• डबल - जैसे कि 3.14 अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है
• बूलियन - true या false
• स्ट्रिंग - जैसे "hello world" अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है
• मैप<string, any=""> - जैसे {"x": 3}</string,>
• सूची - उदाहरण के लिए [1, 2, 3]
• लंबा (हस्ताक्षर किया गया या साइन नहीं किया गया, 64 बिट तक) - [विवरण के लिए नीचे देखें]

float और double के लिए NaN और Infinity वैल्यू का इस्तेमाल नहीं किया जा सकता.

ध्यान दें कि long एक खास टाइप है, जिसे आम तौर पर JSON में इस्तेमाल करने की अनुमति नहीं होती. हालांकि, इसके लिए Proto3 के स्पेसिफ़िकेशन लागू होते हैं. उदाहरण के लिए, इन्हें इस तरह कोड में बदला जाता है:

लंबा

{
    '@type': 'type.googleapis.com/google.protobuf.Int64Value',
    'value': '-123456789123456'
}

अनसाइन किया गया लंबा

{
    '@type': 'type.googleapis.com/google.protobuf.UInt64Value',
    'value': '123456789123456'
}

आम तौर पर, @type कुंजी को रिज़र्व माना जाना चाहिए. इसे पास किए गए मैप के लिए इस्तेमाल नहीं किया जाना चाहिए.

हालांकि, टाइप आसान टाइप के लिए नहीं बताया गया है, इसलिए तार के ऊपर से गुज़रने पर कुछ वैल्यू टाइप बदल जाएंगी. पास किया गया float, double बन जाता है. short, int बन जाता है और इसी तरह आगे चलता रहेगा. Android में, सूची की वैल्यू के लिए List और JSONArray, दोनों का इस्तेमाल किया जा सकता है. उन मामलों में, JSONArray में पास करने से List मिलेगा.

अगर किसी मैप में @type फ़ील्ड के बारे में जानकारी नहीं है, तो उसे डीसीरियलाइज़ (पार्स) किया जाता है, तो उसे मैप के तौर पर छोड़ दिया जाता है. इससे डेवलपर, पुराने क्लाइंट को मिटाए बिना, रिटर्न वैल्यू में नए टाइप वाले फ़ील्ड जोड़ सकते हैं.

कोड सैंपल

इस सेक्शन में दिए गए सैंपल में, इन्हें कोड में बदलने का तरीका बताया गया है:

• स्विफ़्ट में callable.call का उदाहरण
• कॉल के लिए सही रिस्पॉन्स
• कॉल के लिए कोई कार्रवाई नहीं की जा सकी

कोड में बदलने के लिए Swift में Callable.call का उदाहरण

callable.call([
    "aString": "some string",
    "anInt": 57,
    "aFloat": 1.23,
    "aLong": -123456789123456 as Int64
])

अनुरोध का हेडर:

Method: POST
Content-Type: application/json; charset=utf-8
Authorization: Bearer some-auth-token
Firebase-Instance-ID-Token: some-iid-token

अनुरोध का मुख्य हिस्सा:

{
    "data": {
        "aString": "some string",
        "anInt": 57,
        "aFloat": 1.23,
        "aLong": {
            "@type": "type.googleapis.com/google.protobuf.Int64Value",
            "value": "-123456789123456"
        }
    }
}

कोड में बदलने के लिए रिस्पॉन्स

return {
    "aString": "some string",
    "anInt": 57,
    "aFloat": 1.23
};

सफल रिस्पॉन्स हेडर:

200 OK
Content-Type: application/json; charset=utf-8

सही जवाब का मुख्य हिस्सा:

{
    "response": {
        "aString": "some string",
        "anInt": 57,
        "aFloat": 1.23
    }
}

कोड में बदलने में गड़बड़ी

throw new HttpsError("unauthenticated", "Request had invalid credentials.", {
  "some-key": "some-value"
});

प्रोसेस नहीं किया जा सकने वाला रिस्पॉन्स हेडर:

401 UNAUTHENTICATED
Content-Type: application/json; charset=utf-8

पूरे नहीं हो पाने वाले जवाब का मुख्य हिस्सा:

{
    "error": {
        "message": "Request had invalid credentials.",
        "status": "UNAUTHENTICATED",
        "details": {
            "some-key": "some-value"
        }
    }
}