Method: spaces.messages.search

پیام‌هایی را در گوگل چت جستجو می‌کند که کاربر تماس‌گیرنده به آنها دسترسی دارد. فهرستی از پیام‌هایی را که با معیارهای جستجو مطابقت دارند، برمی‌گرداند.

برای جستجو در تمام فضاهایی که کاربر به آنها دسترسی دارد، parent برابر با spaces/- قرار دهید. استفاده از هر مقدار دیگری برای parent منجر به خطای INVALID_ARGUMENT می‌شود. فیلد name پیام‌های برگشتی با نام کامل منبع پر شده است که شامل space خاصی است که پیام در آن قرار دارد.

این API همه انواع پیام‌ها را برنمی‌گرداند. انواع پیام‌های فهرست‌شده در زیر در پاسخ گنجانده نشده‌اند. messages.list برای فهرست کردن همه پیام‌ها استفاده کنید.

  • پیام‌های خصوصی که برای کاربر احراز هویت شده قابل مشاهده هستند.
  • پیام‌های ارسال‌شده توسط برنامه‌های چت در فضاها یا چت‌های گروهی.
  • پیام‌ها در یک برنامه چت، دایرکت.
  • پیام‌های کاربران مسدود شده
  • پیام‌هایی در فضاهایی که تماس‌گیرنده آنها را بی‌صدا کرده است.

نیاز به احراز هویت کاربر با یکی از حوزه‌های مجوز زیر دارد:

  • 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 از سینتکس Transcoding در 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 : از عملگر : (has) پشتیبانی می‌کند و فضاها را بر اساس تطابق جزئی با نام نمایشی آنها فیلتر می‌کند. نتایج به پنج تطابق برتر فضا محدود می‌شوند. به عنوان مثال، space.display_name:Project پیام‌هایی را در پنج فضای برتر که حاوی کلمه "Project" در نام نمایشی خود هستند، جستجو می‌کند.
  • attachment : از عملگر :* (دارای هرگونه) برای بررسی وجود پیوست‌ها پشتیبانی می‌کند. اگر attachment:* مشخص شده باشد، فقط پیام‌هایی که حداقل یک پیوست دارند، برگردانده می‌شوند.
  • annotations.user_mentions.user.name : نام منبع کاربر ذکر شده ( users/{user} ). فقط از : (has) پشتیبانی می‌کند. به عنوان مثال: 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

حداکثر طول پرس و جو ۱۰۰۰ کاراکتر است.

درخواست‌های نامعتبر توسط سرور با خطای INVALID_ARGUMENT رد می‌شوند.

pageSize

integer

اختیاری. حداکثر تعداد نتایجی که باید برگردانده شود. سرویس ممکن است کمتر از این مقدار را برگرداند.

اگر مشخص نشده باشد، حداکثر ۲۵ عدد برگردانده می‌شود.

حداکثر مقدار ۱۰۰ است. اگر از مقداری بیش از ۱۰۰ استفاده کنید، به طور خودکار به ۱۰۰ تغییر می‌کند.

pageToken

string

اختیاری. یک توکن، که از فراخوانی پیام‌های جستجوی قبلی دریافت شده است. این پارامتر را برای بازیابی صفحه بعدی ارائه دهید.

هنگام صفحه‌بندی، تمام پارامترهای دیگر ارائه شده باید با فراخوانی که توکن صفحه را ارائه داده است، مطابقت داشته باشند. ارسال مقادیر متفاوت به سایر پارامترها ممکن است منجر به نتایج غیرمنتظره‌ای شود.

orderBy

string

اختیاری. نحوه‌ی مرتب‌سازی فهرست نتایج.

ویژگی‌های پشتیبانی‌شده برای سفارش بر اساس موارد زیر هستند:

  • createTime : نتایج را بر اساس زمان ایجاد پیام مرتب می‌کند. مقدار پیش‌فرض.
  • relevance : نتایج را بر اساس مرتبط بودن مرتب می‌کند.

ترتیب پیش‌فرض createTime desc است. فقط یک ترتیب برای هر پرس‌وجو ( createTime یا relevance ) پشتیبانی می‌شود. فقط ترتیب نزولی ( desc ) پشتیبانی می‌شود و باید بعد از ویژگی order مشخص شود.

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

برای اطلاعات بیشتر، به راهنمای مجوز مراجعه کنید.

جستجوی پیام‌هامشاهده

انواع نماهایی که برای نتایج جستجوی جزئی پشتیبانی می‌شوند.

انوم‌ها
SEARCH_MESSAGES_VIEW_UNSPECIFIED مقدار پیش‌فرض / تنظیم نشده. API به طور پیش‌فرض به نمای BASIC خواهد رفت.
SEARCH_MESSAGES_VIEW_BASIC فقط پیام‌های منطبق در نتایج را شامل می‌شود، اما هیچ فراداده اضافی ندارد. این مقدار پیش‌فرض است.
SEARCH_MESSAGES_VIEW_FULL شامل همه موارد موجود در نتایج می‌شود: پیام‌های منطبق و فراداده‌های اضافی.

نتیجه پیام جستجو

یک مورد نتیجه واحد از جستجوی پیام.

نمایش 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