Создание, обновление и удаление элементов, добавленных приложением с помощью соединителей Microsoft Graph

Соединители Microsoft Graph — это интуитивно понятный способ добавления внешних данных в Microsoft Graph. Элементы, добавляемые приложением в microsoft служба , представлены ресурсом externalItem в Microsoft Graph.

После создания соединения вы можете добавить содержимое. Каждый элемент из источника данных должен быть представлен в виде externalItem в Microsoft Graph с уникальным идентификатором элемента. Этот идентификатор используется для создания, обновления или удаления элемента в Microsoft Graph. Вы можете использовать первичный ключ из источника данных в качестве ИД элемента или получить его из одного или нескольких полей.

Ключевые компоненты

externalItem содержит три основных компонента: список управления доступом, свойства и содержимое.

Список управления доступом

Список управления доступом (ACL) используется для указания того, предоставляется ли определенным ролям доступ для просмотра элементов в интерфейсах Майкрософт. ACL — это массив записей управления доступом, представляющих пользователя или группу Microsoft Entra. Существует третий тип записей управления доступом: Everyone, представляющий всех пользователей в клиенте.

Пример списка управления доступом.

Значение accessTypedeny имеет приоритет над grant. Например, хотя в указанном ранее элементе доступ предоставлен с помощью параметра Everyone, а конкретному пользователю доступ запрещен, действующим разрешением для этого пользователя будет вариант deny.

Если ваш источник данных не содержит групп Azure AD (например, группы в вашей службе поддержки), применяемых для настройки разрешений для элемента, вы можете создать внешние группы в Microsoft Graph, используя API синхронизации группы для репликации разрешений allow или deny. Избегайте расширения участия ваших внешних групп непосредственно в списках управления доступом отдельных элементов, так как каждое участие группы может привести к многочисленным обновлениям элементов.

Внешние группы включают другую группу, Microsoft Entra пользователей и Microsoft Entra группы. Если у вас есть пользователи, не являющиеся Azure AD, необходимо преобразовать их в Microsoft Entra пользователей в ACL.

Свойства

С помощью компонента свойств можно добавлять метаданные элементов, которые удобно применять в интерфейсах Microsoft Graph. Вы должны зарегистрировать схему для связи перед добавлением в нее элементов и преобразованием типов данных в поддерживаемые типы данных.

Пример компонента свойства.

Содержимое

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

Содержимое — одно из ключевых полей, влияющих на релевантность в интерфейсах Майкрософт. Поддерживаются типы контента: text и html. Если источник данных содержит контент других типов, например двоичные файлы, видео или изображения, вы можете преобразовать их в текстовую форму перед добавлением в Microsoft Graph. Например, оптическое распознавание символов может извлекать из изображений доступный для поиска текст.

Важно!

Решение для соответствия требованиям поддерживает text только тип контента. Если вы включите подключение для соответствия требованиям, задав для свойства enabledContentExperience значение compliance, необходимо принять содержимое в формате обычного текста и задать для типа контента значение text.

Пример компонента содержимого.

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

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

При изменении содержимого в источнике данных вы должны синхронизировать его с элементами связи. Вы можете обновить весь элемент или один или несколько компонентов. После добавления содержимого в Microsoft Graph его можно найти в интерфейсе Microsoft Поиск после настройки вертикали поиска и типов результатов или с помощью API Поиск Microsoft Graph.

Действия

Компонент действий — это временное свойство, которое отправляет действия для элемента. Запись можно выполнять только в это свойство.

Действие состоит из субъекта (выполнившего действие), времени (когда было выполнено действие) и типа действия (какой тип действия было выполнено). Поддерживаемые в настоящее время типы действий можно найти в разделе Описание свойства type для externalActivity.

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

Добавление элемента

Чтобы добавить элемент в индекс, необходимо создать externalItem. При создании элемента ему назначается уникальный идентификатор в URL-адресе.

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

PUT /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json

"properties": {
  "title": "WiFi outage in Conference Room A",
  "priority": 1,
  "assignee": "meganb@contoso.com"
}

Примечание.

Перед поиском индексированных элементов в пользовательском интерфейсе "Поиск (Майкрософт)", администратор должен настроить страницу результатов поиска для соответствующего подключения.

Добавление действий в элемент

Чтобы добавить действия к элементу, вызовите конечную точку addActivities с тем же уникальным идентификатором этого элемента в URL-адресе.

Например, если пользователь с Microsoft Entra ID 18948b93-d3ed-4307-9981-10fc36a08a52 прокомментировал запрос в службу поддержки с номером SR00145 билета 11 апреля 2022 г. в 16:25, запрос на отправку этого действия может выглядеть следующим образом.

POST /external/connections/contosohelpdesk/items/SR00145/addActivities
Content-Type: application/json

"activities": [
 {
   "type": "commented",
   "startDateTime": "2022-04-11T16:25:34.3202005Z",
   "performedBy": {
       "id": "18948b93-d3ed-4307-9981-10fc36a08a52",
       "type": "user"
    }
  }
]

Вы также можете добавить действие к элементу в том же запросе, который создает элемент. Добавьте действие в качестве другой сущности, например acl и content. Если вы добавляете действие таким образом, включите @odata.type для действия или запрос завершится ошибкой. Действия с метками времени старше семи дней не отображаются в приложении Microsoft 365. Конечные пользователи могут видеть только действия в приложении Microsoft 365 для элементов, к которым они могут получить доступ, и иметь действия (например, предоставить им общий доступ, создать, изменить и т. д.).

Обновление элемента

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

PATCH /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json

{
  "assignee": "alexw@contoso.com"
}

Удаление элемента

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

DELETE /external/connections/contosohelpdesk/items/SR00145

Синхронизация данных

При выборе способа синхронизации данных учитывайте следующие сведения:

Механизм обхода контента:

• Добавочное сканирование: обнаруживает и отправляет дополнения в исходные данные; менее высокая производительность по сравнению с полным обходом контента.
• Полный обход контента: Обновления весь элемент из исходных данных (повторное обход), захват всех добавлений и удалений; обеспечивает лучшую точность, но более трудоемкий и ресурсоемкий процесс, чем добавочный обход контента.

Интервал синхронизации:

• На основе событий. Отправляет обновления элементов на основе события. Рекомендуется использовать этот интервал синхронизации для динамических или конфиденциальных данных, таких как состояние элемента.
• По расписанию: отправляет обновления элементов через регулярные интервалы (каждые N минут). Рекомендуется использовать этот интервал синхронизации для содержимого или не конфиденциальных данных, которые реже обновляются, например для вики-сайтов или веб-страниц.

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

Дальнейшие действия

• Использование внешних групп для управления разрешениями
• Запросы с использованием API Поиска (Майкрософт)
• Обзор справочника API соединителей Microsoft Graph
• Поиск объектов настраиваемого типа (externalItem)
• Скачайте образец соединителя поиска с сайта GitHub