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

  • Статья

Эта статья входит в серию руководств по созданию и использованию пользовательских соединителей в Azure Logic Apps, Microsoft Power Automate и Microsoft Power Apps.

Примечание

Обязательно прочитайте обзор пользовательских соединителей, чтобы понять процесс.

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

Чтобы узнать другой способ описания API, перейдите к разделу Создание пользовательского соединителя на основе определения OpenAPI.

Примечание

В настоящее время вы можете создать пользовательский соединитель с нуля в Power Automate и Power Apps. Для Logic Apps вы должны начать хотя бы с базового определения OpenAPI.

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

Запуск мастера пользовательских соединителей

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

  2. В левой области выберите Данные > Пользовательские соединители.

  3. Выберите Новый пользовательский соединитель > Создать с нуля.

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

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

Шаг 1. Обновите общие сведения

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

На вкладке Общие сведения выполнить следующее:

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

  2. Обновите поле Узел в соответствии с адресом для API текстовой аналитики. Узел API и базовый URL-адрес определяют для соединителя способ вызова API.

    Параметр Стоимость
    Описание: Использует API тональности текстовой аналитики Cognitive Services для определения тональности текста (позитивной или негативной)
    Хост westus.api.cognitive.microsoft.com

Шаг 2. Укажите тип аутентификации

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

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

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

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

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

Шаг 3. Создайте определение соединителя

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

Создание действия

Первое, что нужно сделать, это создать действие, которое вызывает операцию тональности API-интерфейса текстовой аналитики.

  1. На вкладке Определение слева отображаются все сведения о действиях, триггеры (для Logic Apps и Power Automate), а также ссылки, которые определены для соединителя. Выберите Создать действие.

    В этом соединителе нет триггеров. Сведения о триггерах для пользовательских соединителей см. в разделе Использование веб-перехватчиков с Azure Logic Apps и Power Automate.

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

    Параметр Стоимость
    Сводка. Возвращает числовую оценку, отражающую обнаруженную тональность
    Описание Оценка, которую возвращает API, выражается числами в диапазоне от 0 до 1. Если оценка близка к 1, у текста положительная тональность, а если к 0 — отрицательная.
    Идентификатор операции DetectSentiment

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

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

  3. Область Запрос отображает информацию на основе HTTP-запроса на действие. Выберите Импорт из образца.

  4. Укажите информацию, необходимую для подключения к API, укажите текст запроса (размещенный после следующего изображения), а затем выберите Импорт. Мы предоставляем эту информацию для вас, но для общедоступного API обычно эта информация находится в документации, такой как API-интерфейс текстовой аналитики (версия 2.0).

    Параметр Стоимость
    Команда POST
    URL <https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>
    Body Используйте следующий код JSON

    Пример:

    {
  "documents": [
    {
      "language": "string",
      "id": "string",
      "text": "string"
    }
  ]
}

  5. Область Ответ отображает информацию на основе HTTP-ответа для действия. Щелкните Добавить ответ по умолчанию.

  6. Укажите текст ответа, а затем выберите Импорт. Как и для текста запроса, мы предоставляем эту информацию для вас после изображения, но обычно она содержится в документации по API.

    Пример:

    {
 "documents": [
   {
     "score": 0.0,
     "id": "string"
   }
 ],
 "errors": [
   {
     "id": "string",
     "message": "string"
   }
 ]
}

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

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

Теперь изменим несколько настроек, чтобы сделать соединитель более понятным, когда кто-то используется его в приложении логики, потоке или приложении.

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

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

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

    Параметр Стоимость
    Title Идентификатор
    Описание: Идентификатор для каждого отправляемого документа
    Default value 1
    Обязательно Да

  4. В области Параметр выберите Язык > Редактировать, а затем повторите процесс, который вы использовали для id на шагах 2 и 3 этой процедуры, со следующими значениями.

    Параметр Стоимость
    Title Язык
    Описание: Код языка для текста, состоящий из 2 или 4 символов
    Default value en
    Обязательно Да

  5. В области Параметр выберите Текст > Редактировать, а затем повторите процесс, который вы использовали для id на шагах 2 и 3 этой процедуры, со следующими значениями.

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

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

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

Шаг 4. (Необязательно) Включите соединитель в качестве подключаемого модуля ИИ

Используйте вкладку Подключаемый модуль ИИ (предварительная версия) для соединителя только в том случае, если вы планируете сертифицировать свой соединитель. Чтобы соединитель можно было использовать в качестве подключаемого модуля ИИ, он должен быть сертифицирован.

Прежде чем включить соединитель в качестве подключаемого модуля ИИ, убедитесь, что вы понимаете сценарий использования подключаемого модуля ИИ и рассмотрели другие аспекты, такие как возможность поддержки, лучшие практики и рекомендации. Дополнительная информация: Создание подключаемого модуля соединителя ИИ (предварительная версия)

  1. В левой области навигации выберите Пользовательские соединители.

    Если пункт Пользовательские соединители не отображается, выберите Еще > Открыть все > Пользовательские соединители. Опция появится в левой области навигации.

  2. В правом верхнем углу выберите пункт из меню Новый пользовательский соединитель.

  3. Убедитесь, что вы выполнили Шаг 1, Шаг 2 и Шаг 3, описанные в этой статье.

  4. Выберите вкладку Подключаемый модуль ИИ (предварительная версия).

  5. В разделе Манифест подключаемого модуля введите данные, чтобы включить этот соединитель в качестве подключаемого модуля ИИ.

    Снимок экрана полей на странице &quot;Манифест подключаемого модуля&quot;.

    Поле Description
    Манифест подключаемого модуля: имя Имя подключаемого модуля ИИ.
    Манифест подключаемого модуля: описание Описание подключаемого модуля ИИ. Дополнительная информация: Создание подключаемого модуля соединителя ИИ (предварительная версия)
    Манифест подключаемого модуля: контактный адрес электронной почты Адрес электронной почты контактного лица для подключаемого модуля ИИ.
    Манифест подключаемого модуля: URL-адрес юридической информации Общедоступное место, где публикуется юридическая информация, связанная с вашим подключаемым модулем ИИ.

  6. Прокрутите вниз до раздела Сведения о действиях подключаемого модуля и введите сведения о действии для каждого действия в подключаемом модуле ИИ соединителя.

    Снимок экрана полей на странице &quot;Сведения действий подключаемого модуля&quot;.

    Поле Description
    Подробности действий подключаемого модуля: сводка Сводная информация о каждом действии подключаемого модуля ИИ, которое могут выполнять пользователи.
    Подробности действий подключаемого модуля: описание Описание каждого действия, которое пользователи могут выполнить в отношении этого конкретного шага действия подключаемого модуля ИИ.
    Флажок: включить работу подключаемого модуля помощника Когда установлен флажок, работа подключаемого модуля ИИ включена.
    Флажок: требуется подтверждение пользователя? Если установлен флажок, требуется подтверждение пользователя.

    Совет

    Если вам нужна помощь в определении ваших действий, включите переключатель Редактор Swagger.

  7. Прокрутите вниз до раздела Параметр и введите сведения о параметре для вашего подключаемого модуля ИИ соединителя.

    Снимок экрана полей на странице &quot;Параметры&quot;.

    Поле Description
    Параметр: имя Имя параметра. Используйте идентифицируемые имена, такие как Идентификатор учетной записи вместо ИД.
    Параметр: описание Описание параметра. Используйте описательное объяснение, например Дата рождения контактного лица в формате ММ/ДД/ГГГГ вместо b_date. Такие имена и описания помогают LLM (большим языковым моделям) эффективно взаимодействовать с подключаемым модулем ИИ.
    Параметр: сводка Сводные данные о параметре.
    Параметр: значение по умолчанию Значение параметра по умолчанию.

  8. В разделе Запрос под разделами Подключаемый модуль ИИ (предварительная версия) выберите входной параметр, а затем введите описание.

Шаг 5. (Необязательно) Используйте поддержку пользовательского кода

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

Примечание

  • Этот шаг необязательный. Вы можете завершить создание соединителя без кода, проигнорировав этот шаг и перейдя к Шаг 6. Проверка соединителя.
  • Поддержка настраиваемого кода доступна в общедоступной предварительной версии.

Вы можете вставить свой код или отправить файл с кодом. Ваш код должен удовлетворять следующим требованиям:

  • Быть написанным на C#.
  • Максимальное время выполнения — пять секунд.
  • Иметь размер файла не более 1 МБ.

Инструкции и примеры написания кода см. в Написание кода в пользовательском соединителе.

Чтобы получить ответы на часто задаваемые вопросы о пользовательском коде, перейдите по ссылке Вопросы и ответы о пользовательском коде.

  1. На вкладке Код вставьте свой собственный код, используя один из следующих вариантов:

    • Копировать/вставить
    • Нажмите кнопку Отправить.

    Если вы решите оправить собственный код, будут доступны только файлы с расширением CS или CSX.

    Снимок экрана: отправьте свой собственный код.

    Важно!

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

  2. После вставки или отправки кода установите переключатель Код отключен, чтобы включить ваш код. Название переключателя изменится на Код включен.

    Вы можете включить или отключить свой код в любое время. Если задан переключатель Код отключен, ваш код будет удален.

  3. Выберите действия и триггеры, которые будут применяться к вашему пользовательскому коду, выбрав нужный вариант в раскрывающемся меню. Если ни одна операция не выбрана, действия и триггеры применяются ко всем операциям.

    Снимок экрана: выбор действий и триггеров.

Шаг 6. Тестирование соединителя

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

Важно!

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

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

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

    Примечание

    Для API-интерфейсов, требующих аутентификации носителя, добавьте Носитель и один пробел перед ключом API.

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

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

      Снимок экрана обновления подключения.

    • (В Power Apps) Вы перейдете к списку подключений, доступных в текущей среде. В левой области выберите Данные > Пользовательские соединители. Выберите созданный соединитель, а затем вернитесь на вкладку Тест.

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

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

    Снимок экрана ответа соединителя.

(Для пользователей интерфейса командной строки) Рекомендации

  • Скачайте все соединители и используйте Git или любую другую систему управления версиями кода для сохранения файлов.

  • В случае неправильного обновления снова разверните соединитель, повторно выполнив команду обновления с правильным набором файлов из системы управления версиями кода.

  • Прежде чем выполнять развертывание в рабочей среде, проверьте пользовательский соединитель и файл параметров в тестовой среде.

  • Всегда тщательно проверяйте, правильно ли указан идентификатор среды и соединителя.

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

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

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

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

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