本頁面由 Cloud Translation API 翻譯而成。

使用 Query API 建立搜尋介面

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

如果是網頁應用程式，且符合最低要求，建議使用搜尋小工具。詳情請參閱「使用搜尋小工具建立搜尋介面」

建構搜尋介面

建構最簡單的搜尋介面需要完成幾個步驟：

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

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

設定搜尋應用程式

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

如要進一步瞭解搜尋應用程式，請參閱「自訂 Cloud Search 搜尋體驗」。

為應用程式產生 OAuth 憑證

除了設定 Google Cloud Search API 存取權中的步驟外，您還必須為網頁應用程式產生 OAuth 憑證。您建立的憑證類型取決於 API 的使用情境。

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

如要進一步瞭解 OAuth 選項和用戶端程式庫，請參閱 [Google 身分識別平台](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"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

使用切面細分結果

Facet 是已編入索引的屬性，用於代表用來精細搜尋結果的類別。使用切面，協助使用者以互動方式精進查詢，更快找到相關項目。

您可以在搜尋應用程式中定義切面，並由查詢中的設定覆寫。

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

使用切面的典型互動模式如下：

建立初始查詢，指定要在切面結果中納入哪些屬性。
算繪搜尋和切面結果。
使用者選取一或多個商情項目值，進一步縮小搜尋結果的範圍。
重複執行查詢，並根據所選值加入篩選器。

舉例來說，如要依年份和 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"
  }
}

接著，您可以根據應用程式適當顯示產生的建議。