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

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

  • Статья

Важно

Возможности и функции Power Virtual Agents теперь являются частью Microsoft Copilot Studio после значительных инвестиций в генеративный искусственный интеллект и расширенную интеграцию с Microsoft Copilot.

Некоторые статьи и снимки экрана могут ссылаться на Power Virtual Agents, пока мы обновляем документацию и учебные материалы.

В 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, вставив образец ответа в отображаемый редактор и выбрав Подтвердить.

    Снимок экрана получения схемы из примера редактора 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-запроса.

Чтобы настроить поведение обработки ошибок.

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

  2. Выберите желаемое поведение из раскрывающегося списка Обработка ошибок.

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

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

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

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

Панель свойств также содержит свойство Время ожидания запроса истекло, которое принимает значение в миллисекундах. Значение по умолчанию — 30 секунд, но при необходимости вы можете изменить это значение.