使用 Query API 建立搜尋介面

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

如果網頁應用程式沒有太多需求，建議您使用搜尋小工具。詳情請參閱「使用搜尋小工具建立搜尋介面」。

建構搜尋介面

如要建構最精簡的搜尋介面，您需要完成幾個步驟：

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

您還可以使用分頁、排序、篩選、 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，以及用於辨識搜尋應用程式 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 的情況下，您可能會顯示「Your search for your original query has not match any results. 目前顯示的是類似查詢的搜尋結果。」

在 BLEND 中，系統可能會顯示以下字串：「Your search for your original query doesn't match 支持足夠的結果. 包含類似查詢的結果。」

處理使用者結果

Cloud Search 會傳回兩種「使用者結果」：查詢中所用姓名的人物相關文件，以及查詢中使用姓名的員工資訊。後者的結果是 Cloud Search 的「使用者搜尋」功能，您可以在查詢 API 回應的 structuredResults 欄位中找到這類查詢的結果：

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

直接報表比對

直接報表比對是 Cloud Search 的「使用者搜尋」功能，可讓使用者查看機構中使用者的直接檢舉報告。結果可在 structuredResults 欄位中取得。

如果查詢與某人的主管或直屬部屬相關，回應會包含 assistCardProtoHolder 內的 structuredResults。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 種：

• 物件篩選器透過 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"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

使用 facet 修正結果

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

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

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

使用 facet 的典型互動模式為：

1. 建立初始查詢，指定要包含在 facet 結果中的屬性。
2. 轉譯搜尋和 facet 結果。
3. 使用者選取一或多個 facet 值以修正結果。
4. 使用依據所選值的篩選器重複查詢。

例如，如要依據年份和 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 的商情項目。

只要將相同的特徵分塊選項定義為 facetOptions，即可覆寫整數型 facet。如有需要，當搜尋應用程式和查詢要求都未定義 facet 選項時，Cloud Search 會使用結構定義中定義的特徵分塊選項。查詢中定義的 facet 優先順序高於搜尋應用程式中定義的 facet，而搜尋應用程式中定義的 facet 則優先於結構定義中定義的 facet。

依文件大小或日期區分的商情項目結果

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

• 如要依據文件大小進行 facet 處理，請使用 itemsize 並定義特徵分塊選項。
• 如要依照文件建立日期進行 facet 處理，請使用 createddatetimestamp。
• 如要依照文件修改的日期進行 facet 處理，請使用 lastmodified。

解讀 facet 值區

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

如果 facet 不是以整數計算，facetResults 會為每個要求的屬性提供一個項目。系統會為每個屬性提供名為 buckets 的值或範圍清單。最常出現的值會優先顯示。

當使用者選取一或多個值做為篩選依據時，請使用所選篩選條件建立新的查詢，然後再次查詢 API。

新增建議

使用 suggest API 提供自動完成功能，可根據使用者的個人查詢記錄以及聯絡人及其文件語料庫提供查詢建議。

舉例來說，下列呼叫針對部分詞組 jo 提供建議。

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

然後，您便可以為應用程式顯示合適的建議。