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

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

অনুরোধের ফর্ম্যাট: হেডার

একটি কলযোগ্য ট্রিগার এন্ডপয়েন্টের HTTP অনুরোধটি নিম্নলিখিত শিরোনাম সহ একটি 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 এর জন্য উপলব্ধ)

যদি অন্য কোনও শিরোনাম অন্তর্ভুক্ত করা হয়, তাহলে অনুরোধটি প্রত্যাখ্যান করা হবে, যেমনটি নীচের প্রতিক্রিয়া ডকুমেন্টেশনে বর্ণিত হয়েছে।

দ্রষ্টব্য: জাভাস্ক্রিপ্ট ক্লায়েন্টগুলিতে, এই অনুরোধগুলি একটি 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. যদি অনুরোধে সরবরাহ করা FCM নিবন্ধন টোকেনটি অবৈধ হয়, তাহলে আচরণটি অনির্ধারিত। প্রতিটি অনুরোধে টোকেনটি পরীক্ষা করা হয় না, শুধুমাত্র যখন এটি FCM দিয়ে একটি পুশ বিজ্ঞপ্তি পাঠানোর জন্য ব্যবহৃত হয়।

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

6. যদি কলেবলটি ইনভোক করা হয় এবং কলেবল ফাংশনের জন্য প্রদত্ত API ব্যবহার করে একটি স্পষ্ট ত্রুটির শর্ত ফেরত দেয়, তাহলে অনুরোধটি ব্যর্থ হয়। ফেরত দেওয়া HTTP স্ট্যাটাস কোডটি code.proto এ সংজ্ঞায়িত ত্রুটির স্থিতির HTTP স্ট্যাটাসের অফিসিয়াল ম্যাপিংয়ের উপর ভিত্তি করে তৈরি করা হয়। নির্দিষ্ট ত্রুটি কোড, বার্তা এবং ফেরত দেওয়া বিবরণ নীচের বিশদ অনুসারে প্রতিক্রিয়ার বডিতে এনকোড করা হয়। এর অর্থ হল যদি ফাংশনটি status OK সহ একটি স্পষ্ট ত্রুটি ফেরত দেয়, তাহলে প্রতিক্রিয়াটির status 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 Cloud 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 (স্বাক্ষরিত বা স্বাক্ষরিত নয়, ৩২ বিট পর্যন্ত) - যেমন 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 উদাহরণ
• কলটির সফল প্রতিক্রিয়া
• কলটির ব্যর্থ প্রতিক্রিয়া

এনকোড করার জন্য 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"
        }
    }
}