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

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

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

ملاحظة: بالنسبة إلى الإشعارات على الأجهزة المملوكة للمستخدمين (مثل التطبيقات المثبَّتة أو الأجهزة الجوّالة أو المتصفّحات)، لا يزال دليل مزامنة العملاء مع Gmail API الذي يستند إلى الاستطلاع هو الطريقة المقترَحة لاسترداد التحديثات.

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

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

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

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

إنشاء موضوع

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

إنشاء اشتراك

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

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

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

لإجراء ذلك، امنح publish أذونات مميّزة إلى [e-mail]. يمكنك إجراء ذلك باستخدام وحدة تحكّم أذونات 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": "[e-mail]", "historyId": "9876543210"}

يمكنك بعد ذلك استخدام طريقة history.list للحصول على تفاصيل التغيير للمستخدم منذ آخر وقت معروف historyId، كما هو موضّح في مزامنة العملاء مع Gmail API.

على سبيل المثال، استخدِم طريقة 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 أيضًا قيودًا خاصة بها، وهي موضّحة بالتفصيل في مستندات الأسعار والحصص.