Push Notifications, Push Notifications

نمای کلی

API جیمیل، اعلان‌های فوری سرور را ارائه می‌دهد که به شما امکان می‌دهد تغییرات در صندوق‌های پستی جیمیل را مشاهده کنید. می‌توانید از این ویژگی برای بهبود عملکرد برنامه خود استفاده کنید. این به شما امکان می‌دهد شبکه اضافی را حذف کنید و هزینه‌های مربوط به منابع نظرسنجی را برای تعیین اینکه آیا تغییر کرده‌اند یا خیر، محاسبه کنید. هر زمان که یک صندوق پستی تغییر کند، API جیمیل به برنامه سرور backend شما اطلاع می‌دهد.

راه‌اندازی اولیه‌ی Cloud Pub/Sub

رابط برنامه‌نویسی کاربردی (API) جیمیل از رابط برنامه‌نویسی کاربردی Cloud Pub/Sub برای ارائه اعلان‌های فوری استفاده می‌کند. این امر امکان ارسال اعلان از طریق روش‌های مختلفی از جمله وب‌هوک‌ها و نظرسنجی در یک نقطه پایانی اشتراک را فراهم می‌کند.

پیش‌نیازها

برای تکمیل بقیه این تنظیمات، مطمئن شوید که پیش‌نیازهای Cloud Pub/Sub را برآورده کرده‌اید و سپس یک کلاینت Cloud Pub/Sub راه‌اندازی کنید .

ایجاد تاپیک

با استفاده از کلاینت Cloud Pub/Sub خود، موضوعی را ایجاد کنید که API Gmail باید به آن اعلان‌ها ارسال کند. نام موضوع می‌تواند هر نامی باشد که شما برای پروژه خود انتخاب می‌کنید (یعنی مطابق با projects/myproject/topics/* ، که myproject شناسه پروژه ذکر شده برای پروژه شما در کنسول توسعه‌دهندگان گوگل است).

ایجاد اشتراک

برای تنظیم اشتراک در موضوعی که ایجاد کرده‌اید، راهنمای Cloud Pub/Sub Subscriber را دنبال کنید. نوع اشتراک را طوری پیکربندی کنید که یا یک webhook push (مثلاً HTTP POST callback) یا pull (مثلاً توسط برنامه شما آغاز شود) باشد. اینگونه است که برنامه شما اعلان‌های مربوط به به‌روزرسانی‌ها را دریافت خواهد کرد.

اعطای حق انتشار در موضوع شما

Cloud Pub/Sub مستلزم آن است که شما به Gmail امتیازات لازم برای انتشار اعلان‌ها در موضوع خود را اعطا کنید.

برای انجام این کار، باید به gmail-api-push@system.gserviceaccount.com امتیاز publish بدهید. می‌توانید این کار را با استفاده از رابط مجوزهای Cloud Pub/Sub Developer Console و با پیروی از دستورالعمل‌های کنترل دسترسی سطح منابع انجام دهید.

پیکربندی اشتراک‌گذاری محدود دامنه سازمان شما ممکن است مانع از اعطای مجوزهای انتشار شود. برای حل این مشکل، می‌توانید یک استثنا برای این حساب سرویس پیکربندی کنید .

دریافت به‌روزرسانی‌های صندوق پستی جیمیل

پس از اتمام تنظیمات اولیه Cloud Pub/Sub، حساب‌های Gmail را طوری پیکربندی کنید که برای به‌روزرسانی‌های صندوق پستی اعلان ارسال کنند.

درخواست تماشا

برای پیکربندی حساب‌های جیمیل برای ارسال اعلان‌ها به موضوع Cloud Pub/Sub، کافیست از کلاینت Gmail API خود برای فراخوانی watch در صندوق پستی کاربر Gmail مشابه هر فراخوانی دیگر Gmail API استفاده کنید. برای انجام این کار، نام موضوع ایجاد شده در بالا و سایر گزینه‌ها، مانند labels برای فیلتر کردن، را در درخواست watch خود ارائه دهید. به عنوان مثال، برای اینکه هر زمان تغییری در صندوق ورودی ایجاد شد، مطلع شوید:

پروتکل 

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 دارید، به راهنمای همگام‌سازی مراجعه کنید.

علاوه بر این، یک فراخوانی موفق watch باید باعث شود که بلافاصله یک اعلان به موضوع Cloud Pub/Sub شما ارسال شود.

اگر در فراخوانی watch خطایی دریافت کردید، جزئیات باید منبع مشکل را توضیح دهند، که معمولاً مربوط به تنظیمات موضوع Cloud Pub/Sub و اشتراک است. برای تأیید صحت تنظیمات و کمک به رفع اشکال مشکلات موضوع و اشتراک، به مستندات Cloud Pub/Sub مراجعه کنید.

تمدید نگهبانی صندوق پستی

شما باید حداقل هر ۷ روز یکبار تابع watch دوباره فراخوانی کنید، در غیر این صورت دریافت به‌روزرسانی‌ها برای کاربر متوقف خواهد شد. توصیه می‌کنیم تابع watch را روزی یک بار فراخوانی کنید. پاسخ watch همچنین دارای یک فیلد انقضا با مهر زمانی برای انقضای watch است.

دریافت اعلان‌ها

هر زمان که به‌روزرسانی صندوق پستی مطابق با watch شما انجام شود، برنامه شما یک پیام اعلان دریافت می‌کند که تغییر را شرح می‌دهد.

اگر اشتراک push را پیکربندی کرده باشید، اعلان webhook به سرور شما با 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 شناخته شده‌اش ، طبق راهنمای همگام‌سازی ، استفاده کنید.

برای مثال، برای استفاده از history.list جهت شناسایی تغییراتی که بین فراخوانی اولیه watch و دریافت پیام اعلان به اشتراک گذاشته شده در مثال قبلی رخ داده است، عدد 1234567890 را به عنوان startHistoryId به history.list ارسال کنید. پس از آن، می‌توان 9876543210 به عنوان آخرین historyId شناخته شده برای موارد استفاده بعدی ذخیره کرد.

اگر به جای آن، اشتراک pull را پیکربندی کرده‌اید، برای جزئیات بیشتر در مورد دریافت پیام‌ها، به نمونه‌های کد موجود در راهنمای pull مشترک Cloud Pub/Sub مراجعه کنید.

پاسخ به اعلان‌ها

همه اعلان‌ها باید تأیید شوند. اگر از webhook push delivery استفاده می‌کنید، پاسخ موفقیت‌آمیز (مثلاً HTTP 200) اعلان را تأیید می‌کند.

اگر از تحویل pull ( REST Pull ، RPC Pull یا RPC StreamingPull ) استفاده می‌کنید، باید با یک فراخوانی تأیید ( REST یا RPC ) پیگیری کنید. برای جزئیات بیشتر در مورد تأیید پیام‌ها به صورت ناهمزمان یا همزمان با استفاده از کتابخانه‌های رسمی کلاینت مبتنی بر RPC، به نمونه‌های کد موجود در راهنمای Cloud Pub/Sub Subscriber Pull مراجعه کنید.

اگر اعلان‌ها تأیید نشوند (مثلاً فراخوانی وب‌هوک شما خطا برگرداند یا زمان آن تمام شود)، Cloud Pub/Sub اعلان را بعداً دوباره امتحان می‌کند.

متوقف کردن به‌روزرسانی‌های صندوق پستی

برای متوقف کردن دریافت به‌روزرسانی‌ها در صندوق پستی، دستور stop بزنید تا تمام اعلان‌های جدید ظرف چند دقیقه متوقف شوند.

محدودیت‌ها

حداکثر نرخ اعلان

هر کاربر جیمیل که تحت نظر است، حداکثر نرخ اعلان ۱ رویداد در ثانیه را دارد. هر اعلان کاربری که بالاتر از این نرخ باشد، حذف خواهد شد. هنگام مدیریت اعلان‌ها مراقب باشید تا مطمئن شوید که اعلان دیگری را فعال نمی‌کنید و در نتیجه یک حلقه اعلان ایجاد نمی‌کنید.

قابلیت اطمینان

معمولاً همه اعلان‌ها باید ظرف چند ثانیه به طور قابل اعتمادی ارسال شوند؛ با این حال، در برخی شرایط خاص، ممکن است اعلان‌ها با تأخیر یا حذف مواجه شوند. مطمئن شوید که این احتمال را به درستی مدیریت می‌کنید، به طوری که برنامه حتی اگر هیچ پیام فوری دریافت نکند، همچنان همگام‌سازی شود. به عنوان مثال، پس از مدتی که هیچ اعلانی برای یک کاربر وجود ندارد، به فراخوانی دوره‌ای history.list برگردید.

محدودیت‌های انتشار/زیربرنامه ابری

رابط برنامه‌نویسی کاربردی Cloud Pub/Sub نیز محدودیت‌های خاص خود را دارد که به‌طور خاص در مستندات قیمت‌گذاری و سهمیه‌بندی آن توضیح داده شده است.