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

نظرة عامة

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

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

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

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

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

إنشاء موضوع

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

ننصحك باستخدام موضوع واحد لكل الإشعارات الفورية في واجهة برمجة تطبيقات Gmail لتطبيقك، بسبب الحدود القصوى المسموح بها على 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 بنجاح إلى إرسال إشعار فورًا إلى موضوع Cloud Pub/Sub.

إذا تلقّيت رسالة خطأ من المكالمة 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"
}

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

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

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

إذا ضبطت خدمة سحب الاشتراك بدلاً من ذلك، يمكنك الرجوع إلى نماذج الرموز في دليل جذب المشترِكين في 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 أيضًا قيودها، لا سيما في مستندات pricing وquotas.