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

Documents - Suggest Post

服务:
Search Service
API 版本:
2026-04-01

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

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

URI 参数

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

string (uri)

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

string

索引的名称。
api-version
 query True

string

minLength: 1

用于此操作的 API 版本。

请求头

名称 必需 类型 说明
Accept

Accept

接受（Accept）首部。
x-ms-client-request-id

string (uuid)

请求的不透明、全局唯一的客户端生成的字符串标识符。

请求正文

名称 必需 类型 说明
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

意外的错误响应。

安全性

api-key

类型: apiKey
在: header

OAuth2Auth

类型: oauth2
流向: implicit
授权 URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

作用域

名称 说明
https://search.azure.com/.default

示例

SearchIndexSuggestDocumentsPost

示例请求

POST https://exampleservice.search.windows.net/indexes('example-index')/docs/search.post.suggest?api-version=2026-04-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"
    }
  ]
}

定义

名称 说明
Accept

接受（Accept）首部。
ErrorAdditionalInfo

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

错误详细信息。
ErrorResponse

所有 Azure 资源管理器 API 的通用错误响应，用于返回失败操作的错误细节。 （这也遵循 OData 错误响应格式）。
SuggestDocumentsResult

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

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

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

Accept

枚举

接受（Accept）首部。

值 说明
application/json;odata.metadata=none

ErrorAdditionalInfo

对象

资源管理错误附加信息。

名称 类型 说明
info

附加信息。
type

string

附加信息类型。

ErrorDetail

对象

错误详细信息。

名称 类型 说明
additionalInfo

ErrorAdditionalInfo[]

错误附加信息。
code

string

错误代码。
details

ErrorDetail[]

错误详细信息。
message

string

错误消息。
target

string

错误目标。

ErrorResponse

对象

所有 Azure 资源管理器 API 的通用错误响应，用于返回失败操作的错误细节。 （这也遵循 OData 错误响应格式）。

名称 类型 说明
error

ErrorDetail

错误对象。

SuggestDocumentsResult

对象

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

名称 类型 说明
@search.coverage

number (double)

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

SuggestResult[]

查询返回的结果序列。

SuggestRequest

对象

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

名称 类型 说明
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

对象

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

名称 类型 说明
@search.text

string

建议结果的文本。