https.onCall এর জন্য প্রোটোকল স্পেসিফিকেশন

ক্লাউড ফাংশনের জন্য একটি https.onCall ট্রিগার হলো একটি HTTPS ট্রিগার, যার অনুরোধ এবং প্রতিক্রিয়ার জন্য একটি নির্দিষ্ট ফরম্যাট রয়েছে। এই বিভাগে ক্লায়েন্ট SDK-গুলো দ্বারা API বাস্তবায়নের জন্য ব্যবহৃত HTTPS অনুরোধ এবং প্রতিক্রিয়া ফরম্যাটের বিবরণ দেওয়া হয়েছে। যদি অ্যান্ড্রয়েড, অ্যাপল প্ল্যাটফর্ম বা ওয়েব SDK ব্যবহার করে আপনার প্রয়োজনীয়তা পূরণ করা না যায়, তবে এই তথ্যটি আপনার জন্য সহায়ক হতে পারে।

অনুরোধের বিন্যাস: হেডার

কলযোগ্য ট্রিগার এন্ডপয়েন্টে পাঠানো HTTP অনুরোধটি অবশ্যই একটি POST হতে হবে এবং এতে নিম্নলিখিত হেডারগুলো অন্তর্ভুক্ত থাকতে হবে:

• প্রয়োজনীয়: Content-Type: application/json
  • ঐচ্ছিকভাবে সেমিকোলন ; charset=utf-8 যোগ করা যাবে।
• ঐচ্ছিক: Authorization: Bearer <token>
  • অনুরোধকারী লগ-ইন করা ব্যবহারকারীর জন্য একটি Firebase Authentication ইউজার আইডি টোকেন। ব্যাকএন্ড স্বয়ংক্রিয়ভাবে এই টোকেনটি যাচাই করে এবং হ্যান্ডলারের context এটি উপলব্ধ করে। টোকেনটি বৈধ না হলে, অনুরোধটি প্রত্যাখ্যান করা হয়।
• ঐচ্ছিক: Firebase-Instance-ID-Token: <iid>
  • ফায়ারবেস ক্লায়েন্ট SDK থেকে প্রাপ্ত FCM রেজিস্ট্রেশন টোকেন। এটি অবশ্যই একটি স্ট্রিং হতে হবে। এটি হ্যান্ডলারের context পাওয়া যায়। এটি পুশ নোটিফিকেশন টার্গেট করার জন্য ব্যবহৃত হয়।
• ঐচ্ছিক: X-Firebase-AppCheck: <token>
  • অনুরোধকারী ক্লায়েন্ট অ্যাপ দ্বারা প্রদত্ত ফায়ারবেস অ্যাপ চেক টোকেন। ব্যাকএন্ড স্বয়ংক্রিয়ভাবে এই টোকেনটি যাচাই ও ডিকোড করে এবং হ্যান্ডলারের context appId যুক্ত করে। যদি টোকেনটি যাচাই করা না যায়, তবে অনুরোধটি প্রত্যাখ্যান করা হয়। (SDK >=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 ফিল্ড অনুপস্থিত থাকলে, অনুরোধটি 400 Bad Request ত্রুটিসহ INVALID_ARGUMENT এরর কোড দিয়ে প্রত্যাখ্যান করা হয়।

3. অনুরোধে প্রদত্ত অথ টোকেনটি অবৈধ হলে, অনুরোধটি 401 Unauthorized ত্রুটিসহ UNAUTHENTICATED এরর কোড দ্বারা প্রত্যাখ্যাত হয়।

4. অনুরোধে সরবরাহ করা এফসিএম রেজিস্ট্রেশন টোকেনটি অবৈধ হলে, এর আচরণ অনির্ধারিত। প্রতিটি অনুরোধে টোকেনটি যাচাই করা হয় না, তবে এফসিএম-এর মাধ্যমে পুশ নোটিফিকেশন পাঠানোর ক্ষেত্রে এটি প্রযোজ্য নয়।

5. যদি কলযোগ্য ট্রিগারটি আহ্বান করা হয়, কিন্তু কোনো অনিয়ন্ত্রিত ব্যতিক্রমের কারণে ব্যর্থ হয় বা একটি ব্যর্থ প্রমিজ ফেরত দেয়, তাহলে অনুরোধটি 500 Internal Server Error দিয়ে প্রত্যাখ্যান করা হয়, যার এরর কোড হলো INTERNAL । এর ফলে কোডিং-এর ভুলগুলো ভুলবশত ব্যবহারকারীদের কাছে প্রকাশ পাওয়া থেকে বিরত থাকা যায়।

6. যদি কলযোগ্য ফাংশনের জন্য প্রদত্ত API ব্যবহার করে ফাংশনটি কল করা হয় এবং এটি একটি সুস্পষ্ট ত্রুটির অবস্থা ফেরত দেয়, তাহলে অনুরোধটি ব্যর্থ হয়। ফেরত আসা HTTP স্ট্যাটাস কোডটি `code.proto`- তে সংজ্ঞায়িত ত্রুটির স্ট্যাটাস থেকে HTTP স্ট্যাটাসের আনুষ্ঠানিক ম্যাপিংয়ের উপর ভিত্তি করে নির্ধারিত হয়। ফেরত আসা নির্দিষ্ট ত্রুটি কোড, বার্তা এবং বিবরণ নিচে বিস্তারিতভাবে বর্ণিত রেসপন্স বডিতে এনকোড করা থাকে। এর মানে হলো, যদি ফাংশনটি OK স্ট্যাটাস সহ একটি সুস্পষ্ট ত্রুটি ফেরত দেয়, তাহলে রেসপন্সের স্ট্যাটাস হবে 200 OK , কিন্তু রেসপন্সের error ফিল্ডটি সেট করা থাকবে।

7. ক্লায়েন্ট ট্রিগার সফল হলে, প্রতিক্রিয়ার স্ট্যাটাস 200 OK হয়।

প্রতিক্রিয়ার বিন্যাস: হেডার

প্রতিক্রিয়াটিতে নিম্নলিখিত হেডারগুলো রয়েছে:

• Content-Type: application/json
• ঐচ্ছিকভাবে সেমিকোলন ; charset=utf-8 যোগ করা যাবে।

প্রতিক্রিয়া সংস্থা

ক্লায়েন্ট এন্ডপয়েন্ট থেকে প্রাপ্ত প্রতিক্রিয়া সর্বদা একটি JSON অবজেক্ট হয়। ন্যূনতমভাবে এতে result অথবা error থাকে, সাথে যেকোনো ঐচ্ছিক ফিল্ডও থাকে। যদি প্রতিক্রিয়াটি একটি JSON অবজেক্ট না হয়, অথবা এতে data বা error না থাকে, তাহলে ক্লায়েন্ট SDK-এর উচিত অনুরোধটিকে Google error code INTERNAL (13) সহ ব্যর্থ হিসাবে গণ্য করা।

• error - এই ফিল্ডটি উপস্থিত থাকলে, HTTP স্ট্যাটাস কোড বা data উপস্থিত আছে কি না, তা নির্বিশেষে অনুরোধটি ব্যর্থ বলে গণ্য করা হবে। এই ফিল্ডের মানটি ত্রুটির জন্য স্ট্যান্ডার্ড গুগল ক্লাউড HTTP ম্যাপিং ফরম্যাটে একটি JSON অবজেক্ট হওয়া উচিত, যেখানে status , message এবং (ঐচ্ছিকভাবে) details জন্য ফিল্ড থাকবে। code ফিল্ডটি অন্তর্ভুক্ত করা যাবে না। যদি status ফিল্ডটি সেট করা না থাকে, বা এর মান অবৈধ হয়, তাহলে ক্লায়েন্টকে code.proto অনুযায়ী স্ট্যাটাসটিকে INTERNAL হিসেবে বিবেচনা করতে হবে। যদি details উপস্থিত থাকে, তবে প্রযোজ্য ক্ষেত্রে, ক্লায়েন্ট SDK-তে ত্রুটির সাথে সংযুক্ত ব্যবহারকারীর তথ্যের মধ্যে এটি অন্তর্ভুক্ত করা হয়।
  দ্রষ্টব্য: এখানকার details ক্ষেত্রটি ব্যবহারকারীর দেওয়া একটি মান। এটি গুগল Status ফরম্যাটের মতো প্রোটো টাইপ দ্বারা চিহ্নিত মানের তালিকা নাও হতে পারে।
• result - ফাংশন দ্বারা ফেরত দেওয়া মান। এটি যেকোনো বৈধ JSON মান হতে পারে। firebase-functions SDK ব্যবহারকারীর দ্বারা ফেরত দেওয়া মানটিকে স্বয়ংক্রিয়ভাবে এই JSON ফরম্যাটে এনকোড করে। ক্লায়েন্ট SDK-গুলো নিচে বর্ণিত সিরিয়ালাইজেশন ফরম্যাট অনুযায়ী এই প্যারামিটারগুলোকে স্বয়ংক্রিয়ভাবে নেটিভ টাইপে ডিকোড করে।

অন্যান্য ক্ষেত্র উপস্থিত থাকলে, সেগুলি উপেক্ষা করা উচিত।

ক্রমিকীকরণ

যেকোনো ডেটা পেলোডের জন্য সিরিয়ালাইজেশন ফরম্যাট অনুরোধ এবং প্রতিক্রিয়া উভয়ের ক্ষেত্রেই একই।

প্ল্যাটফর্মের সামঞ্জস্যতা বজায় রাখার জন্য, এগুলিকে স্ট্যান্ডার্ড JSON ম্যাপিং ব্যবহার করে একটি proto3 প্রোটোকল বাফারের Any ফিল্ডের মান হিসাবে JSON-এ এনকোড করা হয়। null , int , double , বা string মতো সাধারণ টাইপের মানগুলি সরাসরি এনকোড করা হয় এবং সেগুলিতে তাদের সুস্পষ্ট টাইপ অন্তর্ভুক্ত থাকে না। তাই, একটি float এবং একটি double একই উপায়ে এনকোড করা হয়, এবং কলের অপর প্রান্তে কোনটি পাওয়া যাচ্ছে তা আপনি হয়তো জানতে পারবেন না। যে টাইপগুলি JSON-এর নিজস্ব নয়, সেগুলির মানের জন্য টাইপড proto3 এনকোডিং ব্যবহার করা হয়। আরও তথ্যের জন্য, Any JSON এনকোডিং-এর ডকুমেন্টেশন দেখুন।

নিম্নলিখিত প্রকারগুলি অনুমোদিত:

• নাল - null
• int (signed বা unsigned, ৩২ বিট পর্যন্ত) - যেমন 3 বা -30 ।
• ভাসমান - যেমন 3.14
• দ্বিগুণ - যেমন 3.14
• বুলিয়ান - true বা false
• স্ট্রিং - যেমন "hello world"
• মানচিত্র - যেমন {"x": 3}
• তালিকা - যেমন [1, 2, 3]
• লং (সাইনড বা আনসাইনড, সর্বোচ্চ ৬৪ বিট) - [বিস্তারিত জানতে নিচে দেখুন]

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-এর উদাহরণ

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