Создание пользовательского соединителя пакетной службы Microsoft Graph JSON для Power Automate
Существует более 230 готовых соединителей для Microsoft Power Automate. Многие из этих соединителей используют Microsoft Graph для связи с определенными конечными точками продуктов Майкрософт. Кроме того, существуют и другие сценарии, в которых может потребоваться вызвать Microsoft Graph непосредственно из Power Automate, используя базовые стандартные блоки службы, так как нет соединителя, который напрямую взаимодействует с Microsoft Graph для охвата всего API.
Помимо сценариев прямого вызова Microsoft Graph, ряд конечных точек API Microsoft Graph поддерживают только делегированные разрешения. Соединитель HTTP в Microsoft Power Automate обеспечивает очень гибкую интеграцию, включая вызов Microsoft Graph. Однако соединитель HTTP не имеет возможности кэширования учетных данных пользователя для включения конкретных сценариев делегированных разрешений. В таких случаях можно создать пользовательский соединитель для предоставления оболочки вокруг API Microsoft Graph и включения использования API с делегированными разрешениями.
В этой лаборатории рассматриваются оба описанных выше сценария. Сначала вы создадите пользовательский соединитель для включения интеграции с Microsoft Graph, для которой требуются делегированные разрешения. Во-вторых, вы будете использовать конечную точку запроса $batch, чтобы предоставить доступ к полной мощности Microsoft Graph при использовании делегированных разрешений, для которых требуется, чтобы в приложении присутствовал пользователь , вошедшего в систему.
Примечание.
Это руководство по созданию пользовательского соединителя для использования в Microsoft Power Automate и Azure Logic Apps. В этом руководстве предполагается, что вы ознакомились с обзором пользовательского соединителя , чтобы понять процесс.
Предварительные условия
Чтобы выполнить это упражнение в этой записи, вам потребуется следующее:
- Доступ администратора к арендатору Microsoft 365. Если у вас нет клиента Microsoft 365, вы можете претендовать на него в рамках Программы разработчиков Microsoft 365. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.
- Доступ к Microsoft Power Automate с лицензией Premium. Дополнительные сведения см. в разделе Часто задаваемые вопросы о лицензировании Power Automate . Если у вас нет лицензии Premium, вы можете зарегистрироваться для получения 90-дневной пробной версии.
Отзывы
Оставьте отзыв об этом руководстве в репозитории GitHub.
Создание регистрации приложения в Azure AD
В этом упражнении вы создадите новое приложение Azure Active Directory, которое будет использоваться для предоставления делегированных разрешений для пользовательского соединителя.
Откройте браузер и перейдите в Центр администрирования Microsoft Entra и войдите с помощью учетной записи глобального администратора.
Выберите Идентификатор Microsoft Entra в области навигации слева, разверните узел Удостоверение, Приложения, а затем выберите Регистрация приложений.
Выберите пункт меню Новая регистрация в верхней части колонки Регистрация приложений .
Введите MS Graph Batch App в поле Имя . В разделе Поддерживаемые типы учетных записей выберите Учетные записи в любом каталоге организации. Оставьте раздел URI перенаправления пустым и нажмите кнопку Зарегистрировать.
Скопируйте идентификатор приложения (клиента) в колонке Пакетное приложение MS Graph. Это потребуется в следующем упражнении.
Выберите запись Разрешения API в разделе Управление в колонке Приложение пакетной службы MS Graph . Выберите Добавить разрешение в разделе Разрешения API.
В колонке Запрашивать разрешения API выберите Microsoft Graph, а затем — Делегированные разрешения.
groupНайдите и выберите делегированное разрешение Чтение и запись всех групп. Выберите Добавить разрешения в нижней части колонки.
Выберите запись Сертификаты и секреты в разделе Управление в колонке Приложение пакетной службы MS Graph , а затем выберите Новый секрет клиента. Введите описание, выберите длительность и нажмите кнопку Добавить.
Скопируйте значение для нового секрета. Это потребуется в следующем упражнении.
Важно!
Этот шаг является критически важным, так как секрет не будет доступен после закрытия этой колонки. Сохраните этот секрет в текстовом редакторе для использования в предстоящих упражнениях.
Чтобы включить управление дополнительными службами, доступными через Microsoft Graph, включая свойства Teams, необходимо выбрать дополнительные соответствующие области для управления определенными службами. Например, чтобы расширить наше решение, чтобы включить создание записных книжек OneNote или планов Планировщика, контейнеров и задач, необходимо добавить необходимые области разрешений для соответствующих API.
Создание настраиваемого соединителя
В этом упражнении вы создадите пользовательский соединитель, который можно использовать в Microsoft Power Automate или Azure Logic Apps. Файл определения OpenAPI предварительно создан с правильным путем к конечной точке Microsoft Graph $batch и дополнительными параметрами для включения простого импорта.
Откройте браузер и перейдите к Microsoft Power Automate. Войдите с помощью учетной записи администратора клиента Microsoft 365. Выберите Настраиваемые соединители в меню слева. Если в меню нет настраиваемых соединителей , выберите Дополнительно, а затем — Обнаружить все.
Существует два варианта создания пользовательского соединителя для Microsoft Graph:
- Создание из пустого
- Импорт файла OpenAPI
На странице Настраиваемые соединители выберите ссылку Создать настраиваемый соединитель в правом верхнем углу, а затем в раскрывающемся меню выберите создать из пустого элемента.
Введите MS Graph Batch Connector в текстовое поле Имя соединителя . Choose Continue.
На странице Конфигурация соединителя Общие заполните поля следующим образом.
- Схема: HTTPS
-
Узел:
graph.microsoft.com -
Базовый URL-адрес:
/
Нажмите кнопку Безопасность , чтобы продолжить.
На странице Безопасность заполните поля следующим образом.
-
Выберите, какая проверка подлинности реализована с помощью API:
OAuth 2.0 -
Поставщик удостоверений:
Azure Active Directory - Идентификатор клиента: идентификатор приложения, созданного в предыдущем упражнении.
- Секрет клиента: ключ, созданный в предыдущем упражнении
-
URL-адрес входа:
https://login.windows.net -
Идентификатор клиента:
common -
URL-адрес ресурса:
https://graph.microsoft.com(без конечного /) - Область: оставьте пустым
Нажмите кнопку Определение , чтобы продолжить.
На странице Определение выберите Создать действие и заполните поля следующим образом.
-
Сводка:
Batch -
Описание:
Execute Batch with Delegate Permission -
Идентификатор операции:
Batch -
Видимость:
important
Создайте запрос , выбрав Импорт из примера и заполните поля следующим образом.
-
Глагол:
POST -
URL-адрес:
https://graph.microsoft.com/v1.0/$batch - Заголовки: оставьте пустым
-
Текст:
{}
Нажмите Импорт.
Выберите Создать соединитель в правом верхнем углу.
После создания соединителя скопируйте созданный URL-адрес перенаправления на вкладку Безопасность .
Вернитесь к зарегистрированным приложениям на портале Microsoft Entra, созданном в предыдущем упражнении. Выберите Проверка подлинности в меню слева. Выберите Добавить платформу, а затем нажмите Интернет. Введите URL-адрес перенаправления, скопированный на предыдущем шаге, в URI перенаправления, а затем выберите Настроить.
Авторизация соединителя
Последний шаг настройки, чтобы убедиться, что соединитель готов к использованию, — авторизация и проверка пользовательского соединителя для создания кэшированного подключения.
Важно!
Для выполнения следующих действий требуется войти в систему с правами администратора.
В Microsoft Power Automate выберите Подключения в меню слева. Если в меню отсутствуют подключения, выберите Дополнительно. Выберите ссылку Создать подключение .
Найдите настраиваемый соединитель и завершите подключение, выбрав его и выбрав Создать. Войдите с учетной записью администратора клиента Microsoft 365 Azure Active Directory.
При появлении запроса на запрошенные разрешения установите флажок Согласие от имени вашей организации и нажмите кнопку Принять , чтобы авторизовать разрешения.
После авторизации разрешений в Power Automate создается подключение.
Теперь настраиваемый соединитель настроен и включен. Может возникнуть задержка в применении и доступности разрешений, но соединитель теперь настроен.
Тестирование пакетной обработки в Graph Explorer
Перед созданием потока для использования нового соединителя используйте Обозреватель Microsoft Graph , чтобы узнать о некоторых возможностях и функциях пакетной обработки JSON в Microsoft Graph.
Откройте Обозреватель Microsoft Graph в браузере. Войдите с помощью учетной записи администратора клиента Microsoft 365. Выполните поиск по запросу Пакетная служба из примеров запросов.
Выберите пример запроса Выполнение параллельных ГЕТ в меню слева. Нажмите кнопку Выполнить запрос в правом верхнем углу экрана.
Пример пакетной операции пакетирует три HTTP-запроса GET и отправляет один HTTP POST в конечную точку /v1.0/$batch Graph.
{
"requests": [
{
"url": "/me?$select=displayName,jobTitle,userPrincipalName",
"method": "GET",
"id": "1"
},
{
"url": "/me/messages?$filter=importance eq 'high'&$select=from,subject,receivedDateTime,bodyPreview",
"method": "GET",
"id": "2"
},
{
"url": "/me/events",
"method": "GET",
"id": "3"
}
]
}
Возвращенный ответ показан ниже. Обратите внимание на массив ответов, возвращаемых Microsoft Graph. Ответы на пакетные запросы могут выглядеть в порядке, отличном от порядка запросов в POST. Свойство id должно использоваться для корреляции отдельных пакетных запросов с конкретными пакетными ответами.
Примечание.
Ответ был усечен для удобства чтения.
{
"responses": [
{
"id": "1",
"status": 200,
"headers": {...},
"body": {...}
},
{
"id": "3",
"status": 200,
"headers": {...},
"body": {...}
}
{
"id": "2",
"status": 200,
"headers": {...},
"body": {...}
}
]
}
Каждый ответ содержит idсвойство , status, headersи body .
status Если свойство для запроса указывает на сбой, объект содержит все сведения об ошибке, body возвращенные запросом.
Чтобы обеспечить порядок операций для запросов, отдельные запросы можно упорядочить с помощью свойства dependsOn .
Помимо операций виртуализации и зависимостей пакетная обработка JSON предполагает базовый путь и выполняет запросы из относительного пути. Каждый элемент пакетного запроса выполняется из конечных /v1.0/$batch точек OR /beta/$batch , как указано. Это может иметь значительные различия, так как /beta конечная точка может возвращать дополнительные выходные данные, которые не могут быть возвращены в конечной точке /v1.0 .
Например, выполните следующие два запроса в обозревателе Microsoft Graph.
- Запросите конечную
/v1.0/$batchточку с помощью URL-адреса/me(запрос на копирование и вставку ниже).
{
"requests": [
{
"id": 1,
"url": "/me",
"method": "GET"
}
]
}
Теперь используйте раскрывающийся список селектора версий, чтобы изменить конечную точку beta и выполнить тот же запрос.
Каковы различия в возвращаемых результатах? Попробуйте другие запросы, чтобы определить некоторые различия.
В дополнение к содержимому ответов из /v1.0 конечных точек и /beta важно понимать возможные ошибки при выполнении пакетного запроса, для которого не было предоставлено согласие на разрешение. Например, ниже приведен элемент пакетного запроса для создания записной книжки OneNote.
{
"id": 1,
"url": "/groups/65c5ecf9-3311-449c-9904-29a2c76b9a50/onenote/notebooks",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Meeting Notes"
}
}
Однако если разрешения на создание записных книжек OneNote не предоставлены, будет получен следующий ответ. Обратите внимание на код 403 (Forbidden) состояния и сообщение об ошибке, указывающее, что предоставленный маркер OAuth не включает области, необходимые для выполнения запрошенного действия.
{
"responses": [
{
"id": "1",
"status": 403,
"headers": {
"Cache-Control": "no-cache"
},
"body": {
"error": {
"code": "40004",
"message": "The OAuth token provided does not have the necessary scopes to complete the request.
Please make sure you are including one or more of the following scopes: Notes.ReadWrite.All,
Notes.Read.All (you provided these scopes: Group.Read.All,Group.ReadWrite.All,User.Read,User.Read.All)",
"innerError": {
"request-id": "92d50317-aa06-4bd7-b908-c85ee4eff0e9",
"date": "2018-10-17T02:01:10"
}
}
}
}
]
}
Каждый запрос в пакете будет возвращать код состояния и результаты или сведения об ошибке. Необходимо обработать каждый из ответов, чтобы определить успешность или сбой отдельных пакетных операций.
Создать поток
В этом упражнении вы создадите поток для использования пользовательского соединителя, созданного в предыдущих упражнениях, для создания и настройки команды Майкрософт. Поток будет использовать пользовательский соединитель для отправки запроса POST на создание единой группы Office 365, приостанавливает с задержкой, пока создание группы завершается, а затем отправляет запрос PUT для связывания группы с командой Майкрософт.
В итоге поток будет выглядеть примерно так, как показано на следующем рисунке:
Откройте Microsoft Power Automate в браузере и войдите с учетной записью администратора клиента Office 365. Выберите Мои потоки в области навигации слева. Выберите Новый поток, а затем — Мгновенный поток облака. Введите Create Teamимя потока, а затем выберите Вручную активировать поток в разделе Выбор способа активации этого потока. Выберите пункт Создать.
Выберите элемент Вручную активировать поток , затем выберите Добавить входные данные, выберите Текст и введите Name в качестве заголовка.
Выберите + элемент в разделе Вручную активировать поток , а затем выберите Добавить действие. Введите Batch в поле поиска и задайте в раскрывающемся списке Среда выполнениязначение Пользовательский. Добавьте действие Соединитель пакетной службы MS Graph . Выберите многоточие и переименуйте это действие в Batch POST-groups.
В раскрывающемся списке Дополнительные параметры выберите текст. Добавьте следующий код в текстовое поле Текст действия.
{
"requests": [
{
"url": "/groups",
"method": "POST",
"id": 1,
"headers": { "Content-Type": "application/json" },
"body": {
"description": "REPLACE",
"displayName": "REPLACE",
"groupTypes": ["Unified"],
"mailEnabled": true,
"mailNickname": "REPLACE",
"securityEnabled": false
}
}
]
}
Замените каждый REPLACE заполнитель, выбрав Name значение в ручном триггере в меню Добавить динамическое содержимое .
Выберите + элемент Пакетная служба POST-groups и выберите Добавить действие. Найдите delay и добавьте действие Задержка и настройте в течение 1 минуты.
Выберите + элемент Задержка , а затем выберите Добавить действие. Добавьте действие Соединитель пакетной службы MS Graph . Выберите многоточие и переименуйте это действие в Batch PUT-team.
В раскрывающемся списке Дополнительные параметры выберите текст. Добавьте следующий код в текстовое поле Текст действия.
{
"requests": [
{
"id": 1,
"url": "/groups/REPLACE/team",
"method": "PUT",
"headers": {
"Content-Type": "application/json"
},
"body": {
"memberSettings": {
"allowCreateUpdateChannels": true
},
"messagingSettings": {
"allowUserEditMessages": true,
"allowUserDeleteMessages": true
},
"funSettings": {
"allowGiphy": true,
"giphyContentRating": "strict"
}
}
}
]
}
REPLACE Выберите заполнитель, а затем выберите Выражение в области динамического содержимого. Добавьте следующую формулу в выражение.
body('Batch_POST-groups').responses[0].body.id
Эта формула указывает, что мы хотим использовать идентификатор группы из результата первого действия.
Нажмите кнопку Сохранить, а затем — Тест , чтобы выполнить поток.
Совет
Если появляется сообщение об ошибке, например The template validation failed: 'The action(s) 'Batch_POST-groups' referenced by 'inputs' in action 'Batch_2' are not defined in the template', выражение является неправильным и, скорее всего, ссылается на действие потока, не удается найти. Убедитесь, что имя действия, на которое вы ссылаетесь, точно соответствует.
Нажмите переключатель Действие вручную и нажмите кнопку Тестировать. Укажите имя без пробелов и выберите Выполнить поток , чтобы создать команду.
Наконец, выберите готово , чтобы просмотреть журнал действий. После завершения потока группа и группа Office 365 будут настроены. Выберите элементы действия пакетной службы, чтобы просмотреть результаты вызовов пакетной службы JSON.
Batch PUT-team Объект outputs действия должен иметь код состояния 201 для успешного объединения Team, как показано на рисунке ниже.
Расширение потока
Поток, созданный в предыдущем упражнении, $batch использует API для выполнения двух отдельных запросов к Microsoft Graph. Вызов конечной $batch точки таким образом обеспечивает некоторое преимущество и гибкость, но истинная сила конечной $batch точки возникает при выполнении нескольких запросов к Microsoft Graph в одном $batch вызове. В этом упражнении вы расширите пример создания единой группы и связывания команды, чтобы включить создание нескольких каналов по умолчанию для команды в одном $batch запросе.
Откройте Microsoft Power Automate в браузере и войдите с учетной записью администратора клиента Microsoft 365. Выберите поток, созданный на предыдущем шаге, и нажмите кнопку Изменить.
Выберите Новый шаг и введите Batch в поле поиска. Добавьте действие Соединитель пакетной службы MS Graph . Выберите многоточие и переименуйте это действие в Batch POST-channels.
Добавьте следующий код в текстовое поле основного текста действия.
{
"requests": [
{
"id": 1,
"url": "/teams/REPLACE/channels",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Marketing Collateral",
"description": "Marketing collateral and documentation."
}
},
{
"id": 2,
"dependsOn": [
"1"
],
"url": "/teams/REPLACE/channels",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Vendor Contracts",
"description": "Vendor documents, contracts, agreements and schedules."
}
},
{
"id": 3,
"dependsOn": [
"2"
],
"url": "/teams/REPLACE/channels",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "General Client Agreements",
"description": "General Client documents and agreements."
}
}
]
}
Обратите внимание, что три приведенных выше запроса используют свойство dependsOn для указания порядка последовательности, и каждый из них будет выполнять запрос POST для создания нового канала в новой команде.
Выберите каждый экземпляр REPLACE заполнителя, а затем выберите Выражение в области динамического содержимого. Добавьте следующую формулу в выражение.
body('Batch_PUT-team').responses[0].body.id
Нажмите кнопку Сохранить, а затем — Тест , чтобы выполнить поток. Выберите переключатель Я буду выполнять действие триггера , а затем нажмите кнопку Сохранить & тест. Введите уникальное имя группы в поле Имя без пробелов и выберите Запустить поток , чтобы выполнить поток.
После запуска потока нажмите кнопку Готово , чтобы просмотреть журнал действий. После завершения потока окончательные выходные данные для действия имеют ответ состояния HTTP 201 для каждого созданного Batch POST-channels канала.
Перейдите в Microsoft Teams и войдите с учетной записью администратора клиента Microsoft 365. Убедитесь, что команда, которую вы только что создали, отображается и включает три канала, созданные запросом $batch .
Хотя приведенное выше Batch POST-channels действие было реализовано в этом руководстве как отдельное действие, вызовы для создания каналов могли быть добавлены в качестве дополнительных вызовов в Batch PUT-team действие. Это создало бы команду и все каналы в одном пакетном вызове. Дайте, что попробовать самостоятельно.
Наконец, помните, что вызовы пакетной службы JSON возвращают код состояния HTTP для каждого запроса. В производственном процессе может потребоваться объединить постобработку результатов с действием Apply to each и убедиться, что каждый отдельный ответ имеет код состояния 201 или компенсировать полученные другие коды состояния.
Поздравляем!
Вы завершили руководство по Power Automate Microsoft Graph. Теперь, когда у вас есть работающий настраиваемый соединитель, который вызывает Microsoft Graph, можно экспериментировать и добавлять новые функции. Просмотрите обзор Microsoft Graph , чтобы просмотреть все данные, к которым можно получить доступ с помощью Microsoft Graph.
Отзывы
Оставьте отзыв об этом руководстве в репозитории GitHub.
Возникла проблема с этим разделом? Если это так, отправьте нам отзыв, чтобы мы исправили этот раздел.