建立或更新索引（預覽 REST API）

發行項
06/28/2024

適用於：2023-07-01-Preview。不再支援此版本。立即升級至較新版本。

重要

2023-07-01-Preview 新增向量搜尋。

「vectorSearch」 物件，這是向量搜尋設定的組態。僅適用於向量搜尋演算法。
向量字段所需的「Collection（Edm.Single）」 資料類型。表示單精度浮點數做為基本類型。
向量欄位所需的「維度」 屬性。表示向量內嵌的維度。
向量字段所需的「vectorSearchConfiguration」 屬性。選取此欄位的演算法組態。

2021-04-30-Preview 新增：

“semanticConfiguration” 用於將語意排名範圍設定為特定字段。
「identity」，在 “encryptionKey”下，用來使用使用者指派的受控識別從 Azure Key Vault 擷取客戶管理的加密密鑰。

2020-06-30-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）
- 新增或編輯查詢時間使用的同義字Map （synonymMaps）

若要對現有索引進行任何上述架構變更，請在要求 URI 上指定索引的名稱，然後將完整指定的索引定義與新的或變更的專案一起納入。

加入新的欄位時，索引中的所有現有檔都會自動具有該欄位的 Null 值。在發生兩件事之一之前，不會耗用額外的儲存空間：會為新字段提供一個值（使用合併），或加入新的檔。

suggester 的更新有類似的條件約束：新欄位可以在新增至 suggester 同時新增欄位，但現有字段無法從中移除，也無法新增至沒有索引重建的 suggesters。

不允許更新分析器、Tokenizer、令牌篩選或 char 篩選。您可以使用您想要的變更來建立新的索引，但您必須在新增分析器定義時讓索引離線。在索引更新要求中將 allowIndexDowntime 旗標設定為 true 會讓索引離線：

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

此作業至少會讓索引離線幾秒鐘，這表示索引編製和查詢要求會失敗，直到索引重新上線並準備好處理要求為止。

URI 參數

參數	描述
服務名稱	必填。將此值設定為搜尋服務的唯一用戶定義名稱。
索引名稱	如果使用 PUT，則為 URI 的必要專案。名稱必須是小寫、以字母或數字開頭、沒有斜線或點，且少於 128 個字元。破折號不能連續。
api-version	必填。如需更多版本，請參閱 API 版本。
allowIndexDowntime	自選。 False 預設為 False。針對特定更新設定為 true，例如新增或修改分析器、Tokenizer、令牌篩選、char 篩選或類似屬性。索引會在更新期間離線，通常不超過數秒。

要求標頭

下表描述必要和選擇性的要求標頭。

領域	描述
Content-Type	必填。將此值設定為 `application/json`
api-key	如果您使用 Azure 角色，而且要求會提供持有人令牌，則為選擇性，否則需要密鑰。 api-key 是唯一的系統產生字串，可驗證對搜尋服務的要求。建立要求必須包含設定為系統管理密鑰的 `api-key` 標頭（而不是查詢密鑰）。如需詳細資訊，請參閱使用密鑰驗證連線到 Azure AI 搜尋服務。

要求本文

要求的本文包含架構定義，其中包含送入此索引的檔內的數據欄位清單。

下列 JSON 是支援向量搜尋之架構的高階表示法。架構需要索引鍵欄位，而且該索引鍵字段可以搜尋、可篩選、可排序和可 Facet。

向量搜尋欄位的類型為 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) { }  
}

要求包含下列屬性：

財產	描述
名字	必填。索引的名稱。索引名稱必須只包含小寫字母、數位或破折號，不能以破折號開頭或結尾，且限制為 128 個字元。
描述	選擇性描述。
欄位	此索引的欄位集合，其中每個欄位都有名稱、支援的數據類型符合實體數據模型（EDM），以及定義該欄位上允許動作的屬性。 fields 集合必須有一個類型的字段 `Edm.String`，且 “key” 設定為 “true”。此欄位代表儲存索引之每份檔的唯一標識碼，有時稱為文件識別碼。 fields 集合現在接受向量字段。
相似度	自選。針對在 2020 年 7 月 15 日 7 月 15 日之前建立的服務，請將此屬性設定為選擇加入 BM25 排名演算法。
建議工具	指定建構，此建構會儲存在部分查詢上比對的前置詞，例如自動完成和建議。
評分配置檔	自選。用於全文檢索查詢的相關性微調。
語意	自選。定義影響語意搜尋功能的搜尋索引參數。語意查詢需要語意設定。如需詳細資訊，請參閱建立語意查詢。
vectorSearch	自選。設定各種向量搜尋設定。只能設定向量搜尋演算法。
正規化程式	自選。將字串的語彙排序正規化，產生不區分大小寫的排序和篩選輸出。
analyzers， charFilters， tokenizers， tokenFilters	自選。如果您要定義自定義分析器，請指定索引的這些區段。根據預設，這些區段為 Null。
defaultScoringProfile	覆寫預設評分行為的自定義評分配置檔名稱。
corsOptions	自選。用於索引的跨原始來源查詢。
encryptionKey	自選。用於索引的額外加密，透過 Azure Key Vault 中的客戶管理的加密密鑰（CMK）。適用於在 2019-01-01-01 上建立或之後建立的可計費搜尋服務。

回應

如需成功的建立要求，您應該會看到狀態代碼 “201 Created”。根據預設，響應主體會包含已建立之索引定義的 JSON。不過，如果 Prefer 要求標頭設定為 return=minimal，響應主體是空的，且成功狀態代碼為 “204 無內容”，而不是 “201 Created”。不論 PUT 或 POST 是用來建立索引，都是如此。

如需成功的更新要求，您應該會看到「204 無內容」。根據預設，響應主體是空的。不過，如果 Prefer 要求標頭設定為 return=representation，響應主體會包含已更新之索引定義的 JSON。在此情況下，成功狀態代碼為「200 OK」。。

例子

範例：向量

向量搜尋會在欄位層級實作。此定義會將焦點放在向量欄位上。向量欄位的類型必須為 Collection(Edm.Single)，用來儲存單精度浮點值。向量欄位具有「維度」屬性，可保存機器學習模型用來產生內嵌支援的輸出維度數目。例如，如果您使用 text-embedding-ada-002，則每個輸出維度的最大數目為 1536。 “algorithmConfiguration” 會設定為索引中 “vectorSearch” 組態的名稱。您可以在索引中定義多個，然後為每個欄位指定一個。

許多屬性僅適用於非vector 字段。向量字段會忽略「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"]  
    } 
  ]
}

範例：分析器和正規化程式

分析器和正規化程式參考欄位定義，而且可以預先定義或自定義。如果您使用自定義分析器或正規化程式，請在 “analyzers” 和 “normalizers” 區段中的索引中指定它們。

下列範例說明「標記」的自定義分析器和正規化程式。它也會分別示範「HotelName」和「Description」的預先定義正規化程式（standard）和分析器（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	列出授與索引的網域或來源。
defaultScoringProfile	覆寫預設評分行為的自定義評分配置檔名稱。
encryptionKey	設定與 Azure Key Vault 的連線，以進行客戶管理的加密。
欄位	設定搜尋索引中欄位的定義和屬性。
正規化程式	設定自定義正規化程式。正規化字串的語彙順序，產生不區分大小寫的排序、多面向和篩選輸出。
語意	設定語意搜尋用於排名、標題、醒目提示和答案的欄位。
評分配置檔	用於全文檢索查詢的相關性微調。
相似度
建議工具	設定內部前置詞記憶體，以比對部分查詢，例如自動完成和建議。
vectorSearch	設定用於向量欄位的演算法。

corsOptions

用戶端 JavaScript 預設無法呼叫任何 API，因為瀏覽器會防止所有跨原始來源要求。若要允許索引的跨原始來源查詢，請藉由設定「corsOptions」屬性來啟用 CORS （跨原始來源資源分享）。基於安全性考慮，只有查詢 API 支援 CORS。

屬性描述

allowedOrigins 必填。授與索引存取權的來源逗號分隔清單，其中每個原始來源通常是格式 protocol://<完整域名>：<埠>（雖然通常會省略 <埠>）。這表示允許從這些來源提供的任何 JavaScript 程式代碼查詢您的索引（假設它提供有效的 API 金鑰）。如果您想要允許存取所有來源，請將 * 指定為「allowedOrigins」陣列中的單一專案。不建議用於生產環境，但對於開發或偵錯可能很有用。

maxAgeInSeconds 自選。瀏覽器會使用此值來判斷快取 CORS 預檢回應的持續時間（以秒為單位）。這必須是非負整數。如果此值較大，效能會改善，但這些收益會因 CORS 原則變更生效所需的時間量而抵消。如果未設定，則會使用預設持續時間 5 分鐘。

屬性	描述
allowedOrigins	必填。授與索引存取權的來源逗號分隔清單，其中每個原始來源通常是格式 protocol://<完整域名>：<埠>（雖然通常會省略 <埠>）。這表示允許從這些來源提供的任何 JavaScript 程式代碼查詢您的索引（假設它提供有效的 API 金鑰）。如果您想要允許存取所有來源，請將 `*` 指定為「allowedOrigins」陣列中的單一專案。不建議用於生產環境，但對於開發或偵錯可能很有用。
maxAgeInSeconds	自選。瀏覽器會使用此值來判斷快取 CORS 預檢回應的持續時間（以秒為單位）。這必須是非負整數。如果此值較大，效能會改善，但這些收益會因 CORS 原則變更生效所需的時間量而抵消。如果未設定，則會使用預設持續時間 5 分鐘。

defaultScoringProfile

自選。字串，這是索引中定義的自定義評分配置檔名稱。每當查詢字串上未明確指定自定義配置檔時，就會叫用預設配置檔。如需詳細資訊，請參閱將評分設定檔新增至搜尋索引。

encryptionKey

設定與 Azure Key Vault 的連線，以取得補充客戶管理的加密密鑰（CMK）。適用於在 2019 年 1 月 1 日或之後建立的可計費搜尋服務。

必須驗證金鑰保存庫的連線。您可以針對此目的使用「accessCredentials」或受控識別。

受控識別可以是系統或使用者指派（預覽）。如果搜尋服務同時具有系統指派的受控識別，以及授與密鑰保存庫讀取許可權的角色指派，您可以省略「身分識別」和「accessCredentials」，而要求將會使用受控識別進行驗證。如果搜尋服務具有使用者指派的身分識別和角色指派，請將 “identity” 屬性設定為該身分識別的資源標識符。

屬性	描述
keyVaultKeyName	必填。用於加密的 Azure Key Vault 金鑰名稱。
keyVaultKeyVersion	必填。 Azure Key Vault 金鑰的版本。
keyVaultUri	必填。提供密鑰的 Azure Key Vault URI（也稱為 DNS 名稱）。範例 URI 可能是 `https://my-keyvault-name.vault.azure.net`
accessCredentials	自選。如果您使用受控識別，請省略此屬性。否則，“accessCredentials” 的屬性包括： “applicationId” （Azure Active Directory 應用程式標識符，具有您指定 Azure Key Vault 訪問許可權的 Azure Active Directory 應用程式標識符）。「applicationSecret」（指定 Azure AD 應用程式的驗證金鑰）。
身份	除非您針對 Azure Key Vault 的搜尋服務連線使用使用者指派的受控識別，否則為選擇性。格式為 `"/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"`。

領域

包含欄位定義上屬性的相關信息。

屬性	描述
名字	必填。設定欄位名稱，該欄位在索引或父欄位的 fields 集合中必須是唯一的。
類型	必填。設定欄位的數據類型。欄位可以是簡單或複雜的。簡單欄位是基本類型，例如文字 `Edm.String` 或整數 `Edm.Int32`。複雜欄位可以有簡單或複雜的子欄位。這可讓您建立對象和對象的數位模型，進而讓您將大部分的 JSON 對象結構上傳至索引。 `Collection(Edm.Single)` 容納單精度浮點值。它只用於向量欄位，而且是必要的。如需支援類型的完整清單，請參閱支援的數據類型。
鑰匙	必填。將此屬性設定為 true，以指定欄位的值可唯一識別索引中的檔。索引鍵欄位中值的最大長度為 1024 個字元。每個索引中只有一個最上層欄位必須選擇為索引鍵欄位，而且必須是類型 `Edm.String`。針對簡單欄位和複雜欄位的 `null`，預設值為 `false`。索引鍵字段可用來直接查閱檔，並更新或刪除特定檔。查閱或編製檔索引時，索引鍵欄位的值會以區分大小寫的方式處理。如需詳細資訊，請參閱查閱檔和新增、更新或刪除檔。
檢索	指出是否可以在搜尋結果中傳回欄位。如果您想要使用欄位（例如 margin）做為篩選、排序或評分機制，但不想讓使用者看到字段，請將此屬性設定為 `false`。此屬性必須針對索引鍵字段 `true`，而且必須針對複雜欄位 `null`。這個屬性可以在現有的欄位上變更。將 [可擷取] 設定為 `true` 不會造成索引記憶體需求增加。針對簡單欄位和複雜欄位的 `null`，預設值為 `true`。
搜索	指出欄位是否可全文搜索，而且可以在搜尋查詢中參考。這表示它會經歷語彙分析，例如在編製索引期間斷詞。如果您將可搜尋的字段設定為類似「Sunny day」的值，則會在內部將它正規化為個別標記“sunny” 和 “day”。這可啟用全文搜索這些字詞。預設可搜尋類型 `Edm.String` 或 `Collection(Edm.String)` 的欄位。此屬性必須針對其他非字串數據類型的簡單欄位 `false`，而且複雜欄位必須 `null`。可搜尋的欄位會耗用您索引中的額外空間，因為 Azure AI 搜尋會處理這些欄位的內容，並將其組織在輔助數據結構中以供高效能搜尋。如果您要在索引中節省空間，而且不需要在搜尋中包含欄位，請將可搜尋設定為 `false`。如需詳細資訊，請參閱 azure AI 搜尋中全文搜索的運作方式。
filterable	指出是否要在 `$filter` 查詢中參考欄位。可篩選與可搜尋的字串處理方式不同。可篩選的類型 `Edm.String` 或 `Collection(Edm.String)` 欄位不會進行語彙分析，因此比較僅適用於完全相符專案。例如，如果您將這類字段 `f` 設為「Sunny day」，`$filter=f eq 'sunny'` 找不到相符專案，但 `$filter=f eq 'Sunny day'` 會。複雜欄位必須 `null` 此屬性。針對簡單欄位和複雜欄位的 `null`，預設值為 `true`。若要減少索引大小，請將此屬性設定為 `false` 您不會篩選的欄位。
可排序	指出是否要在 `$orderby` 表示式中參考欄位。根據預設，Azure AI 搜尋會依分數排序結果，但在許多體驗中，使用者想要依檔中的字段排序。只有在單一值時，才能排序簡單字段（在父檔的範圍內有單一值）。 Simple 集合欄位無法排序，因為它們是多重值。複雜集合的簡單子欄位也是多重值，因此無法排序。不論其為即時父欄位或上階字段，都是複雜的集合，都是如此。複雜欄位無法排序，而且這類字段必須 `null` 可排序的屬性。可排序的預設值是單一值簡單欄位的 `true`、多重值簡單欄位的 `false`，以及複雜欄位的 `null`。
facetable	指出是否要在Facet查詢中參考欄位。通常用於搜尋結果的呈現中，包括依類別的點擊計數（例如，搜尋數字相機，並查看依品牌點擊、依百萬像素、價格等等）。複雜欄位必須 `null` 此屬性。類型為 `Edm.GeographyPoint` 或 `Collection(Edm.GeographyPoint)` 的欄位無法面向。所有其他簡單欄位的預設值為 `true`。若要減少索引大小，請將此屬性設定為 `false` 您不會進行 Facet 處理的欄位。
分析器	設定在編製索引和查詢作業期間標記字串的語彙分析器。此屬性的有效值包括語言分析器、內建分析器，以及自定義分析器。預設值為 `standard.lucene`。此屬性只能與可搜尋的字段搭配使用，而且不能與 searchAnalyzer 或 indexAnalyzer 一起設定。選擇分析器並在索引中建立字段之後，就無法變更欄位。必須 `null`複雜欄位。
searchAnalyzer	將此屬性與 indexAnalyzer 一起設定為索引和查詢指定不同的語彙分析器。如果您使用這個屬性，請將分析器設定為 `null`，並確定 indexAnalyzer 已設定為允許的值。此屬性的有效值包括內建分析器，自定義分析器。此屬性只能與可搜尋的欄位搭配使用。搜尋分析器可以在現有的欄位上更新，因為它只在查詢時間使用。必須 `null`複雜欄位。
indexAnalyzer	將此屬性與 searchAnalyzer 一起設定為索引和查詢指定不同的語彙分析器。如果您使用此屬性，請將分析器設定為 `null`，並確定 searchAnalyzer 已設定為允許的值。此屬性的有效值包括內建分析器，自定義分析器。此屬性只能與可搜尋的欄位搭配使用。選擇索引分析器之後，就無法變更欄位。必須 `null`複雜欄位。
normalizer	設定篩選、排序和 Facet 作業的正規化程式。它可以是預先定義的正規化程式名稱，或是索引內定義的自定義正規化程式。默認值為 `null`，這會導致逐字、未分析的文字完全相符。此屬性只能與至少一個可篩選、可排序或可 Facet 設定為 true 的 `Edm.String` 和 `Collection(Edm.String)` 字段搭配使用。只有在加入至索引時，才能在欄位上設定正規化程式，且稍後無法變更。必須 `null`複雜欄位。預先定義的正規化程式有效值包括： `standard`- 小寫文字後面接著 asciifolding。 `lowercase`- 將字元轉換成小寫。 `uppercase` - 將字元轉換成大寫。 `asciifolding` - 如果存在，則會將不在基本拉丁文 Unicode 區塊中的字元轉換成其 ASCII 對等專案。例如，將 “à” 變更為 “a”。 `elision`- 從令牌開頭移除 elision。
synonymMaps	要與此欄位關聯的同義字名稱清單。此屬性只能與可搜尋的欄位搭配使用。目前每個欄位只支援一個同義字對應。將同義字對應指派給字段可確保以該欄位為目標的查詢字詞會使用同義字對應中的規則在查詢時間展開。這個屬性可以在現有的欄位上變更。必須 `null` 或複雜欄位的空白集合。
領域	如果這是類型為 `Edm.ComplexType` 或 `Collection(Edm.ComplexType)`的欄位，則為子字段的清單。簡單欄位必須 `null` 或空白。如需如何使用子欄位的詳細資訊，請參閱如何在 Azure AI 搜尋服務中建立複雜數據類型模型。
尺寸	整數。向量欄位的必要專案。 **這必須符合內嵌模型的輸出內嵌大小。例如，對於熱門的 Azure OpenAI 模型 `text-embedding-ada-002`，其輸出維度為 1536，因此這會是針對該向量字段設定的維度。維度屬性至少有 2 個，而且每個浮點值上限為 2048 個。
vectorSearchConfiguration	向量欄位定義的必要專案。指定向量欄位所使用的「vectorSearch」演演算法組態名稱。建立欄位之後，您無法變更 vectorSearchConfiguration 的名稱，但您可以在索引中變更演算法組態的屬性。這允許調整演算法類型和參數。

注意

類型 Edm.String 可篩選、可排序或多面向的欄位長度最多可以達 32 KB。這是因為這類欄位的值會被視為單一搜尋字詞，而 Azure AI 搜尋中字詞的最大長度為 32 KB。如果您需要將比這更多的文字儲存在單一字串字位中，您必須在索引定義中明確設定可篩選、可排序和可多面向的文字，才能 false。

將欄位設定為可搜尋、可篩選、可排序或可 Facet，對索引大小和查詢效能造成影響。請勿在未在查詢表達式中參考的欄位上設定這些屬性。

如果欄位未設定為可搜尋、可篩選、可排序或可 Facet，則無法在任何查詢表示式中參考欄位。這適用於查詢中未使用的欄位，但在搜尋結果中是必要的。

normalizers

定義自定義正規化程式，其中包含字元篩選和令牌篩選的使用者定義組合。在索引中定義自定義正規化程序之後，您可以在字段定義上依名稱指定。

屬性	描述
名字	必填。指定使用者定義自定義正規化程式的字串欄位。
charFilters	用於自定義正規化程式。它可以是一或多個可用的字元篩選器，支援用於自定義正規化程式：對應 pattern_replace
tokenFilters	用於自定義正規化程式。它可以是一或多個可用的令牌傾斜器，支援用於自定義正規化工具： arabic_normalization 傳 cjk_width elision german_normalization hindi_normalization indic_normalization persian_normalization scandinavian_normalization scandinavian_folding sorani_normalization 小寫大寫

scoringProfiles

評分配置檔適用於全文搜索。配置檔定義在索引中，並指定自定義邏輯，可獎勵較高的搜尋分數，以比對符合配置檔中所定義準則的檔。您可以建立多個評分配置檔，然後將您想要的配置檔指派給查詢。

如果您建立自訂設定檔，您可以藉由設定 defaultScoringProfile來將其設為預設值。如需詳細資訊，請參閱將評分設定檔新增至搜尋索引。

語義

語意組態是索引定義的一部分，用來設定哪些欄位是由語意搜尋來使用排名、標題、醒目提示和答案。語意組態是由標題字段、優先順序的內容欄位和已設定優先順序的關鍵詞欄位所組成。三個子屬性中至少必須指定一個字段（titleField、prioritizedKeywordsFields 和優先順序為ContentFields）。 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": "..."
             }
           ]
         }
       }
     ]
   }
}

屬性	描述
名字	必填。語意組態的名稱。
prioritizedFields	必填。描述要用於語意排名、標題、醒目提示和答案的標題、內容和關鍵詞欄位。必須設定至少三個子屬性之一（titleField、優先順序為KeywordsFields 和優先順序的ContentFields）。
prioritizedFields.titleField	定義要用於語意排名、標題、醒目提示和答案的標題字段。如果您的索引中沒有標題字段，請將此欄位保留空白。
prioritizedFields.prioritizedContentFields	定義要用於語意排名、標題、醒目提示和答案的內容欄位。為了獲得最佳結果，選取的字段應該包含自然語言格式的文字。陣列中欄位的順序代表其優先順序。如果內容很長，優先順序較低的欄位可能會遭到截斷。
prioritizedFields.prioritizedKeywordsFields	定義要用於語意排名、標題、醒目提示和答案的關鍵詞欄位。為了獲得最佳結果，選取的字段應該包含關鍵詞清單。陣列中欄位的順序代表其優先順序。如果內容很長，優先順序較低的欄位可能會遭到截斷。

相似

適用於 2020 年 7 月 15 日之前所建立服務的選擇性屬性。針對這些服務，您可以將此屬性設定為使用 2020 年 7 月引進的 BM25 排名演算法。有效值包括 "#Microsoft.Azure.Search.ClassicSimilarity"（前一個預設值）或 "#Microsoft.Azure.Search.BM25Similarity"。

對於在 2020 年 7 月之後建立的所有服務，設定此屬性沒有任何作用。所有較新的服務都會使用 BM25 作為全文搜索的唯一排名演算法。如需詳細資訊，請參閱 Azure AI 搜尋中的排名演算法。

建議工具

指定建構，此建構會儲存在部分查詢上比對的前置詞，例如自動完成和建議。

屬性	描述
名字	必填。建議工具的名稱。
sourceFields	必填。您要啟用自動完成或建議結果的一或多個字串欄位。
searchMode	必要，且一律設定為 `analyzingInfixMatching`。它會指定比對發生在查詢字串中的任何字詞上。

vectorSearch

vectorSearch 對象允許設定向量搜尋屬性。目前只能設定演算法組態。這可設定用於向量欄位的演算法類型和演算法參數。您可以有多個設定。無法修改和刪除向量欄位所參考的任何組態。任何未參考的組態都可以修改或刪除。向量欄位定義（在欄位集合中）必須指定欄位所使用的向量搜尋演算法組態（透過 vectorSearchConfiguration 屬性）。

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

屬性	描述
名字	必填。演算法組態的名稱。
類	要使用的演算法類型。僅支援 '“hnsw”'，這是階層式導覽小型世界（HNSW）演算法。
hnswParameters	自選。 “hnsw” 演算法的參數。如果省略此物件，則會使用預設值。

hnswParameters

這個物件包含 hnsw 演演算法參數的自定義專案。所有屬性都是選擇性的，如果省略任何屬性，則會使用預設值。

屬性	描述
度量	字串。用於向量比較的相似度計量。針對 `hnsw`，允許的值為 “cosine”、“euclidean” 和 “dotProduct”。預設值為「cosine」。
m	整數。建構期間針對每個新元素建立的雙向連結數目。預設值為 4。允許的範圍是 4 到 10。較大的值會導致更密集的圖形、改善查詢效能，但需要更多記憶體和計算。
efConstruction	整數。索引編製期間所使用之最接近鄰居的動態清單大小。預設值為 400。允許的範圍是 100 到 1000。較大的值會導致更好的索引品質，但需要更多的記憶體和計算。
efSearch	整數。動態清單的大小，其中包含在搜尋期間使用的近鄰。預設值為 500。允許的範圍是 100 到 1000。增加此參數可能會改善搜尋結果，但會降低查詢效能。

由於 efSearch 是查詢時間參數，因此即使現有的欄位使用演算法組態，也可以更新此值。

共用方式為

建立或更新索引（預覽 REST API）

URI 參數

要求標頭

要求本文

回應

例子

定義

corsOptions

defaultScoringProfile

encryptionKey

領域

normalizers

scoringProfiles

語義

相似

建議工具

vectorSearch

hnswParameters

另請參閱

其他資源

共用方式為

建立或更新索引 （預覽 REST API）

URI 參數

要求標頭

要求本文

回應

例子

定義

corsOptions

defaultScoringProfile

encryptionKey

領域

normalizers

scoringProfiles

語義

相似

建議工具

vectorSearch

hnswParameters

另請參閱

其他資源

建立或更新索引（預覽 REST API）