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

(Azure AI 搜索 REST API) 创建索引

项目
02/28/2024

索引是在 Azure AI 搜索中组织和搜索文档的主要方式，类似于表在数据库中组织记录的方式。每个索引都有一个文档集合，这些文档都符合索引架构 (字段名称、数据类型和属性) ，但索引还指定定义其他搜索行为的附加构造 (建议器、评分配置文件和 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 版本。

请求标头

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

字段	说明
Content-Type	必需。将其设置为 `application/json`
api-key	如果使用 Azure 角色并且请求中提供了持有者令牌，则为可选，否则需要密钥。创建请求必须包含 `api-key` 设置为管理密钥 (而不是查询密钥) 的标头。有关详细信息，请参阅使用密钥身份验证连接到 Azure AI 搜索。

请求正文

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

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

{  
  "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 个字符。
字段	必需。将馈送到此索引中的字段的集合，包括名称、数据类型和定义该字段上允许的操作的属性。数据类型符合实体数据模型 (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 AI 搜索中的排名算法。
建议器	可选。用于自动完成的查询或建议的搜索结果，每个索引一个。它是一种数据结构，用于存储前缀，以便在部分查询（如自动完成和建议）上进行匹配。由 `name` 和建议者感知字段组成，这些字段为自动完成的查询和建议的结果提供内容。 `searchMode` 是必需的，并且始终设置为 `analyzingInfixMatching`。它指定将在查询字符串中的任何字词上进行匹配。
scoringProfiles	可选。用于自定义搜索分数排名。设置为 `defaultScoringProfile` 使用自定义配置文件作为默认值，每当未在查询字符串上指定自定义配置文件时调用。有关元素的详细信息，请参阅将计分配置文件添加到搜索索引和下一部分中的示例。
分析器、charFilters、tokenizers、tokenFilters	可选。如果要定义自定义分析器，请指定索引的这些部分。默认情况下，这些部分为 null。
defaultScoringProfile	可选。覆盖默认评分行为的自定义评分配置文件的名称。
corsOptions	可选。默认情况下，客户端 JavaScript 无法调用任何 API，因为浏览器将阻止所有跨域请求。若要允许对索引进行跨域查询，请通过设置 corsOptions 来启用 CORS（跨域资源共享）。出于安全原因，只有查询 API 才支持 CORS。该`corsOptions`部分包括： `allowedOrigins` (必需) 将授予对索引的访问权限的以逗号分隔的源列表，其中每个源通常采用 protocol://< ful-qualified-domain-name>：<port> (尽管<端口>通常) 省略。也就是说，从这些来源提供的任何 JavaScript 代码将有权查询你的索引（假设代码可以提供正确的 `api-key`）。如果要允许访问所有源，请在数组中`allowedOrigins`指定`*`为单个项。不建议将其用于生产环境，但对于开发或调试可能很有用。 `maxAgeInSeconds` (可选) 浏览器使用此值来确定缓存 CORS 预检响应) 持续时间 (秒。此值必须是非负整数。此值越大，性能越好，但 CORS 策略更改生效所需的时间也越长。如果未设置，将使用默认持续时间 5 分钟。
encryptionKey	可选。用于使用自己的密钥加密同义词映射，在 Azure 密钥保管库中管理。适用于在 2019-01-01 或之后创建的可计费搜索服务。节 `encryptionKey` 包含用户定义的 `keyVaultKeyName` (所需的) 、系统生成的 `keyVaultKeyVersion` (所需的) ，以及提供 `keyVaultUri` 所需的密钥 (，也称为 DNS 名称) 。示例 URI 可能是“https://my-keyvault-name.vault.azure.net"”。（可选）可以指定 `accessCredentials` 是否不使用托管系统标识。 `accessCredentials`的属性包括 `applicationId` (Microsoft Entra ID 已授予对指定 Azure 密钥保管库) 的访问权限的应用程序 ID，以及`applicationSecret`已注册应用程序) (身份验证密钥。下一部分中的示例演示了语法。

字段定义

创建索引时，可以在字段上设置以下属性。

Attribute	说明
name	必需。设置字段的名称，该名称在索引字段或父字段的 fields 集合中必须是唯一的。
type	必需。设置字段的数据类型。字段可以是简单或复杂的。简单字段属于基元类型，例如 `Edm.String` 用于文本或 `Edm.Int32` 整数。复杂字段本身可以是简单或复杂的子字段。这使你可以对对象和对象的数组进行建模，这反过来又使你能够将大多数 JSON 对象结构上传到索引。有关支持类型的完整列表，请参阅 Azure AI 搜索) (支持的数据类型。
key	必需。将此属性设置为 true 以指定字段的值唯一标识索引中的文档。键字段中值的最大长度为 1024 个字符。必须选择每个索引中的一个顶级字段作为键字段，并且其类型 `Edm.String`必须为。 `false`对于简单字段，`null`默认值为，对于复杂字段，默认值为。关键字段可用于直接查找文档以及更新或删除特定文档。在查找文档或编制文档索引时，会以区分大小写的方式处理关键字段的值。有关详细信息，请参阅查找文档 (Azure AI 搜索 REST API) 和 (Azure AI 搜索 REST API) 添加、更新或删除文档。
retrievable	指示字段是否可以在搜索结果中返回。如果要使用字段 (例如边距) 作为筛选器、排序或评分机制，但不希望字段对最终用户可见，请将此属性 `false` 设置为。此属性必须 `true` 用于关键字段，并且必须 `null` 用于复杂字段。可以在现有字段上更改此属性。将“可检索”设置为 `true` 不会导致索引存储要求的任何增加。 `true`对于简单字段，`null`默认值为，对于复杂字段，默认值为。
searchable	指示字段是否可全文搜索，并且可以在搜索查询中引用。这意味着它将在索引编制过程中进行词法分析，例如断字。如果将可搜索字段设置为“Sunny day”等值，则会在内部将其规范化并拆分为单个标记“sunny”和“day”。这实现了对这些词的全文搜素。类型 `Edm.String` 为或 `Collection(Edm.String)` 的字段默认可搜索。此属性必须 `false` 适用于其他非字符串数据类型的简单字段，并且必须 `null` 用于复杂字段。可搜索字段会占用索引中的额外空间，因为 Azure AI 搜索将处理这些字段的内容，并在辅助数据结构中组织这些字段，以便进行高性能的搜索。如果要节省索引中的空间，并且不需要字段包含在搜索中，请将“可 `false`搜索”设置为。有关详细信息，请参阅 Azure AI 搜索中全文搜索的工作原理。
filterable	指示是否启用在查询中 `$filter` 引用字段。 Filterable 与可搜索字符串的处理方式不同。类型 `Edm.String` 为或 `Collection(Edm.String)` 可筛选的字段不会进行词法分析，因此比较仅用于完全匹配。例如，如果将此类字段 `f` 设置为“晴天”， `$filter=f eq 'sunny'` 则找不到匹配项，但 `$filter=f eq 'Sunny day'` 会找到匹配项。此属性必须 `null` 适用于复杂字段。 `true`对于简单字段，`null`默认值为，对于复杂字段，默认值为。若要减小索引大小，请在不进行筛选的字段上将此属性设置为 `false` 。
sortable	指示是否启用在表达式中 `$orderby` 引用字段。默认情况下，Azure AI 搜索按分数对结果进行排序，但在许多情况下，用户需要按文档中的字段进行排序。仅当简单字段为单值 (它在父文档) 的范围内具有单个值时，才能对其进行排序。简单集合字段不可排序，因为它们是多值字段。复杂集合的简单子字段也是多值字段，因此无法进行排序。无论是直接父字段还是上级字段（即复杂集合），都是如此。复杂字段不能是可排序的，并且对于此类字段，可排序属性必须为 `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 AI 搜索中为复杂数据类型建模。

注意

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

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

如果字段未设置为可搜索、可筛选、可排序或可查找，则无法在任何查询表达式中引用该字段。这对于查询中未使用但搜索结果中需要的字段非常有用。

注意

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

响应

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

默认情况下，响应正文包含索引定义的 JSON。但是，如果 Prefer 请求标头设置为 return=minimal，则响应正文为空，成功状态代码为“204 无内容”，而不是“201 已创建”。不管是否使用了 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，因为浏览器将阻止所有跨域请求。若要允许跨域查询索引，请通过设置 corsOptions 属性 (Wikipedia) ) 启用 CORS (跨域资源共享。出于安全原因，只有查询 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 密钥保管库中使用客户管理的密钥进行加密。

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

示例：同义词映射

在搜索服务上创建同义词映射后，可以将其分配给 searchable 类型 Edm.String 或 Collection(Edm.String) 索引中的字段。下面的索引定义将“genre”字段配置为使用同义词映射“mysynonymmap”。

可以使用更新索引将此属性添加到现有字段。 field 属性 synonymMaps 指定映射 (每个字段) 一个。可以随时更新 synonymMaps 现有字段的属性。

像往常一样查询 (用引号括起来的术语或短语) 。在 Azure AI 搜索中，必须将两部分字词（如“热浴缸”）表示为短语，否则将单独评估每个术语。如果查询“热浴缸”，搜索引擎将扫描该短语以及你定义的任何同义词，如“热浴盆”。

POST /indexes?api-version=2020-06-30
{
    "name":"myindex",
    "fields":[
    ...
        {
            "name":"genre",
            "type":"Edm.String",
            "searchable":true,
            "analyzer":"en.lucene",
            "synonymMaps": [
                "mysynonymmap"
            ]
        }
    ]
    ...
}

(Azure AI 搜索 REST API) 创建索引

URI 参数

请求标头

请求正文

字段定义

响应

示例

另请参阅

其他资源