Создание пользовательского соединителя из коллекции Postman

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

Чтобы узнать о других способах описания API, перейдите к следующим темам:

• Создание пользовательского соединителя из определения OpenAPI

• Создание пользовательского соединителя с нуля

Предварительные условия

• Коллекция Postman, которая описывает пример API:

  • Загрузите Коллекцию Postman, которую мы создали
    или
  • Изучите руководство по созданию коллекции Postman для пользовательского соединителя. Обратите внимание, что при создании пользовательского соединителя размер коллекции Postman не должен превышать 1 МБ.

• Ключ API для API "Анализ текста" в Cognitive Services

• Одна из следующих подписок:

  • Azure, если вы используете Logic Apps
  • Power Automate
  • Power Apps

• Если вы используете Logic Apps, прежде всего создайте пользовательский соединитель Azure Logic Apps.

Импортировать коллекцию Postman

Теперь вы готовы применить коллекцию Postman, которую вы скачали или создали. В коллекции содержится необходимая информация, которую вы сможете просмотреть и при необходимости изменить, работая с мастером пользовательских соединителей. Сначала импортируйте коллекцию Postman для Logic Apps или для Power Automate и Power Apps.

Импорт коллекции Postman для Logic Apps

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

2. В меню вашего соединителя выберите Соединитель Logic Apps, затем выберите Редактировать.

   

3. В разделе Общие выберите Загрузить коллекцию Postman V1, затем перейдите к коллекции Postman, которую вы создали.

   

   Мастер импортирует эту коллекцию и преобразует ее в определение OpenAPI с именем generatedApiDefinition.swagger.json.

Импорт коллекции Postman для Power Automate и Power Apps

1. Перейдите на сайт make.powerapps.com или flow.microsoft.com.

2. В области навигации последовательно выберите элементы Данные > Настраиваемые соединители.

3. Выберите Создать пользовательский соединитель, а затем Импортировать коллекцию Postman.

4. Введите имя настраиваемого соединителя, найдите загруженную или созданную вами коллекцию Postman и выберите Продолжить.

   

   Параметр	Значение
   Название настраиваемого соединителя	"SentimentDemo"

   Мастер импортирует эту коллекцию и преобразует ее в определение OpenAPI с именем generatedApiDefinition.swagger.json.

Обновление общих сведений

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

1. На странице Общие просмотрите данные, импортированные из коллекции Postman, в том числе имя узла и базовый URL-адрес API. Узел и базовый URL-адрес определяют для соединителя способ вызова API.

   Примечание

   Дополнительные сведения о подключении к локальным API-интерфейсам см. в разделе Подключение к локальным API-интерфейсам с помощью шлюза данных.

2. Обновите описание, указав в нем полезную информацию. Это описание отображается в сведениях о пользовательском соединителе. Оно поможет другим пользователям понять, может ли этот соединитель быть полезным для них.

   Параметр	значение
   Описание	"Использует API тональности текстовой аналитики Cognitive Services для определения тональности текста (позитивной или негативной)"

Укажите тип проверки подлинности

Для настраиваемых соединителей доступно несколько вариантов проверки подлинности. API-интерфейсы Cognitive Services используют проверку подлинности с помощью ключа API.

1. На странице Безопасность в разделе Тип проверки подлинности выберите Ключ API.

2. В разделе Ключ API укажите метку параметра, имя и расположение. Выберите выразительную информативную метку. Этот текст будет отображаться для пользователей, чтобы помочь им при установлении соединений с помощью пользовательского соединителя. Имя параметра и расположение должны совпадать со значениями, которые ожидает API-интерфейс (в нашем примере указаны значения из коллекции Postman). Выберите Подключиться.

   

   Параметр	значение
   Метка параметра	"Ключ API"
   Имя параметра	"Ocp-Apim-Subscription-Key"
   Расположение параметра	"Заголовок"

3. Убедитесь, что в верхней части окна мастера указано имя "SentimentDemo", затем выберите Создать соединитель.

Проверка и изменение определения соединителя

Мастер настраиваемых соединителей предоставляет множество вариантов для определения способа функционирования соединителя, а также способа его предоставления в службах Logic Apps, потоках и приложениях. Мы объясним пользовательский интерфейс и рассмотрим несколько вариантов в этом разделе, но мы также рекомендуем вам изучить его самостоятельно.

Описание пользовательского интерфейса и определения

Прежде чем мы перейдем к некоторым конкретным шагам на странице Определение, давайте сначала посмотрим на пользовательский интерфейс.

1. В этой области отображаются все действия, триггеры (для Logic Apps и Power Automate) и ссылки, которые определены для соединителя. В нашем примере здесь представлено действие DetectSentiment из коллекции Postman. В этом соединителе нет триггеров, но вы можете изучить сведения о триггерах для пользовательских соединителей, прочитав статью Использование веб-перехватчика в качестве триггера для Azure Logic Apps и Power Automate.

   

2. В области Общие отображаются сведения о выбранном действии или триггере. Эти сведения поступают из коллекции Postman. Здесь вы можете изменить сведения, в том числе свойство Видимость для операций и параметров в приложении логики или потоке:

   • важная: всегда сначала предоставляется пользователю для просмотра
   • нет: обычно отображается в приложении логики или потоке
   • расширенная: первоначально скрыто в дополнительном меню
   • внутренняя: не отображается для пользователя

3. В области Запрос отображаются сведения об HTTP-запросе, который включен в коллекцию Postman. В нашем примере вы видите, что команда HTTP равна POST и URL-адрес "/text/analytics/v2.0/sentiment" (полный URL-адрес API имеет значение <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). Мы рассмотрим подробнее параметр текст немного позже.

4. В области Ответ отображаются сведения об HTTP-ответе, включенном в коллекцию Postman. В нашем примере определен только ответ "200" (успешное выполнение), но вы можете определить и другие ответы.

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

Обновление определения

Теперь изменим несколько настроек, чтобы сделать соединитель более понятным при использовании его в Logic App, Power Automate или Power Apps.

1. В области Общие измените значение сводки на следующее: «После определения тональности возвращает оценку в баллах».

2. В области Запрос выберите тело, а затем — Изменить.

3. В области Параметр теперь отображаются три параметра, которые ожидает API: id, language и text. Выберите id, затем — Изменить.

4. В области Свойство схемы обновите значения для параметра, затем выберите Назад.

   

   Параметр	значение
   Заголовок	"ID"
   Описание	"Идентификатор для каждого отправляемого документа"
   Значение по умолчанию	"1"
   Требуется	"Да"

5. В области Параметр выберите язык, затем Изменить и повторите действия, выполненные выше, со следующими значениями.

   Параметр	значение
   Заголовок	"Язык"
   Описание	"Код языка для текста, состоящий из 2 или 4 символов"
   Значение по умолчанию	"en"
   Требуется	"Да"

6. В области Параметр выберите текст, затем Изменить и повторите действия, выполненные выше, со следующими значениями.

   Параметр	значение
   Заголовок	"Текст"
   Описание	"Текст для анализа тональности"
   Значение по умолчанию	Без доступа
   Требуется	"Да"

7. В области Параметр нажмите кнопку Назад, чтобы вернуться на главную страницу определения.

8. В правой верхней части мастера выберите Обновить соединитель.

Тестирование соединителя

После создания соединителя проверьте, правильно ли он работает. Тестирование в настоящее время доступно только в Power Automate и Power Apps.

1. На странице Проверка выберите Новое подключение.

2. Введите ключ API из API Анализа текста, затем выберите Создать подключение.

3. Вернитесь на страницу Проверка:

   • В Power Automate вы вернетесь на страницу Проверка. Щелкните значок обновления, чтобы убедиться, что сведения о подключении обновлены.
   • В Power Apps вы перейдете в список подключений, доступных в текущей среде. В правом верхнем углу выберите значок шестеренки, затем — Настраиваемые соединители. Выберите созданный соединитель, затем вернитесь на страницу Проверка.

4. На странице Проверка введите значение в поле Текст (в других полях используются значения по умолчанию, заданные ранее), затем выберите Проверить операцию.

5. Соединитель вызывает API, и вы можете просмотреть ответ, который включает оценку тональности.

   

Ограничения

В Power Automate и Power Apps, если вы обновляете существующий пользовательский соединитель с использованием коллекции Postman, вам нужно будет заново воспроизвести все ранее существовавшие настройки, прежде чем сохранять соединитель. Например, вам потребуется заново настроить тип аутентификации, значения параметров по умолчанию для действий и т. д.

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

Вы создали настраиваемый соединитель и определили его поведение. Теперь можно его применить.

• Применение пользовательского соединителя из потока
• Использование настраиваемого соединителя из приложения
• Использование пользовательского соединителя из приложения логики

Кроме того, соединитель можно совместно использовать внутри организации или сертифицировать, чтобы его могли применять пользователи за пределами вашей организации.

• Предоставление общего доступа к соединителю
• Сертификация соединителя

Предоставление отзывов

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