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: תומך באופרטור : (has) ומסנן את המרחבים על סמך התאמה חלקית של השם המוצג שלהם. התוצאות מוגבלות לחמשת המרחבים התואמים ביותר. לדוגמה, space.display_name:Project מחפש הודעות בחמשת המרחבים העליונים שכוללים את המילה Project בשמות המוצגים שלהם.
• space.space_type: סוג המרחב. יש תמיכה רק ב-=. לדוגמה, space.space_type="DIRECT_MESSAGE" מחזיר רק הודעות מצ'אטים ישירים. הערכים האפשריים הם DIRECT_MESSAGE, GROUP_CHAT ו-SPACE.
• ‫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 או 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.

integer

אופציונלי. המספר המקסימלי של תוצאות שיוחזרו. יכול להיות שהשירות יחזיר פחות מהערך הזה.

אם לא מציינים ערך, מוחזרות לכל היותר 25 תוצאות.

הערך המקסימלי הוא 100. אם משתמשים בערך גבוה מ-100, הוא משתנה אוטומטית ל-100.

string

אופציונלי. טוקן שהתקבל מקריאה קודמת של הודעות חיפוש. צריך להזין את הפרמטר הזה כדי לאחזר את הדף הבא.

כשמבצעים חלוקה לעמודים, כל הפרמטרים האחרים שסופקו צריכים להיות זהים לקריאה שסיפקה את הטוקן של הדף. העברת ערכים שונים לפרמטרים האחרים עלולה להוביל לתוצאות לא צפויות.

string

אופציונלי. איך רשימת התוצאות מסודרת.

אפשר להשתמש במאפיינים הבאים כדי להגדיר את סדר המיון:

• ‫createTime: מיון התוצאות לפי שעת יצירת ההודעה. ערך ברירת המחדל.
• ‫relevance: מיון התוצאות לפי רלוונטיות. (science תצוגה מקדימה למפתחים)

ברירת המחדל היא createTime desc. יש תמיכה רק בהזמנה אחת לכל שאילתה (createTime או relevance). אפשר להשתמש רק בסדר יורד (desc), וחובה לציין אותו אחרי מאפיין הסדר.

enum (MarkupSyntax)

אופציונלי. מציין את תחביר הפלט הרצוי בשדה formattedText של הודעת צ'אט.

enum (SearchMessagesView)

אופציונלי. מציין איזה סוג של תצוגת תוצאות חיפוש להחזיר. ערך ברירת המחדל הוא SEARCH_MESSAGES_VIEW_BASIC.