使用 Query API 建立搜尋介面

Query API 提供搜尋和建議方法，方便您建立搜尋介面或在應用程式中嵌入搜尋結果。

針對需求最低的網路應用程式，請考慮使用搜尋小工具。詳情請參閱使用搜尋小工具建立搜尋介面。

建立搜尋介面

建立精簡的搜尋介面需要幾個步驟：

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

您可以利用分頁、排序、篩選、商情項目和自動建議等功能，進一步改善搜尋介面。

設定搜尋應用程式

您必須將至少一個搜尋應用程式與您建立的每個搜尋介面建立關聯。搜尋應用程式會提供預設的查詢參數，例如要使用的資料來源、排列順序、篩選器，以及想要的商情項目。如有需要，您可以使用查詢 API 覆寫這些參數。

注意： 雖然您可以在呼叫 query 時覆寫搜尋應用程式設定，但除了搜尋應用程式所設定的資料來源之外，您無法將查詢使用的資料來源數量增加。只要在查詢呼叫中設定 dataSourceRestrictions，即可限制查詢的部分來源。

注意： 更新或刪除結構定義時，搜尋應用程式也會更新。舉例來說，如果結構定義運算子已重新命名，那麼搜尋應用程式設定中也會重新命名該運算子。如果結構定義更新與搜尋應用程式不相容，而您無法更新搜尋應用程式，則結構定義更新就會失敗，並在更新回應中傳送錯誤。

如要進一步瞭解搜尋應用程式，請參閱自訂 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。

下列程式碼片段顯示電影 Titanic 電影資料來源的查詢：

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

顯示查詢結果

搜尋介面至少應會顯示項目 title 以及原始項目的連結。您可以利用搜尋結果提供的其他資訊 (例如摘要和中繼資料)，進一步提升搜尋結果的顯示方式。

注意： 如果您看不到特定資料來源的結果，請確認您已建立自訂搜尋應用程式，且該搜尋應用程式的資料來源已啟用。如要進一步瞭解如何建立搜尋應用程式，請參閱自訂 Cloud Search 搜尋體驗一文。

處理補充結果

根據預設，當使用者查詢不足的結果時，Cloud Search 會傳回補充結果。回應中的 queryInterpretation 欄位表示傳回補充結果的時間。如果只傳回補充結果，InterpretationType 會設為 REPLACE。如果原始查詢的某些結果與補充結果一起傳回，InterpretationType 會設定為 BLEND。無論是哪一種情況，QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY

傳回部分補充結果時，建議您提供文字來指出補充結果。以 REPLACE 為例，您可能會看到「Search for your your query query does not match a results. 顯示類似的查詢結果。」

以 BLEND 為例，系統可能會顯示「Your search for your original query that does not match on results. 包含類似查詢的結果。」

處理使用者搜尋結果

Cloud Search 會傳回兩種「使用者結果」：與查詢搭配使用姓名的姓名相關的文件，以及查詢中查詢者的姓名的員工資訊。後者的結果是 Cloud Search 使用者搜尋功能的函式，而該查詢的結果可以在查詢 API 回應的 structuredResults 欄位中找到：

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

注意： 如果客戶的網域中定義了超過 20 個自訂屬性，則「搜尋使用者」只會使用 20 個自訂屬性。

關閉最佳化功能，包括補充結果

系統會預設啟用最佳化功能，例如補充結果。不過，您可以關閉所有最佳化作業，也可以只停用搜尋應用程式和查詢層級的補充結果：

• 如要在搜尋應用程式層級關閉所有最佳化功能 (包括補充結果、同義詞和拼字檢查功能)，請在搜尋應用程式中，將 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"
}

新增篩選條件

除了查詢運算式以外，您可以套用篩選器來進一步限制結果。您可以在搜尋應用程式和搜尋要求中指定篩選器。

注意： 如果搜尋應用程式和搜尋要求中都含有資料來源的篩選器，則兩個篩選器都必須評估為 true 才能傳回項目。

如要在要求或搜尋應用程式中新增篩選器，請在 dataSourceRestrictions.filterOptions[] 欄位中新增篩選器。

你可以透過下列 2 種主要方式進一步篩選資料來源：

• 物件篩選器透過 filterOptions[].objectType 屬性 — 限制符合自訂結構定義中定義的指定類型的項目。
• 值篩選器：根據查詢運算子和提供的值限制相符的項目。

複合篩選器可讓將多個值篩選器結合成邏輯運算式，藉此執行更複雜的查詢。

在電影結構定義範例中，您可以根據目前使用者套用年齡限制，並根據 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"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

使用商情項目調整搜尋結果範圍

商情項目是索引屬性，代表修正搜尋結果的類別。利用商情項目協助使用者以互動式方式修正查詢，並更快找到相關項目。

您可以在搜尋應用程式中定義商情項目，並透過查詢中的設定加以覆寫。

要求商情項目時，Cloud Search 會計算相符項目中要求屬性的最高值。這些值會在回應中傳回。請使用這些值建構篩選器，以縮小後續查詢的結果範圍。

與商情項目的一般互動模式如下：

1. 進行初始查詢，指定要在商情項目結果中納入哪些屬性。
2. 顯示搜尋和商情項目的結果。
3. 使用者會選取一或多個商情項目值來縮小結果範圍。
4. 使用篩選器產生以所選值為基礎的查詢。

注意： Facet 只能用於具有結構化資料屬性的項目。

舉例來說，如要依照年份和 MPAA 分級來修正電影查詢，請在查詢中加入 facetOptions 屬性。

"facetOptions": [
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "year"
  },
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "rated"
  }
]

含有整數欄位的商情項目結果

您也可以使用整數型欄位來呼叫要求結果。例如，您可以將名為 book_pages 的整數屬性標示為臉孔資料表，以修正搜尋含有「100-200」頁的書籍搜尋結果。

設定整數屬性欄位結構定義時，請將 isFacetable 設為 true，並在 integerPropertyOptions 中新增對應的特徵分塊選項。這能確保每個整數-表屬性都有已定義的預設特徵分組選項。

定義特徵分塊選項邏輯時，請提供用來表示範圍的遞增值陣列。舉例來說，如果使用者指定 2, 5, 10, 100 的範圍，系統會計算 <2、[2-5)、[5-10)、[10-100)、>=100 的商情項目。

您可以在要求中的 facetOptions 定義相同的特徵分塊選項，藉此覆寫整數型商情項目。如果需要，當搜尋應用程式或查詢要求未定義商情項目選項時，Cloud Search 會使用結構定義中定義的值區分類選項。查詢中定義的商情項目的優先順序高於搜尋應用程式中定義的商情項目，搜尋應用程式中的商情項目則優先於結構定義中定義的商情項目。

依文件大小或日期顯示商情項目搜尋結果

您可以使用保留運算子來依文件檔案大小 (以位元組為單位) 或文件建立或修改的時間，修正搜尋結果。您不需要定義自訂結構定義，但必須在搜尋應用程式的 FacetOptions 中指定 operatorName 值。

• 如要依文件大小顯示商情項目，請使用 itemsize 並定義值區選項。
• 如要依文件建立日期進行商情項目，請使用 createddatetimestamp。
• 如要依文件修改日期進行商情項目，請使用 lastmodified。

解讀商情項目值區

搜尋查詢回應中的 facetResults 屬性會在每個 bucket 的 filter 欄位中，填入使用者的確切篩選器要求。

針對非以整數為基礎的商情項目，facetResults 會為每個要求的屬性加入一個項目。系統會為每個屬性提供一個值或範圍的清單，稱為 buckets。最常出現的值會優先顯示。

當使用者選取一或多個要篩選的值時，請使用所選篩選器建構新的查詢，然後再次查詢 API。

新增建議

使用 suggest API，根據使用者的個人查詢記錄，以及聯絡人及其文件資料庫來提供自動查詢建議。

例如，下列呼叫提供部分詞組 jo 的建議。

{
  "query": "jo",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>",
    "peoplePhotoOptions": {
      "peoplePhotoUrlSizeInPx": 32
    },
    "timeZone": "America/Denver"
  }
}

接著，您可以視情況顯示應用程式產生的建議。