Method: spaces.messages.search

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.

integer

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

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

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

string

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

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

string

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

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

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

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

enum (SearchMessagesView)

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