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

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

نص الاستجابة

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

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

تمثيل 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

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

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