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（含）之间。默认值为 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

如需了解详情，请参阅授权指南。

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)

解释查询的原因。如果解释类型不是“无”，此字段将不会显示。

QueryExplaination.ExplainationType

枚举
NONE 系统不使用自然语言解释或更广泛的查询版本来提取搜索结果。
BLEND 原始查询的结果与其他结果混合在一起。下面的“原因”字段会填充其他结果与原始查询的结果混合的原因。
REPLACE 原始查询的结果会被替换。下面的“原因”字段中会填充原始查询的结果替换结果。

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)

此搜索结果的调试信息。

Snippet

搜索结果摘要，汇总了所生成页面的内容。

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

搜索结果的对象类型。

结果显示元数据

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)

属性的名称值对。

结果调试信息

结果的调试信息。

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。

FacetBucket

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

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

integer

与存储分区值匹配的结果数量。仅在确保计数准确无误的情况下，系统才会针对搜索返回计数。Cloud Search 不保证任何查询的构面计数，且构面计数可能间歇性地出现，即使相同查询也是如此。请勿建立对构面计数的依赖关系；而应使用始终返回的构面有哪些百分比。
percentage

integer

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

object (Filter)

选择相应存储分区后，要在搜索请求中传递的过滤条件。
value

object (Value)

ResponseDebugInfo

关于响应的调试信息。

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)

此来源的确切结果计数。