Query API 提供搜尋與建議方法來建立搜尋 或在應用程式中嵌入搜尋結果。
針對需求最少的網頁應用程式,建議使用搜尋小工具。 若需更多資訊,請參閲 使用搜尋小工具建立搜尋介面
建構搜尋介面
如要建構最精簡的搜尋介面,您需要完成以下幾個步驟:
- 設定搜尋應用程式
- 產生應用程式的 OAuth 憑證
- 查詢索引
- 顯示查詢結果
你可以透過下列功能進一步強化搜尋介面: 分頁、排序、篩選、 facet 和自動建議。
設定搜尋應用程式
您必須建立至少一個搜尋應用程式,才能與各個應用程式建立關聯 建立的搜尋介面搜尋應用程式會提供 參數,例如要使用的資料來源、排序順序 篩選器和商情項目您可以視需要覆寫這些參數 查詢 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
以便比對項目,而 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
中,您可能會顯示「Your search for your at
原始查詢的相關結果不足。包含類似結果
快速查詢。」
處理使用者結果
Cloud Search 會傳回兩種「使用者結果」類型:文件與
查詢中已使用該姓名,以及員工資訊
名稱已在查詢中使用後者的結果是 Cloud 函式
Google 搜尋的「使用者搜尋功能」功能,可在
這個
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 協助使用者以互動方式修正查詢並尋找 更快速地瀏覽相關商品
您可以在 搜尋應用程式中的關鍵字。 並由查詢中的設定覆寫
要求 facet 時,Cloud Search 會計算 所要求屬性。這些 值。使用這些值建立篩選器 ,縮小後續查詢的結果範圍
使用 facet 的典型互動模式為:
- 進行初始查詢,指定要納入 facet 的屬性 也就是預測結果
- 轉譯搜尋和 facet 結果。
- 使用者選取一或多個 facet 值以修正結果。
- 使用依據所選值的篩選器重複查詢。
舉例來說,如要依據年份和 MPAA 分級來修正電影查詢要求,
在查詢中加入 facetOptions
屬性。
"facetOptions": [
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "year"
},
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "rated"
}
]
採用整數欄位的 facet 結果
您也可以利用整數式欄位的 facet 要求結果。舉例來說,
可能會將名為 book_pages
的整數屬性標示為 facetable,以便修正
針對包含「100-200」書籍的搜尋結果網頁。
設定整數屬性欄位結構定義時,請設定
isFacetable
新增至 true
,並將對應的值區選項新增至
integerPropertyOptions
。
這可確保每個整數面向屬性都有預設的特徵分塊
已定義選項
定義特徵分塊選項邏輯時,請提供遞增值的陣列
這些表示法舉例來說,如果使用者指定
2, 5, 10, 100
,然後是 <2
、[2-5)
、[5-10)
、[10-100)
和 >=100
的商情項目
計算方式
您可以覆寫以整數為基礎的 facet,方法是定義相同的特徵分塊選項:
facetOptions
。如有需要,Cloud Search 會使用
如果搜尋應用程式和查詢要求都沒有 facet,則傳回結構定義
已定義選項查詢中定義的 facet 優先順序高於定義的 facet
,而搜尋應用程式中定義的 facet
優先順序高於結構定義中定義的 facet。
依文件大小或日期區分的商情項目結果
別擔心!您可以使用
保留運算子
依文件檔案大小、以位元組為單位或
已建立或修改文件。您不需要定義自訂結構定義
但您需要在搜尋應用程式的operatorName
FacetOptions
。
- 如要依據文件大小進行 facet 處理,請使用
itemsize
並定義特徵分塊選項。 - 如要依照文件建立日期進行 facet 處理,請使用
createddatetimestamp
。 - 如要依照文件修改的日期進行 facet 處理,請使用
lastmodified
。
解讀 facet 值區
facetResults
屬性含有使用者確切的篩選要求
在每個屬性的 filter
欄位中
bucket
。
如果是不是以整數計算的 Facet,facetResults
會包含以下項目的項目:
每個要求的資源每個屬性的值或範圍清單,稱為
提供的是 buckets
。最常出現的值會優先顯示。
當使用者選取一或多個值做為篩選依據時,請以下列條件建立新的查詢: 並再次查詢 API
新增建議
使用 suggest API 根據使用者的個人 查詢記錄以及聯絡人及其文件語料庫。
舉例來說,下列呼叫會針對 詞組 jo。
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
連結完畢後,就會顯示為適合您的 應用程式。