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

搜索文档 (预览版 REST API)

API 版本:2021-04-30-Preview、2020-06-30-Preview

重要

2021-04-30-Preview 添加:

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

2020-06-30-Preview 添加:

  • “queryType=semantic” 支持语义重新排序和响应。
  • “拼写检查器” 对查询输入启用拼写更正。
  • “queryType=semantic”和“speller”都需要“queryLanguage”。
  • “featuresMode” 解包搜索分数,报告每字段术语频率、每字段相似性分数和每字段唯一匹配项数。

查询请求针对搜索服务上的单个索引的文档集合。 它包括定义匹配条件的参数,以及用于调整响应的参数。 还可以使用 索引别名 来定位特定索引,而不是使用索引名称本身。

可以使用 GET 或 POST。 查询参数在 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,请将“search”操作添加为 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 认知搜索的 OData 表达式语法

URI 参数

参数 说明
[服务名称] 必需。 将此名称设置为搜索服务的唯一用户定义的名称。
[索引名称]/docs 必需。 指定命名索引的文档集合。 还可以使用 索引别名 的名称代替索引名称。
[查询参数] 查询参数在 GET 请求的 URI 和 POST 请求的请求正文中指定。
api-version 必需。 当前版本为 api-version=2021-04-30-Preview。 有关更多版本,请参阅 API 版本

URL 编码建议

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

  • search
  • $filter
  • facet
  • highlightPreTag
  • highlightPostTag

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

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

请求标头

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

字段 说明
Content-Type 必需。 将此设置为“application/json”
api-key 必需。 一个唯一的系统生成的字符串,用于对搜索服务的请求进行身份验证。 针对文档集合的查询请求可以将管理密钥或查询密钥指定为 API 密钥。 查询键用于对文档集合执行只读操作。 可以在Azure 门户的搜索服务仪表板中找到 API 密钥

请求正文

对于 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": #  
   }  

部分搜索响应的延续

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

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

注意

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

查询参数

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

名称 类型 说明
(预览版) 的解答 字符串 可选。 有效值为“none”和“extractive”。 默认值为“none”。 仅当查询类型为“semantic”时,此参数才有效。 当设置为“提取”时,查询会从语义排名最高的文档中的关键段落中生成并返回答案。 默认值为一个答案,但可以通过添加计数最多指定 10 个答案。 例如,“answers”:“extractive|count-3”返回三个答案。 若要返回答案,searchFields 中必须有足够的信息来制定一个答案。 此外,查询本身必须类似于问题。 关键字搜索不会返回答案。
api-version 字符串 必需。 用于请求的 REST API 的版本。 有关受支持的版本列表,请参阅 API 版本。 对于此操作,无论使用 GET 还是 POST 调用 搜索文档 ,API 版本都指定为 URI 参数。
(预览版) 的标题 字符串 可选。 有效值为“none”和“extractive”。 默认值为“none”。 仅当查询类型为“semantic”时,此参数才有效。 当设置为“extractive”时,查询将返回从排名最高的文档中的关键段落中提取的标题。 当标题设置为“提取”时,默认情况下会启用突出显示,并且可以通过追加管道字符“|”,后跟“highlight-true</false>”选项(如“extractive|highlight-true”)进行配置。
$count 布尔值 可选。 有效值为“true”或“false”。 默认值为“false”。 使用 POST 调用时,此参数将命名计数而不是$count。 指定是否要获取结果的总计数。 这是与搜索和$filter参数匹配的所有文档的计数,忽略$top和$skip。 将此值设置为“true”可能会降低性能。 如果索引稳定,但会根据或过度报告主动添加、更新或删除的任何文档,则计数是准确的。 如果只想获取不包含任何文档的计数,可以使用 $top=0。
facet 字符串 可选。 要分面的字段。 字符串可能包含用于自定义分面的参数,以逗号分隔的名称:值对表示。 使用 POST 调用时,此参数将命名为 facet 而不是 facet。

有效为“count”、“sort”、“values”、“interval”和“timeoffset”。

“count”是分面词的最大数目;默认值为 10。 术语数没有上限,但较高的值会降低性能,尤其是在分面字段包含大量唯一术语时。 例如,“facet=category,count:5”获取分面结果中的前五个类别。 如果 count 参数小于唯一术语的数目,则结果可能不准确。 这由分面查询分布在各个分片上的方式所导致。 可以将计数设置为零或设置为大于或等于可分面字段中唯一值数的值,以获取所有分片的准确计数。 权衡会增加延迟。

“sort”可设置为“count”、“-count”、“value”、“-value”。 使用计数按计数进行降序排序。 使用 -count 按计数对升序排序。 使用值按值对升序排序。 使用 -value 按值降序排序 (例如,“facet=category,count:3,sort:count”按每个城市名称的文档数降序) 分面结果中的前三个类别。 如果前三个类别是预算、汽车旅馆和奢侈品,并且预算命中 5 次、汽车旅馆命中 6 次、奢侈品命中 4 次,则存储桶的顺序将为汽车旅馆、预算、奢侈品。 对于 -value,“facet=rating,sort:-value”会根据 (值按值降序生成所有可能的分级的存储桶,例如,如果分级从 1 到 5,则无论每个分级) 有多少文档匹配,存储桶将排序为 5、4、3、2、1。

“values”可设置为管道分隔的数值或 Edm.DateTimeOffset 值,指定一组动态分面条目值 (,例如“facet=baseRate,values:10 |20 英寸生成三个存储桶:一个用于基速率 0,但不包括 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 参数必须与间隔选项相结合,并且仅当应用于 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”。 一个值,该值指定结果是否应包括 查询结果功能,用于计算与查询相关的文档相关性分数,例如每个字段相似性。 使用“已启用”来公开更多查询结果功能:每个字段相似性分数、每个字段术语频率以及匹配的每个字段数的唯一标记数。 有关详细信息,请参阅 相似性和评分
$filter 字符串 可选。 使用标准 OData 语法的结构化搜索表达式。 只能在筛选器中使用可筛选字段。 使用 POST 调用时,此参数命名为筛选器,而不是$filter。 有关Azure 认知搜索支持的 OData 表达式语法子集的详细信息,请参阅Azure 认知搜索的 OData 表达式语法。
highlight 字符串 可选。 用于命中突出显示的逗号分隔的字段名称集。 只能使用可搜索字段进行点击突出显示。 默认情况下,Azure 认知搜索最多为每个字段返回五处突出显示。 限制可通过在字段名称后面追加“-<max# 突出显示>”来配置每个字段。 例如,“highlight=title-3,description-10”最多从标题字段返回三个突出显示的命中,以及描述字段中最多 10 次命中。 最大突出显示数必须是介于 1 和 1000 之间的整数(包括 1 到 1000)。
highlightPostTag 字符串 可选。 默认为 "</em>"。 追加到突出显示的术语的字符串标记。 必须使用 highlightPreTag 进行设置。 URL 中的保留字符必须采用百分比编码形式(例如,使用 %23 而不是 #)。
highlightPreTag 字符串 可选。 默认为 "</em>"。 一个字符串标记,该标记前面追加到突出显示的术语。 必须使用 highlightPostTag 进行设置。 URL 中的保留字符必须采用百分比编码形式(例如,使用 %23 而不是 #)。
minimumCoverage integer 可选。 有效值为介于 0 和 100 之间的数字,指示索引的百分比必须可用于为查询提供服务,然后才能将其报告为成功。 默认值为“100”。

百分之百的覆盖率意味着所有分片都响应了请求, (服务运行状况问题和维护活动都减少了覆盖) 。 在默认设置下,小于完全覆盖将返回 HTTP 状态代码 503。

如果发生 503 个错误并想要增加查询成功的可能性,尤其是针对针对一个副本配置的服务,则降低 minimumCoverage 可能很有用。 如果设置 minimumCoverage 和 Search 成功,它将返回 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”使用允许符号(例如+*"")的简单查询语法解释查询字符串。 默认情况下,查询在所有可搜索字段 (或搜索字段) 中指示的所有可搜索字段进行评估。

“full”使用 完整的 Lucene 查询语法解释查询 字符串,该语法允许字段特定的搜索和加权搜索。 不支持 Lucene 查询语言中的范围搜索,支持提供类似功能的$filter。

语义式“通过使用在必应语料库上训练的排名模型(以自然语言表示的查询而不是关键字)重新计算前 50 个匹配项来提高搜索结果的精度。 如果将查询类型设置为语义,还必须设置 queryLanguage 和 semanticConfiguration。 如果要还返回前 3 个答案,可以选择设置答案,前提是查询输入采用自然语言 (“什么是...) ,可以选择设置标题,以从排名最高的文档中提取关键段落。
scoringParameter 字符串 可选。 指示评分函数中定义的每个参数的值 (,例如 referencePointParameter) 使用格式“name-value1,value2,...”使用 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 认知搜索中的评分统计信息。 对于使用 模糊搜索 ('~') 的术语,将始终在本地计算计分统计信息。
search 字符串 可选。 要搜索的文本。 默认情况下,除非指定 searchFields,否则所有可搜索字段均处于搜索状态。 在索引中,可搜索字段中的文本进行标记化,因此多个字词可以通过空格分隔 (,例如:“search=hello world”) 。 若要匹配任何字词,请使用 *(这对布尔筛选器查询可能很有用)。 忽略此参数与将其设置为 * 具有相同的效果。 有关搜索语法的详细信息,请参阅 简单查询语法

查询可搜索字段时,结果有时可能出人意料。 标记器包含用于处理英语文本中常见情况(如撇号、数字中的逗号等)的逻辑。 例如,“search=123,456”将匹配单个字词“123,456”,而不是单个术语“123”和“456”,因为逗号用作英文大数的千分隔符。 因此,我们建议使用空格而不是标点符号来分隔搜索参数中的字词。
searchMode 字符串 可选。 有效值为“any”或“all”,默认值为“any”。 指定要将文档算作匹配项,是必须匹配任一搜索词还是必须匹配所有搜索词。
searchFields 字符串 可选。 要对指定文本搜索的逗号分隔的字段名称列表。 目标字段必须在索引架构中标记为可搜索。
$select 字符串 可选。 要包含在结果集中的逗号分隔字段的列表。 只有标记为可检索的字段才能包含在此子句中。 如果未指定或设置为 *,会在投影中包含架构中标记为可检索的所有字段。 使用 POST 调用时,此参数命名为 select 而不是$select。
semanticConfiguration (预览版) 字符串 可选。 如果 queryType=“semantic”,则是必需的。 语义配置的名称,其中列出了哪些字段应用于语义排名、标题、突出显示和答案。 有关详细信息,请参阅 创建语义查询
sessionID 字符串 可选。 使用 sessionId 有助于提高具有多个副本的搜索服务的相关性分数一致性。 在多副本配置中,对于同一查询,单个文档的相关性分数之间可能略有差异。 提供会话 ID 后,该服务将尽最大努力将给定请求路由到该会话的同一副本。 谨慎地重复使用同一会话 ID 值可能会干扰跨副本的请求负载均衡,并严重影响搜索服务的性能。 用作 sessionId 的值不能以“_”字符开头。 如果服务没有任何副本,则此参数不会影响性能或评分一致性。
$skip integer 可选。 要跳过的搜索结果数。 使用 POST 调用时,此参数将命名为 skip,而不是$skip。 此值不能大于 100,000。 如果需要按顺序扫描文档,但由于此限制而无法使用$skip,请考虑对 (索引中的每个文档具有唯一值的字段使用$orderby,例如,使用范围查询) 和$filter。
拼写检查器 (预览版) 字符串 可选。 有效值为“none”和“lexicon”。 默认值为“none”。 通过拼写更正单个搜索查询词来提高召回率。 可以在简单、完整和语义查询类型上使用它。 如果使用,拼写检查器参数需要 queryLanguage。 有关详细信息和示例,请参阅 向查询添加拼写检查
$top integer 可选。 要检索的搜索结果数。 这默认为 50。 使用 POST 调用时,此参数将命名为 top 而不是 $top。 如果指定的值大于 1000 且结果超过 1000 个,则只返回前 1000 个结果,以及指向下一页结果的链接, (以下示例中的“@odata.nextLink”) 。

Azure 认知搜索使用服务器端分页来防止查询一次检索过多的文档。 默认页面大小为 50,最大页面大小为 1000。 这意味着,如果未指定$top,则搜索 文档 最多返回 50 个结果。 如果结果超过 50 个,响应包含检索最多 50 个结果的下一页的信息, (请参阅以下示例中的 “@odata.nextLink”和“@search.nextPageParameters”。 同样,如果为$top指定大于 1000 的值并且结果超过 1000 个,则只返回前 1000 个结果,以及检索最多 1000 个结果的下一页的信息。

响应

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

语义查询的示例响应

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

  • “@search.answers”在指定答案参数时出现,当查询和基础 searchFields 有利于生成答案时。 @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 认知搜索 的 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 认知搜索) 中的 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"
}

示例: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" ]  
    }  

请注意,最后一个分面位于子字段上。 分面统计父文档 (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”的参数,于是搜索索引:

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" ]  
    }  

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

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

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
        }
      . . .

定义

本部分提供有关参数的详细信息,这些参数过于复杂,无法涵盖在主表中。

链接 说明
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-CA、en-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 (默认) ✔️ (预览版) ✔️ (预览版)
印度尼西亚语 [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 (默认) ✔️ (预览版) ✔️ (预览版)
乌尔都语 your-PK (默认) ✔️ (预览版) ✔️ (预览版)
越南语 [va] va、vi-VN (默认) ✔️ (预览版) ✔️ (预览版)

请参阅