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

نظرة عامة

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

عملية الإعداد الأوّلية لخدمة 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).

إنشاء اشتراك

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

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

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

لإجراء ذلك، عليك منح امتيازات publish إلى gmail-api-push@system.gserviceaccount.com. يمكنك إجراء ذلك باستخدام واجهة أذونات 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",
}

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 للحصول على تفاصيل التغيير للمستخدم منذ آخر historyId معروف له، وفقًا لدليل المزامنة.

على سبيل المثال، لاستخدام history.list لتحديد التغييرات التي حدثت بين طلبك الأوّلي watch واستلام رسالة الإشعار المشترَكة في المثال السابق، مرِّر 1234567890 كـ startHistoryId إلى history.list. بعد ذلك، يمكن الاحتفاظ بقيمة 9876543210 كقيمة historyId المعروفة الأخيرة لحالات الاستخدام المستقبلية.

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

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

يجب تأكيد استلام جميع الإشعارات. في حال استخدام عملية التسليم عبر الدفع في Webhook، سيؤدي الرد بنجاح (مثل 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 أيضًا قيودًا خاصة بها، وهي موضّحة بالتفصيل في مستندات الأسعار والحصص.