创建或更新索引 （预览版 REST API）

适用于：2023-07-01-Preview。 此版本不再受支持。 将立即升级到较新版本。

索引 指定索引架构，包括字段集合（字段名称、数据类型和属性），以及定义其他搜索行为的构造（建议器、计分配置文件和 CORS 配置）。

可以在创建请求上使用 POST 或 PUT。 对于任一对象，请求正文提供对象定义。

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。 如果索引不存在，则会创建索引。 如果已存在，则会将其更新为新定义。

创建索引 建立架构和元数据。 填充索引是一个单独的操作。 对于此步骤，可以使用索引器（请参阅 索引器操作，可用于支持的数据源），或 添加、更新或删除文档。 可以创建的索引的最大数目因定价层而异。 在每个索引中，每个元素都有限制。 有关详细信息，请参阅 Azure AI 搜索服务限制。

更新现有索引 必须包含完整的架构定义，包括要保留的任何原始定义。 通常，更新的最佳模式是使用 GET 检索索引定义，对其进行修改，然后使用 PUT 对其进行更新。

由于现有索引包含内容，因此许多索引修改需要 索引删除并重新生成。 以下架构更改是此规则的例外：

• 添加新字段

• 添加或更改 计分配置文件

• 添加或更改 语义配置

• 更改 CORS 选项

• 使用以下三项修改之一更改现有字段：

  • 显示或隐藏字段（retrievable： true | false）
  • 更改查询时使用的分析器（searchAnalyzer）
  • 添加或编辑在查询时使用的 synonymMap （synonymMaps）

若要对现有索引进行任何上述架构更改，请在请求 URI 上指定索引的名称，然后使用新的或更改的元素包括完全指定的索引定义。

添加新字段时，索引中的所有现有文档将自动具有该字段的 null 值。 在发生以下两项操作之一之前，不会占用额外的存储空间：为新字段提供值（使用合并），或添加新文档。

对 suggester 的更新具有类似的约束：可以在添加字段的同时将新字段添加到 suggester，但如果没有索引重新生成，则无法从中删除现有字段，也不能添加到 suggesters。

不允许更新分析器、tokenizer、令牌筛选器或字符筛选器。 可以使用所需的更改创建新索引，但添加新的分析器定义时必须使索引脱机。 在索引更新请求中将 allowIndexDowntime 标志设置为 true 使索引脱机：

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

此操作至少将索引脱机几秒钟，这意味着索引和查询请求将失败，直到索引重新联机并准备好处理请求。

URI 参数

请求标头

下表描述了必需的和可选的请求标头。

请求正文

请求的正文包含一个架构定义，其中包括馈送到此索引的文档中的数据字段列表。

以下 JSON 是支持矢量搜索的架构的高级表示形式。 架构需要键字段，并且该键字段可以搜索、可筛选、可排序和可分面。

矢量搜索字段的类型为 Collection(Edm.Single)。 由于矢量字段不是文本字段，因此不能将向量字段用作键，并且不接受分析器、规范化器、建议器或同义词。 它必须具有“dimensions”属性和“vectorSearchConfiguration”属性。

支持矢量搜索的架构还可以支持关键字搜索。 索引中的其他非函数字段可以使用索引中包含的任何分析器、同义词和计分配置文件。

{  
  "name": (optional on PUT; required on POST) "Name of the index",
  "description": (optional) "Description 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.Single) | Collection(Edm.Double) | Collection(Edm.Boolean) | Collection(Edm.DateTimeOffset) | Collection(Edm.GeographyPoint) | Collection(Edm.ComplexType)",
      "key": true | false (default, only Edm.String fields can be keys, enable on one field only),  
      "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),  
      "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)
      "normalizer": "name_of_normalizer", (optional, applies only to filterable, facetable, or sortable Edm.String and Collection(Edm.String) fields.)
      "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.)
      "dimensions": 1234, (required for vector field definitions. Prohibited for non-vector fields. Integer specifying the dimensionality of the embeddings generated by a machine learning model)
      "vectorSearchConfiguration": "name_of_algorithm_config" (required for vector field definitions. Prohibited for non-vector fields. This should reference an algorithm configuration.)
    }
  ],
  "similarity": (optional) { },
  "suggesters": (optional) [ ... ],  
  "scoringProfiles": (optional) [ ... ],  
  "semantic": (optional) { },
  "vectorSearch": (optional) {
    "algorithmConfigurations": [
        {
            "name": "name_of_algorithm_config",
            "kind": "hnsw" (algorithm type. Only "hnsw" is supported currently.),
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]},
  "normalizers":(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) { }  
}  

请求包含以下属性：

响应

对于成功的创建请求，应会看到状态代码“201 已创建”。 默认情况下，响应正文包含已创建的索引定义的 JSON。 但是，如果将 Prefer 请求标头设置为 return=minimal，则响应正文为空，成功状态代码为“204 无内容”，而不是“201 已创建”。 无论使用 PUT 还是 POST 创建索引，都是如此。

对于成功的更新请求，应会看到“204 无内容”。 默认情况下，响应正文为空。 但是，如果 Prefer 请求标头设置为 return=representation，响应正文将包含已更新的索引定义的 JSON。 在这种情况下，成功状态代码为“200 正常”。

例子

示例：矢量

矢量搜索在字段级别实现。 此定义将焦点放在矢量字段上。 矢量字段的类型必须为 Collection(Edm.Single)，用于存储单精度浮点值。 矢量字段具有一个“dimensions”属性，该属性保存用于生成嵌入的机器学习模型支持的输出维度数。 例如，如果使用 text-embedding-ada-002，则每个 输出维度的最大数目为 1536。 “algorithmConfiguration”设置为索引中的“vectorSearch”配置的名称。 可以在索引中定义多个，然后为每个字段指定一个。

许多属性仅适用于非函数字段。 对于矢量字段，将忽略“filterable”、“sortable”、“facetable”、“analyzer”、“normalizer”和“synonymMaps”等属性。 同样，如果在包含 alpha 数字内容的字段上设置“dimensions”或“vectorSearchConfiguration”等仅向量属性，则忽略这些属性。

{
    "name": "{{index-name}}",
    "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true,
            "searchable": true,
            "retrievable": true,
            "filterable": true
        },
        {
            "name": "titleVector",
            "type": "Collection(Edm.Single)",
            "key": false,
            "searchable": true,
            "retrievable": true,
            "filterable": false,  
            "sortable": false,  
            "facetable": false,
            "analyzer": "",
            "searchAnalyzer": "",
            "indexAnalyzer": "",
            "normalizer": "",
            "synonymMaps": "", 
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        },
        {
            "name": "contentVector",
            "type": "Collection(Edm.Single)",
            "key": false,
            "searchable": true,
            "retrievable": true,
            "filterable": false,  
            "sortable": false,  
            "facetable": false,
            "analyzer": "",
            "searchAnalyzer": "",
            "indexAnalyzer": "",
            "normalizer": "",
            "synonymMaps": "", 
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        }
    ],
    "vectorSearch": {
        "algorithmConfigurations": [
            {
                "name": "my-vector-config",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ]
    }
}

示例：具有向量和非向量字段的字段集合

矢量搜索在字段级别实现。 若要支持混合查询方案，请为向量和非函数查询创建字段对。 “title”、“titleVector”、“content”、“contentVector”字段遵循此约定。 如果还想要使用语义搜索，则必须具有这些行为的非函数文本字段。

{
    "name": "{{index-name}}",
    "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true,
            "filterable": true
        },
        {
            "name": "title",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "content",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "category",
            "type": "Edm.String",
            "filterable": true,
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "titleVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        },
        {
            "name": "contentVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        }
    ],
    "corsOptions": {
        "allowedOrigins": [
            "*"
        ],
        "maxAgeInSeconds": 60
    },
    "vectorSearch": {
        "algorithmConfigurations": [
            {
                "name": "my-vector-config",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ]
    },
    "semantic": {
        "configurations": [
            {
                "name": "my-semantic-config",
                "prioritizedFields": {
                    "titleField": {
                        "fieldName": "title"
                    },
                    "prioritizedContentFields": [
                        {
                            "fieldName": "content"
                        }
                    ],
                    "prioritizedKeywordsFields": [
                        {
                            "fieldName": "category"
                        }
                    ]
                }
            }
        ]
    }
}

示例：具有简单和复杂字段的索引架构

第一个示例显示了包含简单和复杂字段的完整索引架构。 至少一个字符串字段必须将“key”设置为 true。

{
  "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", "normalizer": "tagsNormalizer" },
    { "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, "normalizer": "lowercase" },
          { "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", "normalizer": "tagsNormalizer" }
        ]
    }
  ],
  "suggesters": [ ],
  "analyzers": [ ],
  "normalizers": [ ],
  "encryptionKey": [ ]
}  

示例：建议器

建议器 定义应指定“可搜索”和“可检索”字符串字段（在 REST API 中，默认 "retrievable": true 所有简单字段）。 定义建议器后，可以根据使用 建议 API 或 自动完成 API的查询请求按名称引用它，具体取决于是要返回匹配项还是查询词的其余部分。

{
  "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", "normalizer": "tagsNormalizer" },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },

  ],
  "suggesters": [
    {  
      "name": "sg",  
      "searchMode": "analyzingInfixMatching",  
      "sourceFields": ["HotelName", "Category", "Tags"]  
    } 
  ]
} 

示例：分析器和规范化器

分析器 和 规范化器 在字段定义上引用，并且可以预定义或自定义。 如果使用自定义分析器或规范化器，请在“分析器”和“规范化器”部分的索引中指定它们。

以下示例演示了“Tags”的自定义分析器和规范化器。 它还分别演示“HotelName”和“Description”的预定义规范化器（标准）和分析器（en.microsoft）。

{
  "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, "normalizer": standard  },
    { "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", "normalizer": "tagsNormalizer" },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },

  ],
  "analyzers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
      "name": "tagsAnalyzer",
      "charFilters": [ "html_strip" ],
      "tokenizer": "standard_v2"
    }
  ],
  "normalizers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomNormalizer",
      "name": "tagsNormalizer",
      "tokenFilters": [ "asciifolding", "lowercase" ]
    }
  ]
}  

示例：搜索相关性 相似性

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

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

示例：CORS 选项

默认情况下，客户端 JavaScript 无法调用任何 API，因为浏览器会阻止所有跨域请求。 若要允许跨域查询索引，请通过设置 corsOptions 属性来启用 CORS（跨域资源共享（Wikipedia））。 出于安全原因，只有查询 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)"
        }
    }
} 

示例：使用托管标识的加密密钥

可以使用系统分配的或用户分配的托管标识向 Azure Key Vault 进行身份验证。 在这种情况下，省略访问凭据或设置为 null。 以下示例显示了用户分配的托管标识。 若要使用系统分配的托管标识，请省略访问凭据和标识。 只要搜索服务的系统标识在 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": null,
          "identity" : { 
              "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
              "userAssignedIdentity" : "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"
          }
    }
} 

示例：计分配置文件

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

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

示例：语义配置

语义配置是索引定义的一部分，用于配置语义搜索对排名、标题、突出显示和答案使用哪些字段。 若要使用语义搜索，必须在查询时指定语义配置的名称。 有关详细信息，请参阅 创建语义查询。

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "semantic": {
     "configurations": [
       {
         "name": "my-semantic-config",
         "prioritizedFields": {
           "titleField": {
                 "fieldName": "hotelName"
               },
           "prioritizedContentFields": [
             {
               "fieldName": "description"
             },
             {
               "fieldName": "description_fr"
             }
           ],
           "prioritizedKeywordsFields": [
             {
               "fieldName": "tags"
             },
             {
               "fieldName": "category"
             }
           ]
         }
       }
     ]
   }
}

定义

corsOptions

默认情况下，客户端 JavaScript 无法调用任何 API，因为浏览器会阻止所有跨域请求。 若要允许跨域查询索引，请通过设置“corsOptions”属性来启用 CORS（跨域资源共享）。 出于安全原因，只有查询 API 支持 CORS。

defaultScoringProfile

自选。 一个字符串，该字符串是索引中定义的自定义计分配置文件的名称。 只要查询字符串上未显式指定自定义配置文件，就会调用默认配置文件。 有关详细信息，请参阅 将计分配置文件添加到搜索索引。

encryptionKey

配置与 Azure Key Vault 的连接，以补充 客户管理的加密密钥（CMK）。 可用于在 2019 年 1 月 1 日或之后创建的计费搜索服务。

必须对与密钥保管库的连接进行身份验证。 为此，可以使用“accessCredentials”或托管标识。

托管标识可以是系统或用户分配的（预览版）。 如果搜索服务同时具有系统分配的托管标识和授予对密钥保管库的读取访问权限的角色分配，则可以省略“标识”和“accessCredentials”，并且请求将使用托管标识进行身份验证。 如果搜索服务具有用户分配的标识和角色分配，请将“identity”属性设置为该标识的资源 ID。

领域

包含有关字段定义的属性的信息。

normalizers

定义 自定义规范化程序，该规范化程序具有用户定义的字符筛选器和令牌筛选器的组合。 在索引中定义自定义规范化器后，可以在 字段定义按名称指定它。

scoringProfiles

计分配置文件适用于全文搜索。 配置文件在索引中定义，并指定自定义逻辑，这些逻辑可授予更高的搜索分数，以匹配符合配置文件中定义的条件的文档。 可以创建多个计分配置文件，然后分配要查询的计分配置文件。

如果创建自定义配置文件，可以通过设置 defaultScoringProfile将其设置为默认设置。 有关详细信息，请参阅 将计分配置文件添加到搜索索引。

语义

语义配置是索引定义的一部分，用于配置语义搜索对排名、标题、突出显示和答案使用哪些字段。 语义配置由标题字段、优先级内容字段和优先级关键字字段组成。 至少需要为三个子属性（titleField、prioritizedKeywordsFields 和 prioritizedContentFields）中的每个子属性指定一个字段。 类型为 Edm.String 或 Collection(Edm.String) 的任何字段都可以用作语义配置的一部分。

若要使用语义搜索，必须在查询时指定语义配置的名称。 有关详细信息，请参阅 创建语义查询。

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "semantic": {
     "configurations": [
       {
         "name": "name of the semantic configuration",
         "prioritizedFields": {
           "titleField": {
                 "fieldName": "..."
               },
           "prioritizedContentFields": [
             {
               "fieldName": "..."
             },
             {
               "fieldName": "..."
             }
           ],
           "prioritizedKeywordsFields": [
             {
               "fieldName": "..."
             },
             {
               "fieldName": "..."
             }
           ]
         }
       }
     ]
   }
}

相似

适用于 2020 年 7 月 15 日之前创建的服务的可选属性。 对于这些服务，可以将此属性设置为使用 2020 年 7 月引入的 BM25 排名算法。 有效值包括 "#Microsoft.Azure.Search.ClassicSimilarity"（上一个默认值）或 "#Microsoft.Azure.Search.BM25Similarity"。

对于在 2020 年 7 月之后创建的所有服务，设置此属性不起作用。 所有较新的服务都使用 BM25 作为全文搜索的唯一排名算法。 有关详细信息，请参阅 Azure AI 搜索中的 排名算法。

建议器

指定一个构造，该构造存储用于在部分查询（如自动完成和建议）上匹配的前缀。

vectorSearch

vectorSearch 对象允许配置矢量搜索属性。 目前只能配置算法配置。 这允许配置用于向量字段的算法类型和算法参数。 可以有多个配置。 无法修改和删除矢量字段引用的任何配置。 任何未引用的配置都可以修改或删除。 矢量字段定义（在字段集合中）必须指定字段正在使用的矢量搜索算法配置（通过 vectorSearchConfiguration 属性）。

"vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "my-vector-config",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]
}

hnswParameters

此对象包含用于 hnsw 算法参数的自定义项。 所有属性都是可选的，如果省略任何属性，则使用默认值。

由于 efSearch 是查询时参数，因此即使现有字段正在使用算法配置，也可以更新此值。

另请参阅

• HTTP 状态代码
• 向搜索索引添加计分配置文件
• 搜索文档 API
• 支持的数据类型
• 词法分析器
• 门户中创建 Azure AI 搜索索引
• 创建语义配置