Method: query.search

Cloud Search Query API มีวิธีการค้นหาซึ่งจะแสดงผลการค้นหาที่เกี่ยวข้องมากที่สุดจากคำค้นหาของผู้ใช้ ผลลัพธ์อาจมาจากแอปต่างๆ ของ Google Workspace เช่น Gmail หรือ Google ไดรฟ์ หรืออาจมาจากข้อมูลที่คุณจัดทําดัชนีจากบุคคลที่สามก็ได้

หมายเหตุ: API นี้ต้องใช้บัญชีผู้ใช้ปลายทางมาตรฐานเพื่อเรียกใช้ บัญชีบริการจะส่งคำขอ API การค้นหาโดยตรงไม่ได้ หากต้องการใช้บัญชีบริการในการค้นหา ให้ตั้งค่าการมอบสิทธิ์ทั่วทั้งโดเมนของ Google Workspace

คำขอ HTTP

POST https://cloudsearch.googleapis.com/v1/query/search

URL ใช้ไวยากรณ์การแปลง gRPC

เนื้อหาของคำขอ

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

การแสดง JSON 
{
  "requestOptions": {
    object (RequestOptions)
  },
  "query": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
ช่อง
requestOptions

object (RequestOptions)

ตัวเลือกคำขอ เช่น แอปพลิเคชันการค้นหาและเขตเวลาของผู้ใช้
query

string

สตริงคำค้นหาดิบ ดูโอเปอเรเตอร์การค้นหาที่รองรับในหัวข้อจํากัดการค้นหาให้แคบลงด้วยโอเปอเรเตอร์
pageSize

integer

จำนวนผลการค้นหาสูงสุดที่จะแสดงในหนึ่งหน้า โดยค่าที่ใช้ได้จะอยู่ระหว่าง 1 ถึง 100 ค่าเริ่มต้นคือ 10 ค่าต่ำสุดคือ 50 เมื่อมีการขอผลลัพธ์ที่เกิน 2000
start

integer

ดัชนีเริ่มต้นของผลลัพธ์
dataSourceRestrictions[]

object (DataSourceRestriction)

แหล่งที่มาที่จะใช้สําหรับการค้นหา หากไม่ได้ระบุ ระบบจะใช้แหล่งข้อมูลทั้งหมดจากแอปพลิเคชันการค้นหาปัจจุบัน
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

ตัวเลือกสำหรับการจัดเรียงผลการค้นหา
queryInterpretationOptions

object (QueryInterpretationOptions)

เพื่อตีความข้อความค้นหาของผู้ใช้
contextAttributes[]

object (ContextAttribute)

แอตทริบิวต์บริบทสำหรับคำขอที่จะใช้ในการปรับการจัดอันดับผลการค้นหา จำนวนองค์ประกอบสูงสุดคือ 10 รายการ

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

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

การตอบกลับของ Search API

การแสดง JSON 
{
  "queryInterpretation": {
    object (QueryInterpretation)
  },
  "results": [
    {
      object (SearchResult)
    }
  ],
  "structuredResults": [
    {
      object (StructuredResult)
    }
  ],
  "spellResults": [
    {
      object (SpellResult)
    }
  ],
  "facetResults": [
    {
      object (FacetResult)
    }
  ],
  "hasMoreResults": boolean,
  "debugInfo": {
    object (ResponseDebugInfo)
  },
  "errorInfo": {
    object (ErrorInfo)
  },
  "resultCounts": {
    object (ResultCounts)
  },

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
ช่อง
queryInterpretation

object (QueryInterpretation)

ผลลัพธ์การแปลคำค้นหาสำหรับการค้นหาของผู้ใช้ เว้นว่างไว้หากปิดใช้การแปลความหมายคำค้นหา
results[]

object (SearchResult)

ผลลัพธ์จากคำค้นหา
structuredResults[]

object (StructuredResult)

ผลลัพธ์แบบมีโครงสร้างสำหรับการค้นหาของผู้ใช้ ผลลัพธ์เหล่านี้จะไม่นับรวมกับ pageSize
spellResults[]

object (SpellResult)

การสะกดที่แนะนำสำหรับคำค้นหา
facetResults[]

object (FacetResult)

ผลการค้นหาข้อมูลประกอบที่ซ้ำกัน
hasMoreResults

boolean

มีผลการค้นหาอื่นๆ ที่ตรงกับคำค้นหาหรือไม่
debugInfo

object (ResponseDebugInfo)

ข้อมูลการแก้ไขข้อบกพร่องเกี่ยวกับการตอบกลับ
errorInfo

object (ErrorInfo)

ข้อมูลข้อผิดพลาดเกี่ยวกับการตอบกลับ
resultCounts

object (ResultCounts)

ข้อมูลจำนวนผลลัพธ์ที่ขยาย

ช่องการรวม result_count จำนวนผลลัพธ์ทั้งหมดในแหล่งข้อมูลที่ขอทั้งหมด ละเว้นหากมีการรวมแหล่งที่มาที่กำหนดไว้ล่วงหน้าในชุดแหล่งข้อมูลที่ค้นหา จำนวนผลลัพธ์อาจแสดงผลเป็นค่าประมาณ ไม่ใช่ผลลัพธ์ที่แน่นอนในกรณีต่อไปนี้

  • เมื่อข้อความค้นหามีมากกว่า 2 คำในวลี เช่น "จำนวนผลลัพธ์ตรงกันทั้งหมด" ในเครื่องหมายคำพูด

  • เมื่อจำนวน ACL ของผลการค้นหาที่ไม่ซ้ำกันที่จะประเมินมีจำนวนมากเกินกว่าที่จะคำนวณได้ภายในเวลาในการตอบสนองที่สมเหตุสมผล

ในกรณีที่ระบบค้นหาในเอกสารทั้งหมดไม่ได้ ซึ่งเป็นกรณีที่พบได้น้อย ให้เรียกใช้การค้นหาอีกครั้ง result_count ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
resultCountEstimate

string (int64 format)

จำนวนผลลัพธ์โดยประมาณสำหรับการค้นหานี้
resultCountExact

string (int64 format)

จำนวนผลลัพธ์จริงสำหรับคำค้นหานี้

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

ต้องใช้ขอบเขต OAuth รายการใดรายการหนึ่งต่อไปนี้

  • https://www.googleapis.com/auth/cloud_search.query
  • https://www.googleapis.com/auth/cloud_search

สำหรับข้อมูลเพิ่มเติม โปรดดูที่คู่มือการให้สิทธิ์

QueryInterpretationOptions

เพื่อตีความข้อความค้นหาของผู้ใช้

การแสดง JSON 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
ช่อง
disableNlInterpretation

boolean

ตั้งค่าสถานะเพื่อปิดใช้การแปลความหมายด้วยภาษาธรรมชาติ (NL) ของข้อความค้นหา ค่าเริ่มต้นคือ "เท็จ" ตั้งค่าเป็น "จริง" เพื่อปิดใช้การตีความภาษาธรรมชาติ การตีความ NL ใช้กับแหล่งข้อมูลที่กำหนดไว้ล่วงหน้าเท่านั้น
enableVerbatimMode

boolean

เปิดใช้แฟล็กนี้เพื่อปิดการเพิ่มประสิทธิภาพภายในทั้งหมด เช่น การตีความคำค้นหาในภาษาธรรมชาติ (NL) การดึงข้อมูลผลลัพธ์เสริม และการใช้คำพ้องความหมาย รวมถึงคำที่กำหนดเอง ระบบจะปิดใช้การตีความ Nl หากหนึ่งใน 2 แฟล็กใดเป็นจริง
disableSupplementalResults

boolean

ใช้แฟล็กนี้เพื่อปิดใช้ผลลัพธ์เสริมสำหรับการค้นหา การตั้งค่าผลลัพธ์เสริมที่เลือกที่ระดับ SearchApplication จะมีความสำคัญเหนือกว่าหากตั้งค่าเป็น True

QueryInterpretation

การแสดง JSON 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
ช่อง
interpretedQuery

string

การตีความข้อความค้นหาที่ใช้ในการค้นหา เช่น คำค้นหาที่มีความตั้งใจเป็นภาษาธรรมชาติ เช่น "email from john" จะได้รับการแปลค่าเป็น "from:john source:mail" จะไม่มีการกรอกข้อมูลในฟิลด์นี้เมื่อเหตุผลคือ NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

เหตุผลในการตีความข้อความค้นหา ช่องนี้จะไม่มีการระบุ UNSPECIFIED หากประเภทการแปลไม่ใช่ NONE

QueryInterpretation.InterpretationType

Enum
NONE ไม่มีการตีความภาษาธรรมชาติหรือการค้นหาแบบกว้างๆ เพื่อดึงผลการค้นหา
BLEND ผลลัพธ์จากคำค้นหาเดิมจะผสมกับผลการค้นหาอื่นๆ เหตุผลในการรวมผลลัพธ์อื่นๆ เหล่านี้กับผลลัพธ์จากข้อความค้นหาเดิมจะอยู่ในช่อง "เหตุผล" ด้านล่าง
REPLACE ระบบจะแทนที่ผลลัพธ์จากคำค้นหาเดิม เหตุผลในการแทนที่ผลลัพธ์จากข้อความค้นหาเดิมจะปรากฏในส่วน "เหตุผล" ด้านล่าง

QueryInterpretation.Reason

Enum
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT ข้อความค้นหาใช้การแปลความหมายภาษาธรรมชาติเพื่อดึงผลการค้นหา
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY ข้อความค้นหาและคำในเอกสารมีความคล้ายคลึงกันเพื่อเลือกขอบเขตของข้อความค้นหาให้กว้างขึ้นเพื่อดึงผลการค้นหาเพิ่มเติมเนื่องจากไม่พบผลลัพธ์ที่เพียงพอสำหรับการค้นหาของผู้ใช้ คำค้นหาที่ตีความแล้วจะว่างเปล่าสำหรับกรณีนี้

SearchResult

ผลลัพธ์ที่มีข้อมูลที่จัดทำดัชนีสำหรับเอกสาร

การแสดง JSON 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
ช่อง
title

string

ชื่อของผลการค้นหา
url

string

URL ของผลการค้นหา URL มีการเปลี่ยนเส้นทาง Google ไปยังรายการจริง URL นี้มีลายเซ็นแล้วและไม่ควรเปลี่ยนแปลง
snippet

object (Snippet)

การต่อตัวอย่างข้อมูล (ข้อมูลสรุป) ทั้งหมดที่มีสำหรับผลลัพธ์นี้
metadata

object (Metadata)

ข้อมูลเมตาของผลการค้นหา
clusteredResults[]

object (SearchResult)

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

object (ResultDebugInfo)

แก้ไขข้อบกพร่องเกี่ยวกับผลการค้นหานี้

ตัวอย่างข้อมูล

ตัวอย่างของผลการค้นหา ซึ่งสรุปเนื้อหาของหน้าผลลัพธ์

การแสดง JSON 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
ช่อง
snippet

string

ตัวอย่างข้อมูลของเอกสาร ตัวอย่างข้อมูลของเอกสาร อาจมีอักขระ HTML ที่มีการกำหนดเป็นอักขระหลีกซึ่งไม่ควรกำหนดเป็นอักขระหลีกก่อนที่จะแสดงผล
matchRanges[]

object (MatchRange)

ช่วงที่ตรงกันในข้อมูลโค้ด

MatchRange

ช่วงที่ตรงกันของข้อมูลโค้ด [start, end)

การแสดง JSON 
{
  "start": integer,
  "end": integer
}
ช่อง
start

integer

ตำแหน่งเริ่มต้นของการจับคู่ในข้อมูลโค้ด
end

integer

สิ้นสุดการจับคู่ในข้อมูลโค้ด

ข้อมูลเมตา

ข้อมูลเมตาของผลการค้นหาที่ตรงกัน

การแสดง JSON 
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
ช่อง
source

object (Source)

แหล่งที่มาที่มีชื่อของผลลัพธ์ เช่น Gmail
mimeType

string

ประเภท Mime ของผลการค้นหา
thumbnailUrl

string

URL ภาพขนาดย่อของผลการค้นหา
owner

object (Person)

เจ้าของ (มักจะเป็นผู้สร้าง) เอกสารหรือออบเจ็กต์ของผลการค้นหา
createTime

string (Timestamp format)

เวลาที่สร้างเอกสารหรือออบเจ็กต์นี้ในผลการค้นหา

การประทับเวลาเป็น RFC3339 UTC "Zulu" โดยมีความละเอียดระดับนาโนวินาทีและมีเลขเศษส่วนสูงสุด 9 หลัก ตัวอย่าง: "2014-10-02T15:01:23Z" และ "2014-10-02T15:01:23.045123456Z"
updateTime

string (Timestamp format)

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

การประทับเวลาเป็น RFC3339 UTC "Zulu" โดยมีความละเอียดระดับนาโนวินาทีและมีเลขเศษส่วนสูงสุด 9 หลัก ตัวอย่าง: "2014-10-02T15:01:23Z" และ "2014-10-02T15:01:23.045123456Z"
fields[]

object (NamedProperty)

ช่องที่จัดทำดัชนีใน Structured Data แสดงผลเป็นพร็อพเพอร์ตี้ชื่อทั่วไป
displayOptions

object (ResultDisplayMetadata)

ซึ่งระบุวิธีแสดงผลการค้นหาข้อมูลที่มีโครงสร้าง
objectType

string

ประเภทออบเจ็กต์ของผลการค้นหา

ResultDisplayMetadata

การแสดง JSON 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
ช่อง
objectTypeLabel

string

ป้ายกำกับที่ปรากฏสำหรับออบเจ็กต์
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

เนื้อหาเมตาไลน์ที่จะแสดงพร้อมผลลัพธ์

ResultDisplayMetadata.ResultDisplayLine

คอลเล็กชันของช่องที่ประกอบกันขึ้นเป็นบรรทัดที่แสดง

การแสดง JSON 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
ช่อง
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

แสดงช่องสำหรับผลการค้นหา query.search

การแสดง JSON 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
ช่อง
label

string

ป้ายกำกับที่ปรากฏสำหรับพร็อพเพอร์ตี้
operatorName

string

ชื่อผู้ดำเนินการของพร็อพเพอร์ตี้
property

object (NamedProperty)

คู่ค่าชื่อสำหรับพร็อพเพอร์ตี้

ResultDebugInfo

ข้อมูลการแก้ไขข้อบกพร่องเกี่ยวกับผลลัพธ์

การแสดง JSON 
{
  "formattedDebugInfo": string
}
ช่อง
formattedDebugInfo

string

ข้อมูลการแก้ไขข้อบกพร่องทั่วไปที่จัดรูปแบบสำหรับการแสดงผล

StructuredResult

ผลลัพธ์ที่มีโครงสร้างที่แสดงเป็นส่วนหนึ่งของคำขอการค้นหา

การแสดง JSON 
{
  "person": {
    object (Person)
  }
}
ช่อง
person

object (Person)

ภาพแทนบุคคล

SpellResult

การแสดง JSON 
{
  "suggestedQuery": string
}
ช่อง
suggestedQuery

string

การสะกดที่แนะนำของข้อความค้นหา

FacetResult

การตอบกลับข้อมูลประกอบที่เจาะจงเกี่ยวกับแหล่งที่มา

การแสดง JSON 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
ช่อง
sourceName

string

ชื่อแหล่งที่มาที่มีการแสดงผลข้อมูลประกอบ จะเว้นว่างไม่ได้
objectType

string

ประเภทออบเจ็กต์ที่แสดงผลลัพธ์ข้อมูลประกอบ เว้นว่างได้
operatorName

string

ชื่อของโอเปอเรเตอร์ที่เลือกสำหรับการประกอบ @ดู cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBuckets สำหรับค่าในการตอบกลับที่มีผลลัพธ์อย่างน้อย 1 รายการซึ่งมีตัวกรองที่เกี่ยวข้อง

FacetBucket

ที่เก็บข้อมูลในข้อมูลประกอบคือหน่วยการทำงานพื้นฐาน ที่เก็บข้อมูลอาจประกอบด้วยค่าเดียวหรือช่วงของค่าที่ต่อเนื่องกัน ทั้งนี้ขึ้นอยู่กับประเภทของฟิลด์ที่ฝากข้อมูล ปัจจุบัน FacetBucket จะใช้สำหรับการส่งคืนออบเจ็กต์การตอบกลับเท่านั้น

การแสดง JSON 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
ช่อง
count

integer

จำนวนผลลัพธ์ที่ตรงกับค่าที่เก็บข้อมูล ระบบแสดงผลการนับสำหรับการค้นหาเมื่อมั่นใจในความถูกต้องของการนับแล้วเท่านั้น Cloud Search ไม่รับประกันว่าจำนวนข้อมูลประกอบสำหรับการค้นหาและจำนวนข้อมูลประกอบใดๆ อาจปรากฏเป็นระยะๆ แม้ว่าจะเป็นคำค้นหาที่เหมือนกันก็ตาม อย่าสร้างทรัพยากร Dependency ตามการมีอยู่ของจำนวนข้อมูลประกอบ ให้ใช้เปอร์เซ็นต์การซ้อนทับข้อมูลประกอบ ซึ่งจะแสดงผลลัพธ์เสมอ
percentage

integer

เปอร์เซ็นต์ของผลลัพธ์ที่ตรงกับค่าที่เก็บข้อมูล ค่าที่ส่งคืนจะอยู่ระหว่าง (0-100] และจะปัดเศษลงเป็นจำนวนเต็มหากเป็นเศษส่วน หากไม่มีการส่งกลับค่าอย่างชัดเจน ค่านี้จะแสดงค่าเปอร์เซ็นต์ที่ปัดเศษเป็น 0 ระบบจะแสดงเปอร์เซ็นต์สำหรับการค้นหาทั้งหมด แต่เป็นเพียงค่าประมาณ เนื่องจากระบบจะแสดงเปอร์เซ็นต์เสมอ คุณจึงควรแสดงผลเป็นเปอร์เซ็นต์แทนการนับ
filter

object (Filter)

ตัวกรองที่จะส่งไปในคำขอการค้นหาหากเลือกที่เก็บข้อมูลที่เกี่ยวข้องไว้
value

object (Value)

ResponseDebugInfo

ข้อมูลการแก้ไขข้อบกพร่องเกี่ยวกับการตอบกลับ

การแสดง JSON 
{
  "formattedDebugInfo": string
}
ช่อง
formattedDebugInfo

string

ข้อมูลการแก้ไขข้อบกพร่องทั่วไปที่จัดรูปแบบสำหรับการแสดงผล

ErrorInfo

ข้อมูลข้อผิดพลาดเกี่ยวกับคำตอบ

การแสดง JSON 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
ช่อง
errorMessages[]

object (ErrorMessage)

ErrorMessage

ข้อความแสดงข้อผิดพลาดต่อการตอบกลับแหล่งที่มา

การแสดง JSON 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
ช่อง
source

object (Source)
errorMessage

string

ResultCounts

ข้อมูลจำนวนผลลัพธ์

การแสดง JSON 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
ช่อง
sourceResultCounts[]

object (SourceResultCount)

ข้อมูลจำนวนผลลัพธ์สำหรับแต่ละแหล่งที่มาที่มีผลลัพธ์

SourceResultCount

ข้อมูลจำนวนผลลัพธ์ตามแหล่งที่มา

การแสดง JSON 
{
  "source": {
    object (Source)
  },
  "hasMoreResults": boolean,

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
ช่อง
source

object (Source)

แหล่งที่มาที่เชื่อมโยงกับข้อมูลจำนวนผลลัพธ์
hasMoreResults

boolean

มีผลการค้นหาเพิ่มเติมสำหรับแหล่งที่มานี้หรือไม่

ช่องการรวม result_count

result_count ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
resultCountEstimate

string (int64 format)

จำนวนผลลัพธ์โดยประมาณสำหรับแหล่งที่มานี้
resultCountExact

string (int64 format)

จำนวนผลลัพธ์ที่แน่นอนสำหรับแหล่งที่มานี้