Подключение бота для поиска (предварительная версия)

В этой статье описывается, как создать настраиваемый федеративный поставщик поиска (power by your bot) и подключить его к каналу поиска. Когда администратор клиента включает поставщик в клиенте, корпоративный поиск пользователей из Office.com, SharePoint.com и Bing.com, может включать результаты из пользовательского поставщика поиска.

Платформа федеративного поиска Майкрософт позволяет создавать пользовательские федеративные поставщики поиска, чтобы позволить вашей информации участвовать в Поиск (Майкрософт) ответов и вертикальных интерфейсов без необходимости объединения этой информации с индексом Microsoft 365. Дополнительные сведения см. в статье "Объявление о предварительной версии разработчика" для поиска на платформефедеративного поиска и поиске федерации Dynamics 365 (предварительная версия).

Примечание.

Канал поиска находится в закрытой предварительной версии. Чтобы запросить доступ, используйте форму частной предварительной версии Поиск (Майкрософт) разработчика. В вопросе 7 выберите федеративный поиск.

Для подключения бота к каналу поиска необходимо выполнить следующие действия. Эти шаги подробно описаны далее в этой статье.

1. Реализуйте бота для работы в качестве поставщика поиска.
2. Если боту потребуется выполнить вход пользователей:
   1. В портал Azure предоформите API бота для платформы поиска.
   2. В коде бота используйте созданный область URI для создания маркера пользователя.
3. Развернете бота в Azure.
4. Добавьте канал поиска в бот.
5. Попросите ИТ-администратора просмотреть регистрацию бота и опубликовать бота в клиенте.

Совет

Рекомендуется включить поставщик поиска в тестовом клиенте, прежде чем включить его в рабочей среде.

Необходимые компоненты

• Знание основных сведений о службе Bot Framework и о создании бота с помощью пакета SDK Bot Framework.
• Бот для подключения к каналу.
• Если у вас нет учетной записи Azure, создайте бесплатную учетную запись, прежде чем начинать работу.

Бот можно реализовать на любом из языков, поддерживаемых пакетом SDK Bot Framework. В этой статье в качестве примера используется федеративный поисковый бот C#.

Предоставление API бота для поиска

Совет

Этот шаг необходим только в том случае, если боту требуется доступ к защищенным ресурсам пользователей.

В некоторых бизнес-рабочих процессах бот может потребовать учетных данных пользователя для выполнения действия от имени пользователя. Чтобы создать единый вход для бота в канале поиска, необходимо разрешить платформе поиска защитить маркер доступа от имени пользователя от имени пользователя.

Чтобы создать URI область и идентификатор приложения для бота:

1. Переход на портал Azure.
2. Если у вас еще нет ресурса бота, создайте ресурс Azure Bot.
3. Перейдите в службу идентификатора Microsoft Entra.
4. Перейдите на панель Регистрация приложений.
5. Выберите приложение, связанное с ботом.
6. Перейдите в область предоставления API .
7. Выберите Добавить область.
   1. На панели "Добавление область" рекомендуется сохранить универсальный код ресурса (URI) идентификатора приложения. Выберите Сохранить и продолжить.
   2. Введите имя области.
   3. Для Кто может согласиться?, Администратор и пользователи предпочтительнее, но оба варианта будут работать.
   4. Введите отображаемое имя согласия Администратор и описание согласия Администратор.
   5. При необходимости введите отображаемое имя согласия пользователя и описание согласия пользователя.
   6. Убедитесь, что для состояния задано значение "Включено".
   7. Выберите Добавить область.
8. Выберите Добавить клиентское приложение.
   1. В области "Добавление клиентского приложения" задайте идентификатор81473081-50b9-469a-b9d8-303109583ecbклиента , идентификатор клиента платформы поиска.
   2. В разделе "Авторизованные область" выберите URI область, созданный на предыдущем шаге.
   3. Выберите Добавить приложение.
9. Перейдите в область обзора . Скопируйте URI идентификатора приложения.. Это потребуется при регистрации бота в канале поиска.

Реализация бота

Канал поиска отправляет каждому запросу пользователя боту в качестве действия вызова с именем application/search. Бот возвращает результаты запроса в ответе вызова. Используйте формат адаптивной карточки для результатов запроса, отправляемых обратно в канал поиска.

1. Обновите все пакеты Bot Framework и адаптивных карточек в проекте до последней версии.
2. При необходимости добавьте код проверки подлинности для создания маркера пользователя.
3. Реализуйте метод поиска данных для каждого источника данных для включения.
4. Создайте адаптивную карточку для отображения результатов.

Получение идентификатора трассировки платформы поиска

Платформа поиска назначает уникальный идентификатор трассировки каждому запросу, который он отправляет боту. Платформа добавляет это к данным канала вызова. Возможно, вы решите записать идентификатор трассировки запроса. Используйте свойство данных traceId канала для получения идентификатора трассировки.

В примереSearchHelper.GetSearchTraceId федеративного поиска метод демонстрирует, как получить идентификатор трассировки из действия вызова.

Добавление проверки подлинности

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

Свойство данных authorizations канала может содержать список маркеров проверки подлинности. Если вы предоставляете API бота для поиска, список будет содержать токен от имени. Маркер в списке будет иметь следующую структуру:

Имя свойства	Type	Описание
authType	integer	Тип маркера проверки подлинности: 0 для неизвестного или по умолчанию или 2 для маркера от имени.
token	строка	Сам маркер проверки подлинности.

В примере федеративного поиска:

• Класс SearchBotAuthenticationToken и перечисление AuthenticationTypes представляют эти сведения.
• Метод SearchHelper.GetSearchOboToken демонстрирует, как получить маркер из действия вызова.

После получения маркера его можно использовать при запросе всех защищенных ресурсов для пользователя. Сведения об использовании маркеров от имени см. в разделе платформа удостоверений Майкрософт и поток OAuth 2.0 On-Behalf-Of.

Запрос каждого хранилища данных

Канал поиска отправляет запрос боту в качестве invoke действия с сведениями о запросе в свойстве действия value , который представляет объект JSON со следующей структурой:

Имя свойства	Type	Описание
queryText	строка	Текст запроса.
kind	строка	Тип запроса: "поиск", когда результаты будут отображаться на пользовательской вертикальной вкладке или "searchAnswer", когда результат будет отображаться как ответ на вкладке "Все".
Queryoptions	объект	Дополнительные параметры запроса, используемые для разбиения на страницы.
queryOptions.skip	integer	Индекс первого результата для отправки.
queryOptions.top	integer	Максимальное количество отправляемых результатов.

Результаты поиска возвращаются в ответе вызова:

• Всегда задайте для свойства 200объекта Status ответа вызова значение, указывающее, что сетевое подключение нормально. Свойство объекта Body имеет отдельный код состояния.

• Свойство Body представляет объект JSON со следующей структурой:

  Имя свойства	Type	Описание
  statusCode	integer	Код состояния HTTP, используемый для указания успешности выполнения запроса ботом.
  type	строка	Тип ответа вызова, определяющий формат поля значения. Используйте application/vnd.microsoft.search.searchResponse для результатов поиска или "application/vnd.microsoft.error" для сообщения об ошибке.
  значение	объект	Значение, соответствующее значению type.

  Для сообщений об ошибках объект содержит следующее value :

  Имя свойства	Type	Описание
  кодом	строка	Код ошибки, определенный ботом или null если он не указан.
  message	строка	Сообщение об ошибке или null если оно не указано.

  Для результатов поиска объект содержит следующее value :

  Имя свойства	Type	Описание
  Результаты	массив объектов результатов поиска	Результаты или null нет.
  displayLayouts	массив объектов макета отображения	Макеты отображения или null нет.
  totalResultCount	integer	Общий объем доступных результатов, если поддерживается разбиение на страницы; nullв противном случае .
  moreResultsAvailable	Логический	Указывает, доступны ли дополнительные результаты.

  Объекты результатов поиска содержат:

  Имя свойства	Type	Описание
  значение	строка	Уникальный идентификатор или значение для этого результата поиска.
  LayoutId	строка	Идентификатор макета отображения, используемого для этого результата.
  data.searchResultText	строка	Текст для этого результата.

  Объекты макета отображения содержат следующее:

  Имя свойства	Type	Описание
  LayoutId	строка	Идентификатор макета.
  layoutBody	строка	Текст макета в виде объекта JSON адаптивных карточек.

В примереSearchHelper.RunFederatedSearch федеративного поиска метод демонстрирует, как получить сведения о запросе из действия вызова и как отформатировать ответ вызова.

Отображение результатов поиска

Вы можете создать вертикали поиска и типы результатов, чтобы настроить результаты поиска, которые пользователи видят при поиске в SharePoint, Office и Bing. Вертикали упрощают поиск сведений, доступных пользователям. Дополнительные сведения см. в разделе "Поддерживаемые элементы адаптивной карточки".

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

Регистрация бота в Azure

Чтобы подключить бота к каналу поиска, необходимо подготовить ресурс бота в Azure. Дополнительные сведения см. в статье о регистрации бота в Azure или развертывании бота в Azure.

Подключение бота для поиска

В следующих инструкциях показано, как подключить бота к поиску.

Совет

Рекомендуется включить поставщик поиска в тестовом клиенте, прежде чем включить его в рабочей среде.

1. Переход на портал Azure.

2. Откройте ресурс бота.

3. Откройте панель каналов (предварительная версия).

4. Нажмите Поиск.

5. На вкладке "Поиск Параметры" введите сведения для бота.

   

   1. В разделе Метаданные поставщика поиска введите имя, отображаемое в пользовательском интерфейсе поиска.

   2. В разделе "Фразы триггера" определите фразы, представляющие запросы, которые бот может ответить.

      Примечание.

      Для первоначальных выпусков доступен только английский (en-US).

      • .csv Отправьте файл, содержащий фразы. Файл должен содержать один столбец данных без заголовков.
      • В списке предпочтений языка выберите язык, на котором написаны фразы триггера.

   3. В разделе "Проверка подлинности" укажите, требуется ли для поставщика поиска проверка подлинности пользователей.

      • Если требуется проверка подлинности, введите URL-адрес проверки подлинности. Используйте URI идентификатора приложения, скопированный при предоставлении API для бота.

   4. Выберите Далее.

6. На вкладке "Вертикали", если вы хотите, чтобы результаты от поставщика поиска отображались в собственной пользовательской вертикали на странице результатов поиска, а затем введите вертикальное имя в поле; в противном случае оставьте это поле пустым. Затем выберите Далее.
   Страница результатов поиска предназначена для Office.com, SharePoint.com и Bing.com.

7. На вкладке "Публикация клиента" просмотрите параметры и добавьте сведения о публикации.

   1. Просмотрите имя поставщика поиска и примеры запросов. Вернитесь на предыдущие вкладки, чтобы изменить эту информацию при необходимости.
   2. Введите описание поставщика поиска.
   3. Введите адрес электронной почты в службу поддержки. Используйте электронную почту разработчика или группы разработчиков, имеющих доступ к поставщику поиска.

8. Нажмите кнопку "Добавить ", чтобы запросить утверждение от ИТ-администратора.

Утверждение поставщика поиска в клиенте

Утверждение поставщика поиска в клиенте выполняется ИТ-администратором на странице поиска и аналитики в Центр администрирования Microsoft 365.

Проверка подключения

Рекомендуется включить поставщик поиска в тестовом клиенте, прежде чем включить его в рабочей среде.

Изменение поставщика поиска

Вы можете изменить поставщик поиска перед отправкой его для проверки ИТ-администратором. Это может потребоваться сделать, если первоначальный запрос отклонен или служба отключена.

1. В портал Azure перейдите к ресурсу бота, содержащему поставщик поиска, который требуется изменить.
2. Перейдите на панель каналов (предварительная версия).
3. Выберите канал поиска и нажмите кнопку "Изменить".
   1. В Azure отображается область "Канал поиска". В этой области можно изменить параметры.
   2. Чтобы изменить триггерные фразы, скачайте файл, измените его локально и отправьте файл.
   3. После завершения редактирования нажмите кнопку "Добавить еще раз", чтобы отправить поставщик поиска для проверки ИТ-администратором.

Удаление поставщика поиска

Поставщик поиска будет удален, если удалить канал поиска из ресурса бота.

Чтобы удалить канал поиска из бота, выполните следующие действия.

1. В портал Azure перейдите к ресурсу бота.
2. Перейдите на панель каналов (предварительная версия).
3. Выберите канал поиска.
4. В верхней части области "Канал поиска" выберите "Удалить канал".
5. Нажмите кнопку "Да" , чтобы подтвердить операцию.

Чтобы удалить ресурс бота, выполните следующее:

1. В портал Azure перейдите к ресурсу бота.
2. Если вы еще этого не сделали, удалите канал поиска из бота.
3. В верхней части панели Обзор выберите Удалить.
4. Чтобы подтвердить операцию, выберите ОК.

Дополнительная информация:

Канал поиска использует федеративный поиск и схему адаптивных карточек:

Дополнительные сведения о схеме адаптивной карточки см. в разделе "Адаптивные карточки" для разработчиков ботов.

Сведения о фразах триггера

Фраза триггера — это фраза, которую платформа поиска использует для маршрутизации запроса в настраиваемый поставщик поиска на основе бота. Федеративный поиск пересылает высказывание пользователя поставщику поиска, когда высказывание является близким совпадением с одной из фраз триггеров.

Совет

Если доступно несколько поставщиков поиска, федеративный поиск выбирает только один, в зависимости от предоставленных фраз триггеров и запроса пользователя.

Например, думайте о боте, который управляет расписаниями полетов и состоянием.

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

   Вместо универсального термина, например "график", который может применяться к школам и телевизионным программам, используйте более конкретные фразы, такие как "таблица времени полета" и "расписание полета".

2. Включите различные фразы, охватывающие область функций бота, таких как время отъезда и текущее состояние.

   Например, включите запросы о: время прибытия или отъезда и аэропорты.

Фразы триггера для такого расписания полетов и бота состояния могут включать:

• Расписание полетов
• Состояние полета
• Время вылета 675
• Когда уйдет мой рейс
• Время прибытия 468
• Состояние полета Сиэтла Tacoma
• Состояние полета Хитроу

В качестве другого примера можно включить фразы триггера для бота прогнозирования погоды:

• Локальный прогноз погоды
• Сведения о погоде
• Завтрашная погода
• 10-дневный прогноз погоды
• Сегодня высокий
• Сегодняшняя вероятность дождя
• Будет ли это снег завтра
• Скорость ветра завтра
• Является ли это ветреным снаружи
• Лондонская погода

Поддерживаемые элементы адаптивной карточки

Подмножество схемы адаптивной карточки поддерживается в федеративном поиске. Сведения о форматировании результатов поиска см . на странице "Настройка результатов поиска".

Поддержка включает следующие элементы адаптивной карточки: TextBlock, RichTextBlock, Image, ColumnSet, ImageSet и FactSet. Дополнительные сведения см. в разделе Поиск (Майкрософт)"Управление макетами результатов поиска и схемой адаптивных карточек Обозреватель.

Вы можете создавать каждую карта непосредственно в формате JSON или использовать пакет NuGet AdaptiveCards.

Федеративный поиск не поддерживает HTML

Важно!

Федеративный поиск не будет отображать текст адаптивной карточки, содержащий HTML.

Платформа поиска не включает средство синтаксического анализа HTML. Однако можно исключить некоторые теги и использовать пакет NuGet Html2Markdown для преобразования HTML в Markdown :

1. Удаление <span> и <u> элементы.
2. Замените и <br> элементы <div> элементами абзаца (<p>).
3. Преобразуйте оставшийся HTML-код в Markdown.

Следующие шаги

• Сведения о поддержке каналов в службе Бота Подключение or см. в разделе Подключение бота в каналы.
• Дополнительные сведения о создании ботов см. в статье "Как боты работают и как создать бота с помощью пакета SDK Bot Framework".
• Сведения о развертывании ботов см. в разделе "Развертывание бота " и "Настройка непрерывного развертывания".