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

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

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

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

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

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

  • Power Automate
  • Power Apps

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

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

2. В левой области выберите Решения.

3. Измените или создайте неуправляемое решение для пользовательского соединителя. Узнайте, как создать решение.

4. Выберите раскрывающийся список "Создать настраиваемый соединитель " и выберите "Создать" из пустого списка.

5. Введите имя соединителя, например SentimentDemo. Выберите "Продолжить", чтобы открыть мастер соединителя, в котором вы выполните следующие пять разделов в Power Automate:

   • General

   • Безопасность

   • Definition

   • Код (необязательно)

   • Test

     

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

Вы предоставляете такую информацию о соединителе, как значок, описание, схема, узел и базовый URL-адрес в разделе Общие. Выполните следующие действия:

1. Щелкните значок "Загрузки соединителя" или "Загрузить" в поле значков, чтобы загрузить PNG или JPG изображения соединителя. Убедитесь, что это меньше 1 МБ. Вы также можете назначить цвет фона для значка.

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

3. Выберите схему URL-адреса соединителя, HTTPs или HTTP.

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

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

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

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

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

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

1. В разделе "Безопасность " в разделе "Тип проверки подлинности" выберите ключ API из раскрывающегося списка.

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

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

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

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

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

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

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

Первое, что нужно сделать, это создать действие, которое вызывает операцию тональности API-интерфейса текстовой аналитики. На вкладке "Определение " в левой области отображаются все действия, триггеры (для Logic Apps, Power Automate и Copilot Studio), ссылки и политики, определенные для соединителя.

1. Выберите Создать действие.

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

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

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

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

3. В области Запрос выберите Импорт из примера.

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. В области Ответ выберите Добавить ответ по умолчанию.

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

   Пример:

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

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

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

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

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

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

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

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

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

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

4. В области Параметр выберите Язык>Изменить, затем повторите процесс, который использовался для id, чтобы добавить следующие значения language:

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

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

   Параметр	Стоимость
   Title	Текст
   Описание:	Текст для анализа тональности
   Значение по умолчанию	None
   Обязательно	Да

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

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

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

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

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

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

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

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

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

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

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

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

   

   Внимание!

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

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

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

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

   

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

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

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

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

   Заметка

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

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

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

     

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

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

   Соединитель вызывает API.

5. Просмотрите ответ, который включает оценку тональности.

   

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

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

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

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

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

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

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

• Power Automate
• Power Apps
• Логические приложения
• Copilot Studio

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

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

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

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