使用 Query API 建立搜尋介面

Query API 提供搜尋和建議方法，可建構搜尋介面，或將結果嵌入應用程式。

如果網頁應用程式的需求不高，建議使用搜尋小工具。請參閱「使用搜尋小工具建立搜尋介面」。

建立搜尋介面

如要建構最基本的搜尋介面，需要執行下列步驟：

  1. 設定搜尋應用程式。
  2. 為應用程式產生 OAuth 憑證。
  3. 查詢索引。
  4. 顯示查詢結果。

您可以透過分頁、排序、篩選、構面和自動完成等功能，強化介面。

設定搜尋應用程式

您必須為每個搜尋介面建立至少一個搜尋應用程式。 搜尋應用程式會提供預設參數，例如資料來源、排列順序、篩選器和商情項目。您可以使用 Query API 覆寫這些參數。

您無法在查詢中增加資料來源數量，超過搜尋應用程式中設定的數量。您可以使用 dataSourceRestrictions 將查詢限制為這些來源的子集。

詳情請參閱「自訂搜尋體驗」。

為應用程式產生 OAuth 憑證

除了設定 Cloud Search API 的存取權中的步驟，您還必須為網頁應用程式產生 OAuth 憑證。

使用憑證代表使用者要求授權。使用範圍 https://www.googleapis.com/auth/cloud_search.query。

如要進一步瞭解 OAuth 選項，請參閱 Google Identity Platform。

查詢索引

請使用 search 方法搜尋索引。

每項要求都必須包含文字 query 和 searchApplicationId。

這個範例會查詢電影資料來源：

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  }
}

顯示查詢結果

搜尋介面應顯示項目 title 和原始項目的連結。你也可以使用摘要和中繼資料來改善顯示方式。

處理補充結果

如果查詢的相符結果不足，Cloud Search 會傳回補充結果。這是由 queryInterpretation 欄位所指定。如果只傳回補充結果，則 InterpretationType 為 REPLACE。如果已混音，則為 BLEND。

傳回補充結果時，請考慮通知使用者。如果 a REPLACE，你可能會說：「找不到符合搜尋條件的結果。目前顯示的是相似查詢的結果。」

處理使用者搜尋結果

Cloud Search 會使用「人員搜尋」功能，傳回與人員和員工資訊相關的文件。結果位於「structuredResults」欄位：

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

比對位部屬

「直屬部屬比對」功能可讓使用者查看某人的直屬部屬。回應包含 assistCardProtoHolder，其中 cardType 為 RELATED_PEOPLE_ANSWER_CARD。

關閉最佳化功能

系統預設會啟用最佳化功能，例如提供補充結果。您可以停用這些功能：

醒目顯示摘要

Cloud Search 會傳回已建立索引的文字或 HTML 片段。如果存在查詢字詞，matchRanges 會識別其位置。使用這些範圍醒目顯示文字。

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 欄位提供 createTime、updateTime 和結構化資料等資訊。使用 displayOptions 顯示結構化資料。

擷取其他結果

如要擷取更多結果，請將 start 欄位設為所選的位移。使用 pageSize 調整頁面大小。使用 resultCount 顯示商品總數或預估數量。

將搜尋結果排序

使用 sortOptions 指定順序：

  • operatorName：要排序的屬性。
  • sortOrder：ASCENDING 或 DESCENDING。

相關性是預設和次要排序鍵。

新增篩選器

在搜尋應用程式或要求中，使用篩選器限制結果。如果兩者都為來源指定篩選器，則兩者都必須評估為 true。

在 dataSourceRestrictions.filterOptions[] 中套用篩選器。 主要篩選器類型：

  • 物件篩選器：將比對結果限制為特定類型。
  • 值篩選器：根據運算子和值限制相符項目。

複合篩選條件 會合併多個值篩選條件。

使用 Facet 修正結果

Facet 可協助使用者以互動方式修正查詢。要求 Facet 時，Cloud Search 會計算這些屬性最常出現的值。

一般模式： 1. 查詢，指定刻面屬性。 1. 顯示搜尋和 facet 結果。 1. 使用者選取 facet 值。 1. 根據所選項目重複查詢並套用篩選條件。

以整數為基礎的欄位 Facet 結果

將整數屬性標示為可建立 Facet，即可依範圍縮小結果範圍 (例如「100-200」頁面)。將 isFacetable 設為 true，並在結構定義中定義預設分組選項。

依文件大小或日期分類結果

使用 保留運算子：

  • itemsize：檔案大小 (以位元組為單位)。
  • createddatetimestamp：建立日期。
  • lastmodified：修改日期。

新增建議

使用 suggest API，根據查詢記錄、聯絡人和文件內容提供自動完成建議。