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

Важно!

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

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

Как правило, Microsoft 365 Copilot показывает пользователю параметр always allow для операций HTTP GET и не отображает параметр POST, PATCH, PUT и DELETE. Разработчики подключаемых модулей API могут изменить это поведение для отдельных операций в API. Разработчики также могут настроить текст, который Copilot отображает для пользователя в запросе на подтверждение.

Переопределение поведения запроса

Разработчики могут управлять отображением Microsoft 365 Copilot параметра always allow для конкретной операции, добавляя x-openai-isConsequential свойство в документ OpenAPI для своего API. При задании этого свойства значение true отключается параметр "Всегда разрешать", а для параметра false — его включение. Как правило, любое действие с побочными эффектами во внешней системе должно быть отмечено символом , true чтобы гарантировать, что пользователь находится под контролем и предотвратить непредвиденные последствия действий с побочными эффектами во внешней системе.

Например, рассмотрим API, который создает напоминание: POST /reminders. Так как это операция POST, Microsoft 365 Copilot просит пользователя подтвердить каждый раз, когда используется этот API, и не дает пользователю возможность всегда разрешать эту операцию.

Чтобы включить параметр always allow, добавьте x-openai-isConsequential свойство false, как показано в следующем примере.

post:
  x-openai-isConsequential: false
  summary: Create a new reminder
  description: Create a new budget with a specified name and due date
  operationId: CreateReminder
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Reminder'
    required: true

Теперь представьте связанный API, который получает существующие напоминания: GET /reminders. Так как это GET, Microsoft 365 Copilot показывает пользователю параметр всегда разрешать.

Это поведение можно изменить, добавив x-openai-isConsequential для параметра значение true.

get:
  x-openai-isConsequential: true
  summary: Get existing reminders
  description: Gets a list of existing reminders
  operationId: GetReminders

Настройка текста подтверждения

Разработчики могут указать текст подтверждения, задав body свойство в объекте Confirmation объекта Function capabilities функции в манифесте подключаемого модуля. Значение body должно указывать на то, что делает функция. Если это свойство отсутствует в манифесте, description вместо него используется свойство в объекте Function .

{
  "name": "GetBudgets",
  "description": "Returns details including name and available funds of budgets, optionally filtered by budget name",
  "capabilities": {
    "confirmation": {
      "type": "AdaptiveCard",
      "title": "Search budgets",
      "body": "Do you want to allow searching for budgets?"
    }
  }
}