ضبط الإشعارات الفورية باستخدام Gmail API

يوضّح هذا المستند كيفية إدارة الإشعارات الفورية باستخدام Gmail API.

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

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

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

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

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

إنشاء موضوع

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

إنشاء اشتراك

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

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

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

لإجراء ذلك، امنح publish أذونات إلى gmail-api-push@system.gserviceaccount.com. يمكنك إجراء ذلك باستخدام وحدة تحكّم أذونات Cloud Pub/Sub في Google Cloud 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، يُرجى الرجوع إلى مزامنة البرامج مع Gmail.

بالإضافة إلى ذلك، يؤدي إجراء مكالمة watch ناجحة إلى إرسال إشعار على الفور إلى موضوع النشر/الاشتراك في Cloud Pub/Sub.

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

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

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

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

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

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

يجب تأكيد جميع الإشعارات. في حال استخدام عملية التسليم بالدفع عبر Webhook، يعني الرد بنجاح (مثلاً، HTTP 200) تأكيد استلام الإشعار.

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

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

إيقاف تلقّي آخر الأخبار بشأن صندوق البريد

لإيقاف تلقّي إشعارات بشأن صندوق بريد، استخدِم طريقة stop. من المفترض أن يتوقف ظهور جميع الإشعارات الجديدة خلال بضع دقائق.

القيود

في ما يلي القيود المفروضة على استخدام الإشعارات الفورية المُرسلة من الخادم:

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

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

الموثوقية

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

قيود Cloud Pub/Sub

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