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

Azure AI 搜索 REST API) (建议

项目
11/13/2023

建议请求是一种搜索即用查询，可在建议器感知字段中查找匹配值，并返回包含匹配项的文档。例如，如果对城市字段启用建议，则键入“sea”将生成包含“Seattle”、“Sea Tac”和“Seaside”的文档， (该字段的所有实际城市名称) 。

响应是来自匹配文档的内容以及文档键。与自动完成（后者返回辅助查询中使用的已完成字词或短语）相反，此请求返回解析为实际文档的信息。如果匹配的字词或短语在文档中相同，则会重复匹配的内容。若要改进结果结构，请考虑使用 $select 筛选器返回可提供更多差异和上下文的其他字段。

对于服务请求，需要 HTTPS。可以使用 GET 或 POST 方法构造建议请求。

GET https://[service name].search.windows.net/indexes/[index name]/docs/suggest?[query parameters]  
  Content-Type: application/json  
  api-key: [admin or query key]

POST https://[service name].search.windows.net/indexes/[index name]/docs/suggest?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]

与搜索文档请求不同，可以将建议调用绑定到键盘输入，而搜索调用可能绑定到单击事件。

使用 GET 调用时，请求 URL 的长度不能超过 8 KB。此长度通常足以满足大多数应用程序的需求。但是，某些应用程序会生成非常大的查询，尤其是在使用 OData 筛选器表达式时。对于这些应用程序，HTTP POST 是更好的选择，因为它允许比 GET 更大的筛选器。

对于 POST，限制因素是筛选器中子句的数量，而不是原始筛选器字符串的大小，因为 POST 的请求大小限制大约为 16 MB。即使 POST 请求大小限制非常大，筛选器表达式也不能任意复杂。有关筛选器复杂性限制的详细信息，请参阅 Azure AI 搜索的 OData 表达式语法。

URI 参数

参数	说明
[服务名称]	必需。将此设置为搜索服务的唯一用户定义名称。
[index name]/docs	必需。指定命名索引的文档集合。
api-version	必需。当前稳定版本为 `api-version=2020-06-30`。有关更多版本，请参阅 API 版本。对于查询，API 版本始终指定为 GET 和 POST 的 URI 参数。

URL 编码建议

请记住在直接调用 GET REST API 时对特定查询参数进行 URL 编码。对于建议请求，这包括：

search
$filter
highlightPreTag
highlightPostTag

仅建议对单个参数使用 URL 编码。如果你无意中对整个查询字符串（? 后的所有内容）进行 URL 编码，请求将中断。

此外，仅在使用 GET 直接调用 REST API 时，必须进行 URL 编码。使用 POST 调用建议时，或使用 Azure AI 搜索 .NET 客户端库处理 URL 编码时，无需进行 URL 编码。

请求标头

下表介绍必需和可选的请求标头。

字段说明

Content-Type 必需。将其设置为 application/json

api-key 如果使用 Azure 角色并且请求中提供了持有者令牌，则为可选，否则需要密钥。 api-key 是系统生成的唯一字符串，用于对搜索服务的请求进行身份验证。针对文档集合的查询请求可以将管理密钥或查询密钥指定为 API 密钥。查询键用于对文档集合执行只读操作。有关详细信息，请参阅使用密钥身份验证连接到 Azure AI 搜索。

字段	说明
Content-Type	必需。将其设置为 `application/json`
api-key	如果使用 Azure 角色并且请求中提供了持有者令牌，则为可选，否则需要密钥。 api-key 是系统生成的唯一字符串，用于对搜索服务的请求进行身份验证。针对文档集合的查询请求可以将管理密钥或查询密钥指定为 API 密钥。查询键用于对文档集合执行只读操作。有关详细信息，请参阅使用密钥身份验证连接到 Azure AI 搜索。

请求正文

对于 GET：无。

对于 POST：

{  
      "filter": "odata_filter_expression",  
      "fuzzy": true | false (default),  
      "highlightPreTag": "pre_tag",  
      "highlightPostTag": "post_tag",  
      "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),  
      "orderby": "orderby_expression",  
      "search": "partial_search_input",  
      "searchFields": "field_name_1, field_name_2, ...",  
      "select": "field_name_1, field_name_2, ...",  
      "suggesterName": "suggester_name",  
      "top": # (default 5)  
}

查询参数

使用 GET 调用时，查询接受 URL 上的多个参数，在使用 POST 调用时接受请求正文中的 JSON 属性。在 GET 和 POST 之间，某些参数的语法稍有不同。下面指出了这些差异。

名称	类型	说明
api-version	字符串	必需。用于请求的 REST API 的版本。有关支持版本的列表，请参阅 API 版本。对于此操作，无论使用 GET 还是 POST 调用 API，API 版本都会指定为 URL 中的查询参数。
$filter	字符串	可选。一个表达式，用于筛选要在建议中考虑的文档。筛选器中只能使用可筛选字段。自动完成 API 不支持筛选表达式“search.ismatch”和“search.ismatchscoring*”。使用 POST 调用此参数时，将命名为筛选器，而不是$filter。有关 Azure AI 搜索支持的 OData 表达式语法子集的详细信息，请参阅 Azure AI 搜索的 OData 表达式语法。
模糊	布尔值	可选。默认为 false。设置为 true 时，即使搜索文本中有替换字符或缺失字符，此 API 也会查找建议。每个查询字符串的编辑距离为 1。如果查询字符串是多个字词，则整个字符串中只能有一个缺失、额外、替换或转置的字符。在某些情况下，启用模糊匹配可能是更好的体验，它确实需要性能成本，因为模糊建议搜索速度较慢，并且会消耗更多资源。
highlightPostTag	字符串	可选。默认为空字符串。追加到突出显示的术语的字符串标记。必须使用 highlightPreTag 进行设置。 URL 中的保留字符必须采用百分比编码形式（例如，使用 %23 而不是 #）。使用 GET 调用时，URL 中的保留字符必须采用百分比编码 (例如 %23 而不是 #) 。
highlightPreTag	字符串	可选。默认为空字符串。在突出显示的术语前面附加的字符串标记。必须使用 highlightPostTag 进行设置。使用 GET 调用时，URL 中的保留字符必须采用百分比编码 (例如 %23 而不是 #) 。
$orderby	字符串	可选。逗号分隔的表达式列表，结果将根据它进行排序。每个表达式可以是字段名称或对 `geo.distance()` 函数的调用。每个表达式后跟“asc” (升序) 或“desc” (降序) 。默认值为升序。 $orderby有 32 个子句的限制。使用 POST 调用时，此参数按顺序命名，而不是$orderby。
minimumCoverage	整型	可选。默认值为 80。一个介于 0 和 100 之间的数字，指示必须可用于为查询提供服务的索引百分比，然后才能将其报告为成功。默认值反映了对速度和效率的偏见，而不要完全覆盖。减少覆盖范围会限制查询扩展，从而更快地返回结果。它还允许查询在部分索引可用性上成功，即使一个分片响应缓慢或由于服务运行状况问题或索引维护而不可用。无论 minimumCoverage 的值如何，该索引百分比都必须可用，或者建议返回 HTTP 状态代码 503。如果“建议”在最低级别成功，它将返回 HTTP 200 并在响应中包含一个 @search.coverage 值，该值指示为查询提供服务时可用的索引的百分比。如果发生 503 错误，则降低此值可能会有所帮助。否则，如果响应提供的匹配项不足，可以考虑提高值。
search	字符串	必需。用来建议查询的搜索文本。必须至少为 1 个字符，并且不超过 100 个字符。它不能包含运算符、查询语法或带引号的短语。
searchFields	字符串	可选。用于搜索指定搜索文本的字段名称的逗号分隔列表。目标字段必须在索引的 “建议器 ”定义中列出。
$select	字符串	可选。要检索的逗号分隔的字段列表。如果未指定，则仅返回文档键和建议文本。可通过将此参数设置为 `*` 显式请求所有字段。使用 POST 调用时，此参数名为 select 而不是 $select。
suggesterName	字符串	必需。作为索引定义的一部分的 Suggesters 集合中指定的建议器的名称。建议器确定扫描哪些字段以查找建议的查询词。
$top	整型	可选。默认为 5) 。要检索的自动完成建议的数目。值必须是介于 1 和 100 之间的数字。使用 POST 调用时，此参数将命名为 top 而不是 $top。

响应

状态代码：成功响应返回“200 正常”。

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
    },  
    ...  
  ]  
}

如果使用投影选项来检索字段，则会将这些字段包含在数组的每个元素中：

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}

示例

检索其中的部分搜索输入是“lux”的 5 条建议：

GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30

POST /indexes/hotels/docs/suggest?api-version=2020-06-30 
    {  
      "search": "lux",  
      "top": 5,  
      "suggesterName": "sg"  
    }

请注意，建议操作需要 suggesterName 。

通过