使用 Query API 创建搜索界面

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

对于要求极低的 Web 应用，可以考虑使用搜索微件。请参阅使用搜索微件创建搜索界面。

构建搜索界面

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

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

您可以使用分页、排序、过滤、构面和自动补全等功能来增强界面。

配置搜索应用

您必须为每个搜索界面创建至少一个搜索应用。 搜索应用提供默认参数，例如数据源、排序顺序、过滤条件和构面。您可以使用 Query API 替换这些参数。

对于查询中使用的数据源数量，不得超过搜索应用配置的数值。您可以使用 dataSourceRestrictions 将查询限制为这些来源的子集。

如需了解详情，请参阅自定义搜索体验。

为应用生成 OAuth 凭据

除了执行配置对 Cloud Search API 的访问权限中的步骤以外，您还必须为 Web 应用生成 OAuth 凭据。

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

如需详细了解 OAuth 选项，请参阅 Google Identity Platform。

查询索引

使用 search 方法搜索索引。

每个请求都必须包含文本 query 和 searchApplicationId。

此示例查询了电影数据源：

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

显示查询结果

搜索界面应显示 title 项以及指向原始项的链接。您还可以使用摘要和元数据来改善显示效果。

处理补充结果

如果查询的匹配结果不足，Cloud Search 会返回补充结果。queryInterpretation 字段表示这一点。如果仅返回补充结果，则 InterpretationType 为 REPLACE。如果它们是混合的，则为 BLEND。

返回补充结果时，请考虑通知用户。对于 REPLACE，您可能会说：“您的搜索未返回任何结果。当前显示的是类似查询的搜索结果。”

处理人员结果

Cloud Search 会使用“人员搜索”功能返回与人员和员工信息相关的文档。结果位于 structuredResults 字段中：

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

直接下属匹配

“直属下属匹配”功能可让用户查看某人的直属下属。响应包含一个 cardType 为 RELATED_PEOPLE_ANSWER_CARD 的 assistCardProtoHolder。

关闭优化

默认情况下，系统会启用补充结果等优化功能。您可以停用这些功能：

突出显示片段

Cloud Search 会针对已编入索引的文本或 HTML 返回摘要。如果存在搜索字词，matchRanges 会识别其位置。使用这些范围来突出显示文本。

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 字段来提供 createTime、updateTime 和结构化数据等信息。使用 displayOptions 显示结构化数据。

检索其他结果

如需检索更多结果，请将 start 字段设置为所选的偏移量。使用 pageSize 调整页面大小。使用 resultCount 显示商品总数或估计数量。

对结果排序

使用 sortOptions 指定顺序：

  • operatorName：要按其进行排序的属性。
  • sortOrder：ASCENDING 或 DESCENDING。

相关性是默认的辅助排序键。

添加过滤条件

在搜索应用或请求中使用过滤条件来限制结果。如果两者都为某个来源指定了过滤条件，则这两个过滤条件的计算结果都必须为 true。

在 dataSourceRestrictions.filterOptions[] 中应用过滤条件。 主要过滤条件类型：

  • 对象过滤条件：将匹配项限制为特定类型。
  • 值过滤条件：根据运算符和值限制匹配项。

复合过滤条件用于组合多个值过滤条件。

使用构面优化结果

构面可帮助用户以交互方式优化查询。当您请求构面时，Cloud Search 会计算这些属性最常出现的值。

典型模式： 1. 指定分面属性的查询。 1. 呈现搜索和分面结果。 1. 用户选择属性值。 1. 根据所选内容构造过滤器，然后使用该过滤器重复查询。

包含基于整数的字段的构面结果

将整数属性标记为可用于分面，以便按范围细化结果（例如，“100-200”页）。将 isFacetable 设置为 true，并在架构中定义默认分桶选项。

按文档大小或日期划分构面结果

使用预留的运算符：

  • itemsize：表示文件大小（以字节为单位）。
  • createddatetimestamp：表示创建日期。
  • lastmodified：用于修改日期。

添加建议

使用 suggest API 根据查询历史记录、联系人和文档内容进行自动补全。