Method: query.search

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": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
字段
requestOptions

object (RequestOptions)

请求选项,例如搜索应用和用户时区。

query

string

原始查询字符串。请参阅使用运算符缩小搜索范围,查看受支持的搜索运算符

pageSize

integer

每页返回的搜索结果数量上限。有效值介于 1 到 100(含 1 和 100)之间。默认值为 10。如果请求的结果数超过 2000,则最小值为 50。

start

integer

结果的起始索引。

dataSourceRestrictions[]

object (DataSourceRestriction)

用于查询的来源。如果未指定,则使用当前搜索应用中的所有数据源。

facetOptions[]

object (FacetOptions)

sortOptions

object (SortOptions)

搜索结果排序选项

queryInterpretationOptions

object (QueryInterpretationOptions)

解释用户查询的选项。

contextAttributes[]

object (ContextAttribute)

请求的上下文属性,用于调整搜索结果的排名。元素数量上限为 10。

响应正文

如果成功,则响应正文包含结构如下的数据:

Search API 响应。

JSON 表示法
{
  "queryInterpretation": {
    object (QueryInterpretation)
  },
  "results": [
    {
      object (SearchResult)
    }
  ],
  "structuredResults": [
    {
      object (StructuredResult)
    }
  ],
  "spellResults": [
    {
      object (SpellResult)
    }
  ],
  "facetResults": [
    {
      object (FacetResult)
    }
  ],
  "hasMoreResults": boolean,
  "debugInfo": {
    object (ResponseDebugInfo)
  },
  "errorInfo": {
    object (ErrorInfo)
  },
  "resultCounts": {
    object (ResultCounts)
  },

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
字段
queryInterpretation

object (QueryInterpretation)

用户查询的查询解释结果。如果查询解释功能已停用,则为空。

results[]

object (SearchResult)

搜索查询的结果。

structuredResults[]

object (StructuredResult)

用户查询的结构化结果。这些结果不会计入 pageSize。

spellResults[]

object (SpellResult)

查询建议拼写。

facetResults[]

object (FacetResult)

重复的构面结果。

hasMoreResults

boolean

是否有与查询匹配的更多搜索结果。

debugInfo

object (ResponseDebugInfo)

关于响应的调试信息。

errorInfo

object (ErrorInfo)

关于响应的错误信息。

resultCounts

object (ResultCounts)

展开的结果数信息。

联合字段 result_count。所有请求的数据来源中的结果总数。如果所查询的数据源集中包含预定义来源,则省略此字段。在以下情况下,结果计数可能会以估算值(而不是确切值)的形式返回:

  • 查询中在一个短语中有超过 2 个字词时,例如“结果为完全匹配的引号”。

  • 待评估的唯一搜索结果 ACL 数量过大,在合理延迟时间内无法计算时。

在极少数情况下,当系统无法搜索所有文档时,请重新运行查询。result_count 只能是下列其中一项:

resultCountEstimate

string (int64 format)

此查询的估计结果数。

resultCountExact

string (int64 format)

此查询的确切结果计数。

授权范围

需要以下 OAuth 范围之一:

  • https://www.googleapis.com/auth/cloud_search.query
  • https://www.googleapis.com/auth/cloud_search

有关详情,请参阅 OAuth 2.0 概览

QueryExplainationOptions

解释用户查询的选项。

JSON 表示法
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
字段
disableNlInterpretation

boolean

用于停用查询自然语言 (NL) 解释的标志。默认值为 false,设置为 true 可停用自然语言解释功能。NL 解释仅适用于预定义的数据源。

enableVerbatimMode

boolean

启用此标记可关闭所有内部优化,例如自然语言 (NL) 解释、补充结果检索以及对同义词(包括自定义同义词)的使用。如果两个标记中的任何一个为 true,将停用 Nl 解释。

disableSupplementalResults

boolean

使用此标志可以停用查询的补充结果。如果设为 True,则会以 SearchApplication 级别选择的补充结果设置优先。

查询解释

JSON 表示法
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
字段
interpretedQuery

string

解析搜索中使用的查询。例如,包含自然语言意图(如“来自 John 的电子邮件”)的查询将被解读为 "from:john source:mail"。如果不是 NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY,则此字段将不会填充。

interpretationType

enum (QueryInterpretation.InterpretationType)

reason

enum (QueryInterpretation.Reason)

解释查询的原因。如果解释类型不是 NONE,此字段将不会显示。

QueryExplaination.ExplainationType

枚举
NONE 系统在抓取搜索结果时不会使用自然语言解释,也不会使用更宽泛的查询版本。
BLEND 原始查询的结果与其他结果混合。下面的“'Reason'”字段填充了将这些其他结果与原始查询的结果相融合的原因。
REPLACE 原始查询的结果会被替换。下面的 'Reason' 字段会填充替换原始查询结果的原因。

QueryExplaination.Reason

枚举
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT 查询的自然语言解释用于提取搜索结果。
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY 由于用户查询未找到足够的结果,因此查询和文档相似度可用于有选择地扩大查询以检索其他搜索结果。在这种情况下,经过解释的查询将为空。

搜索结果

包含文档的已编入索引信息的结果。

JSON 表示法
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
字段
title

string

搜索结果的标题。

url

string

搜索结果的网址。该网址包含指向实际商品的 Google 重定向。此网址已签名,不应更改。

snippet

object (Snippet)

可用于此结果的所有摘要(摘要)的串联。

metadata

object (Metadata)

搜索结果的元数据。

clusteredResults[]

object (SearchResult)

如果来源是聚类,请提供聚类结果列表。将只有一个级别的聚类结果。如果当前来源未启用聚类功能,则此字段将为空。

debugInfo

object (ResultDebugInfo)

有关此搜索结果的调试信息。

摘要

搜索结果的摘要,总结了结果页的内容。

JSON 表示法
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
字段
snippet

string

文档的摘要。文档的摘要。可能包含在呈现之前未转义的转义 HTML 字符。

matchRanges[]

object (MatchRange)

代码段中的匹配范围。

匹配范围

代码段的匹配范围 [start, end)。

JSON 表示法
{
  "start": integer,
  "end": integer
}
字段
start

integer

代码段中匹配的起始位置。

end

integer

代码段中的匹配项结束。

元数据

匹配搜索结果的元数据。

JSON 表示法
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
字段
source

object (Source)

结果的命名来源,例如 Gmail。

mimeType

string

搜索结果的 MIME 类型。

thumbnailUrl

string

结果的缩略图网址。

owner

object (Person)

搜索结果的文档或对象的所有者(通常是创建者)。

createTime

string (Timestamp format)

搜索结果中此文档或对象的创建时间。

此时间戳采用 RFC3339 世界协调时间 (UTC)“祖鲁时”格式,纳秒精度和最多九个小数位。示例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

updateTime

string (Timestamp format)

搜索结果中对象的最后修改日期。如果未在此项中设置,则此处返回的值为空。使用 updateTime 计算新鲜度时,如果未设置此值,则此值默认为 2 年(从当前时间算起)。

此时间戳采用 RFC3339 世界协调时间 (UTC)“祖鲁时”格式,纳秒精度和最多九个小数位。示例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

fields[]

object (NamedProperty)

结构化数据中的已编入索引的字段,以通用命名属性的形式返回。

displayOptions

object (ResultDisplayMetadata)

用于指定结构化数据搜索结果显示方式的选项。

objectType

string

搜索结果的对象类型。

ResultDisplayMetadata

JSON 表示法
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
字段
objectTypeLabel

string

此对象的显示标签。

metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

与结果一起显示的 Metaline 内容。

ResultDisplayMetadata.ResultDisplayLine

构成显示行的字段集合

JSON 表示法
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
字段
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

query.search 结果的显示字段

JSON 表示法
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
字段
label

string

属性的显示标签。

operatorName

string

属性的运算符名称。

property

object (NamedProperty)

属性的名称值对。

ResultDebugInfo 类的构造函数

结果的调试信息。

JSON 表示法
{
  "formattedDebugInfo": string
}
字段
formattedDebugInfo

string

已设置用于显示的常规调试信息。

结构化结果

作为搜索请求的一部分返回的结构化结果。

JSON 表示法
{
  "person": {
    object (Person)
  }
}
字段
person

object (Person)

代表人物

拼写结果

JSON 表示法
{
  "suggestedQuery": string
}
字段
suggestedQuery

string

建议的查询拼写。

FacetResult

来源特定构面响应

JSON 表示法
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
字段
sourceName

string

返回构面结果的来源名称。不能为空。

objectType

string

返回构面结果的对象类型。可以留空。

operatorName

string

选择分面的运算符的名称。@see cloudsearch.SchemaPropertyOptions

buckets[]

object (FacetBucket)

响应中的值(至少包含一个具有相应过滤条件的结果)的 FacetBucket。

Facet 存储分区

构面中的存储分区是基本操作单元。一个存储分区可以包含一个值或者一个连续范围的值,具体取决于存储分区的字段类型。FacetBucket 目前仅用于返回响应对象。

JSON 表示法
{
  "count": integer,
  "percentage": integer,
  "value": {
    object (Value)
  }
}
字段
count

integer

与桶值匹配的结果数。仅在确保计数准确性的情况下,才会针对搜索返回计数。Cloud Search 不保证任何查询的构面计数,而构面计数可能只是间歇性存在,即使对于相同的查询也是如此。请勿根据构面计数存在的依赖关系,而应始终返回构面计数百分比。

percentage

integer

与存储分区值匹配的结果所占的百分比。返回的值介于 (0-100] 之间,如果整数是小数,则会向下舍入为整数。如果未明确返回该值,则表示该值表示四舍五入为百分比的值。系统会为所有搜索返回百分比,但这是一个估算值。由于系统始终会返回百分比数据,因此您应呈现百分比数据而非计数数据。

value

object (Value)

响应调试信息

关于响应的调试信息。

JSON 表示法
{
  "formattedDebugInfo": string
}
字段
formattedDebugInfo

string

已设置用于显示的常规调试信息。

错误信息

关于响应的错误信息。

JSON 表示法
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
字段
errorMessages[]

object (ErrorMessage)

ErrorMessage

每个来源响应的错误消息。

JSON 表示法
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
字段
source

object (Source)

errorMessage

string

结果计数

结果计数信息

JSON 表示法
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
字段
sourceResultCounts[]

object (SourceResultCount)

包含结果的每个来源的结果计数信息。

来源结果计数

每个来源的结果数信息。

JSON 表示法
{
  "source": {
    object (Source)
  },
  "hasMoreResults": boolean,

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
字段
source

object (Source)

与结果计数信息关联的来源。

hasMoreResults

boolean

是否有关于此来源的更多搜索结果。

联合字段 result_count

result_count 只能是下列其中一项:

resultCountEstimate

string (int64 format)

此来源的估计结果数。

resultCountExact

string (int64 format)

此来源的确切结果计数。