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

這個網址使用 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。要求取得超過 2000 筆的結果時，最小值為 50。
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)

重複的 facet 結果。
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) 解讀功能。預設值為 False，設為 true 即可停用自然語言解讀功能。NL 解釋功能僅適用於預先定義的資料來源。
enableVerbatimMode

boolean

啟用這個旗標即可關閉所有內部最佳化功能，例如將查詢的自然語言 (NL) 解讀、補充結果擷取和同義詞 (包括自訂字詞) 的使用方式。如果兩個旗標中的任一旗標為 True，系統就會停用 Nl 解譯功能。
disableSupplementalResults

boolean

使用此旗標可停用查詢的補充結果。如果設為 True，系統會優先採用在 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)

查詢解釋的原因。如果解釋類型不是「無」，則這個欄位不會「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 (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
欄位
title

string

搜尋結果的標題。
url

string

搜尋結果的網址。網址包含 Google 重新導向至實際項目。這個網址已簽署，請勿變更。
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

程式碼片段中的相符項目結束。

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

搜尋結果的縮圖網址。
owner

object (Person)

文件或搜尋結果物件的擁有者 (通常是建立者)。
createTime

string (Timestamp format)

這份文件或搜尋結果中的建立時間。

RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

搜尋結果中物件的上次修改日期。如未在項目中設定，這裡傳回的值會是空白。如果使用 updateTime 計算更新間隔且未設定，這個值會預設為距離目前時間的 2 年。

RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
fields[]

object (NamedProperty)

結構化資料中已建立索引的欄位，會以一般命名屬性傳回。
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

來源特定 facet 回應

JSON 表示法 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
欄位
sourceName

string

傳回 Facet 結果的來源名稱。產品不會空白。
objectType

string

傳回 Facet 結果的物件類型。可為空白。
operatorName

string

選擇用於 facet 處理的運算子名稱。@see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

回應值的 FacetBuckets ，至少包含一個符合對應篩選器的單一結果。

FacetBucket

facet 中的值區是基本作業單位，視區塊的欄位類型而定，值區可以包含單一值「或」連續範圍的值。FacetBucket 目前只會用於傳回回應物件。

JSON 表示法 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
欄位
count

integer

符合值區值的結果數量。只有在確認計數準確度時，系統才會傳回計數。Cloud Search 不保證任何查詢的 facet 計數，而且可能只會間歇顯示，即使是相同的查詢也是如此。請勿根據 facet 數量存在建構依附元件；請改用一律傳回的 facet 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)

這個來源的實際結果數量。