Query API 提供搜尋和建議方法，可建構搜尋介面，或在應用程式中嵌入搜尋結果。
如果網頁應用程式的需求極少，建議使用搜尋小工具。 詳情請參閱「使用搜尋小工具建立搜尋介面」。
建立搜尋介面
如要建構最基本的搜尋介面，需要執行下列步驟：
- 設定搜尋應用程式
- 為應用程式產生 OAuth 憑證
- 查詢索引
- 顯示查詢結果
您可以使用分頁、排序、篩選、商情項目和自動建議等功能，進一步強化搜尋介面。
設定搜尋應用程式
您必須建立至少一個搜尋應用程式，才能與您建立的每個搜尋介面建立關聯。搜尋應用程式會提供預設的查詢參數，例如要使用的資料來源、排列順序、篩選器，以及想要的商情項目。如有需要，您可以使用 Query API 覆寫這些參數。
如要進一步瞭解搜尋應用程式，請參閱「自訂 Cloud Search 搜尋體驗」。
為應用程式產生 OAuth 憑證
除了設定 Google Cloud Search API 的存取權中的步驟，您也必須為網頁應用程式產生 OAuth 憑證。您建立的憑證類型取決於 API 的使用情境。
使用憑證代表使用者要求授權。要求授權時，請使用範圍 https://www.googleapis.com/auth/cloud_search.query。
如要進一步瞭解 OAuth 選項和用戶端程式庫，請參閱 [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"})。
查詢索引
使用 search 方法對索引執行搜尋。
每項要求都必須包含兩項資訊：用來比對項目的文字 query，以及用來識別要使用的搜尋應用程式 ID 的 searchApplicationId。
以下程式碼片段顯示對電影《鐵達尼號》資料來源的查詢：
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
},
}
顯示查詢結果
搜尋介面至少應顯示項目 title，以及原始項目的連結。您可以利用搜尋結果中顯示的額外資訊 (例如摘要和中繼資料)，進一步改善搜尋結果的顯示方式。
處理補充結果
如果使用者查詢的結果不足，Cloud Search 預設會傳回補充結果。回應中的 queryInterpretation 欄位會指出何時傳回補充結果。如果只傳回補充結果，InterpretationType 會設為 REPLACE。如果系統傳回原始查詢的幾項結果，以及補充結果，InterpretationType 會設為 BLEND。無論哪種情況，QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY。
如果系統傳回部分補充結果，請考慮提供文字，指出系統傳回了補充結果。舉例來說，如果是 REPLACE，您可能會顯示「找不到任何與原始查詢相符的結果。目前顯示的是相似查詢的結果。」
如果是 BLEND，您可能會顯示「您的原始查詢搜尋結果不夠多。包含類似查詢的結果。
處理使用者搜尋結果
Cloud Search 會傳回兩種類型的「使用者結果」：與查詢中使用的使用者姓名相關的文件，以及查詢中使用的使用者姓名的員工資訊。後者是 Cloud Search 的「人員搜尋」功能所產生的結果，這類查詢的結果會顯示在查詢 API 回應的 structuredResults 欄位中：
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
比對位部屬
「直屬部屬比對」是 Cloud Search 的「使用者搜尋」功能，可讓使用者查看機構中某位人員的直屬部屬。結果會顯示在 structuredResults 欄位中。
如果查詢對象是某人的主管或直屬部屬，回覆內容會顯示 structuredResults 內的 assistCardProtoHolder。assistCardProtoHolder 具有名為 cardType 的欄位，該欄位會等於 RELATED_PEOPLE_ANSWER_CARD。assistCardProtoHolder 包含名為 relatedPeopleAnswerCard 的資訊卡，其中包含實際回應。其中包含 subject (查詢中包含的人員) 和 relatedPeople，也就是與主體相關的一組人員。relationType 欄位會傳回 MANAGER 或 DIRECT_REPORTS 值。
下列程式碼顯示直接下屬比對查詢的回應範例：
{
"results": [],
"structuredResults": [{
"assistCardProtoHolder": {
"extensions": {
"@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
"cardMetadata": {
"cardCategory": "ANSWER"
},
"cardType": "RELATED_PEOPLE_ANSWER_CARD",
"relatedPeopleAnswerCard": {
"subject": {
"email": "AdamStanford@psincs-test01.newjnj.com",
"displayName": "Adam Stanford"
"manager": {
"email": "simonsais@psincs-test01.newjnj.com"
}
},
"relatedPeople": [{
"email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
"displayName": "Edgar Mountain Ramirez"
}, {
"email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
"displayName": "Francisco Jose Martinez"
}],
"relationType": "DIRECT_REPORTS",
}
}
}
}]
}
關閉最佳化功能，包括補充結果
系統預設會啟用最佳化功能，例如補充結果。不過，您可以在搜尋應用程式和查詢層級關閉所有最佳化功能，或僅關閉補充結果：
如要在搜尋應用程式層級關閉所有最佳化功能，包括補充結果、同義詞和拼字修正，請在搜尋應用程式中將
QueryInterpretationConfig.force_verbatim_mode設為true。如要關閉搜尋查詢層級的所有最佳化功能，包括補充結果、同義詞和拼字修正，請將
QueryInterpretationOptions.enableVerbatimMode設為搜尋查詢中的true。如要在搜尋應用程式層級關閉補充結果，請在搜尋查詢中將
QueryInterpretationOptions.forceDisableSupplementalResults設為true。如要在搜尋查詢層級關閉補充結果，請在搜尋查詢中將
QueryInterpretationOptions.disableSupplementalResults設為true。
醒目顯示摘要
如果傳回的項目包含已編入索引的文字或 HTML 內容，系統會傳回內容的程式碼片段。這類內容可協助使用者判斷回傳項目是否相關。
如果摘要中含有查詢字詞，系統也會傳回一或多個相符範圍，指出字詞的位置。
在算繪結果時，使用 matchRanges 醒目顯示相符文字。以下 JavaScript 範例會將程式碼片段轉換為 HTML 標記，並以 <span> 標記包住每個相符範圍。
function highlightSnippet(snippet) {
let text = snippet.snippet;
let formattedText = text;
if (snippet.matchRanges) {
let parts = [];
let index = 0;
for (let match of snippet.matchRanges) {
let start = match.start || 0; // Default to 0 if omitted
let end = match.end;
if (index < start) { // Include any leading text before/between ranges
parts.push(text.slice(index, start));
}
parts.push('<span class="highlight">');
parts.push(text.slice(start, end));
parts.push('</span>');
index = end;
}
parts.push(text.slice(index)); // Include any trailing text after last range
formattedText = parts.join('');
}
return formattedText;
}
假設有以下程式碼片段：
{
"snippet": "This is an example snippet...",
"matchRanges": [
{
"start": 11,
"end": 18
}
]
}
產生的 HTML 字串如下：
This is an <span class="highlight">example</span> snippet...
向上傳者顯示的中繼資料
使用 metadata 欄位顯示傳回項目的其他資訊，這些資訊可能與使用者相關。metadata 欄位包含項目的 createTime 和 updateTime，以及與項目相關聯的任何可退回結構化資料。
如要顯示結構化資料，請使用 displayOptions 欄位。displayOptions 欄位包含物件類型的顯示標籤和一組 metalines。每個中繼行都是顯示標籤和值配對的陣列，如結構定義中所設定。
擷取其他結果
如要擷取其他結果，請將要求中的 start 欄位設為所需偏移值。你可以使用 pageSize 欄位調整每個頁面的大小。
如要顯示傳回的項目數量，或顯示分頁控制項來瀏覽傳回的項目，請使用 resultCount 欄位。系統會根據結果集的大小，提供實際值或預估值。
將搜尋結果排序
使用 sortOptions 欄位指定傳回項目的順序。sortOptions 值是含有兩個欄位的物件：
operatorName：結構化資料屬性的運算子，可依此排序。如果屬性有多個運算子，您只能使用主要等號運算子排序。sortOrder：排序方向，可為ASCENDING或DESCENDING。
系統也會使用關聯性做為次要排序鍵。如果查詢未指定排序順序，系統只會依關聯性排序結果。
"sortOptions": {
"operatorName": "priority",
"sortOrder": "DESCENDING"
}
新增篩選器
除了查詢運算式，您也可以套用篩選器，進一步限制結果。您可以在搜尋應用程式和搜尋要求中指定篩選條件。
如要在要求或搜尋應用程式中新增篩選器，請在 dataSourceRestrictions.filterOptions[] 欄位中新增篩選器。
如要進一步篩選資料來源，主要有 2 種方式：
複合篩選器 可將多個值篩選器合併為邏輯運算式，用於更複雜的查詢。
在電影結構定義範例中，您可以根據目前使用者套用年齡限制，並根據美國電影協會 (MPAA) 分級限制可觀看的電影。
{
"query": "adventure",
"requestOptions": {
"searchApplicationId": "<search_app_id>"
},
"dataSourceRestrictions": [
{
"source": {
"name": "datasources/<data_source_id>"
},
"filterOptions": [
{
"objectType": "movie",
"filter": {
"compositeFilter": {
"logicOperator": "AND"
"subFilters": [
{
"compositeFilter": {
"logicOperator": "OR"
"subFilters": [
{
"valueFilter": {
"operatorName": "rated",
"value": {
"stringValue": "G"
}
}
},
{
"valueFilter": {
"operatorName": "rated",
"value": {
"stringValue": "PG"
}
}
}
]
}
]
}
}
}
]
}
]
}
使用 Facet 修正結果
Facet 是已編入索引的屬性，代表用於縮小搜尋結果範圍的類別。使用層面協助使用者以互動方式修正查詢，並更快找到相關項目。
您可以在搜尋應用程式中定義層面，並在查詢中覆寫設定。
要求 Facet 時，Cloud Search 會計算相符項目中要求屬性的最常出現值。這些值會以回應形式傳回。使用這些值建構篩選器，縮小後續查詢的結果範圍。
與分面互動的一般模式如下：
- 進行初始查詢，指定要在分面結果中納入哪些屬性。
- 顯示搜尋和 Facet 結果。
- 使用者選取一或多個商情項目值，縮小搜尋結果範圍。
- 根據所選值重複查詢並套用篩選條件。
舉例來說，如要依年份和 MPAA 分級篩選電影查詢，請在查詢中加入 facetOptions 屬性。
"facetOptions": [
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "year"
},
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "rated"
}
]
以整數為基礎的欄位 Facet 結果
您也可以使用以整數為基礎的欄位，對要求結果進行分面。舉例來說，您可以將名為 book_pages 的整數屬性標示為可切面，以便在搜尋頁數為「100 到 200」的書籍時，縮小搜尋範圍。
設定整數屬性欄位結構定義時，請將 isFacetable 設為 true，並在 integerPropertyOptions 中新增對應的分類選項。這可確保每個可依整數排序的屬性都已定義預設分組選項。
定義值區選項邏輯時，請提供遞增值陣列，代表範圍。舉例來說，如果使用者指定的範圍為 2, 5, 10, 100，系統就會計算 <2、[2-5)、[5-10)、[10-100) 和 >=100 的層面。
您可以在要求中定義相同的分類選項，藉此覆寫以整數為準的 Facet。facetOptions如果搜尋應用程式和查詢要求都未定義 facet 選項，Cloud Search 會視需要使用結構定義中定義的 bucketing 選項。查詢中定義的 Facet 優先於搜尋應用程式中定義的 Facet，而搜尋應用程式中定義的 Facet 優先於結構定義中定義的 Facet。
依文件大小或日期分類結果
您可以使用保留的運算子，依文件大小 (以位元組為單位) 或文件建立/修改時間，縮小搜尋結果範圍。您不需要定義自訂結構定義，但必須在搜尋應用程式的 FacetOptions 中指定 operatorName 值。
- 如要依文件大小進行分面，請使用
itemsize並定義分組選項。 - 如要依文件建立日期進行分面，請使用
createddatetimestamp。 - 如要依文件修改日期進行分面，請使用
lastmodified。
解讀 facet 值區
搜尋查詢回應中的 facetResults
屬性，會針對每個 bucket，在 filter 欄位中加入使用者的確切篩選要求。
如果商情項目不是以整數為準，facetResults 會為每個要求的屬性加入項目。每個屬性都會提供值或範圍清單，稱為 buckets。系統會優先顯示最常出現的值。
當使用者選取一或多個要篩選的值時，請使用所選篩選器建構新查詢，然後再次查詢 API。
新增建議
使用 suggest API，根據使用者的個人查詢記錄、聯絡人和文件集，提供查詢自動完成功能。
舉例來說，下列呼叫會針對部分片語「jo」提供建議。
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
然後，您可以視應用程式需求顯示建議。