Создавайте эффективные описания OpenAPI для расширения Microsoft 365 Copilot

Подключаемые модули API позволяют агентам Microsoft 365 Copilot взаимодействовать с веб-службами и получать доступ к информации в режиме реального времени. Подключаемый модуль API позволяет пользователям взаимодействовать с данными в режиме реального времени из их бизнес-системы (LOB) с помощью команд на естественном языке, адресованных агенту в Copilot Chat.

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

В этой статье описаны элементы, которые делают описание OpenAPI эффективным для подключаемого модуля, расширяющего возможности агента Copilot.

Элементы описания OpenAPI

В этом разделе описаны элементы описания OpenAPI и способы их оптимизации для агентов Copilot.

Проверка OpenAPI: Хорошим первым шагом является проверка того, что описание OpenAPI соответствует правилам спецификации OpenAPI. Вы можете использовать Hidi, инструмент командной строки, который может проверять описания OpenAPI среди других вариантов использования, или любой другой инструмент по выбору. Допустимое описание OpenAPI не только хорошо работает с Copilot, но и гарантирует, что ваше описание OpenAPI может работать с другими инструментами.

Информационный раздел: поле описания не является обязательным в спецификации OpenAPI, но оно необходимо для описания OpenAPI, предназначенного для расширения навыков Copilot. Copilot необходимо поле описания, чтобы знать, что делает API и когда использовать плагин. При создании манифеста плагина из документа OpenAPI в качестве описания манифеста плагина используется описание в разделе сведений. Поэтому важно, чтобы поле описания всегда было кратким и понятным. Например, вот информационный раздел описания OpenAPI ремонтной мастерской.

info:
  title: Repair Service
  description: A simple service to manage repairs for various items
  version: 1.0.0

Идентификаторы операций: Полезным методом повышения удобства использования описания OpenAPI является добавление для operationID каждой комбинации пути API и метода HTTP, предлагаемого API. Идентификаторы операций являются уникальными идентификаторами операции в API и используются Copilot для создания функций, выполняемых при ответе на запрос пользователя.

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

Идентификаторы операций отображаются во время отладки в виде функций, указывающих, какие операции пытается выполнить Copilot. Ниже приведен пример документа OpenAPI и пример соответствующих выходных данных отладчика:

paths:
  /repairs:
    get:
      operationId: listRepairs
      summary: List all repairs
      description: Returns a list of repairs with their details and images

Выходные данные отладчика:

Изображение отладчика, показывающего выбранную функцию подключаемого модуля.

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

Пример:

parameters:
  - name: assignedTo
    in: query
    description: The name or ID of the person or team to whom the repair is assigned.
    schema:
      type: string
    required: false

Ответы: Четко определите все возможные ответы для каждой операции, включая ответы об успехе и ошибках. Каждый ответ должен содержать код состояния и описание того, что он представляет. Включение примеров ответов помогает Copilot понять, чего ожидать от API.

responses:
  '200':
    description: A list of repairs
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Repair'
        examples:
          example1:
            value:
              [
                {
                  "id": "1",
                  "item": "Laptop",
                  "status": "In Progress",
                  "assignedTo": "John Doe"
                }
              ]
  '404':
    description: No repairs found
  '500':
    description: Server error