এই ডকুমেন্টটিতে জিমেইল এপিআই-তে পুশ নোটিফিকেশন কীভাবে পরিচালনা করতে হয়, তা ব্যাখ্যা করা হয়েছে।
জিমেইল এপিআই সার্ভার পুশ নোটিফিকেশন প্রদান করে, যার মাধ্যমে আপনি জিমেইল মেইলবক্সের পরিবর্তনগুলো পর্যবেক্ষণ করতে পারেন। আপনার অ্যাপ্লিকেশনের পারফরম্যান্স উন্নত করতে এই ফিচারটি ব্যবহার করুন। এটি রিসোর্স পরিবর্তিত হয়েছে কিনা তা জানার জন্য পোলিং করার অতিরিক্ত নেটওয়ার্ক এবং কম্পিউট খরচ দূর করে। যখনই কোনো মেইলবক্স পরিবর্তিত হয়, জিমেইল এপিআই আপনার ব্যাকএন্ড সার্ভার অ্যাপ্লিকেশনকে অবহিত করে।
প্রাথমিক ক্লাউড পাব/সাব সেটআপ
জিমেইল এপিআই পুশ নোটিফিকেশন পাঠানোর জন্য ক্লাউড পাব/সাব এপিআই ব্যবহার করে। এর ফলে একটিমাত্র সাবস্ক্রিপশন এন্ডপয়েন্টে ওয়েবহুক এবং পোলিং-সহ বিভিন্ন পদ্ধতির মাধ্যমে নোটিফিকেশন পাঠানো যায়।
পূর্বশর্ত
এই সেটআপটি সম্পূর্ণ করতে, Cloud Pub/Sub-এর পূর্বশর্তগুলো পূরণ করুন এবং তারপর একটি Cloud Pub/Sub ক্লায়েন্ট সেট আপ করুন ।
একটি বিষয় তৈরি করুন
আপনার ক্লাউড পাব/সাব ক্লায়েন্ট ব্যবহার করে সেই টপিকটি তৈরি করুন যেখানে জিমেইল এপিআই নোটিফিকেশন পাঠাবে। টপিকের নামটি আপনার প্রোজেক্টের অধীনে আপনার পছন্দের যেকোনো নাম হতে পারে (উদাহরণস্বরূপ, projects/myproject/topics/* এর সাথে মেলে এমন নাম, যেখানে myproject হলো গুগল ক্লাউড কনসোলে আপনার প্রোজেক্টের জন্য তালিকাভুক্ত প্রোজেক্ট আইডি)।
একটি সাবস্ক্রিপশন তৈরি করুন
আপনার তৈরি করা টপিকে একটি সাবস্ক্রিপশন সেট আপ করতে, ক্লাউড পাব/সাব সাবস্ক্রিপশন টাইপ গাইডটি অনুসরণ করুন। সাবস্ক্রিপশন টাইপটি ওয়েবহুক পুশ (অর্থাৎ, একটি HTTP POST কলব্যাক) অথবা পুল (অর্থাৎ, আপনার অ্যাপ দ্বারা শুরু করা) হিসেবে কনফিগার করুন। এভাবেই আপনার অ্যাপ্লিকেশন আপডেটের জন্য নোটিফিকেশন পায়।
আপনার বিষয়ে প্রকাশের অধিকার প্রদান করুন
ক্লাউড পাব/সাব ব্যবহার করার জন্য আপনার টপিকে নোটিফিকেশন প্রকাশ করতে জিমেইলকে বিশেষাধিকার প্রদান করতে হবে।
এটি করার জন্য, gmail-api-push@system.gserviceaccount.com কে publish অনুমতি দিন। আপনি গুগল ক্লাউড কনসোলের ক্লাউড পাব/সাব পারমিশন কনসোল ব্যবহার করে এই অ্যাক্সেস কন্ট্রোল নির্দেশাবলী অনুসরণ করে এটি করতে পারেন।
আপনার প্রতিষ্ঠানের ডোমেইনের সীমাবদ্ধ শেয়ারিং কনফিগারেশনের কারণে আপনি হয়তো পাবলিশ করার অনুমতি দিতে পারছেন না। এর সমাধান করতে, আপনি এই সার্ভিস অ্যাকাউন্টের জন্য একটি ব্যতিক্রম কনফিগার করতে পারেন।
জিমেইল মেইলবক্স আপডেট পান
প্রাথমিক ক্লাউড পাব/সাব সেটআপ শেষ হয়ে গেলে, মেইলবক্স আপডেটের নোটিফিকেশন পাঠানোর জন্য জিমেইল অ্যাকাউন্টগুলো কনফিগার করুন।
ঘড়ির অনুরোধ
আপনার ক্লাউড পাব/সাব টপিকে নোটিফিকেশন পাঠানোর জন্য জিমেইল অ্যাকাউন্ট কনফিগার করতে, আপনার জিমেইল এপিআই ক্লায়েন্ট ব্যবহার করে জিমেইল ব্যবহারকারীর মেইলবক্সে ' watch ' মেথডটি কল করুন। এটি অন্য যেকোনো জিমেইল এপিআই কলের মতোই। আপনার watch রিকোয়েস্টে আপনার তৈরি করা টপিকের নাম এবং ফিল্টার করার জন্য labels মতো অন্যান্য অপশনগুলো প্রদান করুন। উদাহরণস্বরূপ, ইনবক্সে কোনো পরিবর্তন হলেই নোটিফিকেশন পেতে নিম্নলিখিত রিকোয়েস্টটি ব্যবহার করুন:
প্রোটোকল
POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json
{
topicName: "projects/myproject/topics/mytopic",
labelIds: ["INBOX"],
labelFilterBehavior: "INCLUDE",
}
পাইথন
request = {
'labelIds': ['INBOX'],
'topicName': 'projects/myproject/topics/mytopic',
'labelFilterBehavior': 'INCLUDE'
}
gmail.users().watch(userId='me', body=request).execute()
প্রতিক্রিয়া দেখুন
watch রিকোয়েস্টটি সফল হলে, আপনি নিম্নলিখিতের মতো একটি রেসপন্স পাবেন:
{ historyId: 1234567890 expiration: 1431990098200 }
রেসপন্সটিতে ব্যবহারকারীর বর্তমান মেইলবক্স historyId থাকে। আপনার ক্লায়েন্ট সেই historyId পরবর্তী সমস্ত পরিবর্তনের জন্য নোটিফিকেশন পায়। যদি আপনার এই historyId আগের পরিবর্তনগুলো প্রসেস করার প্রয়োজন হয়, তাহলে " Synchronize clients with Gmail API" অংশটি দেখুন।
এছাড়াও, একটি সফল watch কলের ফলে আপনার ক্লাউড পাব/সাব টপিকে তাৎক্ষণিকভাবে একটি নোটিফিকেশন পাঠানো হয়।
যদি আপনি watch কল থেকে কোনো ত্রুটি পান, তাহলে তার বিবরণে সমস্যার উৎস ব্যাখ্যা করা থাকবে। এটি সাধারণত ক্লাউড পাব/সাব টপিক এবং সাবস্ক্রিপশনের সেটআপ সংক্রান্ত একটি সমস্যা। সেটআপটি সঠিক কিনা তা নিশ্চিত করতে এবং টপিক ও সাবস্ক্রিপশনের সমস্যা ডিবাগ করার জন্য ক্লাউড পাব/সাব ডকুমেন্টেশন দেখুন।
মেইলবক্স নজরদারি পুনর্নবীকরণ করুন
আপনাকে অবশ্যই প্রতি ৭ দিনে অন্তত একবার watch কল করতে হবে, অন্যথায় আপনি ব্যবহারকারীর জন্য আপডেট পাওয়া বন্ধ করে দেবেন। আমরা দিনে একবার watch কল করার পরামর্শ দিই। watch মেথডের রেসপন্সে একটি expiration ফিল্ডও থাকে, যেখানে watch মেয়াদ শেষ হওয়ার টাইমস্ট্যাম্প দেওয়া থাকে।
বিজ্ঞপ্তি গ্রহণ করুন
যখনই আপনার watch সাথে মিলে যায় এমন কোনো মেইলবক্স আপডেট হয়, আপনার অ্যাপ্লিকেশনটি পরিবর্তনটি বর্ণনা করে একটি নোটিফিকেশন মেসেজ পায়।
যদি আপনি একটি পুশ সাবস্ক্রিপশন কনফিগার করে থাকেন, তাহলে আপনার সার্ভারে পাঠানো একটি ওয়েবহুক নোটিফিকেশন একটি PubsubMessage এর অনুরূপ হবে:
POST https://yourserver.example.com/yourUrl
Content-type: application/json
{
message:
{
// This is the actual notification data, as Base64URL-encoded JSON.
data: "eyJlbWFpbEFkZHJlc3MiOiAidXNlckBleGFtcGxlLmNvbSIsICJoaXN0b3J5SWQiOiAiMTIzNDU2Nzg5MCJ9",
// This is a Cloud Pub/Sub message id, unrelated to Gmail messages.
"messageId": "2070443601311540",
// This is the publish time of the message.
"publishTime": "2021-02-26T19:13:55.749Z",
}
subscription: "projects/myproject/subscriptions/mysubscription"
}
HTTP POST বডিটি JSON ফরম্যাটে থাকে এবং প্রকৃত Gmail নোটিফিকেশন পেলোডটি message.data ফিল্ডে থাকে। message.data ফিল্ডটি একটি Base64URL-এনকোডেড স্ট্রিং, যা ডিকোড করলে একটি JSON অবজেক্ট পাওয়া যায়। এই অবজেক্টটিতে ব্যবহারকারীর ইমেল অ্যাড্রেস এবং নতুন মেইলবক্স হিস্ট্রি আইডি থাকে।
{"emailAddress": "user@example.com", "historyId": "9876543210"}
এরপর আপনি history.list মেথডটি ব্যবহার করে ব্যবহারকারীর সর্বশেষ জানা historyId থেকে তার পরিবর্তনের বিবরণ পেতে পারেন, যেমনটি "Gmail API-এর সাথে ক্লায়েন্ট সিঙ্ক্রোনাইজ করুন" অংশে বর্ণনা করা হয়েছে।
উদাহরণস্বরূপ, আপনার প্রাথমিক watch রিকোয়েস্ট এবং পূর্ববর্তী উদাহরণে শেয়ার করা নোটিফিকেশন মেসেজটি পাওয়ার মধ্যবর্তী সময়ে ঘটে যাওয়া পরিবর্তনগুলো শনাক্ত করতে history.list মেথডটি ব্যবহার করুন। history.list এ startHistoryId হিসেবে 1234567890 পাস করুন। এরপর, ভবিষ্যতের ব্যবহারের জন্য আপনি 9876543210 সর্বশেষ জানা historyId হিসেবে সংরক্ষণ করতে পারেন।
এর পরিবর্তে আপনি যদি একটি পুল সাবস্ক্রিপশন কনফিগার করে থাকেন, তাহলে মেসেজ গ্রহণ করার বিষয়ে আরও বিস্তারিত জানতে ক্লাউড পাব/সাব-এর পুল সাবস্ক্রিপশন গাইডে থাকা কোড স্যাম্পলগুলো দেখুন।
বিজ্ঞপ্তিগুলিতে সাড়া দিন
সমস্ত নোটিফিকেশন অবশ্যই স্বীকার করতে হবে। আপনি যদি ওয়েবহুক পুশ ডেলিভারি ব্যবহার করেন, তাহলে সফলভাবে সাড়া দিলে (উদাহরণস্বরূপ, HTTP 200) নোটিফিকেশনটি স্বীকার করা হয়।
আপনি যদি পুল ডেলিভারি ( REST Pull , RPC Pull , বা RPC StreamingPull ) ব্যবহার করেন, তাহলে আপনাকে অবশ্যই একটি অ্যাকনলেজ কল ( REST বা RPC ) করতে হবে। অফিসিয়াল RPC-ভিত্তিক ক্লায়েন্ট লাইব্রেরি ব্যবহার করে অ্যাসিঙ্ক্রোনাসলি বা সিঙ্ক্রোনাসলি মেসেজ অ্যাকনলেজ করার বিষয়ে আরও বিস্তারিত জানতে Cloud Pub/Sub-এর পুল সাবস্ক্রিপশন গাইডের কোড স্যাম্পলগুলো দেখুন।
আপনি যদি নোটিফিকেশনগুলো স্বীকার না করেন (উদাহরণস্বরূপ, যদি আপনার ওয়েবহুক কলব্যাক কোনো ত্রুটি দেখায় বা এর সময়সীমা শেষ হয়ে যায়), তাহলে ক্লাউড পাব/সাব পরবর্তীতে আবার নোটিফিকেশনটি পাঠানোর চেষ্টা করে।
মেইলবক্স আপডেট বন্ধ করুন
কোনো মেইলবক্সে আপডেট পাওয়া বন্ধ করতে, stop মেথডটি কল করুন। কয়েক মিনিটের মধ্যেই সব নতুন নোটিফিকেশন আসা বন্ধ হয়ে যাবে।
সীমাবদ্ধতা
সার্ভার পুশ নোটিফিকেশন ব্যবহারের সীমাবদ্ধতাগুলো নিচে দেওয়া হলো:
সর্বোচ্চ বিজ্ঞপ্তি হার
পর্যবেক্ষণাধীন প্রতিটি জিমেইল ব্যবহারকারীর জন্য প্রতি সেকেন্ডে সর্বোচ্চ একটি নোটিফিকেশন পাঠানোর সীমা রয়েছে। এই হার অতিক্রমকারী যেকোনো ব্যবহারকারীর নোটিফিকেশন বাতিল করে দেওয়া হয়। নোটিফিকেশন পরিচালনা করার সময় সতর্ক থাকুন, যাতে অন্য কোনো নোটিফিকেশন চালু না হয়ে যায়, কারণ এতে একটি নোটিফিকেশন লুপ শুরু হতে পারে।
নির্ভরযোগ্যতা
সাধারণত, সমস্ত নোটিফিকেশন কয়েক সেকেন্ডের মধ্যেই নির্ভরযোগ্যভাবে পৌঁছে যায়; তবে, কিছু চরম পরিস্থিতিতে নোটিফিকেশন আসতে দেরি হতে পারে বা বাদ পড়ে যেতে পারে। এই সম্ভাবনাটি সুন্দরভাবে সামাল দিন, যাতে কোনো পুশ মেসেজ না পেলেও অ্যাপ্লিকেশনটি সিঙ্ক হতে থাকে। উদাহরণস্বরূপ, কোনো ব্যবহারকারীর জন্য একটি নির্দিষ্ট সময় ধরে কোনো নোটিফিকেশন না এলে, পর্যায়ক্রমে history.list মেথডটি কল করার ব্যবস্থা করুন।
ক্লাউড পাব/সাব সীমাবদ্ধতা
ক্লাউড পাব/সাব এপিআই-এরও নিজস্ব সীমাবদ্ধতা রয়েছে, যা এর মূল্য নির্ধারণ এবং কোটা সংক্রান্ত ডকুমেন্টেশনে বিস্তারিতভাবে উল্লেখ করা হয়েছে।