Query API 提供搜索和建议方法，用于构建搜索界面或在应用中嵌入搜索结果。
对于要求极低的 Web 应用，可以考虑使用搜索微件。请参阅 使用搜索微件创建搜索界面。
构建搜索界面
构建一个最小的搜索界面需要执行以下几个步骤：
- 配置搜索应用。
- 为应用生成 OAuth 凭据。
- 查询索引。
- 显示查询结果。
您可以添加分页、排序、过滤、构面和自动补全等功能来增强界面。
配置搜索应用
对于每个搜索界面，您必须创建至少一个搜索应用 。 搜索应用提供默认参数，例如数据源、排序顺序、过滤条件和构面。您可以使用 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": {...}
}]
}
直接下属匹配
借助直接下属匹配功能，用户可以查看某人的直接下属。响应包含一个 assistCardProtoHolder，其 cardType 为 RELATED_PEOPLE_ANSWER_CARD。
关闭优化功能
补充结果等优化功能默认处于启用状态。您可以停用这些功能：
- 搜索应用级别：将
force_verbatim_mode设置为true。 - 查询级别：将
enableVerbatimMode设置为true。
突出显示片段
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 根据查询历史记录、联系人和文档内容自动补全。