- 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。服務帳戶無法直接執行 Query API 要求。如要使用服務帳戶執行查詢,請設定 Google Workspace 全網域授權委派。
HTTP 要求
POST https://cloudsearch.googleapis.com/v1/query/search
這個網址使用 gRPC 轉碼語法。
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{ "requestOptions": { object ( |
欄位 | |
---|---|
requestOptions |
要求選項,例如搜尋應用程式和使用者時區。 |
query |
原始查詢字串。如要查看支援的搜尋運算子,請參閱使用運算子縮小搜尋範圍 |
pageSize |
要在單一頁面中傳回的搜尋結果數量上限。有效值介於 1 到 100 (含首尾)。預設值為 10。要求取得超過 2000 筆的結果時,最小值為 50。 |
start |
起始結果索引。 |
dataSourceRestrictions[] |
用於查詢的來源。如未指定,系統會使用目前搜尋應用程式的所有資料來源。 |
facetOptions[] |
|
sortOptions |
搜尋結果的排序選項 |
queryInterpretationOptions |
解讀使用者查詢內容的選項。 |
contextAttributes[] |
要求的情境屬性,會用於調整搜尋結果的排名。元素數量上限為 10 個。 |
回應主體
如果成功,回應主體即會包含具有以下結構的資料:
Search API 回應。
JSON 表示法 |
---|
{ "queryInterpretation": { object ( |
欄位 | |
---|---|
queryInterpretation |
查詢使用者查詢內容的解讀結果。如果已停用查詢解釋,則為空白。 |
results[] |
搜尋查詢的結果。 |
structuredResults[] |
使用者查詢的結構化結果。這些結果不會計入 pageSize 中。 |
spellResults[] |
查詢的建議拼字。 |
facetResults[] |
重複的 facet 結果。 |
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) 解讀功能。預設值為 False,設為 true 即可停用自然語言解讀功能。NL 解釋功能僅適用於預先定義的資料來源。 |
enableVerbatimMode |
啟用這個旗標即可關閉所有內部最佳化功能,例如將查詢的自然語言 (NL) 解讀、補充結果擷取和同義詞 (包括自訂字詞) 的使用方式。如果兩個旗標中的任一旗標為 True,系統就會停用 Nl 解譯功能。 |
disableSupplementalResults |
使用此旗標可停用查詢的補充結果。如果設為 True,系統會優先採用在 SearchApplication 層級選擇的補充結果設定。 |
QueryInterpretation
JSON 表示法 |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
欄位 | |
---|---|
interpretedQuery |
用來解讀搜尋的查詢字詞。舉例來說,系統會將使用自然語言意圖 (例如「email from john」的電子郵件) 的查詢解讀為「from:john source:mail」。如果原因為「NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY」,系統就不會填寫這個欄位。 |
interpretationType |
|
reason |
查詢解釋的原因。如果解釋類型不是「無」,則這個欄位不會「UNSPECIFIED」。 |
QueryInterpretation.InterpretationType
列舉 | |
---|---|
NONE |
擷取搜尋結果時,系統不會使用自然語言解讀法,也不會使用較廣泛版本的查詢內容。 |
BLEND |
同時顯示原始查詢的結果與其他結果。將這些其他結果與原始查詢的結果混合的原因,會填入下方的「原因」欄位。 |
REPLACE |
並取代原始查詢的結果。請在下方的「原因」欄位中填入取代原始查詢結果的原因。 |
QueryInterpretation.Reason
列舉 | |
---|---|
UNSPECIFIED |
|
QUERY_HAS_NATURAL_LANGUAGE_INTENT |
系統會使用查詢字詞的自然語言解讀結果擷取搜尋結果。 |
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY |
由於系統找不到的使用者查詢所傳回的結果過多,因此會使用查詢和文件字詞的相似度,選擇性地擴大查詢範圍,以擷取更多搜尋結果。在這個情況下,解讀的查詢都不會顯示。 |
SearchResult
含有文件已索引資訊的結果。
JSON 表示法 |
---|
{ "title": string, "url": string, "snippet": { object ( |
欄位 | |
---|---|
title |
搜尋結果的標題。 |
url |
搜尋結果的網址。網址包含 Google 重新導向至實際項目。這個網址已簽署,請勿變更。 |
snippet |
這個結果可用的所有摘要 (摘要)。 |
metadata |
搜尋結果的中繼資料。 |
clusteredResults[] |
如果來源已叢集,請提供叢集結果清單。只會有一個層級的叢集結果。如果目前的來源未啟用分群,這個欄位會留空。 |
debugInfo |
關於此搜尋結果的除錯資訊。 |
文字片段
搜尋結果的摘要,也就是摘要顯示網頁內容的摘要。
JSON 表示法 |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
欄位 | |
---|---|
snippet |
文件的程式碼片段。文件的程式碼片段。可能包含逸出 HTML 字元,顯示前應未逸出。 |
matchRanges[] |
程式碼片段中的相符範圍。 |
MatchRange
程式碼片段的相符範圍 [start, end)。
JSON 表示法 |
---|
{ "start": integer, "end": integer } |
欄位 | |
---|---|
start |
程式碼片段中相符項目的起始位置。 |
end |
程式碼片段中的相符項目結束。 |
Metadata
相符搜尋結果的中繼資料
JSON 表示法 |
---|
{ "source": { object ( |
欄位 | |
---|---|
source |
搜尋結果的指定來源,例如 Gmail。 |
mimeType |
搜尋結果的 Mime 類型。 |
thumbnailUrl |
搜尋結果的縮圖網址。 |
owner |
文件或搜尋結果物件的擁有者 (通常是建立者)。 |
createTime |
這份文件或搜尋結果中的建立時間。 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度,且最多 9 個小數位數。範例: |
updateTime |
搜尋結果中物件的上次修改日期。如未在項目中設定,這裡傳回的值會是空白。如果使用 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度,且最多 9 個小數位數。範例: |
fields[] |
結構化資料中已建立索引的欄位,會以一般命名屬性傳回。 |
displayOptions |
選項,用於指定如何顯示結構化資料搜尋結果。 |
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
來源特定 facet 回應
JSON 表示法 |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
欄位 | |
---|---|
sourceName |
傳回 Facet 結果的來源名稱。產品不會空白。 |
objectType |
傳回 Facet 結果的物件類型。可為空白。 |
operatorName |
選擇用於 facet 處理的運算子名稱。@see cloudsearch.SchemaPropertyOptions |
buckets[] |
回應值的 FacetBuckets ,至少包含一個符合對應篩選器的單一結果。 |
FacetBucket
facet 中的值區是基本作業單位,視區塊的欄位類型而定,值區可以包含單一值「或」連續範圍的值。FacetBucket 目前只會用於傳回回應物件。
JSON 表示法 |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
欄位 | |
---|---|
count |
符合值區值的結果數量。只有在確認計數準確度時,系統才會傳回計數。Cloud Search 不保證任何查詢的 facet 計數,而且可能只會間歇顯示,即使是相同的查詢也是如此。請勿根據 facet 數量存在建構依附元件;請改用一律傳回的 facet 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 |
這個來源的實際結果數量。 |