قائمة بأرقام تعريف التصنيفات التي تريد تقييد الإشعارات بشأنها إذا لم يتم تحديد أيّ تغييرات، يتم تطبيق جميع التغييرات تلقائيًا. في حال تحديدها، يتم تحديد التصنيفات المطلوبة لإنشاء إشعار فوري.
تم تحديد سلوك الفلترة لـ labelIds list. تم إيقاف هذا الحقل نهائيًا لأنّه كان يتسبب في سلوك غير صحيح في بعض الحالات. استخدِم labelFilterBehavior بدلاً منه.
تم تحديد سلوك الفلترة لـ labelIds list. يحلّ هذا الحقل محلّ labelFilterAction، وفي حال ضبطه، يتم تجاهل labelFilterAction.
topicName
string
اسم موضوع مؤهَّل بالكامل لواجهة برمجة التطبيقات Google Cloud Pub/Sub API لنشر الأحداث عليه يجب أن يكون اسم الموضوع هذا متوفّرًا في Cloud Pub/Sub، ويجب أن تكون قد منحت Gmail إذن "النشر" عليه. على سبيل المثال، "projects/معرّف-مشروعي/topics/اسم-موضوعي" (باستخدام تنسيق تسمية المواضيع في الإصدار 1 من Cloud Pub/Sub).
يُرجى العلم أنّ الجزء my-project-identifier يجب أن يتطابق تمامًا مع معرّف مشروعك كمطوّر على Google (الذي ينفذ طلب الساعة هذا).
نص الاستجابة
الردّ على إشعار فوري على الساعة
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
وقت إيقاف Gmail لإرسال إشعارات بشأن تعديلات صندوق البريد (بالمللي ثانية من بداية حساب الوقت) يُرجى الاتصال بالرقم watch مرة أخرى قبل هذه الفترة لتجديد اشتراك الساعة.
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["- [HTTP request](#body.HTTP_TEMPLATE)\n- [Path parameters](#body.PATH_PARAMETERS)\n- [Request body](#body.request_body)\n - [JSON representation](#body.request_body.SCHEMA_REPRESENTATION)\n- [Response body](#body.response_body)\n - [JSON representation](#body.WatchResponse.SCHEMA_REPRESENTATION)\n- [Authorization scopes](#body.aspect)\n- [LabelFilterAction](#LabelFilterAction)\n\nSet up or update a push notification watch on the given user mailbox.\n\nHTTP request\n\n`POST https://gmail.googleapis.com/gmail/v1/users/{userId}/watch`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\nPath parameters\n\n| Parameters ||\n|----------|-----------------------------------------------------------------------------------------------------------|\n| `userId` | `string` The user's email address. The special value `me` can be used to indicate the authenticated user. |\n\nRequest body\n\nThe request body contains data with the following structure:\n\n| JSON representation |\n|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"labelIds\": [ string ], \"labelFilterAction\": enum (/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction), \"labelFilterBehavior\": enum (/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction), \"topicName\": string } ``` |\n\n| Fields ||\n|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `labelIds[]` | `string` List of labelIds to restrict notifications about. By default, if unspecified, all changes are pushed out. If specified then dictates which labels are required for a push notification to be generated. |\n| `labelFilterAction` **(deprecated)** | `enum (`[LabelFilterAction](/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction)`)` Filtering behavior of `labelIds list` specified. This field is deprecated because it caused incorrect behavior in some cases; use `labelFilterBehavior` instead. |\n| `labelFilterBehavior` | `enum (`[LabelFilterAction](/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction)`)` Filtering behavior of `labelIds list` specified. This field replaces `labelFilterAction`; if set, `labelFilterAction` is ignored. |\n| `topicName` | `string` A fully qualified Google Cloud Pub/Sub API topic name to publish the events to. This topic name **must** already exist in Cloud Pub/Sub and you **must** have already granted gmail \"publish\" permission on it. For example, \"projects/my-project-identifier/topics/my-topic-name\" (using the Cloud Pub/Sub \"v1\" topic naming format). Note that the \"my-project-identifier\" portion must exactly match your Google developer project id (the one executing this watch request). |\n\nResponse body Push notification watch response.\n\nIf successful, the response body contains data with the following structure:\n\n| JSON representation |\n|-------------------------------------------------------|\n| ``` { \"historyId\": string, \"expiration\": string } ``` |\n\n| Fields ||\n|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `historyId` | `string` The ID of the mailbox's current history record. |\n| `expiration` | `string (`[int64](https://developers.google.com/discovery/v1/type-format)` format)` When Gmail will stop sending notifications for mailbox updates (epoch millis). Call `watch` again before this time to renew the watch. |\n\nAuthorization scopes\n\nRequires one of the following OAuth scopes:\n\n- `https://mail.google.com/`\n- `\n https://www.googleapis.com/auth/gmail.modify`\n- `\n https://www.googleapis.com/auth/gmail.readonly`\n- `\n https://www.googleapis.com/auth/gmail.metadata`\n\nFor more information, see the [Authorization guide](/workspace/guides/configure-oauth-consent).\n\nLabelFilterAction Filtering behavior of labelIds list specified.\n\n| Enums ||\n|-----------|---------------------------------------------------------------------------------------------|\n| `include` | Only get push notifications for message changes relating to labelIds specified. |\n| `exclude` | Get push notifications for all message changes except those relating to labelIds specified. |"]]
