Push Notifications, Push Notifications

نمای کلی

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

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

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

پیش نیازها

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

یک موضوع ایجاد کنید

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

به دلیل محدودیت‌های Cloud Pub/Sub در تعداد موضوعات، توصیه می‌کنیم از یک موضوع برای همه اعلان‌های فشاری Gmail API برای برنامه خود استفاده کنید.

یک اشتراک ایجاد کنید

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

به موضوع خود حقوق انتشار بدهید

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

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

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

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

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

برای پیکربندی حساب‌های Gmail برای ارسال اعلان‌ها به موضوع Cloud Pub/Sub، به سادگی از سرویس گیرنده Gmail API خود برای تماس با watch در صندوق پستی کاربر Gmail مانند هر تماس دیگر Gmail API استفاده کنید. برای انجام این کار، نام موضوع ایجاد شده در بالا و هر گزینه دیگری را در درخواست 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 دارید، به راهنمای همگام سازی مراجعه کنید.

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

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

در حال تمدید ساعت صندوق پستی

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

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

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

اگر اشتراک push پیکربندی کرده اید، یک اعلان وب هوک به سرور شما با یک 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 یک رشته رمزگذاری شده با url base64 است که به یک شی JSON حاوی آدرس ایمیل و شناسه تاریخچه صندوق پستی جدید برای کاربر رمزگشایی می‌شود:

{"emailAddress": "user@example.com", "historyId": "9876543210"}

سپس می‌توانید از history.list برای دریافت جزئیات تغییر کاربر از زمان آخرین historyId شناخته شده ، طبق راهنمای همگام‌سازی استفاده کنید.

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

پاسخگویی به اطلاعیه ها

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

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

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

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

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

محدودیت ها

حداکثر نرخ اطلاع رسانی

حداکثر نرخ اعلان هر کاربر Gmail در حال تماشا 1 رویداد در ثانیه است. هر گونه اعلان کاربر بالاتر از این نرخ حذف خواهد شد. هنگام مدیریت اعلان‌ها مراقب باشید که اعلان دیگری را راه‌اندازی نکنید و در نتیجه یک حلقه اعلان راه‌اندازی نکنید.

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

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

محدودیت‌های Cloud Pub/Sub

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