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

Область применения: Azure Logic Apps (потребление)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для выполнения задач приложениями логики пользовательский 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.

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

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

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

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

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

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

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

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

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

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

Ожидание передачи новых данных или информации о событиях с помощью модели триггера веб-перехватчика

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

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

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

В настоящее время конструктор рабочих процессов не поддерживает обнаружение конечных точек веб-перехватчика с помощью Swagger. Поэтому для модели необходимо добавить триггер веб-перехватчика и указать 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.

Поддержка

• За специализированной помощью по пользовательским API обращайтесь по адресу [email protected].

• Если у вас есть вопросы, посетите страницу вопросов и ответов по Azure Logic Apps на сайте Майкрософт.

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

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