Documents - Suggest Get
建议索引中与给定部分查询文本匹配的文档。
GET {endpoint}/indexes('{indexName}')/docs/search.suggest?api-version=2026-04-01&search={search}&suggesterName={suggesterName}GET {endpoint}/indexes('{indexName}')/docs/search.suggest?api-version=2026-04-01&search={search}&suggesterName={suggesterName}&$filter={$filter}&fuzzy={fuzzy}&highlightPostTag={highlightPostTag}&highlightPreTag={highlightPreTag}&minimumCoverage={minimumCoverage}&$orderby={$orderby}&searchFields={searchFields}&$select={$select}&$top={$top}URI 参数
| 名称 | 在 | 必需 | 类型 | 说明 |
|---|---|---|---|---|
|
endpoint
|
path | True |
string (uri) |
搜索服务的终结点 URL。 |
|
index
|
path | True |
string |
索引的名称。 |
|
api-version
|
query | True |
string minLength: 1 |
用于此操作的 API 版本。 |
|
search
|
query | True |
string |
用于建议文档的搜索文本。 必须至少为 1 个字符，且不超过 100 个字符。 |
|
suggester
|
query | True |
string |
作为索引定义的一部分的建议器集合中指定的建议器的名称。 |
|
$filter
|
query |
string |
一个 OData 表达式，用于筛选考虑建议的文档。 |
|
|
$orderby
|
query |
string[] |
要对其结果进行排序的 OData $orderby表达式的列表。 每个表达式可以是字段名称，也可以是对 geo.distance（） 或 search.score（） 函数的调用。 每个表达式后跟 asc 以指示升序，或 desc 表示降序。 默认值为升序。 关系将由匹配文档的分数中断。 如果未指定$orderby，则默认排序顺序按文档匹配分数降序。 最多可以有 32 个$orderby子句。 |
|
|
$select
|
query |
string[] |
要检索的字段列表。 如果未指定，则结果中将仅包含键字段。 |
|
|
$top
|
query |
integer (int32) |
要检索的建议数。 该值必须是 1 到 100 之间的数字。 默认值为 5。 |
|
|
fuzzy
|
query |
boolean |
指示是否对建议查询使用模糊匹配的值。 默认值为 false。 当设置为 true 时，即使搜索文本中存在替换或缺失的字符，查询也会查找术语。 虽然这在某些情况下提供了更好的体验，但会产生性能成本，因为模糊建议查询速度较慢且消耗更多资源。 |
|
|
highlight
|
query |
string |
追加到命中突出显示的字符串标记。 必须使用 highlightPreTag 进行设置。 如果省略，则禁用建议的点击突出显示。 |
|
|
highlight
|
query |
string |
前面追加的字符串标记以命中突出显示。 必须使用 highlightPostTag 进行设置。 如果省略，则禁用建议的点击突出显示。 |
|
|
minimum
|
query |
number (double) |
一个介于 0 和 100 之间的数字，指示建议查询必须涵盖的索引百分比，以便将查询报告为成功。 此参数可用于确保仅包含一个副本的服务的搜索可用性。 默认值为 80。 |
|
|
search
|
query |
string[] |
要搜索指定搜索文本的字段名称列表。 目标字段必须包含在指定的建议器中。 |
请求头
| 名称 | 必需 | 类型 | 说明 |
|---|---|---|---|
| Accept |
接受（Accept）首部。 |
||
| x-ms-client-request-id |
string (uuid) |
请求的不透明、全局唯一的客户端生成的字符串标识符。 |
响应
| 名称 | 类型 | 说明 |
|---|---|---|
| 200 OK |
请求已成功。 |
|
| Other Status Codes |
意外的错误响应。 |
安全性
api-key
类型:
apiKey
在:
header
OAuth2Auth
类型:
oauth2
流向:
implicit
授权 URL:
https://login.microsoftonline.com/common/oauth2/v2.0/authorize
作用域
| 名称 | 说明 |
|---|---|
| https://search.azure.com/.default |
示例
SearchIndexSuggestDocumentsGet
示例请求
GET https://myservice.search.windows.net/indexes('myindex')/docs/search.suggest?api-version=2026-04-01&search=hote&suggesterName=sg&$filter=rating gt 10&fuzzy=False&highlightPostTag=</em>&highlightPreTag=<em>&minimumCoverage=80&$orderby=search.score() desc,rating desc&searchFields=title&$select=docId,title,description&$top=10
示例响应
{
"value": [
{
"@search.text": "Nice <em>Hotel</em>",
"description": "Cheapest hotel in town",
"docId": "1",
"title": "Nice Hotel"
},
{
"@search.text": "Fancy <em>Hotel</em>",
"description": "Best hotel in town",
"docId": "2",
"title": "Fancy Hotel"
}
]
}定义
| 名称 | 说明 |
|---|---|
| Accept |
接受（Accept）首部。 |
|
Error |
资源管理错误附加信息。 |
|
Error |
错误详细信息。 |
|
Error |
所有 Azure 资源管理器 API 的通用错误响应，用于返回失败操作的错误细节。 （这也遵循 OData 错误响应格式）。 |
|
Suggest |
包含来自索引的建议查询结果的响应。 |
|
Suggest |
包含由建议查询找到的文档的结果，以及关联的元数据。 |
Accept
接受（Accept）首部。
| 值 | 说明 |
|---|---|
| application/json;odata.metadata=none |
ErrorAdditionalInfo
资源管理错误附加信息。
| 名称 | 类型 | 说明 |
|---|---|---|
| info |
附加信息。 |
|
| type |
string |
附加信息类型。 |
ErrorDetail
错误详细信息。
| 名称 | 类型 | 说明 |
|---|---|---|
| additionalInfo |
错误附加信息。 |
|
| code |
string |
错误代码。 |
| details |
错误详细信息。 |
|
| message |
string |
错误消息。 |
| target |
string |
错误目标。 |
ErrorResponse
所有 Azure 资源管理器 API 的通用错误响应，用于返回失败操作的错误细节。 （这也遵循 OData 错误响应格式）。
| 名称 | 类型 | 说明 |
|---|---|---|
| error |
错误对象。 |
SuggestDocumentsResult
包含来自索引的建议查询结果的响应。
| 名称 | 类型 | 说明 |
|---|---|---|
| @search.coverage |
number (double) |
一个值，指示查询中包含的索引的百分比，如果请求中未设置 minimumCoverage，则为 null。 |
| value |
查询返回的结果序列。 |
SuggestResult
包含由建议查询找到的文档的结果，以及关联的元数据。
| 名称 | 类型 | 说明 |
|---|---|---|
| @search.text |
string |
建议结果的文本。 |