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

Cloud Functions के लिए 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 App Check टोकन. बैकएंड, इस टोकन की पुष्टि अपने-आप करता है और इसे डिकोड करता है. साथ ही, हैंडलर के context में appId डालता है. अगर टोकन की पुष्टि नहीं की जा सकती, तो अनुरोध अस्वीकार कर दिया जाता है. (SDK के वर्शन >=3.14.0 के लिए उपलब्ध)

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

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

• application/json की अनुमति नहीं है. यह text/plain या application/x-www-form-urlencoded होना चाहिए.
• The 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. अगर कॉल किए जा सकने वाले ट्रिगर को शुरू किया जाता है, लेकिन उसे हैंडल नहीं की जा सकने वाली गड़बड़ी की वजह से शुरू नहीं किया जा सका या वह प्रॉमिस पूरा नहीं कर सका, तो अनुरोध को 500 Internal Server Error के साथ अस्वीकार कर दिया जाता है. इसके लिए, INTERNAL गड़बड़ी का कोड दिखाया जाता है. इससे, कोडिंग की गड़बड़ियों को असली उपयोगकर्ताओं के सामने आने से रोका जा सकता है.

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

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

एपिसोड क्रम से लगाने की सेटिंग

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

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

इन टाइप का इस्तेमाल किया जा सकता है:

• null - null
• int (साइन किया गया या साइन नहीं किया गया, 32 बिट तक) - जैसे, 3 या -30.
• float - जैसे, 3.14
• double - जैसे, 3.14
• boolean - true या false
• string - जैसे, "hello world"
• map<string, any=""> - जैसे, {"x": 3}</string,>
• list - जैसे, [1, 2, 3]
• long (साइन किया गया या साइन नहीं किया गया, 64 बिट तक) - [ज़्यादा जानकारी के लिए, नीचे देखें]

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

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

long

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

unsigned long

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

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

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

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

कोड सैंपल

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

• Swift में, 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"
        }
    }
}