Создание пользовательского соединителя из определения 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.

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

  • Если вы используете 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

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

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

    Редактирование соединителя Logic Apps.

  3. В разделе Общие сведения выберите Отправить файл OpenAPI, а затем перейдите к созданному вами определению OpenAPI.

    Отправка файла OpenAPI.

Примечание

Это руководство посвящено REST API, но вы также можете использовать SOAP API с Logic Apps.

Импорт определения OpenAPI для Power Automate и Power Apps

  1. Выполните вход в Power Apps или Power Automate.

  2. В левой области выберите Данные > Настраиваемые соединители.

    Выбор настраиваемого соединителя.

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

    Импорт файла OpenAPI.

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

    Отправка коллекции.

    Параметр Стоимость
    Название настраиваемого соединителя SentimentDemo

Просмотр общих сведений

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

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

  2. На странице Общее просмотрите данные, импортированные из определения 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.

Метка отображается, когда кто-то впервые устанавливает соединение с пользовательским соединителем; вы можете выбрать Изменить и изменить это значение. Имя параметра и расположение должны совпадать со значениями, которые ожидает API-интерфейс, в данном случае это Ocp-Apim-Subscription-Key и Header.

Следующий раздел определения OpenAPI содержит информацию для этой страницы пользовательского интерфейса:

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

Просмотр определения соединителя

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

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

    Страница определения — действия и триггеры.

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

    • нет: обычно отображается в приложении логики или потоке

    • расширенная: скрыто в дополнительном меню

    • внутренняя: скрыто от пользователя

    • важная: всегда сначала предоставляется пользователю для просмотра

      Страница определения — общие сведения.

  3. В области Запрос отображается информация, касающаяся 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"

  4. В области Ответ отображается информация, касающаяся 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 для пользовательского соединителя.

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

    Страница определения — проверка.

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

Определение OpenAPI, которое вы загрузили ранее, можно считать хорошим базовым примером. Но при реальном применении вам потребуется вносить в определения много изменений, чтобы соединитель было удобно использовать с приложениями логики, потоками или обычными приложениями. Мы покажем вам, как внести изменение в определение.

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

    Изменить текст запроса.

  2. В области Параметр теперь отображаются три параметра, которые ожидает API: ID, Language и Text. Выберите ИД, а затем выберите Редактировать.

    Изменить идентификатор текста запроса.

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

    Изменение свойства схемы.

    Параметр Стоимость
    Описание Числовой идентификатор для каждого отправляемого документа

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

  5. В правом верхнем углу окна мастера выберите Обновить соединитель.

Загрузка обновленного файла OpenAPI

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

  • В Logic Apps его можно скачать из настраиваемого соединителя.

    Загрузка определения OpenAPI для Logic Apps.

  • В Power Automate или Power Apps выполните загрузку из списка пользовательских соединителей.

    Загрузка определения OpenAPI для Power Automate.

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

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

Важно!

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

  1. На странице Проверка нажмите кнопку Создать подключение.

    Новое подключение.

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

    Создание подключения.

  3. Вернитесь на страницу Тест и выполните одно из следующих действий:

    • В Power Automate вы вернетесь на страницу Проверка. Щелкните значок обновления, чтобы убедиться, что сведения о подключении обновлены.

      Обновление подключения.

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

      Значок шестеренки в службе.

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

    Проверка операции.

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

    Ответ соединителя.

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

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

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

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

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