您现在访问的是微软AZURE全睃版技术文档网站,若需覝访问由世纪互蝔违蝥的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

(Azure 认知搜索 REST API 创建索引)

索引是在 Azure 认知搜索中组织和搜索文档的主要方式,类似于表在数据库中组织记录的方式。 每个索引都具有一组文档,这些文档都符合索引架构 (字段名称、数据类型和属性) ,但索引还指定其他构造 (建议器、计分配置文件和 CORS 配置) 定义其他搜索行为。

可以在请求中使用 POST 或 PUT。 对于这两个文件,请求正文中的 JSON 文档提供对象定义。

POST https://[servicename].search.windows.net/indexes?api-version=[api-version]  
  Content-Type: application/json
  api-key: [admin key]  

此外,可使用 PUT 并在 URI 上指定索引名称。

PUT https://[servicename].search.windows.net/indexes/[index name]?api-version=[api-version]
  Content-Type: application/json
  api-key: [admin key]

所有服务请求都需要 HTTPS。 如果索引不存在,将创建它。 如果已经存在,则将其更新为新定义。

创建索引会建立架构和元数据。 填充索引是单独的操作。 对于此步骤,可以使用索引器 (参阅 索引器操作,) 或 添加、更新或删除文档可用于受支持的数据源。 在发布文档时,将生成倒排索引。

备注

可以创建的最大索引数目根据定价层的不同而异。 有关详细信息,请参阅服务限制

URI 参数

参数 说明
服务名称 必需。 将此项设置为搜索服务的用户定义的唯一名称。
索引名称 如果使用 PUT,则对 URI 是必需的。 名称必须为小写,以字母或数字开头,不包含斜杠或点,并且少于128个字符。 在以字母或数字开头后,名称的其余部分可以包含任何字母、数字和短划线,前提是短划线不是连续的。
api-version 必需。 当前稳定版本是 api-version=2020-06-30 。 有关更多版本,请参阅 API 版本

请求标头

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

字段 说明
Content-Type 必需。 将其设置为 application/json
api-key 必需。 api-key 用于对搜索服务的请求进行身份验证。 它是一个字符串值,对于服务是唯一的。 创建请求必须包含 api-key 设置为管理密钥 (的标头,而不是查询键) 。 可以在 "搜索服务" 仪表板中的 "Azure 门户" 中 找到 API 密钥

请求正文

请求正文包含架构定义,而架构定义包含了送入此索引的文档中的数据字段列表。

以下 JSON 是定义主要部分的高级表示形式。

{  
  "name": (optional on PUT; required on POST) "Name of the index",  
  "fields": [  
    {  
      "name": "name_of_field",  
      "type": "Edm.String | Edm.Int32 | Edm.Int64 | Edm.Double | Edm.Boolean | Edm.DateTimeOffset | Edm.GeographyPoint | Edm.ComplexType | Collection(Edm.String) | Collection(Edm.Int32) | Collection(Edm.Int64) | Collection(Edm.Double) | Collection(Edm.Boolean) | Collection(Edm.DateTimeOffset) | Collection(Edm.GeographyPoint) | Collection(Edm.ComplexType)",  
      "searchable": true (default where applicable) | false (only Edm.String and Collection(Edm.String) fields can be searchable),  
      "filterable": true (default) | false,  
      "sortable": true (default where applicable) | false (Collection(Edm.String) fields cannot be sortable),  
      "facetable": true (default where applicable) | false (Edm.GeographyPoint fields cannot be facetable),  
      "key": true | false (default, only Edm.String fields can be keys, enable on one field only),  
      "retrievable": true (default) | false,  
      "analyzer": "name_of_analyzer_for_search_and_indexing", (only if 'searchAnalyzer' and 'indexAnalyzer' are not set)
      "searchAnalyzer": "name_of_search_analyzer", (only if 'indexAnalyzer' is set and 'analyzer' is not set)
      "indexAnalyzer": "name_of_indexing_analyzer", (only if 'searchAnalyzer' is set and 'analyzer' is not set)
      "synonymMaps": [ "name_of_synonym_map" ] (optional, only one synonym map per field is currently supported),
      "fields" : [ ... ] (optional, a list of sub-fields if this is a field of type Edm.ComplexType or Collection(Edm.ComplexType). Must be null or empty for simple fields.)
    }
  "similarity": (optional) { },
  "suggesters": (optional) [ ... ],  
  "scoringProfiles": (optional) [ ... ],  
  "analyzers":(optional) [ ... ],
  "charFilters":(optional) [ ... ],
  "tokenizers":(optional) [ ... ],
  "tokenFilters":(optional) [ ... ],
  "defaultScoringProfile": (optional) "Name of a custom scoring profile to use as the default",  
  "corsOptions": (optional) { },
  "encryptionKey":(optional) { }  
}  

请求包含以下属性:

属性 说明
name 必需。 索引的名称。 索引名称只能包含小写字母、数字或短划线,不能以短划线开头或结尾,且不能超过128个字符。
description 可选说明。
字段 必需。 将向此索引中添加一个字段的集合,包括名称、数据类型和定义该字段允许的操作的特性。 数据类型符合 (EDM) 实体数据模型。 有关详细信息,请参阅 支持的数据类型。 集合中必须有一个指定为 字段的字段。 它必须是字符串字段。 此字段表示存储在索引中的每个文档的唯一标识符,有时称为文档 ID。 文档键区分大小写。 例如,带有密钥 "abc" 的文档被视为不同于带有密钥 "ABC" 的文档。
similarity 可选。 对于2020年7月15日之前创建的服务,请将此属性设置为使用 BM25 排名算法。 有效值包括 "#Microsoft.Azure.Search.ClassicSimilarity""#Microsoft.Azure.Search.BM25Similarity"。 支持此属性的 API 版本包括2020-06-30 和 2019-05-06-Preview。 有关详细信息,请参阅 Azure 认知搜索中的排名算法
建议器 可选。 用于自动完成查询或建议的搜索结果,每个索引一个。 它是一种数据结构,用于存储部分查询(如自动完成和建议)的匹配的前缀。 包含一个 name 和建议器感知字段,这些字段提供自动完成查询和建议结果的内容。 searchMode 是必需的,并且始终设置为 analyzingInfixMatching 。 它指定匹配将对查询字符串中的任何字词进行。
scoringProfiles 可选。 用于自定义搜索评分排名。 设置 defaultScoringProfile 为使用自定义配置文件作为默认配置文件,只要未在查询字符串中指定自定义配置文件,就会调用该配置文件。 有关元素的详细信息,请参阅 将计分配置文件添加到搜索索引 和下一部分中的示例。
分析器、charFilters、tokenizer、tokenFilters 可选。 如果要定义 自定义分析器,请指定索引的这些部分。 默认情况下,这些部分为空。
defaultScoringProfile 可选。 用于覆盖默认评分行为的自定义计分配置文件的名称。
corsOptions 可选。 默认情况下,客户端 JavaScript 无法调用任何 API,因为浏览器将阻止所有跨域请求。 若要允许对索引进行跨域查询,请通过设置 corsOptions 来启用 CORS(跨域资源共享)。 出于安全原因,只有查询 API 才支持 CORS。 corsOptions部分包括:

allowedOrigins (必需) 将被授予对索引的访问权限的以逗号分隔的源列表,其中每个源的格式通常为 protocol:// <fully-qualified-domain-name> : <port> (,不过 <port> 通常会忽略) 。 也就是说,从这些来源提供的任何 JavaScript 代码将有权查询你的索引(假设代码可以提供正确的 api-key)。 若要允许访问所有源,请将指定 * 为数组中的单个项 allowedOrigins 。 不建议在生产环境中使用此方法,但可能对开发或调试很有用。

maxAgeInSeconds (可选) 浏览器使用此值来确定缓存 CORS 预检响应的持续 (时间(以秒为) 单位)。 此值必须是非负整数。 此值越大,性能越好,但 CORS 策略更改生效所需的时间也越长。 如果未设置此值,将使用 5 分钟的默认持续时间。
encryptionKey 可选。 用于使用你自己的密钥加密同义词映射,并在 Azure Key Vault 中进行管理。 可用于在2019-01-01 或之后创建的可计费搜索服务。

encryptionKey部分包含所需的用户定义 keyVaultKeyName () 、系统生成的 keyVaultKeyVersion (必需) ,以及 keyVaultUri 提供所需的密钥 ((也称为 DNS 名称) )。 示例 URI 可能为 " https://my-keyvault-name.vault.azure.net "。

还可以指定是否 accessCredentials 使用托管系统标识。 的属性 accessCredentials 包括 applicationId (Azure Active Directory 应用程序 ID 授予对指定的 Azure Key Vault) 的访问权限,以及 (applicationSecret 指定的 Azure AD 应用程序) 的身份验证密钥。 下一节中的示例说明了语法。

字段定义

创建索引时,可以对字段设置以下属性。

Attribute 说明
name 必需。 设置字段的名称,该名称在索引或父字段的字段集合中必须是唯一的。
类型 必需。 设置字段的数据类型。 字段可以很简单,也可以是复杂的。 简单字段为基元类型, Edm.String 例如文本或 Edm.Int32 整数。 复杂字段 可以具有自身简单或复杂的子字段。 这使您可以对对象和对象数组进行建模,从而使您可以将大多数 JSON 对象结构上传到索引。 有关支持的类型的完整列表,请参阅 Azure 认知搜索)(支持的数据类型
key 必需。 将此特性设置为 true 可指定字段的值唯一标识索引中的文档。 键字段中的值的最大长度为1024个字符。 必须恰好选择每个索引中的一个顶级字段作为键字段,并且该字段的类型必须为 Edm.Stringfalse对于简单字段和复杂字段,默认值为 null

键字段可用于直接查找文档和更新或删除特定文档。 在查找或索引文档时,将以区分大小写的方式处理键字段的值。 有关详细信息,请参阅 查找文档 (azure 认知搜索 REST API)添加、更新或删除文档 (azure 认知搜索 REST API)。
retrievable 指示是否可以在搜索结果中返回字段。 false如果要使用字段 (例如,将边距) 为筛选器、排序或评分机制,但不希望该字段对最终用户可见,请将此属性设置为。 此属性必须为 true 键字段,并且它必须为 null 复杂字段。 可以更改现有字段的属性。 将可检索设置为不 true 会导致索引存储要求增加。 true对于简单字段和复杂字段,默认值为 null
searchable 指示字段是否可全文搜索,并可在搜索查询中引用。 这意味着在索引期间,它会经历 词汇分析 ,如断字。 如果将可搜索字段设置为 "Sunny day" 之类的值,在内部它将被规范化并拆分为单独的令牌 " Sunny " 和 " day " 。 这实现了对这些词的全文搜素。 类型为或的字段 Edm.String Collection(Edm.String) 在默认情况下是可搜索的。 此特性必须是 false 其他非字符串数据类型的简单字段,并且 null 对于复杂字段必须是。

可搜索字段在索引中占用额外的空间,因为 Azure 认知搜索将处理这些字段的内容,并将它们组织到辅助数据结构中,以便进行高性能搜索。 如果要在索引中节省空间,并且不需要在搜索中包含字段,可将 "可搜索" 设置为 false 。 有关详细信息,请参阅 Azure 认知搜索中全文搜索的工作原理
filterable 指示是否启用要在查询中引用的字段 $filter 。 可筛选不同于处理字符串的方式。 Edm.String可以筛选的类型或的字段不会进行 Collection(Edm.String) 词法分析,因此,比较仅用于精确匹配。 例如,如果将此类字段设置 f 为 "Sunny day",则 $filter=f eq 'sunny' 将找不到匹配项,但将找不到匹配项 $filter=f eq 'Sunny day'null对于复杂字段,此属性必须为。 true对于简单字段和复杂字段,默认值为 null 。 若要减小索引大小,请将此属性设置为对 false 不进行筛选的字段。
sortable 指示是否启用要在表达式中引用的字段 $orderby 。 默认情况下,Azure 认知搜索按分数对结果进行排序,但在许多体验中,用户需要按文档中的字段排序。 仅当简单字段为单值 (它在父文档) 的作用域中具有单个值时,才可以对其进行排序。

简单集合字段是多值的,因此不能对其进行排序。 复杂集合的简单子字段也是多值的,因此无法对其进行排序。 无论是直接父字段还是上级字段(这是复杂集合),都是如此。 不能对复杂字段进行排序,并且可排序特性必须 null 为此类字段。 可排序的默认值为 true 单值简单字段、 false 多值简单字段和 null 复杂字段。
facetable 指示是否允许在分面查询中引用字段。 通常用于包含按类别划分的命中次数的搜索结果演示 (例如,搜索数码相机并按品牌、像素、价格等) 查看点击量。 null对于复杂字段,此属性必须为。 类型为或的字段 Edm.GeographyPoint Collection(Edm.GeographyPoint) 不能为可查找。 true对于所有其他简单字段,默认值为。 若要减小索引大小,请将此属性设置为 false 在不分面的字段上。
分析器 在索引和查询操作期间设置词汇切分字符串的词法分析器。 此属性的有效值包括 语言分析器内置分析器自定义分析器。 默认为 standard.lucene。 此属性仅可用于可搜索字段,不能与 searchAnalyzer 或 indexAnalyzer 一起使用。 选择分析器并在索引中创建字段后,就不能为该字段更改字段。 必须 null复杂字段
searchAnalyzer 将此属性与 indexAnalyzer 结合在一起,可指定不同的词法分析器用于索引和查询。 如果使用此属性,请将 "分析器" 设置为 null ,并确保 "indexAnalyzer" 设置为允许的值。 此属性的有效值包括 内置分析器自定义分析器。 此属性仅可用于可搜索字段。 可以在现有字段上更新搜索分析器,因为它仅在查询时使用。 必须 null复杂字段
indexAnalyzer 将此属性与 searchAnalyzer 结合在一起,可指定不同的词法分析器用于索引和查询。 如果使用此属性,请将 "分析器" 设置为 null ,并确保 "searchAnalyzer" 设置为允许的值。 此属性的有效值包括 内置分析器自定义分析器。 此属性仅可用于可搜索字段。 选择索引分析器后,就不能为该字段更改它。 必须 null复杂字段
synonymMaps 要与此字段关联的同义词映射的名称列表。 此属性只能用于可搜索字段。 目前,每个字段仅支持一个同义词映射。 将同义词映射分配给字段可确保使用同义词映射中的规则在查询时扩展面向该字段的查询词。 可以在现有字段上更改此属性。 对于复杂 null 字段,必须是 或空集合。
fields 子字段的列表(如果这是 或 类型的 Edm.ComplexType 字段 Collection(Edm.ComplexType) )。 对于简单 null 字段,必须为 或为空。 有关 如何使用和何时 使用子字段Azure 认知搜索请参阅如何为复杂数据类型建模。

备注

类型为可筛选、可排序或可分面的字段的长度最大为 Edm.String 32 KB。 这是因为此类字段的值被视为单个搜索词,并且一个字词的最大长度在 Azure 认知搜索 32 KB。 如果需要在单个字符串字段中存储超过此文本的文本,则需要在索引定义中将可筛选、可排序和可分面显式 false 设置为 。

将字段设置为可搜索、可筛选、可排序或可分面会影响索引大小和查询性能。 不要在不应在查询表达式中引用的字段上设置这些属性。

如果字段未设置为可搜索、可筛选、可排序或可分面,则不能在任何查询表达式中引用该字段。 这适用于查询中未使用的字段,但搜索结果中需要这些字段。

备注

可以创建的最大索引数因定价层而异。 有关详细信息,请参阅服务限制

响应

对于成功的请求,应看到状态代码“201 Created”。

默认情况下,响应正文将包含已创建的索引定义的 JSON。 但是,如果 Prefer 请求标头设置为 return=minimal,响应正文将为空,并且成功状态代码将是“204 No Content”,而不是“201 Created”。 不管是否使用了 PUT 或 POST 来创建索引,都是如此。

示例

示例:索引架构

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)", 
      "fields": [
          { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
          { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
          { "name": "Type", "type": "Edm.String", "searchable": true },
          { "name": "BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
          { "name": "BedOptions", "type": "Edm.String", "searchable": true },
          { "name": "SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
          { "name": "SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
          { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
        ]
    }
  ],
  "suggesters": [
      { "name": "sg", "searchMode": "analyzingInfixMatching", "sourceFields": ["HotelName"] }
  ],
  "analyzers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
      "name": "tagsAnalyzer",
      "charFilters": [ "html_strip" ],
      "tokenizer": "standard_v2"
    }
  ]
}  

示例:建议器

 "suggesters": [  
   {  
     "name": "name of suggester",  
     "searchMode": "analyzingInfixMatching",  
     "sourceFields": ["field1", "field2", ...]  
   }  
 ]

建议器 按名称引用包含建议 API 或 自动完成 API的查询请求,具体取决于是返回匹配项还是返回查询词的其余部分。 有关创建和使用建议器的信息,请参阅 创建建议器

示例:搜索相关性的相似性

此属性设置用于在全文搜索查询的搜索结果中创建相关性分数的排名算法。 在 2020 年 7 月 15 日之后创建的服务中,将忽略此属性,因为相似性算法始终为 BM25。 对于在 2020 年 7 月 15 日之前创建的现有服务,可以通过设置此构造来选择加入 BM25,如下所示:

 "similarity": {
     "@odata.type": "#Microsoft.Azure.Search.BM25Similarity"
 }

示例:CORS 选项

默认情况下,客户端 JavaScript 无法调用任何 API,因为浏览器将阻止所有跨域请求。 若要允许对索引进行跨源查询,请通过 (属性 (Wikipedia) ) CORS corsOptions 资源共享。 出于安全原因,只有查询 API 才支持 CORS。

{
   "name": "hotels",  
   "fields": [ omitted for brevity],
   "suggesters": [ omitted for brevity  ],
   "analyzers": [ omitted for brevity ],
   "corsOptions": (optional) {  
       "allowedOrigins": ["*"] | ["https://docs.microsoft.com:80", "https://azure.microsoft.com:80", ...],  
       "maxAgeInSeconds": (optional) max_age_in_seconds (non-negative integer)  
     }
}

示例:加密密钥

加密密钥是客户管理的密钥,用于其他加密。 有关详细信息,请参阅 在 中使用客户管理的密钥进行Azure Key Vault。

{
    "name": "hotels",  
    "fields": [ omitted for brevity],
    "suggesters": [ omitted for brevity  ],
    "analyzers": [ omitted for brevity ],
    "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": (optional, only if not using managed system identity) {
        "applicationId": "AAD Application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the specified AAD application)"}
      }
} 

示例:计分概要文件

计分概要文件是架构的一部分,用于定义自定义评分行为,使你可以影响哪些文档显示在搜索结果中的较高级别。 计分配置文件由字段权重和函数组成。 若要使用它们,请在查询字符串上按名称指定配置文件。 有关详细信息,请参阅 将计分概要文件添加到搜索 索引。

{
   "name": "hotels",  
   "fields": [ omitted for brevity],
   "suggesters": [ omitted for brevity  ],
   "analyzers": [ omitted for brevity ],
   "scoringProfiles": [  
   {  
     "name": "name of scoring profile",  
     "text": (optional, only applies to searchable fields) {  
       "weights": {  
         "searchable_field_name": relative_weight_value (positive #'s),  
         ...  
       }  
     },  
     "functions": (optional) [  
       {  
         "type": "magnitude | freshness | distance | tag",  
         "boost": # (positive number used as multiplier for raw score != 1),  
         "fieldName": "...",  
         "interpolation": "constant | linear (default) | quadratic | logarithmic",  
         "magnitude": {  
           "boostingRangeStart": #,  
           "boostingRangeEnd": #,  
           "constantBoostBeyondRange": true | false (default)  
         },  
         "freshness": {  
           "boostingDuration": "..." (value representing timespan leading to now over which boosting occurs)  
         },  
         "distance": {  
           "referencePointParameter": "...", (parameter to be passed in queries to use as reference location)  
           "boostingDistance": # (the distance in kilometers from the reference location where the boosting range ends)  
         },  
         "tag": {  
           "tagsParameter": "..." (parameter to be passed in queries to specify a list of tags to compare against target fields)  
         }  
       }  
     ],  
     "functionAggregation": (optional, applies only when functions are specified)   
       "sum (default) | average | minimum | maximum | firstMatching"  
       }  
 ]
}

请参阅