你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
(Azure AI 搜索 REST API) 自动完成
自动完成 API 使用搜索索引中的现有字词完成部分类型化查询输入,以便在辅助查询中使用。 例如,如果查询输入为 "medic"
,则自动完成 API 返回 "medicare"
、 "medicaid"
、( "medicine"
如果这些字词位于索引中)。 在内部,搜索引擎在配置了 建议器 的字段中查找匹配的字词。
对于服务请求,需要 HTTPS。 可以使用 GET 或 POST 方法构造 自动完成 请求。
GET https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?[query parameters]
Content-Type: application/json
api-key: [admin or query key]
POST https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?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 版本。 对于查询,API 版本始终指定为 GET 和 POST 的 URI 参数。 |
URL 编码建议
请记住在直接调用 GET REST API 时对特定查询参数进行 URL 编码 。 对于 自动完成,以下查询参数可能需要 URL 编码:
- search
- $filter
- highlightPreTag
- highlightPostTag
仅建议将 URL 编码用于单个参数。 如果你无意中对整个查询字符串(?
后的所有内容)进行 URL 编码,请求将中断。
此外,仅在使用 GET 直接调用 REST API 时,必须进行 URL 编码。 使用 POST 或使用处理编码的 Azure AI 搜索 .NET 客户端库时,不需要 URL 编码。
请求标头
下表介绍必需和可选的请求标头。
字段 | 说明 |
---|---|
Content-Type | 必需。 将其设置为 application/json |
api-key | 如果使用的是 Azure 角色 ,并且请求中提供了持有者令牌,则为可选,否则需要密钥。 针对集合的 docs 查询请求可以将管理密钥或查询密钥指定为 api-key 。 查询键用于对索引文档集合执行只读操作。 有关详细信息 ,请参阅使用密钥身份验证连接到 Azure AI 搜索 。 |
请求正文
对于 GET:无。
对于 POST:
{
"autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
"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),
"search": "partial_search_input",
"searchFields": "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 版本都指定为 URI 参数。 |
autocompleteMode | 字符串 | 可选。 默认为 oneTerm。 有效值为 oneTerm、twoTerms、oneTermWithContext。
oneTerm 返回单个术语。 如果查询包含两个字词,则仅完成最后一个字词。 例如,给定 "washington medic" ,响应可能是以下单个字词中的任何一个: "medicaid" 、 "medicare" 、 "medicine" 。
twoTerms 与索引中的两个字词短语匹配。 例如,给定 "medic" ,响应可能是 "medicare coverage" 、 或 "medical assistant" 。 在许多情况下,不会返回单个字词 "medicare" 或 "medical" ,因为优先使用匹配的两个字词短语。oneTermWithContext 使用两个或多个字词完成查询中的最后一个字词,其中最后两个字词是索引中存在的短语。 例如,给定 "washington medic" ,响应可能是 "washington medicaid" 、 "washington medical" 。 |
$filter | 字符串 | 可选。 标准 OData 语法中的结构化搜索表达式,用于筛选用于生成已完成字词建议的文档。 自动完成 API 不支持筛选表达式“search.ismatch”和“search.ismatchscoring*”。 筛选器中只能使用可筛选的字段。 使用 POST 调用时,此参数命名为 filter,而不是$filter。 有关 Azure AI 搜索支持的 OData 表达式 语法子集的详细信息,请参阅 Azure AI 搜索的 OData 表达式语法。 |
模糊 | 布尔值 | 可选。 默认为 false。 设置为 true 时,即使搜索文本中存在替换字符或缺失字符,此 API 也会查找建议 (1) 。 这在某些情况下提供更好的体验,但会降低性能,因为模糊建议搜索速度较慢,消耗更多资源。 |
highlightPostTag | 字符串 | 可选。 默认为空字符串。 追加到突出显示的术语的字符串标记。 必须使用 highlightPreTag 进行设置。 URL 中的保留字符必须采用百分比编码形式(例如,使用 %23 而不是 #)。 使用 GET 调用时,URL 中的保留字符必须 (百分比编码,例如 %23 而不是 #) 。 |
highlightPreTag | 字符串 | 可选。 默认为空字符串。 在突出显示的字词前面追加的字符串标记。 必须使用 highlightPostTag 进行设置。 使用 GET 调用时,URL 中的保留字符必须 (百分比编码,例如 %23 而不是 #) 。 |
minimumCoverage | 整型 | 可选。 默认为 80。 一个介于 0 和 100 之间的数字,指示在报告为成功之前必须可用于为查询提供服务的索引的百分比。
默认值反映了对速度和效率的偏见,而不要完全覆盖。 减少覆盖范围会限制查询扩展,从而更快地返回结果。 它还允许查询在部分索引可用性上成功,即使一个分片因服务运行状况问题或索引维护而响应缓慢或不可用。 无论 minimumCoverage 的值如何,索引百分比都必须可用,否则自动完成将返回 HTTP 状态代码 503。 如果自动完成在 minimumCoverage 级别成功,它将返回 HTTP 200 并在响应中包含一个 @search.coverage 值,该值指示为查询提供服务时可用的索引百分比。 如果发生 503 错误,降低此值可能会有所帮助。 否则,如果响应提供的匹配项不足,可以考虑提高值。 |
search | 字符串 | 必需。 要搜索的文本。 要完成的搜索文本。 必须至少为 1 个字符,并且不超过 100 个字符。 它不能包含运算符、查询语法或带引号的短语。 |
searchFields | 字符串 | 可选。 用于搜索指定搜索文本的字段名称的逗号分隔列表。 目标字段必须在索引的 “建议器 ”定义中列出。 |
suggesterName | 字符串 | 必需。 作为索引定义的一部分的 Suggesters 集合中指定的 建议器 的名称。 建议器确定要扫描哪些字段以查找建议的查询词。 |
$top | 整型 | 可选。 默认为 5。 要检索的自动完成建议数。 值必须是介于 1 和 100 之间的数字。 使用 POST 调用时,此参数命名为 top 而不是$top。 |
(1) 自动完成中模糊的限制:
首先,编辑距离限制为每个标记仅一个字符差异,这与 搜索中的模糊参数不同。 将编辑距离限制为一个字符意味着不会找到所有候选匹配项,但必须设置上限以确保可接受的性能级别。
其次,模糊步骤发生在部分标记扩展之后,仅考虑同一索引分片中的字词进行模糊匹配。 此约束通过消除所有分片上的模糊匹配项聚合来提高自动完成 API 的性能。 随着向索引添加的字词越来越多,导致每个分片的字词分布相似,此约束变得不那么明显。 由于字词均匀分布,分片中的模糊匹配项是整个索引中模糊匹配项的良好近似值。 但是,如果索引的字词较少(例如在测试索引或原型索引中),则结果可能更差,从而导致分片中的表示形式不均匀。 有关如何将索引划分为分片的详细信息,请参阅分区和副本 (replica) 组合。
响应
成功响应时返回状态代码:“200 正常”。
响应有效负载有两个属性。
属性 | 说明 |
---|---|
"text" | 已完成的字词或短语 |
“queryPlusText” | 初始查询输入加上已完成的字词或短语 |
{
"@search.coverage": # (if minimumCoverage was provided in the query),
"value": [
{
"text": "...",
"queryPlusText": "..."
},
...
]
}
示例
示例 1: 检索三个自动完成建议,其中部分搜索输入采用 'washington medic'
默认模式 (oneTerm) :
GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30
POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{
"search": "washington medic",
"filter": "search.in(roleId, 'admin,manager')",
"top": 3,
"suggesterName": "sg"
}
响应:
{
"value": [
{
"text": "medicaid",
"queryPlusText": "washington medicaid"
},
{
"text": "medicare",
"queryPlusText": "washington medicare"
},
{
"text": "medicine",
"queryPlusText": "washington medicine"
}
]
}
示例 2:检索部分搜索输入为 'washington medic'
和 autocompleteMode=twoTerms
的三个自动完成建议:
GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30
POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{
"search": "washington medic",
"autocompleteMode": "twoTerms",
"filter": "planDuration ge 1",
"top": 3,
"suggesterName": "sg"
}
响应:
{
"value": [
{
"text": "medicaid insurance",
"queryPlusText": "washington medicaid insurance"
},
{
"text": "medicare plan",
"queryPlusText": "washington medicare plan"
},
{
"text": "medicine book",
"queryPlusText": "washington medicine book"
}
]
}
请注意,自动完成操作中需要 suggesterName 。