Создание, обновление и удаление подключений в Microsoft Graph

Статья
12/21/2023

Платформа соединителей Microsoft Graph предлагает интуитивно понятный способ добавления внешних данных в Microsoft Graph. Подключение — это логический контейнер для внешних данных, которыми администратор управляет как единым целым.

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

Пример структуры пользовательской системы службы поддержки Tickets Connector.

Образец пользовательской структуры системы поддержки Tickets Connector.

Административный вид подключений, включая настраиваемый Tickets Connector.

Административный вид подключений, включая настраиваемый Tickets Connector.

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

Состояния и операции

Подключение может находиться в одном из следующих состояний:

Состояние	Описание
Draft	Будет подготовлено пустое подключение. Источник данных, схема или параметры не настроены.
Ready	Соединение подготовлено с помощью зарегистрированной схемы и готово к использованию.
Obsolete	Это происходит, если зависимая функция, например API, устарела. Единственное допустимое решение – удалить подключение.
LimitExceeded	При достижении максимального предела для одного подключения или квоты на уровне клиента для всех подключений вы не сможете добавить дополнительные элементы, пока не выйдете из состояния.

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

Операция	Draft	Ready	Obsolete	LimitExceeded
Создание подключения	❌	✔️	❌	✔️
Чтение подключения	✔️	✔️	✔️	✔️
Обновление подключения	✔️	✔️	❌	✔️
Удаление подключения	✔️	✔️	✔️	✔️
Создание схемы	✔️	❌	❌	❌
Чтение схемы	❌	✔️	✔️	✔️
Обновление схемы	❌	❌	❌	❌
Удаление схемы	❌	❌	❌	❌
Создание элемента	❌	✔️	❌	❌
Чтение элемента	❌	✔️	✔️	✔️
Обновление элемента	❌	✔️	❌	✔️
Удаление элемента	❌	✔️	❌	✔️

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

Первым шагом приложения для добавления элементов в поисковый индекс является создание соединения.

Создание подключения

Прежде чем приложение сможет добавлять элементы в поисковый индекс, оно должно создать и настроить соединение:

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

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

Параметры подключения

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

Параметры поиска

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

Параметры действий

В параметрах действий можно предоставить приложениям Microsoft 365 способ обнаружения активности общего доступа, что позволяет рекомендовать содержимое пользователям, которые взаимодействуют с этим содержимым чаще всего. Для этого добавьте urlToItemResolver. Это позволяет разрешать URL-адрес подключения, обнаруженного в приложениях Microsoft 365, в соответствующий идентификатор элемента на externalItem.

На следующем рисунке показано, как элемент может отображаться в рекомендациях в Microsoft 365.

В следующем примере показаны полезные данные activitySettings с полным разделом urlToItemResolvers . Например, когда кто-то предоставляет общий доступ к ссылке https://contoso.com/items/39483948/, он представляет внешний элемент, который был приемлен через подключение Microsoft Graph. В этом примере общая ссылка представляет externalItem с itemId .id_39483948 Это подключение указывает, как сопоставить URL-адрес с itemId этого externalItem. В этом примере это подключение имеет идентификаторcontosohr.

Обновите параметры действий, отправив запрос на исправление для подключения.

PATCH https://graph.microsoft.com/v1.0/external/connections/contosohr

С запросом на исправление отправляются следующие полезные данные activitySettings .

{
  "@odata.type": "#microsoft.graph.externalConnectors.activitySettings",
  "urlToItemResolvers": [
    {
        "@odata.type": "#microsoft.graph.externalConnectors.itemIdResolver",
          "itemId": "id_{myItemId}",  
          "priority": 1,
          "urlMatchInfo": {
            "@odata.type": "microsoft.graph.externalConnectors.urlMatchInfo",
            "baseUrls": [
              "https://contoso.com"
            ],
            "urlPattern": "/items/(?<myItemId>[0-9]+)"
          }
    }
  ]
}

В этом примере поле itemId указывает, как сформировать идентификатор внешнего элемента, который представляет URL-адрес. На itemId ссылается urlPattern (который находится в urlMatchInfo), который извлекается 39483948 в качестве идентификатора externalItem.

Вы можете предоставить список из восьми ресурсов itemIdResolver в ресурсе urlToItemResolvers для полезных данных параметров действий. Для каждого из этих ресурсов urlMatchInfo укажите значение #microsoft.graph.externalConnectors.itemIdResolver для @odata.type, целое число от одного до восьми для свойства priority и объект urlMatchInfo , содержащий список базовых URL-адресов и регулярное выражение.

При совместном использовании ссылки объекты urlMatchInfo , принадлежащие сопоставителям, применяются в порядке, указанном значениями приоритета . В порядке возрастания приоритета URL-адрес сначала сравнивается с URL-адресами в списке baseUrls в свойстве urlMatchInfo . Затем, если база URL-адреса ссылки находится в списке baseUrls , к URL-адресу применяется регулярное выражение urlPattern . Если этот шаблон совпадает, дополнительные сопоставители не применяются. Если ни один из базовых URL-адресов ссылки отсутствует в списке baseUrls или urlPattern не совпадает, следующий urlToItemResolver вычисляется до тех пор, пока не будет найдено совпадение или не будет применено дополнительных ресурсов urltoItemResolver .

Дополнительные сведения о ресурсах urlMatchInfo см. в разделе Тип urlMatchInfo.

Обновление подключения

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

Удаление подключения

Чтобы удалить все элементы, которые были проиндексированы через соединение, вы можете удалить соединение.

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