الإشعارات الفورية

نظرة عامة

توفّر Gmail API إشعارات فورية من الخادم تتيح لك رصد التغييرات في صناديق البريد الإلكتروني في Gmail. يمكنك استخدام هذه الميزة لتحسين أداء تطبيقك. ويسمح لك ذلك بإزالة تكاليف الشبكة والمعالجة الإضافية المرتبطة بالاستعلام عن الموارد لتحديد ما إذا كانت قد تغيّرت. عند تغيير صندوق البريد الإلكتروني، تُرسِل واجهة برمجة التطبيقات Gmail API إشعارًا إلى تطبيق الخادم العميق.

الإعداد الأوّلي لخدمة Cloud Pub/Sub

تستخدِم واجهة برمجة تطبيقات Gmail Cloud Pub/Sub API لإرسال الإشعارات الفورية. يتيح ذلك الإشعار من خلال مجموعة متنوعة من الطرق، بما في ذلك وحدات الربط لطلبات البيانات والاستطلاع على نقطة نهاية اشتراك واحدة.

المتطلبات الأساسية

لإكمال بقية عملية الإعداد هذه، تأكَّد من استيفاء متطلبات Cloud Pub/Sub الأساسية ثم إعداد عميل Cloud Pub/Sub.

إنشاء موضوع

باستخدام برنامج Cloud Pub/Sub، أنشئ الموضوع الذي يجب أن تُرسِل إليه واجهة برمجة التطبيقات Gmail API الإشعارات. يمكن أن يكون اسم الموضوع أي اسم تختاره ضمن مشروعك (أي مطابقًا لـ projects/myproject/topics/*، حيث يكون myproject هو رقم تعريف المشروع المدرَج لمشروعك في Google Developers Console).

ننصحك باستخدام موضوع واحد لجميع إشعارات Gmail API المرسَلة فورًا لتطبيقك، وذلك بسبب قيود Cloud Pub/Sub على عدد المواضيع.

إنشاء اشتراك

اتّبِع دليل المشترك في Cloud Pub/Sub لإعداد اشتراك في الموضوع الذي أنشأته. اضبط نوع الاشتراك ليكون إما إرسالًا عبر ميزة "الردّ التلقائي على الويب" (أي طلب HTTP POST للرجوع) أو سحبًا (أي بدء الإجراء من قبل تطبيقك). بهذه الطريقة، سيتلقّى تطبيقك إشعارات بشأن التحديثات.

منح حقوق النشر حول موضوعك

تتطلّب خدمة Cloud Pub/Sub منك منح Gmail امتيازات لنشر الإشعارات في موضوعك.

لإجراء ذلك، عليك منح امتيازات publish ل gmail-api-push@system.gserviceaccount.com. يمكنك إجراء ذلك باستخدام واجهة أذونات "وحدة تحكّم المطوّر في Cloud Pub/Sub" باتّباع تعليمات التحكّم في الوصول على مستوى الموارد.

تلقّي آخر المعلومات في صندوق البريد الإلكتروني في 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",
}

Python

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 ناجحة إلى إرسال إشعار على الفور إلى موضوع النشر/الاشتراك في السحابة الإلكترونية.

إذا تلقّيت خطأ من طلب watch، من المفترض أن توضّح التفاصيل مصدر المشكلة، والذي يكون عادةً في إعدادموضوع واشتراك Cloud Pub/Sub. يُرجى الرجوع إلى مستندات Cloud Pub/Sub للتأكّد من صحة الإعداد وللحصول على مساعدة بشأن تصحيح الأخطاء في المشاكل المتعلّقة بالموضوع والاشتراك.

تجديد مراقبة صندوق البريد

يجب إعادة الاتصال watch كل 7 أيام على الأقل، وإلا سيتوقّف تلقّي آخر المعلومات عن المستخدم. ننصحك بالاتصال بالرقم watch مرة واحدة في اليوم. يحتوي ردّ watch أيضًا على حقل لتاريخ انتهاء الصلاحية يتضمّن الطابع الزمني لتاريخ انتهاء صلاحية 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"
}

يكون نص طلب POST في HTTP بتنسيق JSON، وتكون الحمولة الفعلية لإشعار Gmail في الحقل message.data. حقل message.data هو سلسلة تم ترميزها باستخدام base64url ويتم فك تشفيرها إلى عنصر JSON يحتوي على عنوان البريد الإلكتروني ومعرّف سجلّ صندوق البريد الجديد للمستخدم:

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

يمكنك بعد ذلك استخدام history.list للحصول على تفاصيل التغييرات التي أجراها المستخدم منذ تاريخه المعروف الذي تم تحديده في historyId، وذلك وفقًا لدليل المزامنة.

إذا كنت قد أعددت اشتراكًا للسحابة الإلكترونية من النوع "الاستلام" بدلاً من ذلك، يمكنك الرجوع إلى نماذج الرموز البرمجية في دليل "الاستلام" للمشتركين في Cloud Pub/Sub للحصول على مزيد من التفاصيل حول تلقّي الرسائل.

الردّ على الإشعارات

يجب الردّ على جميع الإشعارات. إذا كنت تستخدم إرسال الدفع من خلال وحدات الربط، سيؤدي الردّ بنجاح (مثل HTTP 200) إلى تأكيد الإشعار.

في حال استخدام أسلوب الإرسال من خلال السحب (REST Pull RPC Pull أو RPC StreamingPull) ، يجب المتابعة من خلال طلب تأكيد (REST أو RPC). راجِع نماذج الرموز البرمجية في دليل سحب المشتركين في Cloud Pub/Sub للحصول على مزيد من التفاصيل حول تأكيد الرسائل إما بشكل غير متزامن أو بشكل متزامن باستخدام مكتبات العملاء الرسمية المستندة إلى RPC.

إذا لم يتم تأكيد الإشعارات (على سبيل المثال، إذا كان الإجراء المُعاد توجيهه إلى رابط البيانات في التطبيق يعرض خطأ أو ينتهي مهله)، ستعيد Cloud Pub/Sub محاولة إرسال الإشعار في وقت لاحق.

إيقاف تحديثات صندوق البريد الإلكتروني

لإيقاف تلقّي آخر الأخبار بشأن صندوق البريد، اتصل بالرقم stop ومن المفترض أن تتوقف جميع الإشعارات الجديدة في غضون بضع دقائق.

القيود

الحد الأقصى لمعدل الإشعارات

يبلغ معدّل الإشعارات القصوى لكل مستخدم Gmail يتم مراقبته حدثًا واحدًا في الثانية، وسيتم تجاهل أي إشعارات مُرسَلة إلى المستخدم تتجاوز هذا المعدّل. يجب توخّي الحذر عند التعامل مع الإشعارات للتأكّد من عدم بدء إشعار آخر، وبالتالي بدء حلقة إشعارات.

الموثوقية

من المفترض أن يتم عادةً تسليم جميع الإشعارات بشكل موثوق خلال بضع ثوانٍ، ولكن في بعض الحالات القصوى، قد يتأخّر عرض الإشعارات أو لا يتم عرضها. احرص على التعامل مع هذه الحالة بشكلٍ سلس، بحيث يظل التطبيق تتم مزامنته حتى في حال عدم استلام أي رسائل فورية. على سبيل المثال، يمكنك الرجوع إلى الاتصال بدوري history.list بعد فترة بدون إرسال إشعارات إلى المستخدم.

قيود Cloud Pub/Sub

تتضمّن Cloud Pub/Sub API أيضًا قيودًا خاصة بها، وهي موضّحة بالتفصيل في مستندات الأسعار والحصص.