Method: users.watch

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

طلب HTTP

POST https://gmail.googleapis.com/gmail/v1/users/{userId}/watch

يستخدم عنوان URL بنية تحويل الترميز إلى gRPC.

مَعلمات المسار

المَعلمات
userId

string

عنوان البريد الإلكتروني للمستخدم يمكن استخدام القيمة الخاصة me للإشارة إلى المستخدم الذي تم التحقّق من هويته.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

تمثيل JSON 
{
  "labelIds": [
    string
  ],
  "labelFilterAction": enum (LabelFilterAction),
  "labelFilterBehavior": enum (LabelFilterAction),
  "topicName": string
}
الحقول
labelIds[]

string

قائمة بمعرّفات التصنيفات التي يجب حظر الإشعارات بشأنها يتم تلقائيًا إرسال إشعارات بشأن جميع التغييرات ما لم يتم تحديدها. إذا تم تحديدها، فإنّها تحدّد التصنيفات المطلوبة لإنشاء إشعار فوري.
labelFilterAction
(deprecated)

enum (LabelFilterAction)

سلوك الفلترة لـ labelIds list المحدّدة تم إيقاف هذا الحقل نهائيًا لأنّه كان يتسبب في سلوك غير صحيح في بعض الحالات، لذا يُرجى استخدام labelFilterBehavior بدلاً منه.
labelFilterBehavior

enum (LabelFilterAction)

سلوك الفلترة لـ labelIds list المحدّدة يحلّ هذا الحقل محلّ labelFilterAction، وإذا تم ضبطه، يتم تجاهل labelFilterAction.
topicName

string

اسم موضوع مؤهّل بالكامل في Google Cloud Pub/Sub API لنشر الأحداث فيه يجب أن يكون اسم الموضوع هذا متوفّرًا في Cloud Pub/Sub، ويجب أن تكون قد منحت Gmail إذن "النشر" عليه. على سبيل المثال، "projects/my-project-identifier/topics/my-topic-name" (باستخدام تنسيق تسمية المواضيع "v1" في Cloud Pub/Sub)

يُرجى العِلم أنّ جزء "my-project-identifier" يجب أن يتطابق تمامًا مع رقم تعريف مشروع المطوّر في Google (المشروع الذي ينفّذ طلب المراقبة هذا).

نص الاستجابة

استجابة طلب مراقبة الإشعارات الفورية

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "historyId": string,
  "expiration": string
}
الحقول
historyId

string

رقم تعريف سجلّ سجلّ التعديلات الحالي في البريد الإلكتروني
expiration

string (int64 format)

الوقت الذي سيتوقف فيه Gmail عن إرسال إشعارات بشأن تعديلات صندوق البريد الإلكتروني (بالملّي ثانية منذ بداية الحقبة) يُرجى طلب watch مرة أخرى قبل هذا الوقت لتجديد المراقبة.

نطاقات الأذونات

يجب توفير أحد نطاقات OAuth التالية:

  • https://mail.google.com/
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/gmail.metadata

لمزيد من المعلومات، يُرجى الاطّلاع على دليل التفويض.

LabelFilterAction

سلوك الفلترة لقائمة labelIds المحدّدة

عمليات التعداد
include الحصول على إشعارات فورية فقط بشأن تغييرات الرسائل المتعلقة بمعرّفات التصنيفات المحدّدة
exclude الحصول على إشعارات فورية بشأن جميع تغييرات الرسائل باستثناء تلك المتعلقة بمعرّفات التصنيفات المحدّدة