使用 Query API 创建搜索界面

Query API 为构建搜索界面或在应用中嵌入搜索结果提供了搜索和建议方法。

对于要求极低的 Web 应用,可以考虑使用搜索微件。 如需了解详情,请参阅使用搜索微件创建搜索界面

构建搜索界面

构建一个最小的搜索界面需要执行以下几个步骤:

  1. 配置搜索应用
  2. 为应用生成 OAuth 凭据
  3. 查询索引
  4. 显示查询结果

此外,您可以进一步增强搜索界面,为其添加分页、排序、过滤、构面和自动建议等功能。

配置搜索应用

对于您创建的每个搜索界面,必须创建至少一个关联的搜索应用。搜索应用可为查询提供默认参数,例如要包含的数据源、排序顺序、过滤条件以及要请求的构面。如果需要,您可以使用 Query API 替换这些参数。

如需详细了解搜索应用,请参阅打造自定义搜索体验

为应用生成 OAuth 凭据

除了执行配置对 Google Cloud Search REST API 的访问权限中的步骤以外,您还必须为 Web 应用生成 OAuth 凭据。您创建的凭据类型取决于使用该 API 的上下文环境。

使用这些凭据即可代表用户请求授权。请求授权时,请使用 https://www.googleapis.com/auth/cloud_search.query 这一范围。

如需详细了解 OAuth 选项和客户端库,请参阅 Google Identity Platform

查询索引

使用 search 方法对索引执行搜索。

每个请求必须包含两条信息:query 文本(用于匹配项)以及 searchApplicationId(用于标识要使用的搜索应用的 ID)。

以下代码段展示了对电影《泰坦尼克号》的电影数据源的查询:

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

显示查询结果

搜索界面至少应显示 title 项以及指向原始项的链接。您可以利用搜索结果中包含的其他信息(例如片段和元数据)来进一步增强搜索结果的显示效果。

突出显示片段

对于包含已编入索引的文本或 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 字段包含返回项的 createTimeupdateTime 以及与该项关联的所有可返回的结构化数据。

如需显示这些结构化数据,请使用 displayOptions 字段。displayOptions 字段包含对象类型的显示标签和一组 metalines。每个 metaline 都包含架构中配置的一组显示标签和值对。

检索其他结果

如要检索其他结果,请将请求中的 start 字段设置为所需的偏移量。您可以使用 pageSize 字段调整每个页面的大小。

如要显示返回项数量或显示分页控件以对返回项进行分页,请使用 resultCount 字段。提供的值可能为实际值,也可能为估计值,具体取决于结果集的大小。

对结果排序

使用 sortOptions 字段指定返回项的顺序。sortOptions 值是一个包含两个字段的对象:

  • operatorName - 用于排序的结构化数据属性的运算符。对于具有多个运算符的属性,只能使用主相等性运算符进行排序。
  • sortOrder - 排序的方向,可设为 ASCENDINGDESCENDING

相关性也会用作辅助排序键。如果查询中未指定排序顺序,则结果将仅按相关性进行排序。

"sortOptions": {
      "operatorName": "priority",
      "sortOrder": "DESCENDING"
    }
    

添加过滤条件

除了查询表达式之外,您还可以应用过滤条件来进一步限制结果。您可以在搜索应用和搜索请求中指定过滤条件。

如要在请求应用或搜索应用中添加过滤条件,请使用 dataSourceRestrictions.filterOptions[] 字段。

您可以通过以下两种主要方法进一步过滤数据源:

  • 对象过滤条件(通过 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. 根据所选的值构造过滤器,然后使用该过滤器重复查询。

例如,要根据年份和 MPAA 分级优化电影查询,请在查询中添加 facetOptions 属性。

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

解读构面范围

响应中的 facetResults 属性包含每个请求属性的条目。对于每个属性,系统会提供一个值或范围列表(称为 buckets)。最常出现的值会优先显示。

如果用户选择一个或多个值进行过滤,请使用所选过滤条件构造一个新查询并再次查询 API。

添加建议

使用 Suggest API 根据用户的个人查询历史记录与联系人及其文档库自动填充查询。

例如,以下调用会提供针对部分词组 jo 的建议。

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

然后,您可以根据您的应用适当显示生成的建议。