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

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

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

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

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

• ज़रूरी है: Content-Type: application/json
  • ; charset=utf-8 का इस्तेमाल करना ज़रूरी नहीं है.
• ज़रूरी नहीं: Authorization: Bearer <token>
  • अनुरोध करने वाले ऐसे उपयोगकर्ता के लिए Firebase Authentication यूज़र आईडी टोकन जिसने लॉग इन किया है. बैकएंड, इस टोकन की अपने-आप पुष्टि करता है और इसे हैंडलर के context में उपलब्ध कराता है. अगर टोकन मान्य नहीं है, तो अनुरोध अस्वीकार कर दिया जाता है.
• ज़रूरी नहीं: Firebase-Instance-ID-Token: <iid>
  • यह Firebase client 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 होना चाहिए.
• Authorization हेडर, CORS-safelisted request-header नहीं है.
• इसी तरह, अन्य हेडर इस्तेमाल करने की अनुमति नहीं है.

कॉल किए जा सकने वाले ट्रिगर, इन 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 वाली गड़बड़ी दिखाता है, तो जवाब का स्टेटस OK होता है. हालांकि, जवाब में error फ़ील्ड सेट होता है.200 OK

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

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

सीरियलाइज़ेशन

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

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

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

• शून्य - null
• int (signed या unsigned, ज़्यादा से ज़्यादा 32 बिट) - उदाहरण के लिए, 3 या -30.
• फ़्लोट - उदाहरण के लिए, 3.14
• दोहरा - उदाहरण के लिए, 3.14
• बूलियन - true या false
• string - e.g. "hello world"
• map<string, any=""> - e.g. {"x": 3}</string,>
• list - e.g. [1, 2, 3]
• long (signed or unsigned, up to 64 bits) - [see below for details]

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 फ़ील्ड होता है, तो उसे मैप के तौर पर छोड़ दिया जाता है. इससे डेवलपर, पुराने क्लाइंट को बंद किए बिना, रिटर्न वैल्यू में नए टाइप वाले फ़ील्ड जोड़ सकते हैं.

कोड सैंपल

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

• 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"
        }
    }
}