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,
  "markupSyntax": enum (MarkupSyntax),
  "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 عن الرسائل في أول خمس مساحات تحتوي على الكلمة "مشروع" في أسمائها المعروضة.
  • ‫space.space_type: تمثّل هذه السمة نوع المساحة. يُسمح فقط بالقيمة =. على سبيل المثال، تعرض space.space_type="DIRECT_MESSAGE" الرسائل الواردة من الرسائل المباشرة فقط. القيم المحتمَلة هي DIRECT_MESSAGE وGROUP_CHAT وSPACE.
  • 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 أو space.space_type أن تتضمّن بيانات الاعتماد الخاصة بالاتصال أحد نطاقات الأذونات التالية:

  • 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 أو كليهما.
  • لا تتوافق space.space_type إلا مع عامل التشغيل OR، على سبيل المثال: space.space_type = "DIRECT_MESSAGE" OR space.space_type = "GROUP_CHAT".
  • تتيح 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)، ويجب تحديده بعد سمة الترتيب.
markupSyntax

enum (MarkupSyntax)

اختيارية: تحدّد هذه السمة بنية الإخراج المطلوبة لحقل formattedText رسالة محادثة.
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