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

(Azure AI 搜索 REST API) 自动完成

项目
03/05/2024

自动完成 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 也会查找建议 ⁽¹⁾。这在某些情况下提供更好的体验，但会降低性能，因为模糊建议搜索速度较慢，消耗更多资源。
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 。

通过