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

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

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

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

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

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

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

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

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

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

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

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

Вы можете указать произвольный текст ключевых слов (например, AND и OR) и ограничения свойств в синтаксисе KQL в фактической строке поискового запроса (свойства query в тексте запроса query). Оператор XRANK повышает динамический ранг элементов на основе определенных вхождений термина в выражении match, не изменяя, какие элементы соответствуют запросу. Синтаксис и команда зависят от типов объектов (в свойстве 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 последующего поискового запроса.

В настоящее время агрегаты поддерживаются для любого уточняемого свойства в следующих типах SharePoint и OneDrive: driveItem, listItem, list, site и в соединителях Copilot 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	Вопросы и ответы	site
  acronym	Да	Да	-	-	-	-	-	-	-	-	-	Да	-
  bookmark	Да	Да	-	-	-	-	-	-	-	-	-	Да	-
  chatMessage	-	-	-	Верно	-	-	-	-	-	-	-	-	-
  drive	-	-	-	-	Да	Да	-	Да	Да	Да	-	-	Да
  driveItem	-	-	-	-	Да	Да	-	Да	Да	Да	-	-	Да
  event	-	-	-	-	-	-	Верно	-	-	-	-	-	-
  externalItem	-	-	-	-	Да	Да	-	Да	Да	Да	-	-	Да
  список	-	-	-	-	Да	Да	-	Да	Да	Да	-	-	Да
  listItem	-	-	-	-	Да	Да	-	Да	Да	Да	-	-	Да
  message	-	-	Верно	-	-	-	-	-	-	-	-	-	-
  person	-	-	-	-	-	-	-	-	-	-	Верно	-	-
  Вопросы и ответы	Да	Да	-	-	-	-	-	-	-	-	-	Да	-
  site	-	-	-	-	Да	Да	-	Да	Да	Да	-	-	Да

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

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

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

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

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

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

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

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

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

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

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

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

• Подробнее о некоторых основных вариантах использования:

  • Поиск сообщений Teams
  • Поиск сообщений Outlook
  • Поиск событий календаря
  • Поиск человека
  • Поиск содержимого в OneDrive и SharePoint
  • Поиск пользовательских типов, импортированных с помощью соединителей
  • Свернуть результаты поиска
  • Сортировка результатов поиска
  • Уточнение результатов поиска
  • Исправление орфографии в запросе
  • Использование макета отображения при поиске
  • Поиск с разрешениями приложения
  • Результаты поиска XRANK
  • Результаты поиска чередования

• Узнайте больше об API поиска в песочнице Graph.