Создание сопоставления синонимов (REST API поиска ИИ Azure)

  • Статья

В поиске ИИ Azure карта синонимов содержит список правил для расширения или перезаписи поискового запроса на эквивалентные термины.

Для запроса можно использовать POST или PUT. Для любого из них документ JSON в тексте запроса предоставляет определение объекта.

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

Кроме того, можно использовать запрос PUT и указать имя карты синонимов в универсальном коде ресурса (URI).

PUT https://[service name].search.windows.net/synonymmaps/[synonymmap name]?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin key]

Все запросы к службе отправляются по протоколу HTTPS. Если сопоставление синонимов не существует, она создается. Если он уже существует, он обновляется до нового определения.

Примечание

Максимальное количество карт синонимов, которые можно создать, зависит от ценовой категории. Дополнительные сведения см. в статье Ограничения службы.

Параметры URI

Параметр Описание
имя службы Обязательный. Задайте уникальное, определяемое пользователем имя службы поиска.
Имя сопоставления синонимов Требуется для URI, если используется PUT. Имя должно быть строчным, начинаться с буквы или цифры, не содержать косых черт или точек и содержать менее 128 символов. После начала имени с буквы или цифры остальная часть имени может включать любые буквы, цифры и дефисы, если дефисы не являются последовательными.
api-version Обязательный. Текущая стабильная версия — api-version=2020-06-30. Дополнительные версии см. в разделе Версии API .

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

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

Поля Описание
Content-Type Обязательный. Для этого заголовка необходимо задать значение application/json
api-key Необязательно, если вы используете роли Azure и в запросе предоставляется маркер носителя, в противном случае требуется ключ. Ключ API — это уникальная, сгенерированная системой строка, которая проверяет подлинность запроса к службе поиска. Запросы на создание должны включать заголовок, заданный api-key для ключа администратора (в отличие от ключа запроса). Дополнительные сведения см. в статье Подключение к поиску ИИ Azure с помощью проверки подлинности по ключу .

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

Текст запроса содержит определение схемы синонимов, которое включает формат сопоставления синонимов и список правил в указанном формате.

Следующий код JSON представляет собой общее представление main частей определения.

{   
    "name" : (optional on PUT; required on POST) "Name of the synonym map",  
    "format" : (required) "Only Apache Solr format ('solr') is currently supported.",
    "synonyms" : (required) "Synonym rules separated by the new line ('\n') character.",
    "encryptionKey":(optional) { See below for details } 
}

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

Свойство Описание
name Обязательный. Имя карты синонимов. Имя карты синонимов должно содержать только строчные буквы, цифры или дефисы, не может начинаться или заканчиваться дефисами и может содержать только 128 символов.
format Обязательный. В настоящее время поддерживается только формат Apache Solr (solr).
синонимы. Обязательный. Правила синонимов, разделенные символом новой строки (\n).
encryptionKey Необязательный элемент. Используется для шифрования карты синонимов с помощью собственных ключей, управляемых в Key Vault Azure. Доступно для оплачиваемых служб поиска, созданных в 01.01.2019 или позже.

Раздел encryptionKey содержит определяемые keyVaultKeyName пользователем (обязательные), созданные keyVaultKeyVersion системой (обязательные) и предоставляющие keyVaultUri ключ (обязательный, также называемый DNS-именем). Примером URI может быть "https://my-keyvault-name.vault.azure.net".

При необходимости можно указать accessCredentials , используется ли управляемое системное удостоверение. accessCredentials Свойства include applicationId (идентификатор приложения Azure Active Directory, которому были предоставлены разрешения на доступ к указанному Key Vault Azure) и applicationSecret (ключ проверки подлинности указанного приложения Azure AD). Пример в следующем разделе иллюстрирует синтаксис .

Ответ

Для успешного запроса: "201 — Создан ресурс".

Примеры

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

Эквивалентное правило сопоставления содержит эквивалентные термины или фразы, разделенные запятыми ("США, США, США Америки"). Правило расширяет поиск на все эквивалентные термины или фразы. Например, документ поиска, содержащий USA , будет совпадать с запросами, содержащими термин USA или фразы "United States", или "United States of America".

Явное сопоставление обозначается стрелкой => ("США, США, США, США, США Америки => США"). Если этот параметр указан, последовательность терминов поискового запроса, соответствующая левой части => , будет заменена альтернативами в правой части. С учетом правила поисковые запросы U.S. или "United States" будут переписаны в USA. Явное сопоставление применяется только в указанном направлении и в этом случае не перезаписывает запрос USA"United States" на . Обратите внимание, что "США" — это запрос фразы, заключенный в кавычки. Если требуется совпадение во всей фразе, строка запроса должна быть заключена в двойные кавычки. В противном случае каждый термин , "Соединенные" и "штаты", оценивается отдельно.

{   
  "name" : "synonymmap1",  
  "format" : "solr",  
  "synonyms" : "United States, United States of America, USA\n
  Washington, Wash. => WA"
}

Пример. Ключи шифрования

Ключи шифрования — это управляемые клиентом ключи, используемые для дополнительного шифрования. Дополнительные сведения см. в статье Шифрование с помощью ключей, управляемых клиентом, в Azure Key Vault.

{   
  "name" : "synonymmap1",  
  "format" : "solr",  
  "synonyms" : "United States, United States of America, USA\n
  Washington, Wash. => WA",
  "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": "Azure AD Application ID that was granted access permissions to your specified Azure Key Vault",
          "applicationSecret": "Authentication key of the specified Azure AD application)"
      }
  }
}

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