Шаблоны для пользовательских веб-API и REST API, которые можно вызывать из Azure Logic Apps

Применяется к: Azure Logic Apps (Расход + Стандарт)

Хотя Azure Logic Apps предлагает более 1400 соединителей, которые можно использовать в рабочих процессах логических приложений, может потребоваться вызывать API, системы и службы, которые недоступны в виде соединителей. Вы можете создавать собственные API с действиями и триггерами для использования в рабочих процессах. Ниже приведены другие причины создания собственных интерфейсов API, которые можно вызывать из рабочих процессов.

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

В основном соединители — это веб-API, использующие REST для подключаемых интерфейсов, формат метаданных OpenAPI для документации и JSON в качестве формата обмена данными. Соединители являются интерфейсами REST API, которые обмениваются данными через конечные точки HTTP, и для их создания можно использовать любой язык, например .NET, Java, Python или Node.js. Интерфейсы API также можно разместить в службе приложений Azure. Это платформа как услуга (PaaS), предоставляющая один из лучших, самых простых и масштабируемых способов размещения API.

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

API-интерфейсы можно разместить в службе приложений Azure. Это служба PaaS (платформа как услуга), предоставляющая удобное размещение API с высоким уровнем масштабирования.

Чем отличаются пользовательские API от пользовательских соединителей?

Пользовательские API и пользовательские соединители — это веб-API, использующие REST для подключаемых интерфейсов , формат метаданных OpenAPI для документации и JSON в качестве формата обмена данными. Так как API и соединители являются интерфейсами REST API, которые обмениваются данными через конечные точки HTTP, то для создания пользовательских API и соединителей можно использовать любой язык, например .NET, Java, Python или Node.js.

Пользовательские API позволяют вызывать API, не являющиеся соединителями, и предоставлять конечные точки, которые можно вызывать с помощью HTTP + Swagger, службы управления Azure API или служб приложений. Пользовательские соединители работают как пользовательские API, но кроме этого имеют следующие атрибуты:

• Зарегистрированы в качестве ресурсов коннектора Logic Apps в Azure.
• отображаются в конструкторе Logic Apps со значками рядом с соединителями, управляемыми корпорацией Майкрософт;
• Доступно только авторам соединителей и пользователям ресурсов Logic Apps, которые имеют общий клиент Microsoft Entra и подписку Azure в регионе, где развернуты приложения Logic Apps.

Вы также можете предложить зарегистрированные соединители для сертификации Майкрософт. Этот процесс позволяет проверить зарегистрированные соединители на соответствие критериям для общего использования и делает эти соединители доступными для пользователей в Power Automate и Microsoft Power Apps.

Дополнительные сведения см. в следующей документации:

• Обзор настраиваемых соединителей
• Создание пользовательских соединителей из веб-API
• Register custom connectors in Azure Logic Apps (Регистрация пользовательских соединителей в Azure Logic Apps)

Полезные инструменты

Настраиваемый API лучше всего работает с приложениями логики, если API также содержит документ OpenAPI, описывающий операции и параметры API. Есть много библиотек, например Swashbuckle, которые могут автоматически создавать файл Swagger. Чтобы аннотировать файл Swagger для отображаемых имен, типов свойств и т. д., вы также можете использовать TRex, чтобы ваш файл Swagger хорошо работал с приложениями логики.

Модели действий

Для выполнения задач приложениями логики пользовательский API должен предоставлять определенные действия. Каждая операция в API сопоставляется с действием. Базовое действие — это контроллер, который принимает запросы HTTP и возвращает ответы HTTP. Например, рабочий процесс отправляет запрос HTTP в веб- или API-приложение. Ваше приложение затем возвращает ответ HTTP вместе с содержимым, которое может быть обработано рабочим процессом.

Для стандартных действий можно написать метод HTTP-запроса в API и описать этот метод в файле Swagger. Затем можно напрямую вызвать API при помощи действия HTTP или HTTP + Swagger. По умолчанию ответы должны возвращаться в пределах времени ожидания запроса.

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

Выполнение длительных задач с помощью шаблона действия опроса

Чтобы в API выполнялись задачи, длительность обработки которых превышает предельное время ожидания запроса, можно использовать асинхронную модель опроса. Эта модель обеспечивает работу API в отдельном потоке, сохраняя активное подключение к обработчику Azure Logic Apps. Таким образом, рабочий процесс не отключится по истечении времени ожидания и не перейдет к следующему действию в рабочем процессе, пока API не завершит работу.

Общая схема работы

1. Убедитесь, что обработчик получил данные о том, что API принял запрос и начал его выполнение.
2. При последующих запросах о состоянии задания со стороны обработчика необходимо уведомить его, когда ваш API завершит выполнение задачи.
3. Возвратите актуальные данные в систему, чтобы рабочий процесс мог продолжиться.

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

Перейдем к сопоставлению этой модели опроса. Кондитерская представляет ваш собственный API, а вы, клиент, представляете систему Azure Logic Apps. Когда движок обращается к вашему API с запросом, ваш API подтверждает запрос и сообщает временной интервал, в течение которого движок может проверять состояние задания. Обработчик продолжает проверять состояние задания, пока API не ответит, что оно выполнено. Затем данные возвращаются в приложение логики и рабочий процесс возобновляется.

Здесь перечислены конкретные шаги, которые должен выполнить API, описанные с точки зрения самого API.

1. При получении API HTTP-запроса на начало работы немедленно должен возвращаться ответ HTTP 202 ACCEPTED с заголовком location, описанным далее в этом шаге. Этот ответ сообщает движку Azure Logic Apps, что ваш API получил запрос, принял полезную нагрузку (входные данные), и теперь выполняется обработка.

   Ответ 202 ACCEPTED должен содержать описанные ниже заголовки.

   • Обязательный: заголовок location, который указывает абсолютный путь к URL-адресу, по которому обработчик Azure Logic Apps сможет проверить состояние задания API.

   • Необязательный: заголовок retry-after, который указывает для обработчика количество секунд ожидания перед проверкой состояния задания по URL-адресу location.

     По умолчанию подсистема опрашивает location URL-адрес после одной секунды. Чтобы задать другой интервал, включите в ответ заголовок retry-after и количество секунд до следующей операции опроса.

2. По истечении указанного времени обработчик Azure Logic Apps выполняет опрос по URL-адресу location, чтобы проверить состояние задания. После этих проверок из API должны поступать следующие ответы:

   • Если задание выполнено, возвращается ответ HTTP 200 OK вместе с полезной нагрузкой ответа (входными данными для следующего шага).

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

Если в API применена эта модель, в определении рабочего процесса не нужно выполнять никаких действий, чтобы продолжать проверку состояния задания. Когда обработчик получает ответ HTTP 202 ACCEPTED с допустимым заголовком location, он действует в соответствии с асинхронной моделью и проверяет заголовок location, пока из API не поступит ответ, отличный от 202.

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

В качестве альтернативы можно использовать шаблон вебхука для длительно выполняемых задач и асинхронной обработки. Эта модель приостанавливает рабочий процесс и переводит его в режим ожидания "обратного вызова" из API, чтобы завершить обработку перед продолжением рабочего процесса. Этот обратный вызов является запросом HTTP POST. Когда происходит событие, он отправляет сообщение по URL-адресу.

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

Когда мы возвращаемся к модели веб-перехватчика, кондитерская — это ваш пользовательский API, а вы, заказчик торта, — это движок Azure Logic Apps. Движок вызывает ваш API с запросом, включая URL обратного вызова. Выполнив задание, API использует URL-адрес для оповещения обработчика и возврата данных в приложение логики, которое возобновляет рабочий процесс.

Для этой модели настройте на контроллере две конечные точки: subscribe иunsubscribe

• Конечная точка subscribe: когда выполнение достигает действия вашего API в рабочем процессе, движок Azure Logic Apps вызывает конечную точку subscribe. После этого рабочий процесс создает URL-адрес обратного вызова, который сохраняется в API, и ожидает от API обратного вызова по завершении работы. Затем API выполняет обратный вызов с запросом HTTP POST по URL-адресу и передает любое полученное содержимое и заголовки в качестве входных данных для приложения логики.

• Конечная точка unsubscribe: при отмене выполнения рабочего процесса обработчик Azure Logic Apps вызывает конечную точку unsubscribe. В таком случае API может отменить регистрацию URL-адреса обратного вызова и при необходимости остановить любые процессы.

В настоящее время дизайнер рабочих процессов не поддерживает обнаружение конечных точек веб-перехватчика с помощью Swagger. Поэтому для этого шаблона необходимо добавить действие Webhook и указать URL-адрес, заголовки и тело запроса. Также см. раздел Действия и триггеры рабочего процесса. Пример модели веб-перехватчика см. в образце триггера веб-перехватчика в GitHub.

Вот еще несколько советов и замечаний:

• Чтобы передать URL-адрес обратного вызова, можно при необходимости использовать функцию рабочего процесса @listCallbackUrl() в любом предыдущем поле.

• Если у вас есть как ресурс приложения логики, так и подписной сервис, вам не нужно вызывать конечную точку unsubscribe после обращения по URL-адресу обратного вызова. В противном случае среде выполнения Azure Logic Apps потребуется вызвать конечную точку unsubscribe, чтобы сообщить о том, что вызовов больше не ожидается, и разрешить очистку ресурсов на стороне сервера.

Модели триггеров

Пользовательский API может действовать как триггер, запускающий выполнение рабочего процесса, если новые данные или событие соответствует заданному условию. Этот триггер может как выполнять регулярную проверку, так и ожидать передачи новых данных или информации о событиях в конечной точке службы. Если новые данные или событие соответствуют заданному условию, триггер срабатывает и запускает приложение логики, которое отслеживает этот триггер. Для такого запуска логических приложений ваш API может следовать модели опрашивающего триггера или модели триггера веб-перехватчика. Эти шаблоны похожи на их аналоги для действий опроса и действий веб-перехватчика. Узнайте больше о учете использования триггеров.

Регулярная проверка наличия новых данных или событий при помощи модели опрашивающего триггера

Опрашивающий триггер работает так же, как и действие опроса, описанное ранее в этой статье. Обработчик Azure Logic Apps периодически вызывает и проверяет конечную точку триггера на наличие новых данных или событий. Если обработчик обнаруживает новые данные или событие, соответствующие указанным условиям, триггер срабатывает. Затем обработчик создает экземпляр рабочего процесса, который обрабатывает данные в качестве входных.

Ниже описаны конкретные действия опрашивающего триггера с точки зрения API.

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

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

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

• Конечная точка subscribe: при добавлении и сохранении триггера веб-перехватчика в приложении логики движок Azure Logic Apps вызывает конечную точку subscribe. После этого рабочий процесс создает URL-адрес обратного вызова, который сохраняется в API. Если есть новые данные или событие, которое соответствуют заданному условию, API выполняет обратный вызов по URL-адресу при помощи HTTP POST. Полезная нагрузка данных и заголовки передаются в логическое приложение в качестве входных данных.

• Конечная точка unsubscribe: при удалении триггера веб-перехватчика или всего ресурса логического приложения движок Azure Logic Apps вызывает конечную точку unsubscribe. В таком случае API может отменить регистрацию URL-адреса обратного вызова и при необходимости остановить любые процессы.

В настоящее время дизайнер рабочих процессов не поддерживает обнаружение конечных точек веб-перехватчика с помощью Swagger. Поэтому для этого шаблона необходимо добавить Webhook триггер и указать URL-адрес, заголовки и тело запроса. См. также Триггер HTTPWebhook. Для примера шаблона веб-перехватчика ознакомьтесь с образцом контроллера триггера веб-перехватчика на GitHub.

Вот еще несколько советов и замечаний:

• Чтобы передать URL-адрес обратного вызова, можно при необходимости использовать функцию рабочего процесса @listCallbackUrl() в любом предыдущем поле.

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

• Если у вас есть как ресурс приложения логики, так и подписной сервис, вам не нужно вызывать конечную точку unsubscribe после обращения по URL-адресу обратного вызова. В противном случае среде выполнения Logic Apps потребуется вызвать конечную точку unsubscribe, чтобы сообщить о том, что вызовов больше не ожидается, и разрешить очистку ресурсов на стороне сервера.

Улучшите безопасность обращений к вашим API из логических приложений.

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

Разверните и вызовите ваши API

После настройки аутентификации настройте развертывание своих API. Узнайте, как развертывать и вызывать пользовательские API из приложений логики.

Публикация пользовательских API в Azure

Чтобы сделать пользовательские API доступными для других пользователей Azure Logic Apps, необходимо повысить безопасность и зарегистрировать их как соединители Azure Logic Apps. Дополнительные сведения см. в разделе Обзор настраиваемых соединителей.

Чтобы сделать пользовательские API доступными для всех пользователей в Logic Apps, Power Automate и Microsoft Power Apps, необходимо добавить безопасность, зарегистрировать эти API как соединители Azure Logic Apps и представить свои соединители для программы сертификации Microsoft Azure.

Следующие шаги

• Обработка ошибок и исключений
• Вызвать, активировать триггеры или вложить приложения логики с конечными точками HTTP
• Метрирование использования для действий и триггеров