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>
    • ফায়ারবেস অ্যাপ চেক টোকেন ক্লায়েন্ট অ্যাপের দ্বারা প্রদত্ত অনুরোধ করা হচ্ছে। ব্যাকএন্ড স্বয়ংক্রিয়ভাবে এই টোকেনটি যাচাই করে এবং এটিকে ডিকোড করে, হ্যান্ডলারের context appId ইনজেকশন করে। টোকেন যাচাই করা না গেলে, অনুরোধ প্রত্যাখ্যান করা হয়। (SDK>=3.14.0 এর জন্য উপলব্ধ)

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

দ্রষ্টব্য: জাভাস্ক্রিপ্ট ক্লায়েন্টে, এই অনুরোধগুলি একটি CORS OPTIONS প্রিফ্লাইট ট্রিগার করে, কারণ:

  • application/json অনুমোদিত নয়। এটি অবশ্যই text/plain বা application/x-www-form-urlencoded হতে হবে।
  • Authorization শিরোনাম একটি CORS-নিরাপদ অনুরোধ-শিরোনাম নয়।
  • অন্যান্য শিরোনাম একইভাবে অনুমোদিত নয়।

কলযোগ্য ট্রিগার স্বয়ংক্রিয়ভাবে এই OPTIONS অনুরোধগুলি পরিচালনা করে।

শরীরের অনুরোধ

HTTP অনুরোধের মূল অংশটি নিম্নলিখিত ক্ষেত্রগুলির সাথে একটি JSON অবজেক্ট হওয়া উচিত:

  • প্রয়োজনীয়: data - ফাংশনে পাঠানো আর্গুমেন্ট। এটি কোনো বৈধ JSON মান হতে পারে। নীচে বর্ণিত সিরিয়ালাইজেশন বিন্যাস অনুসারে এটি স্বয়ংক্রিয়ভাবে নেটিভ জাভাস্ক্রিপ্ট প্রকারে ডিকোড করা হয়।

অনুরোধে অন্য কোনো ক্ষেত্র উপস্থিত থাকলে, ব্যাকএন্ড অনুরোধটিকে বিকৃত বলে মনে করে এবং এটি প্রত্যাখ্যান করা হয়।

প্রতিক্রিয়া বিন্যাস: স্থিতি কোড

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

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

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

সিরিয়ালাইজেশন

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

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

নিম্নলিখিত ধরনের অনুমোদিত:

  • null - null
  • int (স্বাক্ষরিত বা স্বাক্ষরবিহীন, 32 বিট পর্যন্ত) - যেমন 3 বা -30 ।
  • float - যেমন 3.14
  • দ্বিগুণ - যেমন 3.14
  • বুলিয়ান - true বা false
  • স্ট্রিং - যেমন "hello world"
  • মানচিত্র - যেমন {"x": 3}
  • তালিকা - যেমন [1, 2, 3]
  • দীর্ঘ (স্বাক্ষরিত বা স্বাক্ষরবিহীন, 64 বিট পর্যন্ত) - [বিশদ বিবরণের জন্য নীচে দেখুন]

float এবং double জন্য NaN এবং Infinity মান সমর্থিত নয়।

মনে রাখবেন যে long একটি বিশেষ প্রকার যা সাধারণত JSON-এ অনুমোদিত নয়, তবে প্রোটো3 স্পেসিফিকেশন দ্বারা আচ্ছাদিত। উদাহরণস্বরূপ, এগুলি এনকোড করা হয়েছে:

দীর্ঘ

{
    '@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"
        }
    }
}