Method: users.watch

إعداد أو تعديل إشعار فوري على صندوق بريد المستخدم المحدّد

طلب 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 لنشر الأحداث فيه يجب أن يكون اسم الموضوع هذا متوفّرًا في 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

لمزيد من المعلومات، يُرجى الاطّلاع على OAuth 2.0 Overview.

LabelFilterAction

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

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