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

  • Статья

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

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

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

Предостережение

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

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

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

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

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

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

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

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

EntityType Область разрешений, необходимая для доступа к элементам Источник Примечание
Акроним Acronym.Read.All Поиск (Майкрософт) Аббревиатуры в Microsoft Поиск в вашей организации.
bookmark Bookmark.Read.All Поиск (Майкрософт) Закладки в Microsoft Поиск в вашей организации.
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.
externalItem ExternalItem.Read.All Соединители Microsoft Graph Все содержимое, размещаемое с помощью API соединителей Microsoft Graph.
person People.Read Exchange Online Личные контакты и контакты или адресуемые объекты в организации.
qna QnA.Read.All Поиск (Майкрософт) Вопросы и ответы в Microsoft Поиск в вашей организации.
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 или person, можно включить в свойство fields определенные свойства сущности, которые следует возвратить в результатах поиска. Аналогично используется параметр $select системного запроса OData в запросах REST. API поиска технически не поддерживает эти параметры запроса, так как поведение выражается в тексте POST.

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

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

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

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

  • ListItem не возвращает настраиваемое поле.
  • driveItem вернет внутренний 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.

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

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

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

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

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

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

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

Свойства, к которым применяется предложение сортировки, должны быть сортируемыми в схеме поиска 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.

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

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

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

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

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

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

API Поиск позволяет гостевым пользователям искать элементы в SharePoint или OneDrive, к которым им предоставлен общий доступ. Чтобы получить доступ к списку гостевых пользователей, перейдите к Центр администрирования Microsoft 365, а затем в области навигации слева выберите Пользователи, а затем — Гостевые пользователи.

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

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, такие как настраиваемая схема поиска или источники результатов, могут мешать операциям MICROSOFT Поиск API.

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

Предупреждение об устаревании изменений схемы

Начиная с 31 августа 2023 г. бета-версия ресурса externalItem в пространстве имен Microsoft Graph будет нерекомендуемой. В дальнейшем используйте версию ресурса в пространстве имен Microsoft.Graph.ExternalConnectors . Убедитесь, что все зависимости пространства имен обновляются до указанной даты. Кроме того, можно перейти на версию API версии 1.0.

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

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

Ресурс Тип изменения Первоначальное свойство Текущее свойство
searchRequest Переименованное свойство stored_fields fields
searchQuery Переименованное свойство query_string queryString
searchQueryString Устаревший ресурс Неприменимо Неприменимо
searchHit Переименованное свойство _id hitId
searchHit Переименованное свойство _score rank
searchHit Удаленное свойство _sortField Неприменимо
searchHit Переименованное свойство _source resource
searchHit Переименованное свойство _summary summary
entityTypes Переименование значения перечисления unknownfuturevalue unknownFutureValue

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