Как сделать документ OpenAPI эффективным при расширении Copilot

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

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

Здесь предполагается, что у вас есть API и описание OpenAPI для него.

Проверка 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