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 پیام‌ها را در پنج فضای برتر که حاوی کلمه «پروژه» در نام نمایشی‌شان هستند جستجو می‌کند.
• 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

حداکثر طول پُرسمان ۱۰۰۰ نویسه است.

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

integer

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

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

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

string

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

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

string

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

مشخصه‌های پشتیبانی‌شده برای مرتب‌سازی عبارت‌اند از:

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

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

enum (MarkupSyntax)

اختیاری. نحو خروجی موردنظر را برای فیلد formattedText پیام Chat مشخص می‌کند.

enum (SearchMessagesView)

اختیاری. مشخص می‌کند چه نوع نمای نتایج جستجویی برگردانده شود. پیش‌فرض SEARCH_MESSAGES_VIEW_BASIC است.