Поделиться через

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

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

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

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

  1. Выберите Добавить узел (+), откройте подменю Дополнительно, затем выберите Отправить HTTP-запрос.

    Снимок экрана пункта «Отправить HTTP-запрос» в меню «Дополнительно».

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

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

    Снимок экрана с заполненным URL-адресом API-интерфейса и раскрывающимся списком методов

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

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

    Снимок экрана списка пар ключ-значение заголовков для узла HTTP.

  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-запроса.

      Снимок экрана с содержимым JSON, выбранным для типа контента текста запроса.

    • Необработанный контент: необработанное содержимое позволяет вставить строку данных в тело запроса, и эта строка может иметь любой указанный вами тип контента. Необработанное содержимое вводится с использованием формулы Power Fx, например, строкового содержимого, показанного в следующем примере.

      Снимок экрана с содержимым RAW, выбранным для типа контента текста запроса.

Обработка ошибок и времени ожидания

Узел HTTP-запрос имеет несколько вариантов обработки ситуаций, в которых HTTP-запрос может завершиться неудачей или вернуть ошибку.

По умолчанию функция выдает ошибку. Это означает, что когда HTTP-запрос возвращает ошибку или не может быть выполнен, агент прекращает свою работу и активирует системную тему При ошибке, отображая сообщение об ошибке.

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

Чтобы настроить поведение обработки ошибок узла HTTP-запрос, выполните следующие действия:

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

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

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

    Снимок экрана панели «Свойства HTTP-запроса» для узла «Веб-запрос HTTP», показывающий конфигурацию обработки ошибок, чтобы продолжить работу при ошибке. Выбираются переменные для кода состояния и тела ответа об ошибке.

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

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

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