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

(预览版 REST API) 搜索文档

项目
02/03/2024

适用于：2023-07-01-Preview、2021-04-30-Preview、2020-06-30-Preview

重要

2023-07-01-Preview 添加了：

指定任何矢量查询请求的“vectors”查询参数。每个对象都应包含查询的向量表示形式、要在结果中返回的最近邻居的“k”数，以及要在查询执行期间使用的向量字段。

2021-04-30-Preview 添加了：

“semanticConfiguration” 支持将语义排名范围限定为特定字段。
“captions” 返回从语义排名最高的文档中的关键段落中提取的短语。

2020-06-30-Preview 添加了：

“queryType=semantic” 支持语义重排和响应。
语义查询中的“searchFields”建立用于表述标题和答案的字段的优先级顺序。此方法在 2021-04-30-Preview 中已替换为 “semanticConfiguration” ，现在已过时。
“speller” 可对查询输入进行拼写更正。
“queryType=semantic”和“speller”都需要“queryLanguage”。
“featuresMode” 解包搜索分数，报告每字段字词频率、每字段相似性分数和每字段唯一匹配项数。

查询请求以搜索服务上单个索引的文档集合为目标。它包括定义匹配条件的参数，以及形成响应的参数。还可以使用索引别名来面向特定索引，而不是使用索引名称本身。

可以对大多数查询使用 GET 或 POST，但必须使用 POST 进行矢量搜索，因为矢量查询参数不适合 URI。查询参数在 GET 请求的查询字符串上指定，在 POST 请求的请求正文中指定。

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

如果使用 POST，请添加“搜索”操作作为 URI 参数。

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?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 参数

参数	说明
服务名称	必需。将此名称设置为搜索服务的唯一用户定义名称。
索引名称/文档	必需。指定命名索引的文档集合。索引别名的名称也可以用于代替索引名称。
查询参数 (query parameters)	查询参数在 GET 请求的 URI 和 POST 请求的请求正文中指定。
api-version	必需。当前版本为 `2023-07-01-Preview`。有关更多版本，请参阅 API 版本。

URL 编码建议

请记住在直接调用 GET REST API 时对特定查询参数进行 URL 编码。对于 搜索文档 操作，以下查询参数可能需要 URL 编码：

search
$filter
facet
highlightPreTag
highlightPostTag

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

此外，仅在使用 GET 直接调用 REST API 时，必须进行 URL 编码。使用 POST 或使用处理编码的 Azure AI 搜索 .NET 客户端库时，不需要 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：

{  
     "answers": "none" (default) | "extractive", 
     "count": true | false (default),
     "captions": "none" (default) | "extractive",
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "featuresMode" : "disabled" (default) | "enabled",
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",
     "queryLanguage": "en-us" (default) | (a supported language code), 
     "queryType": "simple" (default) | "full" | "semantic",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" (default) | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "semanticConfiguration": "semantic_configuration_name",
     "sessionId" : "session_id",
     "skip": # (default 0), 
     "speller": "none" (default) | "lexicon",  
     "top": #,
     "vectors": [
      {
        "value": "a vector representation of the query",
        "k": an integer (number of nearest neighbors to return as top results),
        "fields": "a comma-delimited list of vector fields to use in the query"
      }
     ]
   }

部分搜索响应的延续

有时，Azure AI 搜索无法在单个搜索响应中返回所有请求的结果。发生部分响应的原因可能不同，例如查询返回的文档过多时，未指定$top，或为 $top 指定值过大。在这种情况下，Azure AI 搜索在响应正文中包括 @odata.nextLink 注释，如果是 POST 请求，也会 @search.nextPageParameters 包含注释。可使用这些批注的值表述另一个搜索请求，以获取搜索响应的下一部分。此行为称为原始搜索请求的延续，批注称为 延续标记。有关这些注释的语法及其在响应正文中的显示位置的详细信息，请参阅 Response 部分中的示例。

Azure AI 搜索可能返回延续令牌的原因特定于实现，可能会发生更改。可靠的客户端应始终准备好处理返回的文档少于预期并且包含延续标记以继续检索文档的情况。另请注意，必须使用与原始请求相同的 HTTP 方法才能继续。例如，如果已发送 GET 请求，则发送的任何延续请求都必须也使用 GET（对于 POST 同样如此）。

注意

和 @search.nextPageParameters 的用途@odata.nextLink是保护服务免受请求过多结果的查询，而不是提供一般分页机制。如果要分页浏览结果，请结合使用$top和$skip。例如，如果希望页面大小为 10，则第一个请求的$top=10 和 $skip=0，第二个请求应具有$top=10 和 $skip=10，第三个请求应具有 $top=10 和 $skip=20，依此。

查询参数

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

名称	类型	说明
answers (preview)	字符串	可选。有效值为“none”和“extractive”。默认为“none”。仅当查询类型为“semantic”时，此参数才有效。当设置为“extractive”时，查询将从语义排名最高的文档中的关键段落中表述并返回答案。默认值为一个答案，但可以通过添加计数来指定最多 10 个答案。例如，“answers”： “extractive\|count-3”返回三个答案。若要返回答案，目标字段中必须包含看起来像答案的逐字内容。用于答案的语言模型经过训练以识别答案，而不是生成答案。此外，查询本身必须看起来像一个问题。
api-version	字符串	必需。用于请求的 REST API 的版本。有关支持的版本列表，请参阅 API 版本。对于此操作，无论使用 GET 还是 POST 调用搜索文档，api-version 都指定为 URI 参数。
字幕 (预览)	字符串	可选。有效值为“none”和“extractive”。默认为“none”。仅当查询类型为“semantic”时，此参数才有效。设置为“extractive”时，查询将返回从排名最高的文档中的关键段落中提取的标题。当标题设置为“extractive”时，默认情况下会启用突出显示，可以通过追加管道字符“\|”后跟“highlight-true</false>”选项（如“extractive\|highlight-true”）来配置突出显示。
$count	布尔值	可选。有效值为“true”或“false”。默认为“false”。使用 POST 调用时，此参数命名为 count 而不是$count。指定是否要获取结果的总计数。此值是匹配搜索和$filter参数的所有文档的计数，忽略$top和$skip。将此值设置为“true”可能会降低性能。如果索引稳定，计数是准确的，但会低于或过度报告主动添加、更新或删除的任何文档。如果只想获取不带任何文档的计数，可以使用 $top=0。
facet 或 facet	字符串	可选。分面依据的字段，其中字段被归为“facetable”。使用 GET 调用时， `facet` 是一个字段 (`facet: field1`) 。使用 POST 调用此参数时，将命名 `facets` 为而不是 `facet` ，并指定为数组 (`facets: [field1, field2, field3]`) 。字符串可能包含用于自定义分面的参数，以逗号分隔的名称/值对表示。有效值为“count”、“sort”、“values”、“interval”和“timeoffset”。 “count”是分面字词的最大数目;默认值为 10。字词数没有上限，但值越高会降低性能，尤其是在分面字段包含大量唯一字词时。例如，“facet=category，count：5”获取分面结果中的前五个类别。如果 count 参数小于唯一项的数目，则结果可能不准确。这由分面查询分布在各个分片上的方式所导致。若要获取所有分片的准确计数，可以将 count 设置为零或设置为大于或等于可分面字段中唯一值数的值。缺点是延迟增加。 “sort”可以设置为“count”、“-count”、“value”、“-value”。使用 count 按计数降序排序。使用 -count 按计数进行升序排序。使用值按值进行升序排序。使用 -value 按值降序排序 (例如，“facet=category，count：3，sort：count”按每个城市名称的文档数降序获取分面结果中的前三个类别) 。如果前三个类别是预算、汽车旅馆和豪华，而预算有五个命中，汽车旅馆有六个命中，豪华有四个，那么桶的顺序是汽车旅馆，预算，豪华。对于 -value，“facet=rating，sort：-value”生成所有可能评级的存储桶，按值 (降序排列，例如，如果评级从 1 到 5，则存储桶排序为 5、4、3、2、1，而不考虑与每个分级) 匹配的文档数。 “values”可以设置为管道分隔的数值或 Edm.DateTimeOffset 值，指定一组动态的 facet 条目值 (例如“facet=baseRate，values：10 \|20“ 生成三个桶：一个用于基准速率 0 到 10，但不包括 10，一个用于 10 到但不包括 20，一个用于 20 及更高) 。字符串“facet=lastRenovationDate，values：2010-02-01T00：00：00Z”生成两个存储桶：一个用于 2010 年 2 月 1 日之前装修的酒店，一个用于 2010 年 2 月 1 日或之后翻新的酒店。值必须按顺序升序列出，才能获得预期结果。 “interval”是一个大于 0 的整数间隔，表示数字，或日期时间值的分钟、小时、日、周、月、季度、年。例如，“facet=baseRate，interval：100”基于大小 100 的基本速率范围生成存储桶。如果基本费率都在 $60 到 $600 之间，则存在 0-100、100-200、200-300、300-400、400-500 和 500-600 的存储桶。字符串“facet=lastRenovationDate，interval：year”为每年酒店翻新时生成一个存储桶。 “timeoffset”可以设置为 ([+-]hh：mm、[+-]hhmm 或 [+-]hh) 。如果使用，则 timeoffset 参数必须与 interval 选项组合，并且仅当应用于 Edm.DateTimeOffset 类型的字段时。该值指定在设置时间边界时要考虑的 UTC 时间偏移量。例如：“facet=lastRenovationDate，interval：day，timeoffset：-01：00”使用从 01：00：00 UTC 开始 (午夜的目标时区) 的日边界。可以在同一方面规范中组合计数和排序，但它们不能与间隔或值组合，并且间隔和值不能组合在一起。如果未指定时间偏移量，则基于 UTC 时间计算日期时间的间隔方面。例如：对于“facet=lastRenovationDate，interval：day”，日边界从 00：00：00 UTC 开始。
featuresMode（预览版）	布尔值	可选。有效值为“enabled”和“disabled”。默认值为“disabled”。一个值，该值指定结果是否应包含查询结果特征，用于计算文档相对于查询的相关性分数，例如每个字段的相似性。使用“enabled”可公开更多查询结果功能：每个字段的相似性分数、每个字段的术语频率以及每个字段匹配的唯一标记数。有关详细信息，请参阅相似性和评分。
$filter	字符串	可选。使用标准 OData 语法的结构化搜索表达式。筛选器中只能使用可筛选的字段。使用 POST 调用时，此参数命名为 filter，而不是$filter。有关 Azure AI 搜索支持的 OData 表达式语法子集的详细信息，请参阅 Azure AI 搜索的 OData 表达式语法。
highlight	字符串	可选。用于命中突出显示的逗号分隔的字段名称集。仅可搜索字段可用于突出显示命中。默认情况下，Azure AI 搜索每个字段最多返回五个突出显示。可以通过在字段名称后面追加“-<max of highlights>”来配置每个字段的限制。例如，“highlight=title-3，description-10”从标题字段中返回最多 3 个突出显示的命中，从说明字段中返回最多 10 个命中。最大突出显示数必须是介于 1 和 1000（含 1 和 1000）之间的整数。
highlightPostTag	字符串	可选。默认为 `"</em>"`。追加到突出显示的术语的字符串标记。必须使用 highlightPreTag 进行设置。 URL 中的保留字符必须采用百分比编码形式（例如，使用 %23 而不是 #）。
highlightPreTag	字符串	可选。默认为 `"</em>"`。在突出显示的字词前面追加的字符串标记。必须使用 highlightPostTag 进行设置。 URL 中的保留字符必须采用百分比编码形式（例如，使用 %23 而不是 #）。
minimumCoverage	整型	可选。有效值是介于 0 和 100 之间的数字，指示在报告为成功之前必须可用于为查询提供服务的索引的百分比。默认为“100”。百分之百的覆盖率意味着所有分片都响应了请求， (服务运行状况问题和维护活动都没有减少) 覆盖范围。在默认设置下，小于完全覆盖将返回 HTTP 状态代码 503。如果发生 503 错误，并且希望提高查询成功的概率，尤其是对于为一个副本 (replica) 配置的服务，则降低 minimumCoverage 会很有用。如果设置 minimumCoverage 且搜索成功，它将返回 HTTP 200 并在响应中包含一个 @search.coverage 值，该值指示查询中包含的索引的百分比。在此方案中，并非所有匹配的文档都保证出现在搜索结果中，但如果搜索可用性比召回更重要，那么减少覆盖范围可能是一种可行的缓解策略。
$orderby	字符串	可选。逗号分隔的表达式列表，结果将根据它进行排序。使用 POST 调用时，此参数命名为 orderby 而不是 $orderby。每个表达式可以是字段名称，也可以是对 geo.distance () 函数的调用。每个表达式后跟“asc”表示升序，“desc”表示降序。如果排序字段中有 null 值，则 null 先按升序显示，最后按降序显示。默认值为升序。排序的依据将是文档的匹配分数。如果未指定$orderby，则默认排序顺序为按文档匹配分数降序。 $orderby的子句限制为 32 个。
queryLanguage (预览版)	字符串	可选。有效值是受支持的语言。默认为“en-us”。如果使用 speller=lexicon 或 queryType=semantic，则必须设置此参数。 queryLanguage 中指定的语言既用于拼写检查，也用于重新运行结果和提取描述文字或答案的语义模型。用于 queryLanguage 的库独立于其他基于区域设置的字段属性，例如用于索引和全文搜索的语言分析器。
queryType	字符串	可选。有效值为“simple”、“full”或“semantic” (预览) 。默认为“simple”。对于矢量搜索，此值将被忽略，但适用于混合方案中的文本搜索。 “simple”使用允许符号（如、 ``和 `""`）`+`的简单查询语法解释查询字符串。默认情况下，查询将跨所有可搜索字段 (或 searchFields 中指示的字段) 在每个文档中进行评估。 “full”使用完整的 Lucene 查询语法解释查询字符串，该语法允许特定于字段的和加权的搜索。不支持使用 Lucene 查询语言进行范围搜索，而支持$filter，后者提供类似的功能。 ”semantic“通过使用在必应语料库上训练的排名模型重新排名前 50 个匹配项，以自然语言（而不是关键字）表示的查询，从而提高搜索结果的精度。如果将查询类型设置为 semantic，则还必须设置 queryLanguage 和 semanticConfiguration。如果查询输入是用自然语言 (“ 什么是...*) ，可以选择设置标题以从排名最高的文档中提取关键段落。
scoringParameter	字符串	可选。指示使用格式“name-value1，value2,...”的评分函数 (如 referencePointParameter) 中定义的每个参数的值使用 POST 调用时，此参数命名为 scoringParameters，而不是 scoringParameter。此外，还可以将其指定为字符串的 JSON 数组，其中每个字符串都是一个单独的名称/值对。对于包含函数的评分配置文件，请使用 `-` 字符将该函数与其输入列表分开。例如，名为的 `"mylocation"` 函数为“&scoringParameter=mylocation--122.2,44.8”。第一个短划线将函数名称与值列表分开，而第二个短划线是此示例中 (经度的第一个值的一部分) 。对于可包含逗号的标记提升等评分参数，可以使用单引号对列表中的任何此类值进行转义。如果值本身包含单引号，可通过双重单引号转义它们。假设你有一个名为 `"mytag"` 的标记提升参数，并且你想要提升标记值“Hello， O'Brien”和“Smith”，则查询字符串选项将为“&scoringParameter=mytag-'Hello， O''Brien'，Smith”。只有包含逗号的值才需要引号。
scoringProfile	字符串	可选。用于为匹配的文档评估匹配分数以便对结果进行排序的评分配置文件的名称。
scoringStatistics	字符串	可选。有效值为“local”或“global”。默认为“local”。指定是计算评分统计信息（例如文档频率、跨所有分片的全局 () ）以更一致的评分，还是针对当前分片) 本地 (以降低延迟。请参阅 Azure AI 搜索中的评分统计信息。对于使用模糊搜索 (“~”) 的字词，始终在本地计算评分统计信息。
search	字符串	可选。要搜索的文本。对于矢量搜索，此值将被忽略，但适用于混合方案中的文本搜索。在 REST API 中，默认情况下会搜索所有可搜索字段，除非指定了 searchFields。在索引中，可搜索字段中的文本已标记化，因此多个字词可以通过空格 (分隔，例如：“search=hello world”) 。若要匹配任何字词，请使用 ``（这对布尔筛选器查询可能很有用）。忽略此参数与将其设置为 `` 具有相同的效果。有关搜索语法的详细信息，请参阅简单查询语法。查询可搜索字段时，结果有时会出人意料。标记器包含用于处理英语文本中常见情况（如撇号、数字中的逗号等）的逻辑。例如，“search=123,456”将匹配单个字词“123,456”，而不是单个字词“123”和“456”，因为逗号用作英语中较大数字的千位分隔符。因此，建议使用空格而不是标点符号来分隔搜索参数中的字词。
searchMode	字符串	可选。有效值为“any”或“all”，默认值为“any”。指定要将文档算作匹配项，是必须匹配任一搜索词还是必须匹配所有搜索词。
searchFields	字符串	可选。要对指定文本搜索的逗号分隔的字段名称列表。目标字段必须在索引架构中标记为可搜索，并且类型必须为 `Edm.String`、 `Edm.ComplexType`或 `Collection(Edm.String)`。
$select	字符串	可选。要包含在结果集中的逗号分隔字段的列表。此子句中只能包含标记为可检索的字段。如果未指定或设置为 `*`，会在投影中包含架构中标记为可检索的所有字段。使用 POST 调用时，此参数名为 select 而不是 $select。
semanticConfiguration (预览版)	字符串	可选。如果 queryType=“semantic”，则为必需。语义配置的名称，其中列出了哪些字段应用于语义排名、标题、突出显示和答案。有关详细信息，请参阅创建语义查询。
sessionID	字符串	可选。使用 sessionId 有助于提高具有多个副本的搜索服务的相关性分数一致性。在多副本 (replica) 配置中，同一查询的各个文档的相关性分数之间可能略有差异。提供会话 ID 时，服务会尽力将给定请求路由到该会话的同一副本 (replica) 。请注意，重复重复使用相同的会话 ID 值可能会干扰跨副本的请求负载均衡，并会对搜索服务的性能产生负面影响。用作 sessionId 的值不能以“_”字符开头。如果服务没有任何副本，则此参数不会影响性能或分数一致性。
$skip	整型	可选。要跳过的搜索结果数。使用 POST 调用时，此参数名为 skip，而不是 $skip。此值不能大于 100,000。如果需要按顺序扫描文档，但由于此限制而无法使用$skip，请考虑对索引中每个文档具有唯一值的字段使用$orderby (，例如，) 和$filter改为使用范围查询。
拼写检查器 (预览)	字符串	可选。有效值为“none”和“lexicon”。默认值为“none”。通过对单个搜索查询词进行拼写更正来提高召回率。可以在简单查询、完整查询和语义查询类型上使用它。如果使用，拼写检查器参数需要 queryLanguage。有关详细信息和示例，请参阅向查询添加拼写检查。
$top	整型	可选。要检索的搜索结果数。这默认为 50。使用 POST 调用时，此参数将命名为 top 而不是 $top。如果指定的值大于 1000 且结果超过 1000 个，则仅返回前 1000 个结果，以及指向下一页结果的链接， (在以下示例中查看“@odata.nextLink”) 。 Azure AI 搜索使用服务器端分页来防止查询一次检索过多的文档。默认页面大小为 50，而最大页面大小为 1000。这意味着，默认情况下，如果未指定$top ，搜索文档最多返回 50 个结果。如果结果超过 50 个，响应包括检索最多 50 个结果的下一页的信息， (请参阅以下示例中的“@odata.nextLink”和“@search.nextPageParameters”。同样，如果为$top指定大于 1000 的值，并且结果超过 1000 个，则仅返回前 1000 个结果，以及检索最多 1000 个结果的下一页的信息。
向量 (预览)	array	可选。数组中的对象类型是矢量查询。矢量查询的查询参数。 “value”是搜索查询的向量表示形式。此表示形式必须在外部形成。 Azure AI 搜索不会创建嵌入。 “k”是一个整数，指定要返回为顶部命中数的最近邻居数。默认值为 50。最小值为 1，最大值为 10,000。 “fields”是包含矢量数据的逗号分隔列表字段名称。只有类型的 `Collection(Edm.Single)` 字段才能包含在“字段”列表中。

响应

对于成功的响应，返回“状态代码：200 正常”。本文中有两个示例响应，分别用于语义搜索和 featuresMode。

语义查询的示例响应

第一个示例显示了语义查询 “云如何形成”的最顶层结果的完整响应。

指定 answers 参数时，当查询和索引中的目标字段包含可识别为答案的内容时，将显示“@search.answers”。 @search.answers具有键、文本和突出显示的数组。分数是答案强度的指标。
“value”是响应的主体。 @search.rerankerScore由语义排名算法分配，用于对结果进行排名 (@search.score 来自 BM25 相似性算法，在) 对初始结果进行评分时使用。标题包括纯文本和突出显示的版本。此示例是使用 OCR 和实体识别技能创建的。响应中包含提取和合并内容的字段。

{
    "@search.answers": [
        {
            "key": "aHR0cHM6Ly9oZWlkaXN0YmxvYnN0b3JhZ2UuYmxvYi5jb3JlLndpbmRvd3MubmV0L25hc2EtZWJvb2stMS01MC9wYWdlLTQ1LnBkZg2",
            "text": "Sunlight heats the land all day, warming that moist air and causing it to rise high into the atmosphere until it cools and condenses into water droplets. Clouds generally form where air is ascending (over land in this case),   but not where it is descending (over the river).",
            "highlights": "Sunlight heats the land all day, warming that moist air and causing it to rise high into the   atmosphere until it cools and condenses into water droplets. Clouds generally form<em> where air is ascending</em> (over land in this case),   but not where it is<em> descending</em> (over the river).",
            "score": 0.94639826
        }
    ],
    "value": [
        {
            "@search.score": 0.5479723,
            "@search.rerankerScore": 1.0321671911515296,
            "@search.captions": [
                {
                    "text": "Like all clouds, it forms when the air reaches its dew point—the temperature at which an air mass is cool enough for its water vapor to condense into liquid droplets. This false-color image shows valley fog, which is common in the Pacific Northwest of North America.",
                    "highlights": "Like all<em> clouds</em>, it<em> forms</em> when the air reaches its dew point—the temperature at    which an air mass is cool enough for its water vapor to condense into liquid droplets. This false-color image shows valley<em> fog</em>, which is common in the Pacific Northwest of North America."
                }
            ],
            "content": "\nA\nT\n\nM\nO\n\nS\nP\n\nH\nE\n\nR\nE\n\nE\nA\n\nR\nT\n\nH\n\n34\n\nValley Fog\nCanada\n\nFog is essentially a cloud lying on the ground. Like all clouds, it forms when the air reaches its dew point—the temperature at  \n\nwhich an air mass is cool enough for its water vapor to condense into liquid droplets.\n\nThis false-color image shows valley fog, which is common in the Pacific Northwest of North America. On clear winter nights, the \n\nground and overlying air cool off rapidly, especially at high elevations. Cold air is denser than warm air, and it sinks down into the \n\nvalleys. The moist air in the valleys gets chilled to its dew point, and fog forms. If undisturbed by winds, such fog may persist for \n\ndays. The Terra satellite captured this image of foggy valleys northeast of Vancouver in February 2010.\n\n\n",
            "metadata_storage_path": "aHR0cHM6Ly9oZWlkaXN0YmxvYnN0b3JhZ2UuYmxvYi5jb3JlLndpbmRvd3MubmV0L25hc2EtZWJvb2stMS01MC9wYWdlLTQxLnBkZg2",
            "people": [],
            "locations": [
                "Pacific Northwest",
                "North America",
                "Vancouver"
            ],
            "merged_content": "\nA\nT\n\nM\nO\n\nS\nP\n\nH\nE\n\nR\nE\n\nE\nA\n\nR\nT\n\nH\n\n34\n\nValley Fog\nCanada\n\nFog is essentially a cloud lying on the ground. Like all clouds, it forms when the air reaches its dew point—the temperature at  \n\nwhich an air mass is cool enough for its water vapor to condense into liquid droplets.\n\nThis false-color image shows valley fog, which is common in the Pacific Northwest of North America. On clear winter nights, the \n\nground and overlying air cool off rapidly, especially at high elevations. Cold air is denser than warm air, and it sinks down into the \n\nvalleys. The moist air in the valleys gets chilled to its dew point, and fog forms. If undisturbed by winds, such fog may persist for \n\ndays. The Terra satellite captured this image of foggy valleys northeast of Vancouver in February 2010.\n\n\n",
            "text": [],
            "layoutText": []
        }
    ]
}

featuresMode 的示例响应

此示例显示包含 featuresMode 的查询的“@search.features”输出。

  {
    "@odata.count": # (if $count=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "featuresMode" : ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

示例

可以在 Azure AI 搜索的 OData 表达式语法中找到更多示例。

示例：简单搜索

使用简单的查询语法在索引中查找文档。此查询返回酒店，其中可搜索字段包含字词“舒适度”和“位置”，但不包含“汽车旅馆”：

Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }

提示

使用 searchMode=all 将覆盖 searchMode=any 的默认值，并确保 -motel 表示“AND NOT”而不是“OR NOT”。如果没有 searchMode=all，将获取“OR NOT”，从而展开而不是限制搜索结果，这对某些用户来说可能违反语感。

示例：完整的 Lucene 搜索

使用 Lucene 查询语法在索引中查找文档 (请参阅 Azure AI 搜索) 中的 Lucene 查询语法。此查询返回酒店，其中类别字段包含字词“budget”和所有包含短语“recently renovated”的可搜索字段。包含短语“recently renovated”的文档作为字词提升值 (3) 的结果排名更高

GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2021-04-30-Preview&querytype=full`

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}

示例：语义搜索

使用答案、标题和突出显示的内容调用语义排名模型。可以在上一部分中找到此查询的响应。

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
{
  "search": "how do clouds form",
  "queryType": "semantic",
  "semanticConfiguration": "my-semantic-config",
  "queryLanguage": "en-us",
  "answers": "extractive",
  "captions": "extractive",
  "count": "true"
}

示例：矢量搜索

对于具有类型 Collection(Edm.Single) 字段和向量配置的索引，可以指定矢量查询参数。向量查询参数包括查询范围内的向量字段、要返回的“k”个最高命中次数以及查询输入的向量表示形式。

如果索引包含文本字段，则添加“select”参数很有用。匹配和相关性基于向量，但包含可读内容的字段对读取结果的用户更有用。或者，可以编写将搜索结果中的矢量数据转换为文本的代码。

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "search": (this parameter is ignored in vector search),
    "vectors": [{
        "value": [
            -0.009154141,
            0.018708462,
            . . . 
            -0.02178128,
            -0.00086512347
        ],
        "fields": "contentVector",
        "k": 5
    }],
    "select": "title, content, category"
}

示例：orderby

搜索索引并返回按日期降序排序的结果。

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

示例：使用 OData 表达式进行筛选

检索与特定筛选器表达式匹配的文档：

GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }

示例：分面搜索

在分面搜索中，搜索索引并检索分面中的类别、评级、标记以及特定范围内具有 baseRate 的项。

GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }

请注意，最后一个分面位于子字段上。 Facets 计算父文档 (Hotels) 而不是中间子文档 (会议室) ，因此响应将确定每个价格存储桶中具有任何房间的酒店数量。

示例：缩小分面查询的范围

使用筛选器，在用户选择“评级 3”和类别“Motel”后，缩小上一个分面查询结果的范围。

GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview 
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

示例：具有每个类别限制的分面搜索

在分面搜索中，对查询中返回的唯一字词设置上限。默认值为 10，但你可以对方面特性使用 count 参数来增大或减小此值。此示例返回城市的各个方面，限制为 5。

GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }

示例：字段内搜索

在特定字段 (搜索索引，例如语言字段)

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

跨多个字段搜索索引。例如，可使用多种语言存储和查询可搜索的字段，全都在同一索引内进行。如果英语和法语说明在同一文档中共存，则可以返回查询结果中的任意或全部内容：

GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }

一次只能查询一个索引。除非计划一次查询一个索引，否则不要为每种语言创建多个索引。

示例：分页结果

获取项目的第一页， (页面大小为 10) ：

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

获取页面大小为 10) (项的第二页：

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

示例：限制结果集中的字段

检索特定的字段集：

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

示例：结果中的命中突出显示

搜索索引并返回命中突出显示的片段：

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "highlight": "Description"  
    }

示例：地理空间搜索

搜索索引并返回按距离引用位置从近到远顺序排序的文档：

GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

示例：“由我查找” (提高附近位置的相关性

搜索索引，假设有一个名为“geo”的评分配置文件，其中包含两个距离评分函数，一个定义名为“currentLocation”的参数，一个定义名为“lastLocation”的参数。在以下示例中，“currentLocation”具有单连接号 (-) 分隔符。它后跟经度和纬度坐标，其中经度为负值。

GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }

示例：查询完整索引而不是分片

在索引中查找文档，同时偏向于一致的评分，而不考虑较低的延迟。此查询计算整个索引中的文档频率，并尽最大努力为同一“会话”内的所有查询设定相同的副本 (replica) ，这有助于生成稳定且可重现的排名。

GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }

示例： (featuresMode) 评分统计信息

在索引中查找文档，并返回每个结果的信息检索功能列表，描述匹配文档与查询之间的评分。该查询还会计算整个索引中的文档频率，以生成更一致的评分。

GET /indexes/hotels/docs?search=hotel&featuresMode=enabled&scoringStatistics=global&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "featuresMode": "enabled",
      "scoringStatistics" :"global"
    }

包含 search.features 的响应示例如下所示：

    "@search.score": 0.91875637,
    "@search.features": {
        "Description": {
            "uniqueTokenMatches": 1,
            "similarityScore": 0.2917966,
            "termFrequency": 2
        },
        "HotelName": {
            "uniqueTokenMatches": 1,
            "similarityScore": 0.44458693,
            "termFrequency": 1
        }
      . . .

定义

本部分提供有关main表中过于复杂而无法涵盖的参数的详细信息。

链接	说明
queryLanguage	拼写检查器和语义搜索支持的语言列表。

queryLanguage

下表中的“queryLanguage”列中提供了 queryLanguage 参数的有效值，并且不区分大小写。整个参数的默认值为“en-us”。在每种语言中，每个双字符语言代码都有一个默认变体。例如，如果指定“es”，则默认使用“es-us”。 queryLanguage 参数是包含“queryType=semantic”或“speller=lexicon”的查询请求所必需的。整个请求只有一个 queryLanguage 值，该值将用于语义排名、标题、答案和拼写器， (没有替代单个功能) 。

目前，语言支持因功能而异。完整功能集仅支持英语、西班牙语、法语和德语，但请注意，拼写检查实现的变体较少。

如果指定给定功能不支持的语言代码（例如 EN-GB 和拼写检查器），则服务将返回 HTTP 400。

有关使用每项功能的详细信息，请参阅启用语义排名和标题、返回语义答案和向查询添加拼写检查。

“ (预览版) ”指示所有功能 (语义排名、标题、答案和拼写检查) 的验证测试正在进行或挂起。我们鼓励使用下表中的所有语言变体，但建议对预览语言进行更多测试，以确保结果对你的内容有效。已使用等效数据集验证具有检查标记且没有预览指定的语言，具有可度量的相关性。

语言	queryLanguage	语义排名器和标题	语义答案	拼写
英语 [`en`]	`en, en-US` (默认) 、`en-GB`、`en-IN`、 `en-CAen-AU`	✔️	✔️	✔️ (`en, en-US`)
法语 [`fr`]	`fr`， `fr-FR` (默认) ， `fr-CA`	✔️	✔️	✔️ (`fr, fr-FR`)
德语 [`de`]	`de, de-DE`（默认值）	✔️	✔️	✔️ (`de, de-DE`)
西班牙语 [`es`]	`es, es-ES`（默认）、`es-MX`	✔️	✔️	✔️ (`es, es-ES`)
意大利语 [`it`]	`it, it-IT`（默认值）	✔️	✔️
日语 [`ja`]	`ja, ja-JP`（默认值）	✔️	✔️ (预览版)
中文 [`zh`]	`zh, zh-CN`（默认）、`zh-TW`	✔️	✔️ (预览版)
葡萄牙语 [`pt`]	`pt, pt-BR`（默认）、`pt-PT`	✔️	✔️ (预览版)
荷兰语 [`nl`]	`nl, nl-BE, nl-NL`（默认值）	✔️ (预览)	✔️ (预览)	✔️ `nl, nl-NL` ()
阿拉伯语 [`ar`]	`ar, ar-SA`（默认）、`ar-EG, ar-MA, ar-KW, ar-JO`	✔️ (预览)	✔️ (预览)
亚美尼亚语	`hy-AM`（默认值）	✔️ (预览)	✔️ (预览)
Bangla	`bn-IN`（默认值）	✔️ (预览)	✔️ (预览)
巴斯克语	`eu-ES`（默认值）	✔️ (预览)	✔️ (预览)
保加利亚语 [`bg`]	`bg, bg-BG`（默认值）	✔️ (预览)	✔️ (预览)
加泰罗尼亚语 [`ca`]	`ca, ca-ES`（默认值）	✔️ (预览)	✔️ (预览)
克罗地亚 [`hr`]	`hr, hr-HR` (默认) hr-BA	✔️ (预览)	✔️ (预览)
捷克语 [`cs`]	`cs, cs-CZ`（默认值）	✔️ (预览)	✔️ (预览)
丹麦语 [`da`]	`da, da-DK`（默认值）	✔️ (预览)	✔️ (预览)
爱沙尼亚语 [`et`]	`et, et-EE`（默认值）	✔️ (预览)	✔️ (预览)
芬兰语 [`fi`]	`fi, fi-FI`（默认值）	✔️ (预览)	✔️ (预览)
加利西亚语	`gl-ES`（默认值）	✔️ (预览)	✔️ (预览)
希腊文 [`el`]	`el, el-GR`（默认值）	✔️ (预览)	✔️ (预览)
古吉拉特语	`gu-IN`（默认值）	✔️ (预览)	✔️ (预览)
希伯来语	`he-IL`（默认值）	✔️ (预览)	✔️ (预览)
印地语 [`hi`]	`hi, hi-IN`（默认值）	✔️ (预览)	✔️ (预览)
匈牙利语 [`hu`]	`hu, hu-HU`（默认值）	✔️ (预览)	✔️ (预览)
冰岛语 [`is`]	`is, is-IS`（默认值）	✔️ (预览)	✔️ (预览)
印度尼西亚语 [`id`]	`id, id-ID`（默认值）	✔️ (预览)	✔️ (预览)
爱尔兰语	`ga-IE`（默认值）	✔️ (预览)	✔️ (预览)
卡纳达语	`kn-IN`（默认值）	✔️ (预览)	✔️ (预览)
朝鲜语 [`ko`]	`ko, ko-KR`（默认值）	✔️ (预览)	✔️ (预览)
拉脱维亚语 [`lv`]	`lv, lv-LV`（默认值）	✔️ (预览)	✔️ (预览)
立陶宛语 [`lt`]	`lt, lt-LT`（默认值）	✔️ (预览)	✔️ (预览)
马拉雅拉姆语	`ml-IN`（默认值）	✔️ (预览版)	✔️ (预览版)
马来西亚语 [`ms`]	`ms, ms-MY`（默认）、`ms-BN`	✔️ (预览版)	✔️ (预览版)
马拉地语	`mr-IN`（默认值）	✔️ (预览版)	✔️ (预览版)
挪威语 [`no`]	否、no-NO (默认) 、nb-NO	✔️ (预览版)	✔️ (预览版)
波斯语	`fa-AE`（默认值）	✔️ (预览版)	✔️ (预览版)
波兰语 [`pl`]	`pl, pl-PL`（默认值）	✔️ (预览版)	✔️ (预览版)
旁遮普语	`pa-IN`（默认值）	✔️ (预览版)	✔️ (预览版)
罗马尼亚语 [`ro`]	`ro, ro-RO`（默认值）	✔️ (预览版)	✔️ (预览版)
俄语 [`ru`]	`ru, ru-RU`（默认值）	✔️ (预览版)	✔️ (预览版)
塞尔维亚语 [`sr`] (西里尔文或拉丁文)	`sr, sr-BA`（默认）、`sr-ME, sr-RS`	✔️ (预览版)	✔️ (预览版)
斯洛伐克语 [`sk`]	`sk, sk-SK`（默认值）	✔️ (预览版)	✔️ (预览版)
斯洛文尼亚语 [`sl`]	`sl, sl-SL`（默认值）	✔️ (预览版)	✔️ (预览版)
泰米尔语 [`ta`]	`ta, ta-IN`（默认值）	✔️ (预览版)	✔️ (预览版)
瑞典语 [`sv`]	`sv, sv-SE`（默认值）	✔️ (预览版)	✔️ (预览版)
泰卢固语	`te-IN`（默认值）	✔️ (预览版)	✔️ (预览版)
泰语 [`th`]	`th, th-TH`（默认值）	✔️ (预览版)	✔️ (预览版)
土耳其语 [`tr`]	`tr, tr-TR`（默认值）	✔️ (预览版)	✔️ (预览版)
乌克兰语 [`uk`]	`uk, uk-UA`（默认值）	✔️ (预览版)	✔️ (预览版)
乌尔都语	`ur-PK`（默认值）	✔️ (预览版)	✔️ (预览版)
越南语 [`va`]	`va, vi-VN`（默认值）	✔️ (预览版)	✔️ (预览版)