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

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

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

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

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

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

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

إنشاء موضوع

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

إنشاء اشتراك

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

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

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

لإجراء ذلك، امنح امتيازات publish إلى gmail-api-push@system.gserviceaccount.com. يمكنك إجراء ذلك باستخدام Cloud Pub/Sub permissions console في the Google Cloud console باتّباع تعليمات access control instructions هذه.

قد يمنعك إعداد مشاركة النطاق المقيّدة في مؤسستك من منح أذونات النشر. لحلّ هذه المشكلة، يمكنك ضبط استثناء لحساب الخدمة هذا.

الحصول على تعديلات صندوق بريد 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 API.

بالإضافة إلى ذلك، يؤدي طلب 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 API.

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

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

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

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

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

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

إيقاف تلقّي التعديلات على صندوق البريد

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

القيود

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

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

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

الموثوقية

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

قيود Cloud Pub/Sub

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