Method: query.search

Cloud Search 查詢 API 提供搜尋方法，可根據使用者查詢傳回最相關的結果。結果可能來自 Gmail 或 Google 雲端硬碟等 Google Workspace 應用程式，也可能來自您從第三方建立索引的資料。

注意：執行這項 API 時，必須使用標準使用者帳戶。服務帳戶無法直接執行查詢 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 之間 (包括 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 回應。下一個 ID：19

如果成功，回應主體會含有以下結構的資料：

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 可停用自然語言解讀功能。自然語言解讀功能僅適用於預先定義的資料來源。
enableVerbatimMode

boolean

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

boolean

使用這項標記可針對查詢停用補充結果。如果設為 True，系統會優先採用在 SearchApplication 層級選擇的補充結果設定。

QueryInterpretation

JSON 表示法 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason),
  "interpretedQueryActualResultCount": integer,
  "interpretedQueryEstimatedResultCount": string
}
欄位
interpretedQuery

string

搜尋時使用的查詢解讀結果。舉例來說，如果查詢內容是「john 的電子郵件」這類自然語言意圖，系統會解讀為「from:john source:mail」。如果原因是 NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY，則不會填寫這個欄位。
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

查詢解讀的原因。如果解讀類型不是 NONE，這個欄位就不會是 UNSPECIFIED。
interpretedQueryActualResultCount

integer

解譯查詢實際傳回的結果數。
interpretedQueryEstimatedResultCount

string (int64 format)

解讀查詢後預計傳回的結果數量。

QueryInterpretation.InterpretationType

列舉
NONE 系統不會使用自然語言解讀結果，也不會使用範圍較廣的查詢來擷取搜尋結果。
BLEND 原始查詢的結果會與其他結果合併。下方「原因」欄位會填入將這些其他結果與原始查詢結果混合的原因。
REPLACE 原始查詢的結果會遭到取代。下方「原因」欄位會填入取代原始查詢結果的原因。

QueryInterpretation.Reason

列舉
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT 系統會解讀查詢的自然語言，並據此擷取搜尋結果。
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY 查詢和文件字詞相似度，有助於在使用者查詢找不到足夠結果時，選擇性擴大查詢範圍，擷取更多搜尋結果。這個案件的解讀查詢會是空白。

SearchResult

結果包含文件的索引資訊。下一個 ID：16

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

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

中繼資料

相符搜尋結果的中繼資料。

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)

搜尋結果中顯示的文件或物件建立時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime

string (Timestamp format)

搜尋結果中物件的上次修改日期。如果未在項目中設定，這裡傳回的值會是空白。如果使用 updateTime 計算新近度，但未設定該值，系統會將這個值預設為目前時間的 2 年前。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
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

顯示查詢.搜尋結果的欄位

JSON 表示法 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
欄位
label

string

房源的顯示標籤。
operatorName

string

房源的營運商名稱。
property

object (NamedProperty)

屬性的名稱/值組合。

ResultDebugInfo

結果的偵錯資訊。

JSON 表示法 
{
  "formattedDebugInfo": string
}
欄位
formattedDebugInfo

string

一般偵錯資訊，格式適合顯示。

StructuredResult

搜尋要求中傳回的結構化結果。

JSON 表示法 
{

  // Union field structured_result can be only one of the following:
  "person": {
    object (Person)
  }
  // End of list of possible types for union field structured_result.
}
欄位

聯集欄位 structured_result。

structured_result 只能是下列其中一個設定：
person

object (Person)

人物表示法

SpellResult

JSON 表示法 
{
  "suggestedQuery": string,
  "suggestionType": enum (SpellResult.SuggestionType),
  "suggestedQueryHtml": {
    object (SafeHtmlProto)
  }
}
欄位
suggestedQuery

string

查詢的建議拼字。
suggestionType

enum (SpellResult.SuggestionType)

目前查詢觸發的建議。
suggestedQueryHtml

object (SafeHtmlProto)

經過清理的 HTML，代表可用於 UI 的拼字檢查修正查詢。這通常會包含特定語言的標記，用來標示查詢中經過拼字檢查的部分。

SpellResult.SuggestionType

查詢觸發的建議類型。

列舉
SUGGESTION_TYPE_UNSPECIFIED 預設拼字檢查類型
NON_EMPTY_RESULTS_SPELL_SUGGESTION 沒有任何結果的拼字建議已變更。系統仍會顯示原始查詢的結果 (有非零 / 結果)，並建議可產生結果的拼字。
ZERO_RESULTS_FULL_PAGE_REPLACEMENT 如果原始查詢沒有結果，系統會觸發拼字建議。如果原始查詢沒有結果，但拼字建議有結果，系統就會觸發拼字修正查詢的結果。

SafeHtmlProto

重要事項：請勿接受來自不受信任來源的這則訊息，因為攻擊者很容易偽造不符合類型安全合約的序列化訊息，例如可能含有攻擊者控制的指令碼。接收 SafeHtmlProto 的系統會隱含信任 SafeHtmlProto 的產生者。因此，在 RPC 回應中傳回這則訊息通常是安全的，但在 RPC 要求中接受這則訊息通常不安全。

JSON 表示法 
{
  "privateDoNotAccessOrElseSafeHtmlWrappedValue": string
}
欄位
privateDoNotAccessOrElseSafeHtmlWrappedValue

string

重要事項：請勿設定或讀取這個欄位 (即使是從測試中也是如此)，這個欄位是私人的。如要瞭解用來建立或讀取這則訊息的程式設計語言套件，請參閱 .proto 檔案頂端的說明文件。

FacetResult

特定來源的構面回應

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

string

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

string

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

string

用於分層的運算子名稱。@see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

回應中值的 FacetBuckets，至少包含一個具有對應篩選條件的結果。

FacetBucket

分面中的 bucket 是基本作業單位。視分組欄位的類型而定，值區可包含單一值或連續值範圍。FacetBucket 目前僅用於傳回回應物件。

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

  // Union field bucket_value can be only one of the following:
  "value": {
    object (Value)
  }
  // End of list of possible types for union field bucket_value.
}
欄位
count

integer

與範圍值相符的結果數量。只有在確保計數準確度時，系統才會傳回搜尋次數。Cloud Search 無法保證任何查詢的構面計數，即使是相同的查詢，構面計數也可能只會間歇性顯示。請勿根據顯示的構面數量建立依附元件，而是使用一律會傳回的構面數量百分比。
percentage

integer

與範圍值相符的結果百分比。傳回的值介於 (0-100]，如果為分數，則會向下捨入為整數。如果未明確傳回值，則代表四捨五入後為 0 的百分比值。系統會傳回所有搜尋的百分比，但這些都是預估值。由於系統一律會傳回百分比，因此您應轉譯百分比，而非計數。
filter

object (Filter)

如果選取對應值區，則要傳遞至搜尋要求的篩選器。
聯集欄位 bucket_value。分面值區間或值 bucket_value 只能是下列其中一項：
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)

這個來源的確切結果數。