Создание HTTP-запросов
В Copilot Studio вы можете расширить возможности помощника, вызывая внешние API REST с помощью узла HTTP-запрос. Этот вызов может быть полезен, когда вам необходимо получить данные из внешней системы или манипулировать данными в этой системе.
Предварительные условия
Используйте узел HTTP-запроса
Выберите Добавить узел (+), откройте подменю Дополнительно, затем выберите Отправить HTTP-запрос.
В поле URL-адрес введите URL-адрес для конечной точки API-интерфейса, который требуется вызвать.
Выберите соответствующий Метод запроса в раскрывающемся списке. Поддерживаются методы GET, POST, PATCH, PUT и DELETE.
В разделе Заголовки и текст на узле выберите кнопку Изменить, которая открывает панель Свойства HTTP-запроса.
При желании вы можете добавить в HTTP-запрос один или несколько заголовков. Выберите кнопку Добавить, чтобы добавить ключ и значение каждого заголовка.
По умолчанию в теле HTTP-запроса содержимое не отправляется, но вы можете указать содержимое в теле.
В узле выберите тип данных ответа из доступных вариантов.
Вы можете предоставить пример ответа JSON, который обычно можно найти в документации по API-интерфейсу, который вы вызываете. Он генерирует переменную Power Fx, позволяя вам использовать ее в другом месте вашего холста разработки с поддержкой Intellisense в редакторе Power Fx. Выберите Из образца данных, затем выберите Получить схему из образца JSON. Вставьте ваш образец ответ в редактор и выберите Подтвердить.
Под пунктом Сохранить ответ как выберите, где вы хотите хранить ответ на HTTP-запрос, либо создав новую переменную, либо выбрав существующую.
Отправка содержимого в тексте HTTP-запроса
В разделе Заголовки и текст на узле выберите кнопку Изменить, которая открывает панель Свойства HTTP-запроса.
В разделе Текст выберите соответствующий тип контента. По умолчанию для Текст установлено значение Нет содержимого, то есть в тексте запроса не должно быть никакого содержимого, что чаще всего используется с запросом GET. Чтобы добавить содержимое в текст, выберите один из доступных вариантов.
Содержимое JSON: содержимое JSON позволяет вам предоставить объект JSON в теле запроса. Этот объект часто используется при выполнении запросов POST или PUT. При выборе этого варианта редактор позволяет вам вводить содержимое JSON.
Вы также можете указать содержимое JSON с помощью Power Fx, что позволяет включать динамические значения и ссылочные переменные. Выберите кнопку Изменить JSON, выберите Формула, затем введите объект Power Fx (любой существующий введенный JSON преобразуется в объект Power Fx), который преобразуется в JSON при выполнении HTTP-запроса.
Необработанный контент: необработанное содержимое позволяет вставить строку данных в тело запроса, и эта строка может иметь любой указанный вами тип контента. Необработанное содержимое вводится с использованием формулы Power Fx, например, строкового содержимого, показанного в следующем примере.
Обработка ошибок и время ожидания
Узел HTTP-запрос имеет несколько вариантов обработки ситуаций, в которых HTTP-запрос может завершиться неудачей или вернуть ошибку.
По умолчанию функция "вызывает ошибку". Это означает, что когда HTTP-запрос возвращает ошибку или не выполняется, помощник останавливает свою работу и запускает системную тему Ошибка, отображая сообщение об ошибке.
Однако вы можете настроить обработку ошибок так, чтобы она не вызывала системную тему Ошибка. Вместо этого она записывает код состояния HTTP и любой текст ответа с сообщением об ошибке в указанные вами переменные, что позволяет вам опрашивать эти переменные по мере необходимости, а также позволяет теме продолжать работу. Такая конфигурация полезна в сценариях, когда вы хотите, чтобы помощник продолжал работу даже в случае сбоя определенного HTTP-запроса.
Чтобы настроить поведение обработки ошибок.
В разделе Заголовки и текст на узле выберите кнопку Изменить, которая открывает панель Свойства HTTP-запроса.
Выберите желаемое поведение из раскрывающегося списка Обработка ошибок.
Если вы выберете Продолжить при ошибке, настройте переменные Код состояния и Текст ответа об ошибке, либо создавая новые переменные, либо выбирая существующие переменные из средства выбора.
В этом примере кода если HTTP-запрос завершается неудачей, помощник сохраняет код состояния HTTP в переменной Topic.StatusCode, а текст ответа — в переменной Topic.ErrorResponse. Помощник переходит к следующим шагам в теме.
Переменная Ответ с сообщением об ошибке имеет тип Любой. Вы можете использовать Узел анализа значения, чтобы преобразовать эту переменную в запись Power Fx.
Панель свойств также содержит свойство Время ожидания запроса истекло, которое принимает значение в миллисекундах. Значение по умолчанию — 30 секунд, но при необходимости вы можете изменить это значение.