Создание индекса (REST API поиска Azure AI)

Индекс — это основное средство упорядочения и поиска документов в службе поиска ИИ 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

Заголовки запросов

Таблица ниже содержит обязательные и необязательные заголовки запроса.

Текст запроса

Текст запроса содержит определение схемы, указывающее список полей данных в документах, которые будут переданы в этот индекс.

Следующий код 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) { }  
}  

Запрос содержит следующие свойства.

Определения полей

При создании индекса для поля можно задать следующие атрибуты.

Ответ

При успешном выполнении запроса возвращается код состояния 201 (создан).

По умолчанию текст ответа содержит 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 автозаполнения, в зависимости от того, нужно ли возвращать соответствие или оставшуюся часть термина запроса. Дополнительные сведения о создании и использовании средства подбора см. в статье Создание средства подбора.

Пример. Сходство для релевантности поиска

Это свойство задает алгоритм ранжирования, используемый для создания оценки релевантности в результатах поиска полнотекстового поискового запроса. В службах, созданных после 15 июля 2020 г., это свойство игнорируется, так как алгоритм сходства всегда имеет значение BM25. Для существующих служб, созданных до 15 июля 2020 г., вы можете согласиться на BM25, задав эту конструкцию следующим образом:

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

Пример. Параметры CORS

Клиентский Код JavaScript не может вызывать API по умолчанию, так как браузер будет препятствовать всем запросам между источниками. Чтобы разрешить запросы между источниками к индексу, включите CORS (общий доступ к ресурсам независимо от источника (Википедия)), задав corsOptions атрибут . По соображениям безопасности технологию CORS поддерживают только интерфейсы API запросов.

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

Пример. Карты синонимов

После создания карты синонимов в службе поиска ее можно назначить searchable полям типа Edm.String или Collection(Edm.String) в индексе. Приведенное ниже определение индекса настраивает поле "жанр" для использования карты синонимов mysynonymmap.

Чтобы добавить это свойство в существующее поле, можно использовать команду Обновить индекс . Свойство synonymMaps field указывает карту (по одному на поле). Свойства существующих полей можно обновить synonymMaps в любое время.

Запрос, как обычно, с помощью терминов или фраз (заключенных в кавычки). В поиске ИИ Azure термины из двух частей, такие как "горячая ванна", должны быть выражены в виде фразы, в противном случае каждый термин оценивается независимо. Если вы запросите "горячая ванна", поисковая система будет сканировать эту фразу, а также любые синонимы, которые вы определили, например, джакузи.

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

См. также раздел

• Коды состояния HTTP
• Добавление профилей повышения в индекс поиска
• Поиск документов (REST API Когнитивного поиска Azure)
• Поддерживаемые типы данных
• Лексические анализаторы