Method: query.search

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

หมายเหตุ: API นี้ต้องใช้บัญชีผู้ใช้ปลายทางมาตรฐานเพื่อดำเนินการ บัญชีบริการไม่สามารถส่งคําขอ Query 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

สตริงการค้นหาไฟล์ข้อมูล RAW ดูโอเปอเรเตอร์การค้นหาที่รองรับในส่วนจำกัดขอบเขตการค้นหาด้วยโอเปอเรเตอร์
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) ค่าเริ่มต้นคือเท็จ ตั้งค่าเป็น "จริง" เพื่อปิดใช้การตีความภาษาที่เป็นธรรมชาติ การตีความภาษาดัตช์มีผลกับแหล่งข้อมูลที่กําหนดไว้ล่วงหน้าเท่านั้น
enableVerbatimMode

boolean

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

boolean

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

QueryInterpretation

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

string

การตีความคำค้นหาที่ใช้ในการค้นหา เช่น การค้นหาที่มีเจตนาเป็นภาษาธรรมชาติ เช่น "อีเมลจาก 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)

หากแหล่งที่มาเป็นคลัสเตอร์ ให้ระบุรายการผลลัพธ์ที่เป็นคลัสเตอร์ ผลลัพธ์ที่คลัสเตอร์จะมีเพียง 1 ระดับ หากไม่ได้เปิดใช้แหล่งที่มาปัจจุบันสําหรับการจัดกลุ่ม ช่องนี้จะว่างเปล่า
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)

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

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

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