使用 Query API 建立搜尋介面

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

如果是有最低需求的網頁應用程式，建議您使用搜尋小工具。詳情請參閱「使用搜尋小工具建立搜尋介面」一文

建構搜尋介面

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

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

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

設定搜尋應用程式

您必須建立至少一個搜尋應用程式，才能與您建立的每個搜尋介面建立關聯。搜尋應用程式會提供查詢的預設參數，例如要使用的資料來源、排序順序、篩選器，以及要要求的商情項目。如有需要，您可以使用查詢 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 種：

• 物件篩選器 (透過 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. 進行初始查詢，指定要在 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。這可確保每個整數-facetable 屬性已定義預設的值區值區選項。

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

只要將相同的值區選項定義為 facetOptions，即可覆寫以整數為基礎的商情項目。如有需要，當搜尋應用程式和查詢要求未定義 facet 選項時，Cloud Search 會使用結構定義中定義的值區選項。查詢中定義的商情項目優先順序高於搜尋應用程式中定義的 Facet，而搜尋應用程式中定義的商情項目會優先於結構定義中定義的商情項目。

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

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

• 如要依文件大小進行商情項目，請使用 itemsize 並定義特徵分塊選項。
• 如需依文件建立日期進行 Facet 處理，請使用 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"
  }
}

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