你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
搜索文档（预览版 REST API）
适用于：2023-07-01-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” 所取代，现已过时。
- “拼写器” 启用查询输入的拼写更正。
- “queryLanguage” 是“queryType=semantic”和“speller”所必需的。
- “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，请将“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 AI 搜索
URI 参数
| 参数 | 描述 |
|---|---|
| 服务名称 | 必填。 将此名称设置为搜索服务的唯一用户定义的名称。 |
| 索引名称/文档 | 必填。 指定命名索引的文档集合。 还可以使用 索引别名的名称 代替索引名称。 |
| 查询参数 | 查询参数在 GET 请求的 URI 和 POST 请求的请求正文中指定。 |
| api-version | 必填。 有关更多版本，请参阅 API 版本。 |
URL 编码建议
请务必在直接调用 GET REST API 时 URL 编码 特定的查询参数。 对于 搜索文档 操作，以下查询参数可能需要 URL 编码：
- 搜索
- $filter
- 方面
- 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 搜索。 |
请求正文
对于 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。 可以使用这些批注的值来构建另一个搜索请求，以获取搜索响应的下一部分。 此行为称为原始搜索请求的 延续，注释称为 延续标记。 请参阅“响应”部分中的示例，详细了解这些批注的语法及其在响应正文中的显示位置。
Azure AI 搜索可能返回延续令牌的原因特定于实现，可能会更改。 可靠客户端应始终准备好处理返回的文档少于预期且包含继续标记以继续检索文档的情况。 另请注意，必须使用与原始请求相同的 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”返回三个答案。 若要返回答案，目标字段中必须存在类似于答案的逐字内容。 用于答案的语言模型经过训练以识别答案，而不是生成答案。 此外，查询本身必须看起来像一个问题。 |
| api-version | 字符串 | 必填。 用于请求的 REST API 的版本。 有关受支持的版本列表，请参阅 API 版本。 对于此操作，无论使用 GET 还是 POST 调用 搜索文档，API 版本都指定为 URI 参数。 |
| 标题（预览版） | 字符串 | 自选。 有效值为“none”和“extractive”。 默认值为“none”。 仅当查询类型为“semantic”时，此参数才有效。 设置为“提取”时，查询将返回从排名最高的文档中的关键段落中提取的标题。 当标题设置为“提取”时，默认情况下会启用突出显示，并且可以通过追加管道字符“|”，然后追加“highlight-<true/false>”选项（例如“extractive|highlight-true”）来配置突出显示。 |
| $count | 布尔 | 自选。 有效值为“true”或“false”。 默认值为“false”。 使用 POST 调用时，此参数将命名计数而不是$count。 指定是否提取结果总数。 此值是与搜索和$filter参数匹配的所有文档的计数，忽略$top和$skip。 将此值设置为“true”可能会降低性能。 如果索引稳定，但会在主动添加、更新或删除的任何文档下或过度报告，则计数是准确的。 如果只想获取不包含任何文档的计数，可以使用 $top=0。 |
| facet 或 facet | 字符串 | 自选。 要分面的字段，其中字段被归为“可分面”。 使用 GET 调用时，facet 是字段（facet: field1）。 使用 POST 调用时，此参数命名为 facets 而不是 facet，并指定为数组（facets: [field1, field2, field3]）。 字符串可能包含用于自定义分面的参数，以逗号分隔的名称/值对表示。
有效值为“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”按每个城市名称的文档数降序获取分面结果中的前三个类别）。 如果前三类是预算、汽车旅馆和豪华，预算有五个命中数，汽车旅馆有六个，而豪华有四个，那么桶按“汽车旅馆”、“预算”、“豪华”的顺序排列。 对于 -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 AI 搜索支持的 OData 表达式语法子集的详细信息，请参阅 Azure AI 搜索的 OData 表达式语法。 |
| 高亮 | 字符串 | 自选。 用于命中突出显示的一组逗号分隔字段名称。 只能使用可搜索字段进行命中突出显示。 默认情况下，Azure AI 搜索返回每个字段最多五个突出显示。 限制通过追加字段名称后追加“-<最大突出显示>”来配置每个字段。 例如，“highlight=title-3，description-10”最多从标题字段中返回三个突出显示的命中，以及描述字段中最多 10 次命中。 最大突出显示数必须是介于 1 和 1000（含 1000）之间的整数。 |
| highlightPostTag | 字符串 | 自选。 默认为 "</em>"。 追加到突出显示的术语的字符串标记。 必须使用 highlightPreTag 进行设置。 URL 中的保留字符必须进行百分比编码（例如，%23 而不是 #）。 |
| highlightPreTag | 字符串 | 自选。 默认为 "</em>"。 在突出显示的术语前面追加的字符串标记。 必须使用 highlightPostTag 进行设置。 URL 中的保留字符必须进行百分比编码（例如，%23 而不是 #）。 |
| minimumCoverage | 整数 | 自选。 有效值为介于 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 （预览版） | 字符串 | 自选。 有效值为支持的语言 |
| queryType | 字符串 | 自选。 有效值为“simple”、“full”或“semantic”（预览）。 默认值为“simple”。 对于矢量搜索，此值将被忽略，但适用于混合方案中的文本搜索。
“简单”使用 简单的查询语法 来解释查询字符串，这些语法允许符号，如 +、*和 ""。 默认情况下，每个文档中所有可搜索字段（或 searchFields 中指示的字段）都会评估查询。
“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 AI 搜索中的 |
| 搜索 | 字符串 | 自选。 要搜索的文本。 对于矢量搜索，此值将被忽略，但适用于混合方案中的文本搜索。 在 REST API 中，除非指定 searchFields，否则默认搜索所有可搜索字段。 在索引中，可搜索字段中的文本被标记化，因此多个字词可以通过空格分隔（例如：“search=hello world”）。 若要匹配任何术语，请使用 *（这对于布尔筛选器查询非常有用）。 省略此参数的效果与将此参数设置为 *的效果相同。 有关搜索语法的详细信息，请参阅 简单查询语法。
查询可搜索字段时，结果有时可能出人意料。 tokenizer 包括用于处理英语文本常见的事例（如撇号、数字中的逗号等）的逻辑。 例如，“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 有助于提高具有多个副本的搜索服务的相关性分数一致性。 在多副本配置中，对于同一查询，单个文档的相关性分数之间可能会略有差异。 提供会话 ID 时，该服务尽力将给定请求路由到该会话的同一副本。 谨慎地重复使用同一会话 ID 值可能会干扰跨副本的请求负载均衡，并对搜索服务的性能产生不利影响。 用作 sessionId 的值不能以“_”字符开头。 如果服务没有任何副本，则此参数不会影响性能或分数一致性。 |
| $skip | 整数 | 自选。 要跳过的搜索结果数。 使用 POST 调用时，此参数命名为 skip，而不是$skip。 此值不能大于 100,000。 如果需要按顺序扫描文档，但由于此限制而无法使用$skip，请考虑对索引中每个文档具有唯一值的字段使用$orderby（例如，文档键），并改为使用范围查询$filter。 |
| 拼写检查器（预览版） | 字符串 | 自选。 有效值为“none”和“lexicon”。 默认值为“none”。 通过拼写更正单个搜索查询词来提高召回率。 可以在简单、完整和语义查询类型上使用它。 如果使用，拼写检查器参数需要 queryLanguage。 有关详细信息和示例，请参阅 向查询添加拼写检查。 |
| $top | 整数 | 自选。 要检索的搜索结果数。 这默认为 50。 使用 POST 调用时，此参数将命名为顶部，而不是$top。 如果指定的值大于 1000 且结果数超过 1000 个，则只返回前 1000 个结果，以及指向下一页结果的链接（请参阅以下示例中的“@odata.nextLink”。
Azure AI 搜索使用 服务器端分页 来防止查询一次检索过多的文档。 默认页面大小为 50，而最大页面大小为 1000。 这意味着，默认情况下，如果未指定$top，搜索文档 最多返回 50 个结果。 如果结果超过 50 个，响应将包含检索最多 50 个结果的下一页的信息（请参阅以下 示例中的“@odata.nextLink”和“@search.nextPageParameters”。 同样，如果为$top指定大于 1000 的值并且结果超过 1000 个，则只返回前 1000 个结果，以及检索最多 1000 个结果的下一页的信息。 |
| vectors （预览版） | 数组 | 自选。 数组中的对象类型是矢量查询。 矢量查询的查询参数。
“value”是搜索查询的矢量表示形式。 必须在外部形成此表示形式。 Azure AI 搜索不会创建嵌入内容。 “k”是一个整数，用于指定要作为热门命中返回的最近的邻居数。 默认值为 50。 最小值为 1，最大值为 10,000。 “fields”是一个逗号分隔的列表字段名称，其中包含矢量数据。 只有 Collection(Edm.Single) 类型的字段才能包含在“fields”列表中。 |
响应
状态代码：为成功的响应返回 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 搜索的
示例：简单搜索
使用简单的查询语法在索引中查找文档。 此查询返回可搜索字段包含术语“舒适”和“位置”但不包含“汽车旅馆”的酒店：
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 搜索中的
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" ]
}
请注意，最后一个分面位于子字段上。 分面将计算父文档（Hotels）而不是中间子文档（会议室），因此响应将确定每个价格存储桶中具有任何房间的酒店数。
示例：缩小分面查询
使用筛选器，在用户选择“Rating 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，但可以使用 facet 属性上的 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" ]
}
示例：查询完整索引而不是分片
在索引中查找文档，同时倾向于在较低的延迟上获得一致的评分。 此查询计算整个索引中的文档频率，并尽最大努力为同一“会话”中的所有查询设定相同的副本，这有助于生成稳定且可重现的排名。
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 （默认值） |
✔️ （预览版） | ✔️ （预览版） | |
| 孟加拉语 |
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-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 （默认值） |
✔️ （预览版） | ✔️ （预览版） |
另请参阅
- 在 Azure AI 搜索 中创建查询
- Azure AI 搜索 中的
查询 - Azure AI 搜索 全文搜索的工作原理
- Azure 搜索 的
OData 表达式语法 - Azure AI 搜索 中的简单查询语法