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

Подключаемые модули API для Microsoft 365 Copilot

  • Статья

Подключаемые модули API позволяют декларативным агентам в Microsoft 365 Copilot взаимодействовать с REST API с описанием OpenAPI. С помощью подключаемого модуля API пользователи могут попросить декларативного агента не только запрашивать сведения в REST API, но и создавать, обновлять и удалять данные и объекты. Все, что может сделать REST API, доступно через запросы на естественном языке.

Важно!

Подключаемые модули API поддерживаются только как действия в декларативных агентах. Они не включены в Microsoft 365 Copilot.

Подключаемый модуль API предоставляет документ с описанием OpenAPI и манифест подключаемого модуля, который Copilot использует для изучения возможностей API. Затем Copilot может решить, когда API установленного и включенного подключаемого модуля подходит для ответа на любой запрос. Дополнительные сведения о файле манифеста, необходимом для подключаемого модуля API, см. в статье Схема манифеста подключаемого модуля API для Microsoft 365 Copilot.

Например, рассмотрим API бюджетов, который позволяет запрашивать и создавать бюджеты, взимать расходы или добавлять средства в существующие бюджеты. Запрос "Сколько осталось в бюджете на поездки Contoso" может активировать подключаемый модуль бюджета, вызвав следующий вызов API.

GET /budgets?name=contoso%20travel

Copilot использует ответ от вызова API для создания ответа: "Бюджет на поездки Contoso в настоящее время содержит 5000 долл. США в виде доступных средств. Если вам нужно выделить средства на определенные категории или отслеживать расходы, я могу помочь вам в этом. Просто дайте мне знать, как я могу помочь!"

Запрос "Взимать 500 долл. США с бюджета на поездки Contoso за авиабилет Меган" можно перевести в следующий вызов API.

POST /budgets/charge
Content-Type: application/json

{
  "budgetName": "Contoso travel",
  "amount": 500,
  "description": "Megan's airline ticket"
}

Copilot отвечает пользователю, используя возвращенную информацию: "Плата в размере $ 500 за авиабилет Меган была успешно обработана. Бюджет на поездки Contoso теперь имеет 4500 долларов США, остающихся в наличии. Если вам нужно выполнить еще какие-либо транзакции или вам нужна дополнительная помощь с бюджетом, пожалуйста, сообщите мне!

Принцип работы подключаемых модулей API

Схема последовательностей, показывающая, как работает подключаемый модуль API

  1. Пользователь спрашивает агента: "Сколько осталось в четвертом бюджете реконструкции лобби кофе?"

  2. Агент определяет связанный с бюджетом подключаемый модуль из доступных подключаемых модулей, имеющих функцию GetBudget для получения сведений о бюджете. Он сопоставляет части вопроса пользователя с параметрами функции: budgetName="".

  3. Агент просит пользователя разрешить ему отправку Fourth Coffee lobby renovation в подключаемый модуль.

  4. Пользователь разрешает предоставление общего доступа к данным с подключаемым модулем один раз или разрешает всегда предоставлять общий доступ к данным для этой функции.

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

  6. Хранилище маркеров возвращает маркер или ключ. При необходимости хранилище маркеров заставляет агент запрашивать у пользователя вход.

  7. Агент отправляет запрос в API подключаемого модуля, который размещен за пределами Microsoft 365.

    GET /budgets?budgetName=Fourth+Coffee+lobby+renovation

  8. API возвращает ответ API в формате, указанном в спецификации OpenAPI.

    {
  "name": "Fourth Coffee lobby renovation",
  "availableFunds": 5000.00
}

  9. Агент создает ответ на основе ответа API.

  10. Агент отправляет ответ "Доступные средства, оставшиеся в четвертом бюджете реконструкции лобби кофе составляет $ 5000".

Подтверждающие действия

Copilot запрашивает пользователя перед отправкой каких-либо данных в подключаемый модуль API.

Снимок экрана: диалоговое окно подтверждения подключаемого модуля.

По умолчанию API, которые только извлекают данные, предоставляют пользователю параметр "Всегда разрешать", а API, изменяющие данные, — нет. Разработчики подключаемых модулей могут переопределить эти значения по умолчанию. Дополнительные сведения см. в разделе Запросы на подтверждение подключаемых модулей API для Microsoft 365 Copilot.

Настройка презентации ответа

Copilot создает диалоговые ответы, используя данные из ответов API. Подключаемые модули могут настраивать эти ответы, предоставляя шаблоны адаптивных карточек для структурированного отображения данных.

Снимок экрана: ответ адаптивной карточки из подключаемого модуля API

Создание пакетов подключаемого модуля API

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

  • Набор средств Teams в Visual Studio или Visual Studio Code может создавать пакеты подключаемых модулей на основе существующего описания OpenAPI. Если у вас нет API, набор средств Teams также содержит начальные проекты с примером API и соответствующим пакетом подключаемого модуля.
  • Kiota — это программа командной строки и расширение Visual Studio Code, которое может создавать пакеты подключаемых модулей на основе существующего описания OpenAPI.

Ограничения

URL-адреса в ответах API отредактированы

Чтобы защитить конфиденциальность пользователя, Copilot редактирует все URL-адреса, содержащиеся в ответах API. Единственным исключением из этого поведения является любой URL-адрес в свойстве, указанном свойством url объекта свойств семантики ответа.

Связанные материалы