Создание пользовательского соединителя из определения OpenAPI
Примечание
Эта статья входит в серию руководств по созданию и использованию пользовательских соединителей в Azure Logic Apps, Microsoft Power Automate и Microsoft Power Apps. Обязательно прочитайте обзор пользовательских соединителей, чтобы понять процесс.
Чтобы создать пользовательский соединитель, нужно описать API, к которому вы хотите подключиться, чтобы соединитель получил информацию о структурах данных и операциях API. В этой теме вы создадите пользовательский соединитель, используя определение OpenAPI, которое описывает API тональности текстовой аналитики Cognitive Services (наш пример для данной серии руководств).
Чтобы узнать другой способ описания API, перейдите к разделу Создание пользовательского соединителя с нуля.
Предварительные условия
Определение OpenAPI, описывающее пример API. При создании пользовательского соединителя определение OpenAPI должно быть меньше 1 МБ. Определение OpenAPI должно быть в формате OpenAPI 2.0 (ранее известен как Swagger).
При наличии нескольких определений безопасности пользовательский соединитель выбирает определение безопасности верхнего уровня. Создание пользовательского соединителя не поддерживает учетные данные клиента (например, приложение и пароль) в определении безопасности OAuth.
Ключ API для API анализа текста в Cognitive Services.
Одна из следующих подписок:
- Azure, если вы используете Logic Apps
- Power Automate
- Power Apps
Если вы используете Logic Apps, прежде всего создайте пользовательский соединитель Azure Logic Apps.
Импорт определения OpenAPI
Теперь вы готовы к работе с загруженным вами определением OpenAPI. Вся необходимая информация содержится в определении, и вы можете просматривать и обновлять эту информацию в процессе работы с мастером пользовательских соединителей.
Сначала импортируйте определение OpenAPI для Logic Apps или для Power Automate или Power Apps.
Примечание
Определение OpenAPI должно быть в формате OpenAPI 2.0 (ранее известен как Swagger). Определения OpenAPI в формате OpenAPI 3.0 не поддерживаются.
Импорт определения OpenAPI для Logic Apps
Откройте портал Azure, найдите и откройте соединитель Logic Apps, который вы создали при работе с руководством по созданию пользовательского соединителя в Azure Logic Apps.
В меню вашего соединителя выберите Соединитель Logic Apps, а затем выберите Редактировать.
В разделе Общие сведения выберите Отправить файл OpenAPI, а затем перейдите к созданному вами определению OpenAPI.
Примечание
Это руководство посвящено REST API, но вы также можете использовать SOAP API с Logic Apps.
Импорт определения OpenAPI для Power Automate и Power Apps
Выполните вход в Power Apps или Power Automate.
В левой области выберите Данные > Пользовательские соединители.
Выберите Создать пользовательский соединитель, а затем выберите Импортировать файл OpenAPI.
Введите имя пользовательского соединителя, перейдите к загруженному или созданному вами определению OpenAPI и выберите Продолжить.
Параметр Стоимость Название пользовательского соединителя SentimentDemo
Просмотр общих сведений
С этого момента мы будем рассматривать действия в пользовательском интерфейсе Power Automate, но они почти ничем не различаются во всех трех программах. Мы укажем на любые различия. В этой части темы мы в будем основном рассматривать пользовательский интерфейс и покажем, как определенные значения соответствуют разделам файла OpenAPI.
Убедитесь, что в верхней части окна мастера указано имя SentimentDemo, а затем выберите Создать соединитель.
На странице Общее просмотрите данные, импортированные из определения OpenAPI, в том числе имя узла API и базовый URL-адрес API. Узел API и базовый URL-адрес определяют для соединителя способ вызова API.
Примечание
Дополнительные сведения о подключении к локальным API-интерфейсам см. в разделе Подключение к локальным API-интерфейсам с помощью шлюза данных.
Следующий раздел определения OpenAPI содержит информацию для этой страницы пользовательского интерфейса:
"info": { "version": "1.0.0", "title": "SentimentDemo", "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative" }, "host": "westus.api.cognitive.microsoft.com", "basePath": "/", "schemes": [ "https" ]
Проверка типа проверки подлинности
Для пользовательских соединителей доступно несколько вариантов проверки подлинности. API-интерфейсы Cognitive Services используют аутентификацию по ключам API, так что именно они указываются в определении OpenAPI.
На странице Безопасность проверьте информацию, касающуюся аутентификации для ключа API.
Метка отображается, когда кто-то впервые устанавливает соединение с пользовательским соединителем; вы можете выбрать Изменить и изменить это значение. Имя параметра и расположение должны совпадать со значениями, которые ожидает API-интерфейс, в данном случае это Ocp-Apim-Subscription-Key и Header.
Следующий раздел определения OpenAPI содержит информацию для этой страницы пользовательского интерфейса:
"securityDefinitions": {
"api_key": {
"type": "apiKey",
"in": "header",
"name": "Ocp-Apim-Subscription-Key"
}
}
Просмотр определения соединителя
Страница Определение мастера пользовательского соединителя предоставляет множество параметров для определения того, как работает ваш соединитель и как он отображается в приложениях Logic Apps, потоках и приложениях. Мы объясним пользовательский интерфейс и рассмотрим несколько вариантов в этом разделе, но мы также рекомендуем вам изучить его самостоятельно. Для получения информации об определении объектов с нуля в этом пользовательском интерфейсе, см. раздел Создание определения соединителя.
В следующей области отображаются все действия, триггеры (для Logic Apps и Power Automate) и ссылки, которые определены для соединителя. В этом случае отображается действие
DetectSentiment
со стороны определения OpenAPI. В этом соединителе нет триггеров, но вы можете изучить сведения о триггерах для пользовательских соединителей, прочитав статью Использование веб-перехватчика в качестве триггера для Azure Logic Apps и Power Automate.В области Общие отображаются сведения о выбранном действии или триггере. Здесь вы можете изменить сведения, в том числе свойство Видимость для операций и параметров в приложении логики или потоке:
нет: обычно отображается в приложении логики или потоке
расширенная: скрыто в дополнительном меню
внутренняя: скрыто от пользователя
важная: всегда сначала предоставляется пользователю для просмотра
В области Запрос отображается информация, касающаяся HTTP-запроса, включенного в определение OpenAPI. В нашем примере вы видите, что команда HTTP равна POST и URL-адрес /text/analytics/v2.0/sentiment (полный URL-адрес API имеет значение
<https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>
). Мы рассмотрим подробнее параметр текст немного позже.Следующий раздел определения OpenAPI содержит информацию для областей Общее и Запрос пользовательского интерфейса:
"paths": { "/text/analytics/v2.0/sentiment": { "post": { "summary": "Returns a numeric score representing the sentiment detected", "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.", "operationId": "DetectSentiment"
В области Ответ отображается информация, касающаяся HTTP-ответа, включенного в определение OpenAPI. В нашем примере определен только ответ 200 (успешное выполнение), но вы можете определить и другие ответы.
Следующий раздел определения OpenAPI содержит некоторую информацию, связанную с ответом:
"score": { "type": "number", "format": "float", "description": "score", "x-ms-summary": "score" }, "id": { "type": "string", "description": "id", "x-ms-summary": "id" }
В этом разделе показаны два значения, возвращаемые соединителем:
id
иscore
. Указываются также их типы данных и полеx-ms-summary
, которое является расширением OpenAPI. Дополнительные сведения об этом и других расширениях см. в разделе Расширение определения OpenAPI для пользовательского соединителя.В области Проверка отображаются все проблемы, обнаруженные в определении API. Обязательно проверьте данные в этой области, прежде чем сохранять соединитель.
Обновление определения
Определение OpenAPI, которое вы загрузили ранее, можно считать хорошим базовым примером. Но при реальном применении вам потребуется вносить в определения много изменений, чтобы соединитель было удобно использовать с приложениями логики, потоками или обычными приложениями. Мы покажем вам, как внести изменение в определение.
В области Запрос выберите тело, а затем — Изменить.
В области Параметр теперь отображаются три параметра, которые ожидает API:
ID
,Language
иText
. Выберите ИД, а затем выберите Редактировать.В области Свойство схемы обновите описание для параметра, а затем выберите Назад.
Параметр Стоимость Описание Числовой идентификатор для каждого отправляемого документа В области Параметр выберите Назад, чтобы вернуться на главную страницу определения.
В правом верхнем углу окна мастера выберите Обновить соединитель.
Загрузка обновленного файла OpenAPI
В настоящее время вы можете создать пользовательский соединитель из файла OpenAPI или с нуля (в Power Automate и Power Apps). Независимо от метода создания, вы можете скачать определение OpenAPI, которое служба использует для внутренних целей.
В Logic Apps его можно скачать из пользовательского соединителя.
В Power Automate или Power Apps выполните загрузку из списка пользовательских соединителей.
Тестирование соединителя
После создания соединителя проверьте, правильно ли он работает. Тестирование в настоящее время доступно только в Power Automate и Power Apps.
Важно!
При использовании ключа API рекомендуется не проверять соединитель сразу после его создания. Может пройти несколько минут, пока соединитель будет готов к подключению к API-интерфейсу.
На странице Проверка нажмите кнопку Создать подключение.
Введите ключ API из API анализа текста, а затем выберите Создать подключение.
Вернитесь на страницу Тест и выполните одно из следующих действий:
В Power Automate вы вернетесь на страницу Проверка. Щелкните значок обновления, чтобы убедиться, что сведения о подключении обновлены.
В Power Apps вы перейдете в список подключений, доступных в текущей среде. В правом верхнем углу выберите значок шестеренки, а затем выберите Пользовательские соединители. Выберите созданный соединитель, а затем вернитесь на страницу Тест.
На странице Тест введите значение в поле текст (в других полях используются значения по умолчанию, заданные ранее), а затем выберите Проверить операцию.
Соединитель вызывает API, и вы можете просмотреть ответ, который включает оценку тональности.
Следующие шаги
Вы создали пользовательский соединитель и определили его поведение. Теперь можно его применить.
- Применение пользовательского соединителя из потока
- Использование пользовательского соединителя из приложения
- Использование пользовательского соединителя из приложения логики
Кроме того, соединитель можно совместно использовать внутри организации или сертифицировать, чтобы его могли применять пользователи за пределами вашей организации.
Предоставление отзывов
Для нас очень важны отзывы о проблемах с нашей платформой соединителей и новые идеи о функциях. Чтобы оставить отзыв, выберите пункт Сообщить о проблемах или получить помощь с соединителями и выберите тип отзыва.