Method: spaces.messages.search

חיפוש הודעות ב-Google Chat שהמשתמש המתקשר יכול לגשת אליהן. הפונקציה מחזירה רשימה של הודעות שתואמות לקריטריונים של החיפוש.

כדי לחפש בכל המרחבים שלמשתמש יש גישה אליהם, מגדירים את parent ל-spaces/-. שימוש בכל ערך אחר עבור parent יוביל לשגיאה INVALID_ARGUMENT. ההודעות שמוחזרות כוללות את השדה name עם שם המשאב המלא, שכולל את space הספציפי שבו ההודעה נמצאת.

ה-API הזה לא מחזיר את כל סוגי ההודעות. סוגי ההודעות שמפורטים בהמשך לא נכללים בתשובה. משתמשים ב-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 Transcoding.

פרמטרים של נתיב

פרמטרים
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

האורך המקסימלי של שאילתה הוא 1,000 תווים.

השרת דוחה שאילתות לא תקינות עם שגיאת INVALID_ARGUMENT.
pageSize

integer

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

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

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

string

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

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

string

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

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

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

סדר ברירת המחדל הוא createTime desc. יש תמיכה רק בסדר אחד לכל שאילתה (createTime או relevance). אפשר להשתמש רק בסדר יורד (desc), והוא צריך להופיע אחרי מאפיין הסדר.
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

סוגי התצוגה שנתמכים לתוצאות חיפוש חלקיות.

טיפוסים בני מנייה (enum)
SEARCH_MESSAGES_VIEW_UNSPECIFIED ערך ברירת המחדל או הערך שלא הוגדר. ה-API יוגדר כברירת מחדל לתצוגה 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