Method: spaces.messages.search

Searches for messages in Google Chat that the calling user has access to. Returns a list of messages matching the search criteria.

To search across all spaces the user has access to, set parent to spaces/-. Using any other value for parent results in an INVALID_ARGUMENT error. The returned messages have their name field populated with the full resource name, which includes the specific space in which the message resides.

This API doesn't return all message types. The types of messages listed below aren't included in the response. Use messages.list to list all messages.

  • Private Messages that are visible to the authenticated user.
  • Messages posted by Chat apps in spaces or group chats.
  • Messages in a Chat app DM.
  • Messages from blocked users.
  • Messages in spaces that the caller has muted.

Requires user authentication with one of the following authorization scopes:

  • 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

หากต้องการจำกัดการค้นหาให้อยู่ในพื้นที่ทำงานอย่างน้อย 1 แห่ง ให้ใช้ space.name หรือ space.display_name ใน filter

เนื้อหาคำขอ

เนื้อหาของคำขอมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้

การแสดง JSON 
{
  "filter": string,
  "pageSize": integer,
  "pageToken": string,
  "orderBy": string,
  "view": enum (SearchMessagesView)
}
ช่อง
filter

string

ต้องระบุ คำค้นหา

การค้นหาสามารถระบุคีย์เวิร์ดในการค้นหาอย่างน้อย 1 รายการ ซึ่งใช้เพื่อกรองผลลัพธ์

นอกจากนี้ คุณยังกรองผลลัพธ์โดยใช้ช่องข้อความต่อไปนี้ได้ด้วย

  • createTime: Accepts a timestamp in RFC-3339 format and the supported comparison operators are: < and >=.
  • sender.name: The resource name of the sender (users/{user}). Only supports =. You can use the e-mail as an alias for {user}. For example, users/example@gmail.com, where example@gmail.com is the e-mail of the Google Chat user.
  • space.name: The resource name of the space where the message is posted. (spaces/{space}). Only supports =. If this filter is not set, the search is performed across all direct messages and spaces the user has access to as a space member.
  • space.display_name: Supports the operator : (has) and filters spaces based on a partial match of their display name. Results are limited to the top five space matches. For example, space.display_name:Project searches for messages in the top five spaces that contain the word "Project" in their display names.
  • attachment: Supports the operator :* (has any) to check for the presence of attachments. If attachment:* is specified, only messages that have at least one attachment are returned.
  • annotations.user_mentions.user.name: The resource name of the mentioned user (users/{user}). Only supports : (has). For example: annotations.user_mentions.user.name:"users/1234567890" returns only messages that contain a mention to the specified user. Alternatively, the alias me can be used to filter for messages that mention the caller user, for example: annotations.user_mentions.user.name:users/me. You can also use the e-mail as an alias for {user}, for example, users/example@gmail.com.

For advanced filtering, the following functions are also available:

  • has_link(): Returns only messages that have at least one hyperlink in the message text.
  • is_unread(): Filters out messages that have been read by the calling user.

Using the space.display_name filter requires that the calling credentials include one of the following authorization scopes:

  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.spaces

Using the is_unread() filter requires that the calling credentials include one of the following authorization scopes:

  • https://www.googleapis.com/auth/chat.users.readstate.readonly
  • https://www.googleapis.com/auth/chat.users.readstate

Across different fields, only AND operators are supported. A valid example is sender.name = "users/1234567890" AND is_unread(). The word AND is optional and is implied if omitted. For example, sender.name = "users/1234567890" is_unread() is valid and is equivalent to the previous example. An invalid example is sender.name = "users/1234567890" OR is_unread() because OR is not supported between different fields.

Among the same field:

  • createTime supports only AND, and can only be used to represent an interval, such as createTime >= "2022-01-01T00:00:00+00:00" AND createTime < "2023-01-01T00:00:00+00:00".
  • sender.name supports only the OR operator, for example: sender.name = "users/1234567890" OR sender.name = "users/0987654321".
  • space.name supports only the OR operator, for example: space.name = "spaces/ABCDEFGH" OR space.name = "spaces/QWERTYUI".
  • space.display_name supports the operators AND and OR, but not a mix of both. For example: space.display_name:Project AND space.display_name:Tasks returns messages that are in spaces with display names containing both Project and Tasks, whereas space.display_name:Project OR space.display_name:Tasks returns messages that are in spaces with display names containing either Project or Tasks or both.
  • annotations.user_mentions.user.name supports the operators AND and OR, but not a mix of both. For example: annotations.user_mentions.user.name:"users/1234567890" AND annotations.user_mentions.user.name:"users/0987654321" returns only messages that mentions both users, whereas annotations.user_mentions.user.name:"users/1234567890" OR annotations.user_mentions.user.name:"users/0987654321" returns messages that mention either user or both.

Parentheses are required to disambiguate operator precedence when combining AND and OR operators in the same query. For example: (sender.name="users/me" OR sender.name="users/123456") AND is_unread(). Otherwise, parentheses are optional.

The following example queries are valid:

"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

The maximum query length is 1,000 characters.

Invalid queries are rejected by the server with an INVALID_ARGUMENT error.
pageSize

integer

ไม่บังคับ จำนวนผลลัพธ์สูงสุดที่จะแสดง บริการอาจแสดงผลลัพธ์น้อยกว่าค่านี้

หากไม่ได้ระบุไว้ ระบบจะแสดงผลลัพธ์ไม่เกิน 25 รายการ

ค่าสูงสุดคือ 100 หากคุณใช้ค่ามากกว่า 100 ระบบจะเปลี่ยนเป็น 100 โดยอัตโนมัติ
pageToken

string

ไม่บังคับ โทเค็นที่ได้รับจากการเรียกใช้การค้นหาข้อความครั้งก่อน ระบุพารามิเตอร์นี้เพื่อดึงข้อมูลหน้าถัดไป

เมื่อแบ่งหน้า พารามิเตอร์อื่นๆ ทั้งหมดที่ระบุควรตรงกับการเรียกใช้ที่ให้โทเค็นหน้า การส่งค่าอื่นไปยังพารามิเตอร์อื่นๆ อาจทำให้เกิดผลลัพธ์ที่ไม่คาดคิด
orderBy

string

ไม่บังคับ วิธีจัดเรียงรายการผลลัพธ์

แอตทริบิวต์ที่รองรับสำหรับการจัดเรียงมีดังนี้

  • createTime: Sorts the results by the time of the message creation. ค่าเริ่มต้น
  • relevance: Sorts the results by relevance.

การจัดเรียงเริ่มต้นคือ createTime desc ระบบรองรับการจัดเรียงเพียงรายการเดียวต่อการค้นหา (createTime หรือ relevance) ระบบรองรับเฉพาะการจัดเรียงจากมากไปน้อย (desc) และต้องระบุหลังแอตทริบิวต์การจัดเรียง
view

enum (SearchMessagesView)

ไม่บังคับ Specifies what kind of search results view to return. The default is SEARCH_MESSAGES_VIEW_BASIC.

เนื้อหาการตอบกลับ

Response message for searching messages.

หากทำสำเร็จ เนื้อหาการตอบกลับจะมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้

การแสดง JSON 
{
  "results": [
    {
      object (SearchMessageResult)
    }
  ],
  "nextPageToken": string
}
ช่อง
results[]

object (SearchMessageResult)

รายการผลการค้นหาที่ตรงกับคำค้นหา
nextPageToken

string

โทเค็นที่ใช้ดึงข้อมูลหน้าถัดไป หากช่องนี้ว่างเปล่า แสดงว่าไม่มีหน้าถัดไป

ขอบเขตการให้สิทธิ์

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/chat.messages
  • https://www.googleapis.com/auth/chat.messages.readonly

For more information, see the Authorization guide.

SearchMessagesView

The kinds of view that are supported for partial search results.

Enum
SEARCH_MESSAGES_VIEW_UNSPECIFIED ค่าเริ่มต้น / ค่าที่ไม่ได้ตั้งค่า API จะตั้งค่าเริ่มต้นเป็นมุมมอง BASIC
SEARCH_MESSAGES_VIEW_BASIC Includes only the matched messages in the results, but no additional metadata. นี่คือค่าเริ่มต้น
SEARCH_MESSAGES_VIEW_FULL Includes everything in the results: the matched messages and additional metadata.

SearchMessageResult

A single result item from a message search.

การแสดง 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

Indicates if the matched message is read by the calling user.

จะแสดงผลก็ต่อเมื่อมุมมองคำขอเป็น SEARCH_MESSAGES_VIEW_FULL และข้อมูลเข้าสู่ระบบของผู้เรียกใช้มี ขอบเขตการให้สิทธิ์ต่อไปนี้ขอบเขตใดขอบเขตหนึ่ง

  • https://www.googleapis.com/auth/chat.users.readstate.readonly
  • https://www.googleapis.com/auth/chat.users.readstate