پیکربندی اعلان‌های فوری در Gmail API

این سند نحوه مدیریت اعلان‌های فوری در Gmail API را توضیح می‌دهد.

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 شناسه پروژه ذکر شده برای پروژه شما در کنسول Google Cloud است).

ایجاد اشتراک

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

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

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

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

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

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

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

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

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

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

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

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

شما باید حداقل هر ۷ روز یکبار تابع watch فراخوانی کنید، در غیر این صورت دریافت به‌روزرسانی‌ها برای کاربر متوقف خواهد شد. توصیه می‌کنیم watch روزی یک بار فراخوانی کنید. پاسخ متد watch همچنین دارای یک فیلد expiration با مهر زمانی برای انقضای 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 شناخته‌شده‌اش استفاده کنید، همانطور که در بخش همگام‌سازی کلاینت‌ها با Gmail API توضیح داده شده است.

برای مثال، از متد 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، به نمونه‌های کد موجود در راهنمای اشتراک pull در Cloud Pub/Sub مراجعه کنید.

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

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

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

محدودیت‌ها

محدودیت‌های کار با اعلان‌های سرور به شرح زیر است:

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

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

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

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

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

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