Method: spaces.messages.search

ค้นหาข้อความใน Google Chat ที่ผู้ใช้ที่เรียกใช้มีสิทธิ์เข้าถึง แสดงรายการข้อความที่ตรงกับเกณฑ์การค้นหา

หากต้องการค้นหาในพื้นที่ทำงานทั้งหมดที่ผู้ใช้มีสิทธิ์เข้าถึง ให้ตั้งค่า parent เป็น spaces/- การใช้ค่าอื่นสำหรับ parent จะทำให้เกิดข้อผิดพลาด INVALID_ARGUMENT ข้อความที่แสดงจะมีช่อง name ที่ระบุชื่อทรัพยากรแบบเต็ม ซึ่งรวมถึง space ที่ข้อความนั้นอยู่

API นี้จะไม่แสดงข้อความทุกประเภท ข้อความประเภทที่ระบุไว้ด้านล่างจะไม่รวมอยู่ในการตอบกลับ ใช้ messages.list เพื่อแสดงข้อความทั้งหมด

  • ข้อความส่วนตัวที่ผู้ใช้ที่ตรวจสอบสิทธิ์แล้วมองเห็น
  • ข้อความที่โพสต์โดยแอป Chat ในพื้นที่ทำงานหรือแชทเป็นกลุ่ม
  • ข้อความใน DM ของแอป 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

พารามิเตอร์เส้นทาง

พารามิเตอร์
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: ยอมรับการประทับเวลาในรูปแบบ RFC-3339 และโอเปอเรเตอร์เปรียบเทียบที่รองรับคือ: < และ >=
  • sender.name: ชื่อทรัพยากรของผู้ส่ง (users/{user}) รองรับเฉพาะ = คุณสามารถใช้อีเมลเป็นชื่อแทนสำหรับ {user} เช่น users/example@gmail.com โดยที่ example@gmail.com คืออีเมลของผู้ใช้ Google Chat
  • space.name: ชื่อทรัพยากรของพื้นที่ทำงานที่โพสต์ข้อความ (spaces/{space}) รองรับเฉพาะ = หากไม่ได้ตั้งค่าตัวกรองนี้ ระบบจะทำการค้นหาในข้อความส่วนตัวและพื้นที่ทำงานทั้งหมดที่ผู้ใช้มีสิทธิ์เข้าถึงในฐานะสมาชิกพื้นที่ทำงาน
  • space.display_name: รองรับโอเปอเรเตอร์ : (มี) และกรองพื้นที่ทำงานตามการจับคู่บางส่วนของชื่อที่แสดง ผลลัพธ์จะจำกัดไว้ที่พื้นที่ทำงาน 5 รายการแรกที่ตรงกัน เช่น space.display_name:Project จะค้นหาข้อความในพื้นที่ทำงาน 5 รายการแรกที่มีคำว่า "Project" ในชื่อที่แสดง
  • attachment: รองรับโอเปอเรเตอร์ :* (มี) เพื่อตรวจสอบว่ามีไฟล์แนบหรือไม่ หากระบุ attachment:* ระบบจะแสดงเฉพาะข้อความที่มีไฟล์แนบอย่างน้อย 1 ไฟล์
  • 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(): แสดงเฉพาะข้อความที่มีไฮเปอร์ลิงก์อย่างน้อย 1 รายการในข้อความ
  • 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 หรือทั้ง 2 อย่าง
  • annotations.user_mentions.user.name รองรับโอเปอเรเตอร์ AND และ OR แต่ไม่รองรับการใช้ร่วมกัน เช่น annotations.user_mentions.user.name:"users/1234567890" AND annotations.user_mentions.user.name:"users/0987654321" จะแสดงเฉพาะข้อความที่กล่าวถึงผู้ใช้ทั้ง 2 ราย ในขณะที่ annotations.user_mentions.user.name:"users/1234567890" OR annotations.user_mentions.user.name:"users/0987654321" จะแสดงข้อความที่กล่าวถึงผู้ใช้รายใดรายหนึ่งหรือทั้ง 2 ราย

ต้องใส่วงเล็บเพื่อแยกความกำกวมของลำดับความสำคัญของโอเปอเรเตอร์เมื่อรวมโอเปอเรเตอร์ 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: จัดเรียงผลลัพธ์ตามความเกี่ยวข้อง ( Developer Preview)

การจัดลำดับเริ่มต้นคือ 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