通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Documents - Suggest Post

服务:
Search Service
API 版本:
2025-09-01

建议索引中与给定部分查询文本匹配的文档。

POST {endpoint}/indexes('{indexName}')/docs/search.post.suggest?api-version=2025-09-01

URI 参数

名称 在 必需 类型 说明
endpoint
 path True

string

搜索服务的终结点 URL。
indexName
 path True

string

索引的名称。
api-version
 query True

string

客户端 API 版本。

请求头

名称 必需 类型 说明
x-ms-client-request-id

string (uuid)

随请求一起发送的跟踪 ID，以帮助调试。

请求正文

名称 必需 类型 说明
search True

string

用于建议文档的搜索文本。 必须至少为 1 个字符，且不超过 100 个字符。
suggesterName True

string

建议器集合中指定的建议器的名称，该集合是索引定义的一部分。
filter

string

一个 OData 表达式，用于筛选考虑建议的文档。
fuzzy

boolean

指示是否对建议查询使用模糊匹配的值。 默认值为 false。 设置为 true 时，即使搜索文本中存在替换或缺失的字符，查询也会查找建议。 虽然这在某些情况下提供了更好的体验，但会产生性能成本，因为模糊建议搜索速度较慢且消耗更多资源。
highlightPostTag

string

附加到命中突出显示的字符串标记。 必须使用 highlightPreTag 进行设置。 如果省略，则禁用建议的点击突出显示。
highlightPreTag

string

在点击突出显示之前添加的字符串标记。 必须使用 highlightPostTag 进行设置。 如果省略，则禁用建议的点击突出显示。
minimumCoverage

number (double)

介于 0 和 100 之间的数字，指示建议查询必须涵盖的索引百分比，以便将查询报告为成功。 此参数可用于确保搜索可用性，即使对于只有一个副本的服务也是如此。 默认值为 80。
orderby

string

以逗号分隔的 OData $orderby表达式列表，用于对结果进行排序。 每个表达式可以是字段名称，也可以是对 geo.distance（） 或 search.score（） 函数的调用。 每个表达式后面可以跟 asc 表示升序，或 desc 表示降序。 默认值为升序。 平局将因文件的比赛比分而打破。 如果未指定$orderby，则默认排序顺序是按文档匹配分数降序排列。 最多可以有 32 个$orderby子句。
searchFields

string

用于搜索指定搜索文本的字段名称的逗号分隔列表。 目标字段必须包含在指定的建议器中。
select

string

要检索的字段的逗号分隔列表。 如果未指定，则结果中将仅包含键字段。
top

integer (int32)

要检索的建议数。 这必须是介于 1 和 100 之间的值。 默认值为 5。

响应

名称 类型 说明
200 OK

SuggestDocumentsResult

包含与部分输入匹配的建议文档的响应。
Other Status Codes

ErrorResponse

错误响应。

示例

SearchIndexSuggestDocumentsPost

示例请求

POST https://stableexampleservice.search.windows.net/indexes('stable-test')/docs/search.post.suggest?api-version=2025-09-01


{
  "filter": "ownerId eq 'sam' and id lt '15'",
  "fuzzy": true,
  "highlightPostTag": "</em>",
  "highlightPreTag": "<em>",
  "minimumCoverage": 80,
  "orderby": "id desc",
  "search": "p",
  "searchFields": "category",
  "select": "id,name,category,ownerId",
  "suggesterName": "sg",
  "top": 10
}

示例响应

状态代码:
200 
{
  "@search.coverage": 100,
  "value": [
    {
      "@search.text": "<em>pu</em>rple",
      "id": "14",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "13",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "11",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "1",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    }
  ]
}

定义

名称 说明
ErrorAdditionalInfo

资源管理错误附加信息。
ErrorDetail

错误详细信息。
ErrorResponse

错误响应
SuggestDocumentsResult

包含来自索引的建议查询结果的响应。
SuggestRequest

用于过滤、排序、模糊匹配和其他建议查询行为的参数。
SuggestResult

包含建议查询找到的文档以及相关元数据的结果。

ErrorAdditionalInfo

Object

资源管理错误附加信息。

名称 类型 说明
info

object

其他信息。
type

string

其他信息类型。

ErrorDetail

Object

错误详细信息。

名称 类型 说明
additionalInfo

ErrorAdditionalInfo[]

错误附加信息。
code

string

错误代码。
details

ErrorDetail[]

错误详细信息。
message

string

错误消息。
target

string

错误目标。

ErrorResponse

Object

错误响应

名称 类型 说明
error

ErrorDetail

错误对象。

SuggestDocumentsResult

Object

包含来自索引的建议查询结果的响应。

名称 类型 说明
@search.coverage

number (double)

一个值，指示查询中包含的索引的百分比，如果请求中未设置 minimumCoverage，则为 null。
value

SuggestResult[]

查询返回的结果序列。

SuggestRequest

Object

用于过滤、排序、模糊匹配和其他建议查询行为的参数。

名称 类型 说明
filter

string

一个 OData 表达式，用于筛选考虑建议的文档。
fuzzy

boolean

指示是否对建议查询使用模糊匹配的值。 默认值为 false。 设置为 true 时，即使搜索文本中存在替换或缺失的字符，查询也会查找建议。 虽然这在某些情况下提供了更好的体验，但会产生性能成本，因为模糊建议搜索速度较慢且消耗更多资源。
highlightPostTag

string

附加到命中突出显示的字符串标记。 必须使用 highlightPreTag 进行设置。 如果省略，则禁用建议的点击突出显示。
highlightPreTag

string

在点击突出显示之前添加的字符串标记。 必须使用 highlightPostTag 进行设置。 如果省略，则禁用建议的点击突出显示。
minimumCoverage

number (double)

介于 0 和 100 之间的数字，指示建议查询必须涵盖的索引百分比，以便将查询报告为成功。 此参数可用于确保搜索可用性，即使对于只有一个副本的服务也是如此。 默认值为 80。
orderby

string

以逗号分隔的 OData $orderby表达式列表，用于对结果进行排序。 每个表达式可以是字段名称，也可以是对 geo.distance（） 或 search.score（） 函数的调用。 每个表达式后面可以跟 asc 表示升序，或 desc 表示降序。 默认值为升序。 平局将因文件的比赛比分而打破。 如果未指定$orderby，则默认排序顺序是按文档匹配分数降序排列。 最多可以有 32 个$orderby子句。
search

string

用于建议文档的搜索文本。 必须至少为 1 个字符，且不超过 100 个字符。
searchFields

string

用于搜索指定搜索文本的字段名称的逗号分隔列表。 目标字段必须包含在指定的建议器中。
select

string

要检索的字段的逗号分隔列表。 如果未指定，则结果中将仅包含键字段。
suggesterName

string

建议器集合中指定的建议器的名称，该集合是索引定义的一部分。
top

integer (int32)

要检索的建议数。 这必须是介于 1 和 100 之间的值。 默认值为 5。

SuggestResult

Object

包含建议查询找到的文档以及相关元数据的结果。

名称 类型 说明
@search.text

string

建议结果的文本。