https.onCall . के लिए प्रोटोकॉल विनिर्देश

क्लाउड फ़ंक्शंस के लिए https.onCall ट्रिगर अनुरोध और प्रतिक्रिया के लिए एक विशिष्ट प्रारूप के साथ एक HTTPS ट्रिगर है। यह अनुभाग एपीआई को लागू करने के लिए क्लाइंट एसडीके द्वारा उपयोग किए जाने वाले HTTPS अनुरोध और प्रतिक्रिया प्रारूपों के लिए एक विनिर्देश प्रदान करता है। यदि आपकी आवश्यकताएँ Android, Apple प्लेटफ़ॉर्म या वेब SDK का उपयोग करके पूरी नहीं की जा सकती हैं तो यह जानकारी आपके लिए उपयोगी हो सकती है।

अनुरोध प्रारूप: हेडर

कॉल करने योग्य ट्रिगर एंडपॉइंट के लिए HTTP अनुरोध निम्नलिखित हेडर के साथ एक POST होना चाहिए:

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

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

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

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

कॉल करने योग्य ट्रिगर स्वचालित रूप से इन OPTIONS अनुरोधों को संभालता है।

निकाय से अनुरोध करें

HTTP अनुरोध का मुख्य भाग निम्नलिखित में से किसी भी फ़ील्ड के साथ एक JSON ऑब्जेक्ट होना चाहिए:

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

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

प्रतिक्रिया प्रारूप: स्थिति कोड

ऐसे कई मामले हैं जिनके परिणामस्वरूप प्रतिक्रिया में त्रुटियों के लिए अलग-अलग HTTP स्थिति कोड और स्ट्रिंग स्थिति कोड हो सकते हैं।

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

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

3. यदि अनुरोध में प्रदान किया गया प्रमाणीकरण टोकन अमान्य है, तो अनुरोध को 401 Unauthorized के साथ UNAUTHENTICATED के त्रुटि कोड के साथ अस्वीकार कर दिया जाता है।

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

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

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

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

क्रमबद्धता

मनमाने डेटा पेलोड के लिए क्रमांकन प्रारूप अनुरोध और प्रतिक्रिया दोनों के लिए समान है।

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

निम्नलिखित प्रकारों की अनुमति है:

• शून्य - null
• int (हस्ताक्षरित या अहस्ताक्षरित, 32 बिट तक) - उदाहरण के लिए 3 या -30 ।
• फ्लोट - उदाहरण के लिए 3.14
• डबल - उदाहरण के लिए 3.14
• बूलियन - true या false
• स्ट्रिंग - उदाहरण के लिए "hello world"
• नक्शा - जैसे {"x": 3}
• सूची - जैसे [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 बन जाता है, इत्यादि। एंड्रॉइड में, सूची मानों के लिए List और JSONArray दोनों समर्थित हैं। उन मामलों में, JSONArray में पास करने से एक List प्राप्त होगी।

यदि किसी अज्ञात @type फ़ील्ड वाले मानचित्र को डीसेरिएलाइज़ किया जाता है, तो इसे मानचित्र के रूप में छोड़ दिया जाता है। यह डेवलपर्स को पुराने क्लाइंट को तोड़े बिना अपने रिटर्न वैल्यू में नए प्रकार के फ़ील्ड जोड़ने की अनुमति देता है।

कोड नमूने

इस अनुभाग के नमूने बताते हैं कि निम्नलिखित को कैसे एन्कोड किया जाए:

• स्विफ्ट में एक कॉल करने योग्य.कॉल उदाहरण
• कॉल के लिए एक सफल प्रतिक्रिया
• कॉल के लिए विफलता प्रतिक्रिया

एन्कोड करने के लिए स्विफ्ट में 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"
        }
    }
}