Поделиться через

Использование API Поиска (Майкрософт) для запросов данных

  • Статья

Вы можете использовать API Поиска (Майкрософт) для запроса данных Microsoft 365 в своих приложениях.

Поисковые запросы выполняются в контексте вошедшего пользователя, указанного маркером доступа с делегированными разрешениями.

Основные варианты использования

API Microsoft Search предоставляет метод query для поиска по данным в Microsoft Search; в этот метод передается searchRequest в теле запроса, определяя характер поиска.

В этом разделе перечислены распространенные варианты использования метода запроса на основе свойств и параметров, заданных в тексте запросаsearchRequest .

Поисковые запросы выполняются от имени пользователя. Результаты поиска ограничиваются для применения правил контроля доступа к элементам. Например, в контексте файлов разрешения для них оцениваются в составе поискового запроса. Пользователь не может обратиться в результатах поиска к большему количеству элементов, чем он мог бы получить из соответствующей операции GET с теми же разрешениями и управлением доступом.

Варианты использования Свойства, определяемые в тексте запроса query
Результаты поиска в области по типам объектов entityTypes
Результаты со страницы from и size
Получение наиболее релевантных электронных писем enableTopResults
Получение выбранных свойств fields
Использование KQL в терминах запросов query
Свертывание результатов поиска collapseProperties
Сортировка результатов поиска sortProperties
Уточнение результатов с помощью агрегатов aggregations
Исправление орфографии в запросе queryAlterationOptions
Макет отображения при поиске (предварительная версия) resultTemplateOptions

Поиск в области по типам объектов

Область действия поискового запроса определяется с помощью свойства entityTypes полезных данных запроса query. В следующей таблице описаны доступные типы запросов и поддерживаемые разрешения на доступ к данным.

EntityType Область разрешений, необходимая для доступа к элементам Источник Примечание
акроним Acronym.Read.All Поиск (Майкрософт) Аббревиатуры в поиске (Майкрософт) в организации.
bookmark Bookmark.Read.All Поиск (Майкрософт) Закладки в поиске (Майкрософт) в вашей организации.
chatMessage Chat.Read, Chat.ReadWrite, ChannelMessage.Read.All Teams Сообщения Teams.
message Mail.Read, Mail.ReadWrite Exchange Online Сообщения электронной почты.
event Calendars.Read, Calendars.ReadWrite Exchange Online События календаря.
drive Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePoint Библиотеки документов.
driveItem Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePoint и OneDrive Файлы, папки, страницы и новости.
list Sites.Read.All, Sites.ReadWrite.All SharePoint и OneDrive Списки Учтите, что библиотеки документов также возвращаются как списки.
listItem Sites.Read.All, Sites.ReadWrite.All SharePoint и OneDrive Элементы списка. Учтите, что файлы и папки также возвращаются как элементы списка; listItem — это суперкласс driveItem.
qna QnA.Read.All Поиск (Майкрософт) Вопросы и ответы в Поиске (Майкрософт) в вашей организации.
site Sites.Read.All, Sites.ReadWrite.All SharePoint Сайты в SharePoint.

Результаты поиска на странице

Управляйте разбивкой результатов поиска на страницы, указав описанные ниже два свойства в тексте запроса query.

  • from — целое значение, указывающее начальную точку (начиная с 0) для перечисления результатов поиска на странице. Значение по умолчанию равно 0.

  • size — целое число, обозначающее количество результатов, возвращаемых для страницы. Кол-во результатов по умолчанию: 25. Максимальное кол-во результатов: 1000.

При поиске объекта event или message учитывайте указанные ниже ограничения.

  • Значение from должно начинаться с нуля для запроса первой страницы. В противном случае запрос возвращает ошибку HTTP 400 Bad request.
  • Максимальное кол-во результатов на странице (size) составляет 25 для message и event.

Верхний предел для элементов SharePoint или OneDrive — 1000. Рекомендуемый размер страницы — 200. Чем больше размер страницы, тем, как правило, больше задержка.

Рекомендации:

  • В исходном запросе задайте меньший размер первой страницы. Например, задайте для свойства from значение 0, а для свойства size — 25.

  • Для получения последующих страниц обновите свойства from и size. Вы можете увеличивать размер страницы в каждом последующем запросе. В приведенной ниже таблице показан пример.

    Страница from size
    1 0 25
    2 25 50
    3 75 75
    4 150 100

Получение наиболее релевантных электронных писем

Если при поиске объекта message задать для свойства enableTopResults значение true, возвращается гибридный список сообщений: первые три сообщения в отклике сортируются по релевантности, а остальные — по дате/времени.

Получение выбранных свойств

При поиске по типу сущности, например message, event, drive, driveItem, list, listItem, site, externalItem, можно включить в свойство itfields определенные свойства сущности, которые следует возвратить в результатах поиска. Аналогично используется параметр $select системного запроса OData в запросах REST. API поиска не поддерживает эти параметры запроса, так как их действие подавляется в теле запроса POST.

Для всех этих типов сущностей указание свойства fields сокращает количество свойств, возвращаемых в отклике, что оптимизирует нагрузку на линию.

listItem и externalItem — единственные поддерживаемые сущности, которые позволяют настройку расширенных извлекаемых полей в схеме. Из всех других сущностей расширенные свойства невозможно извлечь путем применения API поиска. Например, если вы создали извлекаемое поле для externalItem в схеме поиска или у вас есть извлекаемый пользовательский столбец в listItem, вы можете извлечь эти свойства из результатов поиска. Чтобы получить расширенное свойство файла, укажите в запросе тип listItem.

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

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

  • listItem не возвращает никаких настраиваемых полей.
  • externalItem возвращает все поля с атрибутом retrievable в схеме соединителя Microsoft Graph для этого конкретного подключения.

Поддержка языка KQL

Вы можете указать произвольный текст ключевых слов (например, AND и OR) и ограничения свойств в синтаксисе KQL в фактической строке поискового запроса (свойства query в тексте запроса query). Оператор XRANK повышает динамический ранг элементов на основе определенных вхождений терминов в выражении соответствия, не изменяя, какие элементы соответствуют запросу. Синтаксис и команда зависят от типов объектов (в свойстве entityTypes), указанных в тексте того же запроса query.

Свойства, доступные для поиска, зависят от типа объекта. Дополнительные сведения см. в следующих статьях:

Свертывание результатов поиска

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

Метод запроса позволяет настроить свойство collapse, указав collapseProperties в requests параметре , который представляет собой коллекцию объектов collapseProperty . Это позволяет указать набор одного или нескольких свойств свертывания.

Обратите внимание, что результаты сворачивания в настоящее время поддерживаются для следующих типов сущностей: driveItem, listItem, drive, list, site, externalItem.

Чтобы эффективно использовать предложение collapse, свойства, к которые оно применяется, должны быть запрашиваемыми, сортируемыми или уточняемыми. При использовании многоуровневого свертывания важно отметить, что максимальный размер каждого последующего свойства, указанный в многоуровневом запросе, должен быть равен или меньше предыдущего. Если максимальный размер последующего свойства превышает предыдущее, сервер ответит ошибкой HTTP 400 Bad Request .

Дополнительные примеры результатов см. в разделе Свертывание результатов поиска .

Сортировка результатов поиска

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

  • message и event сортируются по дате.
  • Все типы SharePoint, OneDrive, пользователей и соединителей сортируются по релевантности.

Метод запроса позволяет настроить порядок поиска, указав sortProperties в requests параметре , который представляет собой коллекцию объектов sortProperty . Это дает возможность указать список из одного или нескольких сортируемых средств и порядок сортировки.

Учтите, что сортировка результатов в настоящее время поддерживается только для следующих типов SharePoint и OneDrive: driveItem, listItem, list, site.

Свойства, к которым применяется предложение sort, должны быть сортируемыми в схеме поиска SharePoint. Если свойство, указанное в запросе, не является сортируемым или не существует, в отклике будет возвращена ошибка HTTP 400 Bad Request. Обратите внимание, что нельзя задать сортировку документов по релевантности с использованием sortProperty.

При указании параметра name объекта sortProperty можно использовать имя свойства из типа Microsoft Graph (например, в driveItem) или имя управляемого свойств в индексе поиска.

Примеры сортировки результатов см. в разделе Сортировка результатов поиска.

Уточнение результатов с помощью агрегатов

Агрегаты (также называемые уточнениями в SharePoint) — это очень популярное средство, которое позволяет расширить возможности поиска. В дополнение к результатам они предоставляют некоторые обобщенные сведения о наборе данных, из которого получены результатов поиска. Например, можно представить сведения о наиболее заметных авторах документов, которые удовлетворяют запросу, или о самых распространенных типах файлов и т. д.

В searchRequest укажите агрегаты, которые надо получить в дополнение к результатам поиска. Описание каждого агрегата приведено в aggregationOption, где указывается свойство, на основе которого будет рассчитываться агрегат, и количество объектов searchBucket, возвращаемое в отклике.

Свойства, по которым запрашивается агрегат, должны быть уточняемыми в схеме поиска SharePoint. Если указанное свойство не является уточняемым или не существует, отклик возвращаетHTTP 400 Bad Request.

Когда будет получен отклик, содержащий набор объектов searchBucket, можно уточнить поисковый запрос, ограничив его только совпадающими элементами из одного объекта searchBucket. Это достигается путем передачи обратного значения aggregationsFilterToken в свойстве aggregationFilters последующего searchRequest.

В настоящий момент агрегаты поддерживаются для любого свойства с возможностью уточнения в следующих типах SharePoint и OneDrive: driveItem, listItem, list, site и в соединителях Microsoft Graph externalItem.

Примеры использования агрегатов для улучшения и снижения объема результатов поиска см. в разделе Уточнение результатов поиска.

Исправление орфографии в запросе

Исправление орфографии — популярный способ обработки несоответствий между опечатками в запросе пользователя и правильными словами в содержимом. При обнаружении опечаток в исходном пользовательском запросе вы можете получить результат поиска для исходного запроса пользователя или исправленной версии запроса. Вы также можете получить сведения об исправлении опечаток в свойстве queryAlterationResponse объекта searchResponse.

В тексте запроса метода query укажите queryAlterationOptions для применения с целью исправления орфографии в запросе. Описание queryAlterationOptions определяется в searchRequest.

Примеры использования исправлений орфографии см. в разделе Исправление орфографии в запросе.

Макет отображения при поиске

API поиска позволяет отображать результаты поиска из соединителей при помощи макета отображения или шаблона результатов, настроенного ИТ-администратором для каждого соединителя. Шаблоны результатов — это адаптивные карточки, которые являются семантически значимым сочетанием макета и данных.

Чтобы получить шаблон результатов в searchResponse, присвойте свойству enableResultTemplate значение true, которое определяется в resultTemplateOptions в searchRequest. Отклик включает resultTemplateId для каждого объекта searchHit, который сопоставляется с одним из макетов отображения, включенных в словарь resultTemplates, являющийся частью отклика.

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

Обработка ошибок

API поиска возвращает отклики с ошибками, описанные в определении объектов ошибок OData, каждый из которых представляет собой объект JSON, содержащий код и сообщение.

Известные ограничения

На API поиска распространяются описанные ниже ограничения.

  • Метод query определяется, чтобы разрешить передачу коллекции из одного или нескольких экземпляров searchRequest. Однако в настоящее время служба может обрабатывать только по одному экземпляру searchRequest за раз.

  • Ресурс searchRequest поддерживает одновременную передачу объектов нескольких типов. В следующей таблице перечислены поддерживаемые сочетания.

    Тип сущности acronym bookmark message chatMessage drive driveItem event externalItem список listItem person qna site
    acronym Да Да - - - - - - - - - Да -
    bookmark Да Да - - - - - - - - - Да -
    chatMessage - - - Верно - - - - - - - - -
    drive - - - - Да Да - Да Да Да - - Да
    driveItem - - - - Да Да - Да Да Да - - Да
    event - - - - - - Верно - - - - - -
    externalItem - - - - Да Да - Да Да Да - - Да
    список - - - - Да Да - Да Да Да - - Да
    listItem - - - - Да Да - Да Да Да - - Да
    message - - Верно - - - - - - - - - -
    person - - - - - - - - - - Верно - -
    qna Да Да - - - - - - - - - Да -
    site - - - - Да Да - Да Да Да - - Да

  • Свойство contentSource, определяющее используемое соединение, применимо только при присвоении свойству entityType значения externalItem.

  • API поиска не поддерживает настраиваемую сортировку для аббревиатуры, закладки, сообщения, chatMessage, event, person, qna или externalItem.

  • API поиска не поддерживает агрегаты для аббревиатуры, закладки, сообщения, события, сайта, человека, qna или диска.

  • API поиска не поддерживает xrank для аббревиатуры, закладки, сообщения, chatMessage, event, person, qna или externalItem.

  • Гостевой поиск не поддерживает поиск по аббревиатуре, закладке, сообщению, chatMessage, event, person, qna или externalItem.

  • Настройки в поиске SharePoint, такие как пользовательская схема поиска или источники результатов, могут мешать операциям API поиска (Майкрософт).

  • API поиска не поддерживает схему поиска на уровне сайта. Используйте схему поиска на уровне клиента или схему поиска по умолчанию.

Связанные материалы