- HTTP 请求
- 请求正文
- 响应正文
- 授权范围
- QueryInterpretationOptions
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- QueryInterpretation
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- QueryInterpretation.InterpretationType
- QueryInterpretation.Reason
- SearchResult
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 代码段
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- MatchRange
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 元数据
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- ResultDisplayMetadata
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- ResultDisplayMetadata.ResultDisplayLine
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- ResultDisplayMetadata.ResultDisplayField
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- ResultDebugInfo
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- StructuredResult
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- SpellResult
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- FacetResult
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- FacetBucket
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- ResponseDebugInfo
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- ErrorInfo
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- ErrorMessage
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- ResultCounts
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- SourceResultCount
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 试试看!
Cloud Search Query API 提供的搜索方法可从用户查询中返回最相关的结果。结果可能来自 Google Workspace 应用(例如 Gmail 或 Google 云端硬盘),也可能来自您已从第三方编入索引的数据。
注意:此 API 需要使用标准最终用户账号才能执行。服务账号无法直接执行 Query API 请求;要使用服务账号执行查询,请设置 Google Workspace 全网域授权。
HTTP 请求
POST https://cloudsearch.googleapis.com/v1/query/search
网址采用 gRPC 转码语法。
请求正文
请求正文中包含结构如下的数据:
JSON 表示法 |
---|
{ "requestOptions": { object ( |
字段 | |
---|---|
requestOptions |
请求选项,例如搜索应用和用户时区。 |
query |
原始查询字符串。如需了解支持的搜索运算符,请参阅使用运算符缩小搜索范围 |
pageSize |
每页可返回的搜索结果数量上限。有效值介于 1 和 100 之间(含 1 和 100)。默认值为 10。如果请求的结果数超过 2000,则最小值为 50。 |
start |
结果的起始索引。 |
dataSourceRestrictions[] |
用于查询的来源。如果未指定,系统会使用当前搜索应用中的所有数据源。 |
facetOptions[] |
|
sortOptions |
搜索结果排序选项 |
queryInterpretationOptions |
来解读用户查询 |
contextAttributes[] |
请求的上下文属性,将用于调整搜索结果的排名。元素数量上限为 10 个。 |
响应正文
如果成功,响应正文将包含结构如下的数据:
Search API 响应。
JSON 表示法 |
---|
{ "queryInterpretation": { object ( |
字段 | |
---|---|
queryInterpretation |
用户查询的查询解释结果。如果停用查询解释,则为空。 |
results[] |
搜索查询的结果。 |
structuredResults[] |
用户查询的结构化结果。这些结果不会计入 pageSize。 |
spellResults[] |
查询的建议拼写。 |
facetResults[] |
重复的分面结果。 |
hasMoreResults |
是否有更多与查询匹配的搜索结果。 |
debugInfo |
有关响应的调试信息。 |
errorInfo |
有关响应的错误信息。 |
resultCounts |
展开的结果数信息。 |
联合字段
在系统无法搜索所有文档时的极少数情况下,请重新运行查询。 |
|
resultCountEstimate |
此查询的估算结果计数。 |
resultCountExact |
此查询的确切结果数。 |
授权范围
需要以下 OAuth 范围之一:
https://www.googleapis.com/auth/cloud_search.query
https://www.googleapis.com/auth/cloud_search
有关详情,请参阅授权指南。
QueryInterpretationOptions
来解读用户查询
JSON 表示法 |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
字段 | |
---|---|
disableNlInterpretation |
用于停用查询的自然语言 (NL) 解释的标志。默认值为 false,设置为 true 可停用自然语言解释。NL 解释仅适用于预定义的数据源。 |
enableVerbatimMode |
启用此标志可停用所有内部优化功能,例如查询的自然语言 (NL) 解释、补充结果检索和同义词(包括自定义)的使用。如果两个标记中的任意一个为 true,则会停用 Nl 解释。 |
disableSupplementalResults |
使用此标志可停用查询的补充结果。如果设置为 True,则在 SearchApplication 级别选择的补充结果设置将具有优先权。 |
QueryInterpretation
JSON 表示法 |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
字段 | |
---|---|
interpretedQuery |
对搜索中所用查询的解释。例如,包含自然语言意图(如“来自小王的电子邮件”)的查询将被解读为“from:john source:mail”。当原因为 NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY 时,此字段将不会被填充。 |
interpretationType |
|
reason |
解释查询的原因。如果解释类型不是“无”,则此字段将不为 UNSPECIFIED。 |
QueryInterpretation.InterpretationType
枚举 | |
---|---|
NONE |
既不使用自然语言解释,也不使用更大版本的查询来提取搜索结果。 |
BLEND |
原始查询的结果与其他结果混合。将这些其他结果与原始查询的结果进行混合的原因会填充到“原因”中字段。 |
REPLACE |
原始查询的结果将被替换。替换原始查询的结果的原因会填充到“原因”中字段。 |
QueryInterpretation.Reason
枚举 | |
---|---|
UNSPECIFIED |
|
QUERY_HAS_NATURAL_LANGUAGE_INTENT |
系统使用查询的自然语言解释来提取搜索结果。 |
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY |
由于未找到与用户查询有关的足够结果,因此使用查询和文档字词相似度,有选择地扩大查询范围以检索更多搜索结果。在这种情况下,解读查询将为空。 |
SearchResult
包含已编入索引的文档信息的结果。
JSON 表示法 |
---|
{ "title": string, "url": string, "snippet": { object ( |
字段 | |
---|---|
title |
搜索结果的标题。 |
url |
搜索结果的网址。该网址包含指向实际商品的 Google 重定向。此网址已签名,不应进行更改。 |
snippet |
此结果可用的所有代码段(摘要)的串联。 |
metadata |
搜索结果的元数据。 |
clusteredResults[] |
如果源已聚类,请提供聚类结果的列表。聚类结果只有一级。如果当前来源未启用聚簇,则此字段将为空。 |
debugInfo |
有关此搜索结果的调试信息。 |
Snippet
搜索结果摘要,总结结果页面的内容。
JSON 表示法 |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
字段 | |
---|---|
snippet |
文档的摘要。文档的摘要。可以包含已转义的 HTML 字符,这些字符应在呈现之前不进行转义。 |
matchRanges[] |
代码段中匹配的范围。 |
MatchRange
代码段的匹配范围 [start, end)。
JSON 表示法 |
---|
{ "start": integer, "end": integer } |
字段 | |
---|---|
start |
匹配项在代码段中的起始位置。 |
end |
摘要中对局的结尾。 |
元数据
匹配搜索结果的元数据。
JSON 表示法 |
---|
{ "source": { object ( |
字段 | |
---|---|
source |
结果的指定来源,例如 Gmail。 |
mimeType |
搜索结果的 MIME 类型。 |
thumbnailUrl |
结果的缩略图网址。 |
owner |
搜索结果的文档或对象的所有者(通常是创建者)。 |
createTime |
此文档或对象在搜索结果中的创建时间。 时间戳采用 RFC3339 世界协调时间(UTC,即“祖鲁时”)格式,精确到纳秒,最多九个小数位。示例: |
updateTime |
搜索结果中相应对象的上次修改日期。如果未在该项中设置,则此处返回的值为空。如果 时间戳采用 RFC3339 世界协调时间(UTC,即“祖鲁时”)格式,精确到纳秒,最多九个小数位。示例: |
fields[] |
结构化数据中编入索引的字段,作为通用命名属性返回。 |
displayOptions |
用于指定如何显示结构化数据搜索结果的选项。 |
objectType |
搜索结果的对象类型。 |
ResultDisplayMetadata
JSON 表示法 |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
字段 | |
---|---|
objectTypeLabel |
对象的显示标签。 |
metalines[] |
要与结果一起显示的 元行内容。 |
ResultDisplayMetadata.ResultDisplayLine
构成所显示行的字段集合
JSON 表示法 |
---|
{
"fields": [
{
object ( |
字段 | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
query.search 结果的显示字段
JSON 表示法 |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
字段 | |
---|---|
label |
属性的显示标签。 |
operatorName |
属性的运算符名称。 |
property |
属性的名称值对。 |
ResultDebugInfo
有关结果的调试信息。
JSON 表示法 |
---|
{ "formattedDebugInfo": string } |
字段 | |
---|---|
formattedDebugInfo |
采用适合显示格式的常规调试信息。 |
StructuredResult
作为搜索请求的一部分返回的结构化结果。
JSON 表示法 |
---|
{
"person": {
object ( |
字段 | |
---|---|
person |
代表人物 |
SpellResult
JSON 表示法 |
---|
{ "suggestedQuery": string } |
字段 | |
---|---|
suggestedQuery |
查询的建议拼写。 |
FacetResult
特定于来源的商品详情响应
JSON 表示法 |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
字段 | |
---|---|
sourceName |
返回分面结果的来源名称。不能为空。 |
objectType |
要为其返回分面结果的对象类型。可以留空。 |
operatorName |
为商品详情选择的运算符的名称。@see cloudsearch.SchemaPropertyOptions |
buckets[] |
FacetBuckets,用于响应至少包含一个具有相应过滤器的结果的值。 |
FacetBucket
构面中的存储分区是基本操作单元。存储分区可以包含单个值或连续值范围,具体取决于分区字段的类型。FacetBucket 目前仅用于返回响应对象。
JSON 表示法 |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
字段 | |
---|---|
count |
与分桶值匹配的结果数。只有在确保计数准确性的情况下,系统才会为搜索返回计数。Cloud Search 不保证任何查询的构面计数,构面计数可能只是间歇性存在,即使对于相同的查询也是如此。不要基于存在的分面计数构建依赖项;而是使用始终返回的分面百分比。 |
percentage |
与分桶值匹配的结果的百分比。返回的值介于 (0-100] 之间,如果为小数,会向下舍入为整数。如果未明确返回该值,则代表舍入到 0 的百分比值。系统会针对所有搜索返回百分比,但这只是一个估算值。由于始终返回百分比,因此您应该呈现百分比,而不是计数。 |
filter |
要在搜索请求中传递的过滤条件(如果选择了相应存储分区)。 |
value |
|
ResponseDebugInfo
有关响应的调试信息。
JSON 表示法 |
---|
{ "formattedDebugInfo": string } |
字段 | |
---|---|
formattedDebugInfo |
采用适合显示格式的常规调试信息。 |
错误信息
有关响应的错误信息。
JSON 表示法 |
---|
{
"errorMessages": [
{
object ( |
字段 | |
---|---|
errorMessages[] |
|
ErrorMessage
每个来源响应的错误消息。
JSON 表示法 |
---|
{
"source": {
object ( |
字段 | |
---|---|
source |
|
errorMessage |
|
ResultCounts
结果计数信息
JSON 表示法 |
---|
{
"sourceResultCounts": [
{
object ( |
字段 | |
---|---|
sourceResultCounts[] |
包含结果的每个来源的结果计数信息。 |
SourceResultCount
每个来源的结果计数信息。
JSON 表示法 |
---|
{ "source": { object ( |
字段 | |
---|---|
source |
与结果计数信息关联的来源。 |
hasMoreResults |
是否有更多关于此来源的搜索结果。 |
联合字段
|
|
resultCountEstimate |
此来源的估算结果数量。 |
resultCountExact |
此来源的确切结果数。 |