Создание HTTP-запросов

Note

Функции, описанные в этой статье, питаются стандартным жгутом, который использует опции выставления счетов, описанные в разделе «Лицензирование для агентов, работающих на стандартном жгуте». Узнайте, как получить доступ к стандартным функциям в стандартных агентах и потоках агентов доступа.

В Copilot Studio вы можете расширить возможности агента, используя узел HTTP-запрос для вызова внешних REST API. Этот вызов может быть полезен, когда вам необходимо получить данные из внешней системы или манипулировать данными в этой системе.

Необходимые условия

• Создание и изменение тем

Использование узла "HTTP-запрос"

1. Выберите значок Добавить узел под узлом, после которого вы хотите вызвать внешний API, наведите курсор на Дополнительно и выберите Отправить HTTP-запрос.

2. В поле URL-адрес введите URL-адрес для конечной точки API-интерфейса, который требуется вызвать.

3. Выберите соответствующий Метод запроса в раскрывающемся списке. Поддерживаются методы GET, POST, PATCH, PUT и DELETE.

   

4. В разделе Заголовки и текст узла выберите кнопку Изменить, которая откроет панель Свойства HTTP-запроса.

5. При желании вы можете добавить в HTTP-запрос один или несколько заголовков. Выберите кнопку Добавить, чтобы добавить ключ и значение каждого заголовка.

   

   Вы можете использовать раздел заголовков для передачи токенов аутентификации, типа содержимого или любых других необходимых заголовков для вызываемого API. Например, вы можете добавить такой заголовок, как Authorization: Bearer <your_token>, чтобы аутентифицировать запрос.

6. По умолчанию в теле HTTP-запроса содержимое не отправляется, но вы можете указать содержимое в теле.

7. В узле выберите тип данных ответа из доступных вариантов.

   Вы можете предоставить пример ответа JSON, который обычно можно найти в документации по API-интерфейсу, который вы вызываете. Будет создана переменная Power Fx, которую можно использовать в других местах на холсте разработки, с поддержкой IntelliSense в редакторе Power Fx. Выберите Из образца данных, затем выберите Получить схему из образца JSON. Вставьте ваш образец ответ в редактор и выберите Подтвердить.

8. В разделе Сохранить ответ пользователя как выберите, где вы хотите сохранить ответ на HTTP-запрос, создав новую переменную или выбрав существующую.

Отправка содержимого в тексте HTTP-запроса

1. В разделе Заголовки и текст узла выберите кнопку Изменить, которая откроет панель Свойства HTTP-запроса.

2. В разделе Текст выберите соответствующий тип контента. По умолчанию для Текст установлено значение Нет содержимого, то есть в тексте запроса не должно быть никакого содержимого, что чаще всего используется с запросом 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-запрос, выполните следующие действия:

1. В разделе Заголовки и текст выберите Изменить. Появится панель Свойства HTTP-запроса.

2. В разделе Обработка ошибок выберите требуемое поведение: Создать ошибку или Продолжить при ошибке.

3. Если выбран вариант Продолжить при ошибке, настройте переменные для кода состояния и текста ответа об ошибке.

   

В этом примере в случае сбоя HTTP-запроса агент сохраняет код состояния HTTP в переменной Topic.StatusCode и текст ответа в переменной Topic.ErrorResponse. Агент переходит к следующим шагам в теме.

Переменная Ответ с сообщением об ошибке имеет тип Любой. Вы можете использовать узел Анализировать значение для преобразования этой переменной в запись Power Fx.

В панели Свойства HTTP-запроса также можно задать свойство Время ожидания запроса в миллисекундах. Значение по умолчанию — 30 секунд.