- คำขอ HTTP
- เนื้อความของคำขอ
- เนื้อหาการตอบกลับ
- ขอบเขตการให้สิทธิ์
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType
- QueryInterpretation.Reason
- SearchResult
- ตัวอย่างข้อมูล
- MatchRange
- ข้อมูลเมตา
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo
- StructuredResult
- SpellResult
- FacetResult
- FacetBucket
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCounts
- SourceResultCount
- ลองใช้งาน
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 |
สตริงคำค้นหาดิบ ดูโอเปอเรเตอร์การค้นหาที่รองรับในหัวข้อจำกัดขอบเขตการค้นหาด้วยโอเปอเรเตอร์ |
pageSize |
จำนวนผลการค้นหาสูงสุดที่จะแสดงผลในหนึ่งหน้า ค่าที่ใช้ได้ต้องอยู่ระหว่าง 1 ถึง 100 ค่าเริ่มต้นคือ 10 ค่าต่ำสุดคือ 50 เมื่อมีการขอผลลัพธ์ที่เกิน 2,000 |
start |
ดัชนีเริ่มต้นของผลการค้นหา |
dataSourceRestrictions[] |
แหล่งที่มาที่จะใช้สำหรับการค้นหา หากไม่ได้ระบุไว้ ระบบจะใช้แหล่งข้อมูลทั้งหมดจากแอปพลิเคชันการค้นหาปัจจุบัน |
facetOptions[] |
|
sortOptions |
ตัวเลือกสำหรับการจัดเรียงผลการค้นหา |
queryInterpretationOptions |
เพื่อตีความการค้นหาของผู้ใช้ |
contextAttributes[] |
แอตทริบิวต์บริบทของคำขอที่จะใช้ในการปรับการจัดอันดับผลการค้นหา จำนวนองค์ประกอบสูงสุดคือ 10 |
เนื้อหาการตอบกลับ
หากทำสำเร็จ เนื้อหาการตอบกลับจะมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้
การตอบกลับจาก Search API
การแสดง JSON |
---|
{ "queryInterpretation": { object ( |
ช่อง | |
---|---|
queryInterpretation |
ผลการตีความการค้นหาสำหรับการค้นหาของผู้ใช้ เว้นว่างหากปิดใช้การแปลความหมายการค้นหา |
results[] |
ผลลัพธ์จากคําค้นหา |
structuredResults[] |
ผลการค้นหาที่มีโครงสร้างสำหรับการค้นหาของผู้ใช้ ผลลัพธ์เหล่านี้จะไม่นับรวมใน pageSize |
spellResults[] |
การสะกดที่แนะนำสำหรับการค้นหา |
facetResults[] |
ผลลัพธ์ข้อมูลประกอบซ้ำ |
hasMoreResults |
มีผลการค้นหาที่ตรงกับคําค้นหามากขึ้นหรือไม่ |
debugInfo |
ข้อมูลการแก้ไขข้อบกพร่องเกี่ยวกับการตอบกลับ |
errorInfo |
ข้อมูลข้อผิดพลาดเกี่ยวกับการตอบกลับ |
resultCounts |
ข้อมูลจำนวนผลลัพธ์ที่ขยาย |
ฟิลด์การรวม
ในกรณีที่ไม่ค่อยเกิดขึ้น เมื่อระบบไม่สามารถค้นหาเอกสารทั้งหมด ให้ทำการค้นหาอีกครั้ง |
|
resultCountEstimate |
จำนวนผลลัพธ์โดยประมาณสำหรับคำค้นหานี้ |
resultCountExact |
จำนวนผลลัพธ์ที่แน่นอนสำหรับการค้นหานี้ |
ขอบเขตการให้สิทธิ์
ต้องมีขอบเขต 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 |
ตั้งค่าสถานะเพื่อปิดใช้การตีความภาษาที่เป็นธรรมชาติ (NL) ของข้อความค้นหา ค่าเริ่มต้นคือ "เท็จ" ตั้งค่าเป็น "จริง" เพื่อปิดใช้การตีความภาษาที่เป็นธรรมชาติ การตีความแบบ NL จะใช้กับแหล่งข้อมูลที่กำหนดไว้ล่วงหน้าเท่านั้น |
enableVerbatimMode |
เปิดใช้แฟล็กนี้เพื่อปิดการเพิ่มประสิทธิภาพภายในทั้งหมด เช่น การตีความข้อความค้นหาที่เป็นภาษาธรรมชาติ (NL) การดึงข้อมูลผลลัพธ์เสริม และการใช้คำพ้องความหมาย ซึ่งรวมถึงคำที่กำหนดเอง การตีความ Nl จะถูกปิดใช้งานหากแฟล็กข้อใดข้อหนึ่งจากทั้ง 2 รายการเป็นจริง |
disableSupplementalResults |
ใช้แฟล็กนี้เพื่อปิดใช้ผลลัพธ์เสริมสำหรับการค้นหา การตั้งค่าผลลัพธ์เสริมที่เลือกในระดับ SearchApplication จะมีลำดับความสำคัญเหนือกว่าหากตั้งค่าเป็น "จริง" |
QueryInterpretation
การแสดง JSON |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
ช่อง | |
---|---|
interpretedQuery |
การตีความข้อความค้นหาที่ใช้ในการค้นหา ตัวอย่างเช่น คำค้นหาที่ตั้งใจเป็นภาษาธรรมชาติ เช่น "email from john" จะถูกตีความว่าเป็น "from:john source:mail" ฟิลด์นี้จะไม่ถูกกรอกเมื่อเหตุผลคือ NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY |
interpretationType |
|
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 ( |
ช่อง | |
---|---|
title |
ชื่อของผลการค้นหา |
url |
URL ของผลการค้นหา URL มีการเปลี่ยนเส้นทางของ Google ไปยังรายการจริง URL นี้มีการรับรองแล้วและไม่ควรเปลี่ยน |
snippet |
การต่อตัวอย่างข้อมูลทั้งหมด (ข้อมูลสรุป) ที่ใช้ได้สำหรับผลการค้นหานี้ |
metadata |
ข้อมูลเมตาของผลการค้นหา |
clusteredResults[] |
หากมีการจัดกลุ่มต้นทางไว้ ให้ระบุรายการผลลัพธ์ที่จัดเป็นคลัสเตอร์ จะมีผลลัพธ์ที่จัดเป็นคลัสเตอร์เพียงระดับเดียว หากไม่ได้เปิดใช้แหล่งที่มาปัจจุบันสำหรับคลัสเตอร์ ช่องนี้จะว่างเปล่า |
debugInfo |
ข้อมูลการแก้ไขข้อบกพร่องเกี่ยวกับผลการค้นหานี้ |
ตัวอย่างข้อมูล
ตัวอย่างข้อมูลของผลการค้นหา ซึ่งสรุปเนื้อหาของหน้าผลลัพธ์
การแสดง JSON |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
ช่อง | |
---|---|
snippet |
ตัวอย่างข้อมูลของเอกสาร ตัวอย่างข้อมูลของเอกสาร อาจมีอักขระ HTML ที่ใช้ Escape ซึ่งควรไม่ใช้ Escape ก่อนการแสดงผล |
matchRanges[] |
ช่วงที่ตรงกันในข้อมูลโค้ด |
MatchRange
ช่วงที่ตรงกันของตัวอย่าง [start, end)
การแสดง JSON |
---|
{ "start": integer, "end": integer } |
ช่อง | |
---|---|
start |
ตำแหน่งเริ่มต้นของการจับคู่ในข้อมูลโค้ด |
end |
สิ้นสุดการจับคู่ในข้อมูลโค้ด |
Metadata
ข้อมูลเมตาของผลการค้นหาที่ตรงกัน
การแสดง JSON |
---|
{ "source": { object ( |
ช่อง | |
---|---|
source |
แหล่งที่มาที่ระบุชื่อสำหรับผลการค้นหา เช่น Gmail |
mimeType |
ประเภท Mime ของผลการค้นหา |
thumbnailUrl |
URL ภาพขนาดย่อของผลการค้นหา |
owner |
เจ้าของ (มักจะเป็นผู้สร้าง) เอกสารหรือวัตถุของผลการค้นหา |
createTime |
เวลาที่สร้างสำหรับเอกสารหรือออบเจ็กต์นี้ในผลการค้นหา การประทับเวลาจะอยู่ในรูปแบบ RFC3339 UTC "Zulu" ที่มีความละเอียดระดับนาโนวินาทีและมีตัวเลขเศษส่วนได้สูงสุด 9 หลัก ตัวอย่าง: |
updateTime |
วันที่แก้ไขล่าสุดสำหรับออบเจ็กต์ในผลการค้นหา หากไม่ได้ตั้งค่าไว้ในรายการ ค่าที่แสดงที่นี่จะว่างเปล่า เมื่อใช้ การประทับเวลาจะอยู่ในรูปแบบ RFC3339 UTC "Zulu" ที่มีความละเอียดระดับนาโนวินาทีและมีตัวเลขเศษส่วนได้สูงสุด 9 หลัก ตัวอย่าง: |
fields[] |
ช่องที่จัดทำดัชนีใน Structured Data แสดงผลเป็นพร็อพเพอร์ตี้ที่มีชื่อทั่วไป |
displayOptions |
ที่ระบุวิธีแสดงผลการค้นหา Structured Data |
objectType |
ประเภทออบเจ็กต์ของผลการค้นหา |
ResultDisplayMetadata
การแสดง JSON |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
ช่อง | |
---|---|
objectTypeLabel |
ป้ายกำกับที่ปรากฏสำหรับออบเจ็กต์ |
metalines[] |
เนื้อหาเมตาที่จะแสดงพร้อมกับผลการค้นหา |
ResultDisplayMetadata.ResultDisplayLine
คอลเล็กชันของช่องต่างๆ ที่ประกอบขึ้นเป็นเส้นที่แสดง
การแสดง JSON |
---|
{
"fields": [
{
object ( |
ช่อง | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
แสดงฟิลด์สำหรับผลการค้นหา query.search
การแสดง JSON |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
ช่อง | |
---|---|
label |
ป้ายกํากับที่ปรากฏสําหรับพร็อพเพอร์ตี้ |
operatorName |
ชื่อโอเปอเรเตอร์ของพร็อพเพอร์ตี้ |
property |
คู่ค่าชื่อของพร็อพเพอร์ตี้ |
ResultDebugInfo
ข้อมูลการแก้ไขข้อบกพร่องเกี่ยวกับผลลัพธ์
การแสดง JSON |
---|
{ "formattedDebugInfo": string } |
ช่อง | |
---|---|
formattedDebugInfo |
จัดรูปแบบข้อมูลการแก้ไขข้อบกพร่องทั่วไปสำหรับการแสดงผลแล้ว |
StructuredResult
ผลการค้นหาที่มีโครงสร้างซึ่งแสดงผลเป็นส่วนหนึ่งของคำขอการค้นหา
การแสดง JSON |
---|
{
"person": {
object ( |
ช่อง | |
---|---|
person |
การนําเสนอบุคคล |
SpellResult
การแสดง JSON |
---|
{ "suggestedQuery": string } |
ช่อง | |
---|---|
suggestedQuery |
การสะกดคำที่แนะนำ |
FacetResult
คำตอบสำหรับข้อมูลประกอบที่เจาะจงแหล่งที่มา
การแสดง JSON |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
ช่อง | |
---|---|
sourceName |
ชื่อแหล่งที่มาที่แสดงผลการค้นหาประกอบ ต้องไม่ว่างเปล่า |
objectType |
ประเภทออบเจ็กต์ที่แสดงผลการค้นหา Facet เว้นว่างได้ |
operatorName |
ชื่อของโอเปอเรเตอร์ที่เลือกสำหรับข้อมูลประกอบ @ดู cloudsearch.SchemaPropertyOptions |
buckets[] |
FacetBucket สำหรับค่าในการตอบสนองที่มีผลลัพธ์อย่างน้อย 1 รายการซึ่งมีตัวกรองที่เกี่ยวข้อง |
FacetBucket
ที่เก็บข้อมูลในข้อมูลประกอบเป็นหน่วยการดำเนินการพื้นฐาน ที่เก็บข้อมูลอาจประกอบด้วยค่าเดียวหรือช่วงของค่าที่ต่อเนื่องกัน ทั้งนี้ขึ้นอยู่กับประเภทของช่องที่ฝากไว้ ปัจจุบัน FacetBucket จะใช้สำหรับการส่งคืนออบเจ็กต์การตอบกลับเท่านั้น
การแสดง JSON |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
ช่อง | |
---|---|
count |
จำนวนผลลัพธ์ที่ตรงกับค่าของที่เก็บข้อมูล ระบบจะแสดงจำนวนการค้นหาก็ต่อเมื่อตรวจสอบความถูกต้องของการนับแล้วเท่านั้น Cloud Search ไม่รับประกันจำนวนข้อมูลประกอบสำหรับคำค้นหาและจำนวนข้อมูลประกอบใดๆ อาจแสดงเป็นพักๆ แม้ว่าจะเป็นคำค้นหาที่เหมือนกันก็ตาม อย่าสร้างการพึ่งพาการมีอยู่ของจำนวนข้อมูลประกอบ แต่ให้ใช้เปอร์เซ็นต์ Ount ข้อมูลประกอบซึ่งจะแสดงผลลัพธ์เสมอ |
percentage |
เปอร์เซ็นต์ของผลลัพธ์ที่ตรงกับค่าที่เก็บข้อมูล ค่าที่ส่งคืนอยู่ระหว่าง (0-100] และจะปัดเศษลงเป็นจำนวนเต็มหากเป็นเศษส่วน หากค่านี้ไม่แสดงผลอย่างชัดเจน จะแสดงค่าเปอร์เซ็นต์ที่ปัดเป็น 0 จะแสดงค่าเปอร์เซ็นต์สำหรับการค้นหาทั้งหมด แต่เป็นค่าโดยประมาณ เนื่องจากระบบจะส่งคืนเปอร์เซ็นต์เสมอ คุณจึงควรแสดงผลเปอร์เซ็นต์แทนจำนวน |
filter |
ตัวกรองที่จะส่งไปในคำขอการค้นหาหากเลือกที่เก็บข้อมูลที่เกี่ยวข้องไว้ |
value |
|
ResponseDebugInfo
ข้อมูลการแก้ไขข้อบกพร่องเกี่ยวกับการตอบกลับ
การแสดง JSON |
---|
{ "formattedDebugInfo": string } |
ช่อง | |
---|---|
formattedDebugInfo |
จัดรูปแบบข้อมูลการแก้ไขข้อบกพร่องทั่วไปสำหรับการแสดงผลแล้ว |
ErrorInfo
ข้อมูลข้อผิดพลาดเกี่ยวกับการตอบกลับ
การแสดง JSON |
---|
{
"errorMessages": [
{
object ( |
ช่อง | |
---|---|
errorMessages[] |
|
ErrorMessage
ข้อความแสดงข้อผิดพลาดต่อการตอบกลับแหล่งที่มา
การแสดง JSON |
---|
{
"source": {
object ( |
ช่อง | |
---|---|
source |
|
errorMessage |
|
ResultCounts
ข้อมูลจำนวนผลลัพธ์
การแสดง JSON |
---|
{
"sourceResultCounts": [
{
object ( |
ช่อง | |
---|---|
sourceResultCounts[] |
ข้อมูลจำนวนผลลัพธ์สำหรับแต่ละแหล่งที่มาที่มีผลลัพธ์ |
SourceResultCount
ข้อมูลจำนวนผลลัพธ์ตามต้นฉบับ
การแสดง JSON |
---|
{ "source": { object ( |
ช่อง | |
---|---|
source |
แหล่งที่มาที่เชื่อมโยงกับข้อมูลจำนวนผลลัพธ์ |
hasMoreResults |
มีผลการค้นหาเพิ่มเติมสําหรับแหล่งที่มานี้หรือไม่ |
ฟิลด์การรวม
|
|
resultCountEstimate |
จำนวนผลลัพธ์โดยประมาณสำหรับแหล่งที่มานี้ |
resultCountExact |
จำนวนผลลัพธ์ที่แน่นอนสำหรับแหล่งที่มานี้ |