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

使用 Query API 建立搜尋介面

Query API 提供搜尋與建議方法來建立搜尋或在應用程式中嵌入搜尋結果。

針對需求最少的網頁應用程式，建議使用搜尋小工具。若需更多資訊，請參閲使用搜尋小工具建立搜尋介面

建構搜尋介面

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

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

你可以透過下列功能進一步強化搜尋介面：分頁、排序、篩選、 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 以便比對項目，而 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 中，您可能會顯示「Your search for your at 原始查詢的相關結果不足。包含類似結果快速查詢。」

處理使用者結果

Cloud Search 會傳回兩種「使用者結果」類型：文件與查詢中已使用該姓名，以及員工資訊名稱已在查詢中使用後者的結果是 Cloud 函式 Google 搜尋的「使用者搜尋功能」功能，可在這個 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 是已建立索引的屬性，代表用於縮小搜尋範圍的類別也就是預測結果使用 facet 協助使用者以互動方式修正查詢並尋找更快速地瀏覽相關商品

您可以在搜尋應用程式中的關鍵字。並由查詢中的設定覆寫

要求 facet 時，Cloud Search 會計算所要求屬性。這些值。使用這些值建立篩選器，縮小後續查詢的結果範圍

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

進行初始查詢，指定要納入 facet 的屬性也就是預測結果
轉譯搜尋和 facet 結果。
使用者選取一或多個 facet 值以修正結果。
使用依據所選值的篩選器重複查詢。

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

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

您也可以利用整數式欄位的 facet 要求結果。舉例來說，可能會將名為 book_pages 的整數屬性標示為 facetable，以便修正針對包含「100-200」書籍的搜尋結果網頁。

設定整數屬性欄位結構定義時，請設定 isFacetable敬上新增至 true，並將對應的值區選項新增至 integerPropertyOptions。這可確保每個整數面向屬性都有預設的特徵分塊已定義選項

定義特徵分塊選項邏輯時，請提供遞增值的陣列這些表示法舉例來說，如果使用者指定 2, 5, 10, 100，然後是 <2、[2-5)、[5-10)、[10-100) 和 >=100 的商情項目計算方式

您可以覆寫以整數為基礎的 facet，方法是定義相同的特徵分塊選項： facetOptions敬上。如有需要，Cloud Search 會使用如果搜尋應用程式和查詢要求都沒有 facet，則傳回結構定義已定義選項查詢中定義的 facet 優先順序高於定義的 facet ，而搜尋應用程式中定義的 facet 優先順序高於結構定義中定義的 facet。

別擔心！您可以使用保留運算子依文件檔案大小、以位元組為單位或已建立或修改文件。您不需要定義自訂結構定義但您需要在搜尋應用程式的operatorName FacetOptions。

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

解讀 facet 值區

facetResults 屬性含有使用者確切的篩選要求在每個屬性的 filter 欄位中 bucket。

如果是不是以整數計算的 Facet，facetResults 會包含以下項目的項目：每個要求的資源每個屬性的值或範圍清單，稱為提供的是 buckets。最常出現的值會優先顯示。

當使用者選取一或多個值做為篩選依據時，請以下列條件建立新的查詢：並再次查詢 API

新增建議

使用 suggest API 根據使用者的個人查詢記錄以及聯絡人及其文件語料庫。

舉例來說，下列呼叫會針對詞組 jo。

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

連結完畢後，就會顯示為適合您的應用程式。