REST службы Когнитивный поиск Azure

  • Статья
  • Чтение занимает 4 мин

Когнитивный поиск Azure — это полностью управляемая облачная служба поиска, которая предоставляет широкие возможности поиска по содержимому, принадлежащему пользователю. Одним из способов добавления возможностей поиска является использование REST API поиска с операциями, которые создают индексы и управляют ими, загружают данные, реализуют функции поиска, выполняют запросы и обрабатывают результаты.

Для создания или изменения самой службы можно использовать отдельный REST API управления . Кроме того, можно использовать портал для многих задач управления службами и содержимым. Чтобы приступить к работе, см. статью "Создание службы поиска" в портал Azure.

Основные понятия

Когнитивный поиск содержит основные понятия служб поиска и индексов и документов:

  • Служба поиска содержит один или несколько индексов.
  • Индекс предоставляет постоянное хранилище документов поиска.
  • Документы поиска загружаются из внешних источников в виде документов JSON и отправляются в индекс, чтобы сделать его пригодным для поиска.

Можно также создать индексатор для автоматизации индексирования. Индексатор имеет источник данных и указывает на индекс. При необходимости он также может иметь набор навыков , который добавляет ИИ в конвейер индексатора.

Обогащение СИ — это расширение индексаторов, добавляющих преобразования машинного обучения, которые извлекают или создают текст, или добавляют структуру в контент, чтобы его можно было индексировать службой поиска. Конструкция, которая управляет обогащением ИИ, называется набором навыков. Во время приема данных он определяет последовательность шагов, которые обнаруживают, структуру или преобразуют содержимое, которое в противном случае невозможно найти (например, содержимое изображения).

Вместе существует пять типов операций, которые могут выполняться в службе:

Операция Описание
Index Создание, удаление, обновление или настройка индекса поиска.
Document Добавление, обновление или удаление документов в индексе, запрос индекса или поиск определенных документов по идентификатору.
Индексатор Автоматизируйте аспекты операции индексирования, настроив источник данных и индексатор , который можно запланировать или запустить по требованию. Эта функция поддерживается для ограниченного числа типов источников данных в Azure.
Набор навыков Часть рабочей нагрузки обогащения ИИ , набор навыков определяет ряд обработки обогащения, которая извлекает или создает доступный для поиска текст из неструктурированного текста, файлов приложений или файлов изображений. Набор навыков вызывается индексатором.
Схема синонимов Сопоставление синонимов — это ресурс уровня обслуживания, содержащий определяемые пользователем синонимы. Этот ресурс поддерживается независимо от индексов поиска. После отправки можно указать любое поле с возможностью поиска на карту синонимов (по одному на поле).

Вызов API

Интерфейсы API, описанные в этом разделе, предназначены для выполнения различных операций с поисковыми данными, таких как создание и заполнение индекса, добавление документов и отправка запросов. При вызове API учитывайте следующие моменты:

  • Запросы должны выдаваться по протоколу HTTPS (на порте по умолчанию 443).

  • Запросы должны содержать версию API в URI. Значение должно иметь поддерживаемую версию, отформатированную, как показано в следующем примере: GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • Заголовки запросов должны содержать ключ API , созданный для подготовленной службы поиска. Если есть действительный ключ, для каждого запроса устанавливаются отношения доверия между приложением, которое отправляет запрос, и службой, которая его обрабатывает. При необходимости можно задать заголовок Accept HTTP. Если заголовок не задан, предполагается, что используется application/jsonзначение по умолчанию.

Проверка подлинности с использованием ключа

Каждый HTTP-запрос к службе поиска проходит проверку подлинности на основе двух фрагментов информации: URL-адреса службы поиска и ключа API, который предоставляет подтверждение, что запрос получен из доверенной сущности. Существует два типа ключей API для разных уровней работы.

Клавиши Описание Ограничения
Административный Ключи администратора предоставляют полные права для всех операций, включая возможность управления службой, получение определений состояния и объектов, а также создание и удаление индексов, индексаторов и источников данных.

Два ключа API администратора, называемые первичными и вторичнымиключами на портале, автоматически создаются при создании службы и могут быть повторно созданы по запросу. При наличии двух ключей один ключ можно сменить, а второй использовать для непрерывного доступа к службе.

Ключи администратора указываются только в заголовках HTTP-запросов. Ключ API администратора нельзя поместить в URL-адрес .		 Не более 2 на службу
Запрос Ключи запросов предоставляют доступ только для чтения к содержимому в индексе (документах) и обычно распространяются в клиентские приложения, которые выдают поисковые запросы.

Ключи запросов создаются по запросу. Их можно создать вручную на портале или программным путем с помощью REST API управления.

Ключи запросов можно указать в заголовке HTTP-запроса для операции поиска, предложения или поиска. Кроме того, ключ запроса можно передать в качестве параметра в URL-адресе. В зависимости от того, как клиентское приложение формулирует запрос, может быть проще передать ключ в качестве параметра запроса:

GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]		 50 на службу

Визуально нет никакой разницы между ключом администратора и ключом запроса. Оба ключа представляют собой строки из 32 случайно сгенерированных буквенно-цифровых символов. Если вы теряете отслеживание того, какой тип ключа указан в приложении, можно проверить значения ключей на портале или использовать REST API управления для возврата значения и типа ключа.

Примечание

В целях безопасности в URI запроса не рекомендуется передавать конфиденциальные данные, например api-key. По этой причине Когнитивный поиск Azure будет принимать ключ api-key запроса только в строке запроса, и следует избегать этого, если содержимое индекса не должно быть общедоступным. Как правило, мы рекомендуем передавать api-key в заголовке запроса.

Авторизация

Когнитивный поиск поддерживает управление доступом на основе ролей Azure (Azure RBAC) для администрирования службы поиска с помощью ролей владельца, участника и читателя.

При необходимости для решений поиска, которые могут использовать функции предварительной версии, можно использовать Azure RBAC для управления доступом к индексам и другим объектам в службе поиска. Для этого подхода требуется служба поиска, настроенная для Azure RBAC на плоскости данных, и заголовок авторизации для вызовов REST API, прошедших проверку подлинности с помощью Azure Active Directory.

См. также