Method: spaces.messages.search

يبحث هذا الطلب عن الرسائل في Google Chat التي يمكن للمستخدم الذي يرسل الطلب الوصول إليها. ويعرض قائمة بالرسائل التي تطابق معايير البحث.

للبحث في جميع المساحات التي يمكن للمستخدم الوصول إليها، اضبط parent على spaces/-. يؤدي استخدام أي قيمة أخرى لـ parent إلى ظهور الخطأ INVALID_ARGUMENT. تحتوي الرسائل المعروضة على حقل name الذي يتضمّن اسم المورِد الكامل، بما في ذلك space معيّنة تتضمّن الرسالة.

لا تعرض واجهة برمجة التطبيقات هذه جميع أنواع الرسائل. لا يتم تضمين أنواع الرسائل المُدرَجة أدناه في الاستجابة. استخدِم messages.list لعرض جميع الرسائل.

  • الرسائل الخاصة التي تظهر للمستخدم الذي تم التحقّق من هويته
  • الرسائل التي تنشرها تطبيقات Chat في المساحات أو المحادثات الجماعية
  • الرسائل في الرسائل المباشرة لتطبيق Chat
  • الرسائل من المستخدمين المحظورين
  • الرسائل في المساحات التي كتمها المتصل

يتطلب مصادقة المستخدم باستخدام أحد نطاقات التفويض التالية:

  • https://www.googleapis.com/auth/chat.messages.readonly
  • https://www.googleapis.com/auth/chat.messages

طلب HTTP

POST https://chat.googleapis.com/v1/{parent=spaces/*}/messages:search

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

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

المعلمات
parent

string

الحقل مطلوب. اسم مورِد المساحة التي تريد البحث فيها

للبحث في جميع المساحات التي يمكن للمستخدم الوصول إليها، اضبط هذا الحقل على spaces/-. يؤدي استخدام أي قيمة أخرى لـ parent إلى ظهور الخطأ INVALID_ARGUMENT.

لقصر البحث على مساحة واحدة أو أكثر، استخدِم space.name أو space.display_name في filter.

نص الطلب

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

تمثيل JSON 
{
  "filter": string,
  "pageSize": integer,
  "pageToken": string,
  "orderBy": string,
  "view": enum (SearchMessagesView)
}
الحقول
filter

string

الحقل مطلوب. طلب بحث

يمكن أن يحدّد طلب البحث كلمة رئيسية واحدة أو أكثر للبحث، تُستخدَم لفلترة النتائج،

يمكنك أيضًا فلترة النتائج باستخدام حقول الرسائل التالية:

  • createTime: يقبل طابعًا زمنيًا بتنسيق RFC-3339 وعاملَي المقارنة المتوافقَين: < و>=.
  • sender.name: اسم مورِد المُرسِل (users/{user}). لا يتوافق هذا الحقل إلا مع =. يمكنك استخدام عنوان البريد الإلكتروني كاسم مستعار لـ {user}. على سبيل المثال، users/example@gmail.com، حيث example@gmail.com هو عنوان البريد الإلكتروني لمستخدم Google Chat.
  • space.name: اسم مورِد المساحة التي تم نشر الرسالة فيها (spaces/{space}). لا يتوافق هذا الحقل إلا مع =. إذا لم يتم ضبط هذا الفلتر، يتم إجراء البحث في جميع الرسائل المباشرة والمساحات التي يمكن للمستخدم الوصول إليها كعضو في مساحة.
  • space.display_name: يتوافق هذا الحقل مع عامل التشغيل : (يحتوي على) ويُفلتر المساحات استنادًا إلى تطابق جزئي لاسمها المعروض. تقتصر النتائج على أفضل خمس مساحات مطابقة. على سبيل المثال، يبحث space.display_name:Project عن الرسائل في أفضل خمس مساحات تحتوي أسماؤها المعروضة على الكلمة "Project".
  • attachment: يتوافق هذا الحقل مع عامل التشغيل :* (يحتوي على أي) للتحقّق من وجود مرفقات. إذا تم تحديد attachment:*، لا يتم عرض سوى الرسائل التي تحتوي على مرفق واحد على الأقل.
  • annotations.user_mentions.user.name: اسم مورِد المستخدم الذي تمت الإشارة إليه (users/{user}). لا يتوافق هذا الحقل إلا مع : (يحتوي على). على سبيل المثال: لا يعرض annotations.user_mentions.user.name:"users/1234567890" سوى الرسائل التي تحتوي على إشارة إلى المستخدم المحدّد. بدلاً من ذلك، يمكن استخدام الاسم المستعار me لفلترة الرسائل التي تشير إلى المستخدم الذي يرسل الطلب، على سبيل المثال: annotations.user_mentions.user.name:users/me. يمكنك أيضًا استخدام عنوان البريد الإلكتروني كاسم مستعار لـ {user}، على سبيل المثال، users/example@gmail.com.

لإجراء فلترة متقدّمة، تتوفّر أيضًا الدوال التالية:

  • has_link(): لا يعرض هذا الحقل سوى الرسائل التي تحتوي على رابط تشعّبي واحد على الأقل في نص الرسالة.
  • is_unread(): يفلتر هذا الحقل الرسائل التي قرأها المستخدم الذي يرسل الطلب.

يتطلّب استخدام الفلتر space.display_name أن تتضمّن بيانات الاعتماد التي يرسل بها الطلب أحد نطاقات الأذونات التالية:

  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.spaces

يتطلّب استخدام الفلتر is_unread() أن تتضمّن بيانات الاعتماد التي يرسل بها الطلب أحد نطاقات الأذونات التالية:

  • https://www.googleapis.com/auth/chat.users.readstate.readonly
  • https://www.googleapis.com/auth/chat.users.readstate

لا تتوافق الحقول المختلفة إلا مع عوامل التشغيل AND. أحد الأمثلة الصالحة هو sender.name = "users/1234567890" AND is_unread(). الكلمة AND اختيارية ويتم تضمينها ضمنيًا إذا تم حذفها. على سبيل المثال، sender.name = "users/1234567890" is_unread() صالحة وتعادل المثال السابق. أحد الأمثلة غير الصالحة هو sender.name = "users/1234567890" OR is_unread() لأنّ OR غير متوافق بين حقول مختلفة.

في الحقل نفسه:

  • createTime لا يتوافق إلا مع AND، ولا يمكن استخدامه إلا لتمثيل فترة، مثل createTime >= "2022-01-01T00:00:00+00:00" AND createTime < "2023-01-01T00:00:00+00:00".
  • sender.name لا يتوافق إلا مع عامل التشغيل OR، على سبيل المثال: sender.name = "users/1234567890" OR sender.name = "users/0987654321".
  • space.name لا يتوافق إلا مع عامل التشغيل OR، على سبيل المثال: space.name = "spaces/ABCDEFGH" OR space.name = "spaces/QWERTYUI".
  • space.display_name يتوافق مع عاملَي التشغيل AND وOR، ولكن ليس مع مزيج منهما. على سبيل المثال: يعرض space.display_name:Project AND space.display_name:Tasks الرسائل التي تكون في مساحات تحتوي أسماؤها المعروضة على الكلمتَين Project وTasks، بينما يعرض space.display_name:Project OR space.display_name:Tasks الرسائل التي تكون في مساحات تحتوي أسماؤها المعروضة على الكلمة Project أو Tasks أو كلتيهما.
  • annotations.user_mentions.user.name يتوافق مع عاملَي التشغيل AND و OR، ولكن ليس مع مزيج منهما. على سبيل المثال: لا يعرض annotations.user_mentions.user.name:"users/1234567890" AND annotations.user_mentions.user.name:"users/0987654321" سوى الرسائل التي تشير إلى كلا المستخدمَين، بينما يعرض annotations.user_mentions.user.name:"users/1234567890" OR annotations.user_mentions.user.name:"users/0987654321" الرسائل التي تشير إلى أحد المستخدمَين أو كليهما.

الأقواس مطلوبة لتمييز أسبقية عامل التشغيل عند الجمع بين عاملَي التشغيل AND وOR في طلب البحث نفسه. على سبيل المثال: (sender.name="users/me" OR sender.name="users/123456") AND is_unread(). في ما عدا ذلك، تكون الأقواس اختيارية.

طلبات البحث التالية صالحة:

"Pending reports" AND createTime >= "2023-01-01T00:00:00Z"

sender.name = "users/example@gmail.com"

annotations.user_mentions.user.name:"users/0987654321"

attachment:* AND space.name = "spaces/ABCDEFGH"

tasks AND is_unread() AND sender.name = "users/1234567890"

"things to do" "urgent"

(sender.name = "users/1234567890")
AND (createTime < "2023-05-01T00:00:00Z")

tasks AND space.name = "spaces/ABCDEFGH" AND has_link()

"project one" is_unread()

space.display_name:Project tasks

الحد الأقصى لطول طلب البحث هو 1,000 حرف.

يرفض الخادم طلبات البحث غير الصالحة ويعرض الخطأ INVALID_ARGUMENT.
pageSize

integer

اختياريّ. الحد الأقصى لعدد النتائج المطلوب عرضها قد تعرض الخدمة عددًا أقل من هذه القيمة.

إذا لم يتم تحديد هذه القيمة، يتم عرض 25 نتيجة على الأكثر.

الحد الأقصى للقيمة هو 100. إذا استخدمت قيمة أكبر من 100، يتم تغييرها تلقائيًا إلى 100.
pageToken

string

اختياريّ. رمز مميّز تم استلامه من طلب البحث السابق عن الرسائل يُرجى تقديم هذه المَعلمة لاسترداد الصفحة التالية.

عند تقسيم النتائج على صفحات، يجب أن تتطابق جميع المَعلمات الأخرى المقدَّمة مع الطلب الذي قدّم الرمز المميّز للصفحة. قد يؤدي تمرير قيم مختلفة إلى المَعلمات الأخرى إلى نتائج غير متوقّعة.
orderBy

string

اختياريّ. طريقة ترتيب قائمة النتائج

السمات المتوافقة التي يمكن الترتيب حسبها هي:

  • createTime: يرتب النتائج حسب وقت إنشاء الرسالة. القيمة التلقائية
  • relevance: يرتب النتائج حسب مدى الصلة بالموضوع.

الترتيب التلقائي هو createTime desc. لا يتوافق كل طلب بحث إلا مع ترتيب واحد (createTime أو relevance). لا يتوافق هذا الحقل إلا مع الترتيب التنازلي (desc)، ويجب تحديده بعد سمة الترتيب.
view

enum (SearchMessagesView)

اختياريّ. يحدّد نوع عرض نتائج البحث المطلوب إرجاعه. القيمة التلقائية هي SEARCH_MESSAGES_VIEW_BASIC.

نص الاستجابة

رسالة الاستجابة للبحث عن الرسائل

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

تمثيل JSON 
{
  "results": [
    {
      object (SearchMessageResult)
    }
  ],
  "nextPageToken": string
}
الحقول
results[]

object (SearchMessageResult)

قائمة بنتائج البحث التي تطابقت مع طلب البحث
nextPageToken

string

رمز مميّز يمكن استخدامه لاسترداد الصفحة التالية إذا كان هذا الحقل فارغًا، ما يعني أنّه لا توجد صفحات لاحقة.

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

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

  • https://www.googleapis.com/auth/chat.messages
  • https://www.googleapis.com/auth/chat.messages.readonly

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

SearchMessagesView

أنواع العرض المتوافقة مع نتائج البحث الجزئية

عمليات التعداد
SEARCH_MESSAGES_VIEW_UNSPECIFIED القيمة التلقائية أو القيمة التي لم يتم ضبطها ستستخدم واجهة برمجة التطبيقات العرض BASIC تلقائيًا.
SEARCH_MESSAGES_VIEW_BASIC لا يتضمّن هذا العرض في النتائج سوى الرسائل المطابقة، بدون أي بيانات وصفية إضافية. هذه هي القيمة الافتراضية.
SEARCH_MESSAGES_VIEW_FULL يتضمّن هذا العرض كل شيء في النتائج: الرسائل المطابقة والبيانات الوصفية الإضافية.

SearchMessageResult

نتيجة واحدة من عملية البحث عن الرسائل

تمثيل JSON 
{
  "message": {
    object (Message)
  },
  "spaceMuteSetting": enum (MuteSetting),
  "read": boolean
}
الحقول
message

object (Message)

الرسالة المطابقة
spaceMuteSetting

enum (MuteSetting)

إعدادات كتم صوت المساحة للمستخدم الذي يرسل الطلب، حيث تم نشر الرسالة يمكن أن يستخدم تطبيق المتصل هذه المعلومات لتحديد كيفية معالجة الرسالة استنادًا إلى ما إذا كان قد تم كتم صوت المساحة للمستخدم أم لا.

لا يتم عرض هذا الحقل إلا إذا كان عرض الطلب هو SEARCH_MESSAGES_VIEW_FULL وكانت بيانات الاعتماد التي يرسل بها الطلب تتضمّن نطاق الأذونات التالي:

  • https://www.googleapis.com/auth/chat.users.spacesettings
read

boolean

يشير إلى ما إذا كان المستخدم الذي يرسل الطلب قد قرأ الرسالة المطابقة

لا يتم عرض هذا الحقل إلا إذا كان عرض الطلب هو SEARCH_MESSAGES_VIEW_FULL وكانت بيانات الاعتماد التي يرسل بها الطلب تتضمّن أحد نطاقات الأذونات التالية:

  • https://www.googleapis.com/auth/chat.users.readstate.readonly
  • https://www.googleapis.com/auth/chat.users.readstate