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,
  "markupSyntax": enum (MarkupSyntax),
  "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 พื้นที่แรกที่มีคำว่า "โปรเจ็กต์" ในชื่อที่แสดง
  • space.space_type: ประเภทพื้นที่ทำงาน รองรับเฉพาะ = เช่น space.space_type="DIRECT_MESSAGE" จะแสดงเฉพาะข้อความจากข้อความส่วนตัว โดยค่าที่เลือกได้มีดังนี้ DIRECT_MESSAGE, GROUP_CHAT และ SPACE
  • 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 หรือ 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 แต่ไม่รองรับการใช้ทั้ง 2 อย่างร่วมกัน ตัวอย่างเช่น space.display_name:Project AND space.display_name:Tasks จะแสดงข้อความที่อยู่ในพื้นที่ซึ่งมีชื่อที่แสดงที่มีทั้ง Project และ Tasks ในขณะที่ space.display_name:Project OR space.display_name:Tasks จะแสดงข้อความที่อยู่ในพื้นที่ซึ่งมีชื่อที่แสดงที่มี Project หรือ Tasks หรือทั้ง 2 อย่าง
  • space.space_type รองรับเฉพาะโอเปอเรเตอร์ OR เช่น space.space_type = "DIRECT_MESSAGE" OR space.space_type = "GROUP_CHAT"
  • annotations.user_mentions.user.name รองรับโอเปอเรเตอร์ AND และ OR แต่ไม่รองรับการใช้ทั้ง 2 อย่างร่วมกัน ตัวอย่างเช่น 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) และต้องระบุหลังแอตทริบิวต์การจัดเรียง
markupSyntax

enum (MarkupSyntax)

ไม่บังคับ ระบุไวยากรณ์เอาต์พุตที่ต้องการสำหรับฟิลด์ข้อความแชท formattedText
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