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 เมื่อมีการขอผลลัพธ์ที่เกิน 2,000
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 จะมีลำดับความสำคัญเหนือกว่าหากตั้งค่าเป็น "จริง"

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)

เหตุผลในการตีความการค้นหา ช่องนี้จะเป็น "ไม่ได้ระบุ" หากประเภทการตีความไม่ใช่ "ไม่มี"

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 ที่ใช้ Escape ซึ่งควรไม่ใช้ Escape ก่อนการแสดงผล
matchRanges[]

object (MatchRange)

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

MatchRange

ช่วงที่ตรงกันของตัวอย่าง [start, end)

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

integer

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

integer

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

Metadata

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

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

ที่ระบุวิธีแสดงผลการค้นหา Structured Data
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

ประเภทออบเจ็กต์ที่แสดงผลการค้นหา Facet เว้นว่างได้
operatorName

string

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

object (FacetBucket)

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

FacetBucket

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

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

integer

จำนวนผลลัพธ์ที่ตรงกับค่าของที่เก็บข้อมูล ระบบจะแสดงจำนวนการค้นหาก็ต่อเมื่อตรวจสอบความถูกต้องของการนับแล้วเท่านั้น Cloud Search ไม่รับประกันจำนวนข้อมูลประกอบสำหรับคำค้นหาและจำนวนข้อมูลประกอบใดๆ อาจแสดงเป็นพักๆ แม้ว่าจะเป็นคำค้นหาที่เหมือนกันก็ตาม อย่าสร้างการพึ่งพาการมีอยู่ของจำนวนข้อมูลประกอบ แต่ให้ใช้เปอร์เซ็นต์ Ount ข้อมูลประกอบซึ่งจะแสดงผลลัพธ์เสมอ
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)

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