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


Схема манифеста подключаемого модуля API 2.2 для Microsoft 365 Copilot

Подключаемые модули API позволяют Microsoft 365 Copilot взаимодействовать с REST API, описанными в описании OpenAPI. Описание OpenAPI в подключаемом модуле API описывает ИНТЕРФЕЙСы REST API, с которыми может взаимодействовать Copilot. Кроме того, подключаемый модуль API содержит файл манифеста подключаемого модуля, который предоставляет метаданные о подключаемом модуле, такие как имя, описание и версия подключаемого модуля. Манифест подключаемого модуля также содержит сведения о возможностях подключаемого модуля, таких как поддерживаемые им API и операции, которые он может выполнять.

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

Изменения предыдущей версии

Эта версия схемы содержит следующие изменения по версии 2.1.

  • Добавлено security_info свойство к объекту Function capabilities. Это свойство позволяет засвидетельствовать поведение подключаемого модуля, чтобы оценить риски вызова функции.
  • Удалено устаревшее localization свойство из объекта возможностей подключаемого модуля. Манифесты, созданные с помощью набора средств Teams с использованием схемы версии 2.1, включали нерекомендуемое localization свойство. Манифесты, использующие схему 2.2, не пройдут проверку, если это свойство включено.

Схема JSON

Схему, описанную в этом документе, можно найти в формате схемы JSONздесь.

Конвенций

Относительные ссылки в URL-адресах

Если не указано иное, все свойства, которые являются URL-адресами, могут быть относительными ссылками. Относительные ссылки в документе манифеста относительно расположения документа манифеста.

Длина строки

Если не указано иное, все строковые свойства должны быть ограничены 4K-символами. Эта длина строки не предоставляет допустимый размер для всего документа. Реализации могут свободно вводить собственные практические ограничения на длину манифеста.

Нераспознанные свойства

Объекты JSON, определенные в этом документе, поддерживают только описанные свойства. Нераспознанные свойства в любом объекте JSON должны сделать весь документ недопустимым.

Локализация строк

Локализуемые строки могут использовать ключ локализации вместо значения литерала. Синтаксис : [[key_name]], где key_name — это имя ключа в свойстве localizationKeys в файлах локализации. Дополнительные сведения о локализации см. в статье Локализация агента.

Пример локализованной строки

{
    "schema_version": "v2.2",
    "name_for_human": "[[plugin_name]]",
    "description_for_human": "[[plugin_description]]"
}

Объект манифеста подключаемого модуля

Корнем документа манифеста подключаемого модуля является объект JSON, содержащий свойства, описывающие подключаемый модуль.

Объект манифеста подключаемого модуля содержит следующие свойства.

Свойство Тип Описание
schema_version String Обязательный. Версия схемы. Предыдущие версии: v1 и v2. Необходимо указать значение v2.2.
name_for_human String Обязательный. Короткое, понятное для пользователя имя подключаемого модуля. Он должен содержать по крайней мере один символ nonwhitespace. Символы, превышающие 20, могут игнорироваться. Это свойство локализуется.
namespace Строка Устарело. Необязательный параметр.
description_for_model String Необязательный параметр. Описание подключаемого модуля, предоставленного модели. В этом описании должно быть описано, для чего предназначен подключаемый модуль и в каких обстоятельствах его функции актуальны. Символы после версии 2048 могут игнорироваться. Это свойство локализуется.
description_for_human String Обязательный. Понятное описание подключаемого модуля. Символы, превышающие 100, могут игнорироваться. Это свойство локализуется.
logo_url String Необязательный параметр. URL-адрес, используемый для получения логотипа, который может использоваться оркестратором. Реализации могут предоставлять альтернативные методы для предоставления логотипов, соответствующих их визуальным требованиям. Это свойство локализуется.
contact_email String Необязательный параметр. Адрес электронной почты контактного лица для обеспечения безопасности, модерации, поддержки и деактивации.
legal_info_url String Необязательный параметр. Абсолютный URL-адрес, который находит документ, содержащий условия обслуживания для подключаемого модуля. Это свойство локализуется.
privacy_policy_url String Необязательный параметр. Абсолютный URL-адрес, который находит документ, содержащий политику конфиденциальности для подключаемого модуля. Это свойство локализуется.
functions Массив объекта Function Необязательный параметр. Набор объектов функций, описывающих функции, доступные для подключаемого модуля. Имя каждого объекта функции должно быть уникальным в массиве. Порядок массива незначим. functions Если свойство отсутствует и есть среда выполнения OpenAPI, функции выводятся из операций OpenAPI.
runtimes Массив объекта среды выполнения OpenAPI Необязательный параметр. Набор объектов среды выполнения, описывающих среды выполнения, используемые подключаемым модулем.
capabilities Объект возможностей подключаемого модуля Необязательный параметр. Описывает возможности подключаемого модуля.

Объект Function

Сведения о том, как модель должна взаимодействовать с функцией.

Объект функции содержит следующие свойства.

Свойство Тип Описание
id String Необязательный параметр.
name String Обязательный. Строка, однозначно идентифицирующая эту функцию. Объекты среды выполнения могут ссылаться на этот идентификатор для привязки среды выполнения к функции. Если функция привязана к среде выполнения OpenAPI, значение должно соответствовать значению operationId в описании OpenAPI. Значение должно соответствовать регулярному выражению ^[A-Za-z0-9_]+$ .
description String Необязательный параметр. Описание, лучше адаптированное к модели, например рекомендации по длине контекста маркера или ключевое слово использование для улучшенного запроса подключаемого модуля.
parameters Объект параметров функции Необязательный параметр. Объект , содержащий свойства, описывающие параметры функции независимо от среды выполнения. Он отражает форму json-схемы , но поддерживает только небольшое подмножество возможностей схемы JSON. parameters Если свойство отсутствует, функции, описанные объектом среды выполнения типаOpenApi, используют описание OpenAPI для определения параметров. Каждый член объекта JSON является объектом параметра функции, который описывает семантику параметра.
returns Возвращаемый объектВозвращаемый объект OR Rich Необязательный параметр. Описывает семантику значения, возвращаемого функцией.
states Объект состояний функции Необязательный параметр. Определяет объекты состояния для состояний оркестратора.
capabilities Объект функциональных возможностей Необязательный параметр. Содержит коллекцию данных, используемых для настройки необязательных возможностей оркестратора при вызове функции.

Пример объекта function

{
  "functions": [
    {
      "name": "add_todo",
      "description": "Adds a new Todo",
      "parameters": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          }
        },
        "required": [
          "description"
        ]
      },
      "returns": {
        "type": "string"
      }
    }
  ]
}

Объект параметров функции

Объект , используемый для идентификации набора параметров, которые могут быть переданы функции. Этот объект структурирован так, чтобы зеркало форму объекта схемы JSON, но он поддерживает только подмножество ключевых слов схемы JSON.

Объект function parameters содержит следующие свойства.

Свойство Тип Описание
type String Необязательный параметр. Тип схемы JSON. Необходимо указать значение object.
properties Объект свойств параметров функции Обязательно. Объект , сопоставляющий имена параметров с их определениями.
required Массив строк Необязательное. Имена свойств, которые являются обязательными параметрами. В отличие от схемы JSON, значения в этом массиве должны соответствовать именам, указанным в свойстве properties .
Пример объекта параметров функции
{
  "type": "object",
  "properties": {
    "param1": {
      "type": "string"
    },
    "param2": {
      "type": "number"
    }
  },
  "required": [
    "param1"
  ]
}

Объект свойств параметров функции

Объект , сопоставляющий имена параметров с их определениями.

Объект свойств параметров функции содержит следующие свойства.

Свойство Тип Описание
Сопоставление имен ^[A-Za-z0-9_]+$ Объект параметра функции Необязательный параметр. Определение параметра, соответствующее параметру, соответствующему имени свойства.

Объект параметра функции

Объект , описывающий семантику параметра функции.

Объект параметра функции содержит следующие свойства.

Свойство Тип Описание
type String Обязательный. Задает тип параметра. Возможные значения: string, array, boolean, integer, number.
items Объект параметра функции Необязательный параметр. Объект параметра функции, описывающий один элемент в массиве. ДОЛЖЕН присутствовать только в том случае, если type имеет значение array.
enum Массив строк Необязательное. Массив допустимых значений для этого параметра. ДОЛЖЕН присутствовать только в том случае, если type имеет значение string.
description String Необязательный параметр. Описание параметра.
default Массив, логическое значение, строка, число, целое число Необязательный параметр. Значение типа, указанного type свойством , указывающее значение, используемое API, если значение для необязательного параметра не указано.
Пример параметра функции
{
  "type": "string",
  "description": "The color of the item",
  "enum": [
    "green",
    "blue",
    "orange"
  ]
}

Возвращаемый объект

Содержит семантику значения, возвращаемого функцией .

Возвращаемый объект содержит следующие свойства.

Свойство Тип Описание
type String Обязательный. Указывает тип значения, возвращаемого API. Возможные значения: string.
description String Необязательный параметр. Описание значения, возвращаемого API.

Объект rich return

Указывает, что функция возвращает ответ, совместимый с протоколом Rich Responses.

Многофункциональный возвращаемый объект содержит следующие свойства.

Свойство Тип Описание
$ref String Обязательный. Необходимо указать значение https://copilot.microsoft.com/schemas/rich-response-v1.0.json.

Объект состояний функции

Определяет объекты состояния для состояний оркестратора.

Объект состояния функции содержит следующие свойства.

Свойство Тип Описание
reasoning Объект State Необязательный параметр. Состояние, в котором модель может вызывать функции и выполнять вычисления.
responding Объект State Необязательный параметр. Состояние, в котором модель может создавать текст, отображаемый пользователю. Модель не может вызывать функции в состоянии ответа.
disengaging Объект State Необязательный параметр.

Объект State

Содержит конкретные инструкции для вызова функции в определенном состоянии оркестратора.

Объект состояния содержит следующие свойства.

Свойство Тип Описание
description String Необязательный параметр. Описывает назначение функции при использовании в определенном состоянии оркестратора.
instructions Массив, строка Необязательный параметр. Строка или массив строк, которые используются для предоставления инструкций оркестратору по использованию этой функции в определенном состоянии оркестратора. Предоставление одной строки указывает на намерение предоставить полный набор инструкций, которые переопределяют все встроенные запросы функций. Предоставление массива строк указывает на намерение расширить встроенный механизм запроса функции.
examples Массив, строка Необязательный параметр. Строка или массив строк, которые используются для предоставления примеров оркестратору о том, как можно вызвать эту функцию.
Пример объекта state
{
  "functions": [
    {
      "name": "searchEmails",
      "description": "search for Emails from using 3S search Service",
      "states": {
        "reasoning": {
          "description": "\n# `searchEmails(**params) -> str` returns the emails from user's inbox based on search query.",
          "instructions": [
            "Examine the output of `searchEmails(**params) -> str`.",
            "Do not include any information that is not present in the JSON results.",
            "Exclude any irrelevant data from the JSON results",
            "Determine if the response contains an error field.",
            "If an error is present, provide the error code and error message extracted from the response JSON.",
            "If there is no error, extract and include as much relevant information as possible from the JSON result to meet the user's needs."
          ],
          "examples": []
        }
      }
    }
  ]
}

Объект функциональных возможностей

Содержит коллекцию данных, используемых для настройки необязательных возможностей оркестратора при вызове функции.

Объект function capabilities содержит следующие свойства.

Свойство Тип Описание
confirmation Объект подтверждения Необязательный параметр. Описывает диалоговое окно подтверждения, которое должно быть представлено пользователю перед вызовом функции.
response_semantics Объект семантики ответа Необязательный параметр. Описывает, как оркестратор может интерпретировать полезные данные ответа и предоставлять визуальную отрисовку.
security_info Объект сведений о безопасности Необязательный параметр. Содержит аттестации о поведении подключаемого модуля для оценки рисков вызова функции. Если это свойство пропущено, функция не может взаимодействовать с другими подключаемыми модулями или возможностями содержащего агента.

Объект подтверждения

Описывает, как оркестратор запрашивает у пользователя подтверждение перед вызовом функции.

Объект подтверждения содержит следующие свойства.

Свойство Тип Описание
type String Необязательный параметр. Указывает тип подтверждения. Возможные значения: None, AdaptiveCard.
title String Необязательный параметр. Название диалогового окна подтверждения. Это свойство локализуется.
body String Необязательный параметр. Текст диалогового окна подтверждения. Это свойство локализуется.

Объект семантики ответа

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

Объект семантики ответа содержит следующие свойства.

Свойство Тип Описание
data_path String Обязательный. Запрос JSONPath RFC9535 , который определяет набор элементов из ответа функции для отображения с помощью шаблона, указанного в каждом элементе.
properties Объект свойств семантики ответа Необязательный параметр. Позволяет сопоставлять запросы JSONPath с известными элементами данных. Каждый запрос JSONPath относительно результирующих значений.
static_template Объект Необязательное. Объект JSON, соответствующий схеме адаптивных карточек и языку шаблонов. Этот экземпляр адаптивной карточки используется для отрисовки результата из ответа подключаемого модуля. Это значение используется, если template_selector отсутствует или не удается разрешить в адаптивный карта.
oauth_card_path String Необязательный параметр.
Пример статического шаблона
{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.resources",
        "properties": {
          "title": "$.name",
          "subtitle": "$.location",
          "url": "$.href",
          "information_protection_label": "$.ipLabel"
        },
        "static_template": {
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "type": "AdaptiveCard",
          "version": "1.5",
          "body": [
            {
              "type": "TextBlock",
              "text": "${name}",
              "weight": "Bolder"
            },
            {
              "type": "TextBlock",
              "text": "${description}"
            }
          ],
          "action": [
            {
              "type": "Action.OpenUrl",
              "title": "View",
              "text": "${href}"
            }
          ]
        }
      }
    }
  }
}
Пример динамического шаблона
{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.attachments",
        "properties": {
          "title": "$.title",
          "subtitle": "$.subtitle",
          "url": "$.url",
          "thumbnail_url": "$.thumbnailUrl",
          "template_selector": "$.template"
        }
      }
    }
  }
}

Объект свойств семантики ответа

Позволяет сопоставлять запросы JSONPath с известными элементами данных. Каждый запрос JSONPath относительно результирующих значений.

Объект свойств семантики ответа содержит следующие свойства.

Свойство Тип Описание
title String Необязательный параметр. Заголовок ссылки на результат.
subtitle String Необязательный параметр. Подзаголовок ссылки для результата.
url String Необязательный параметр. URL-адрес ссылки на результат.
thumbnail_url String Необязательный параметр. URL-адрес эскиза для результата.
information_protection_label String Необязательный параметр. Индикатор конфиденциальности данных содержимого результата.
template_selector String Необязательный параметр. Выражение JSONPath для экземпляра адаптивной карточки, используемого для отрисовки результата.

Объект сведений о безопасности

Содержит сведения об использовании для определения относительного риска вызова функции.

Объект сведений для безопасности содержит следующие свойства.

Свойство Тип Описание
data_handling Массив строк Обязательное. Массив строк, описывающих поведение функции по обработке данных. Допустимые значения: GetPublicData, GetPrivateData, DataTransform, DataExportи ResourceStateUpdate.
Значения обработки данных
Значение Описание Пример
GetPublicData Указывает, что функция получает данные из внешнего источника, который не требует проверки подлинности. Функция, которая выполняет вызов службы для получения данных с общедоступного веб-сайта.
GetPrivateData Указывает, что функция получает данные из внешнего источника, требующего проверки подлинности, или из текущего приложения пользователя. Функция, которая получает данные из частной базы данных или из открытого документа пользователя.
DataTransform Указывает, что функция возвращает только выходные данные на основе входных данных, не вводя новые данные или не вызывая обновления ресурса. Функция, которая преобразует число в слово или форматирует дату.
DataExport Указывает, что функция отправляет или записывает данные в расположение за пределами самой функции. Функция, которая сохраняет данные в локальный или облачный файл.
ResourceStateUpdate Указывает, что функция влияет на ресурс путем инициации транзакции, изменения процесса в реальном мире, предоставления или запрета разрешений или выполнения любых других действий, требующих явного подтверждения пользователем. Функция, которая бронирует гостиничный номер или изменяет состояние рабочего элемента с active на resolved.

Примечание.

Манифесты подключаемого DataExport модуля, использующие значение, могут завершиться ошибкой проверки при попытке установить подключаемый модуль. Это временно и будет решено в ближайшее время.

Объект среды выполнения OpenAPI

Описывает, как подключаемый модуль вызывает функции OpenAPI.

Объект среды выполнения OpenAPI содержит следующие свойства.

Свойство Тип Описание
type String Обязательный. Определяет эту среду выполнения как среду выполнения OpenAPI. Необходимо указать значение OpenApi.
auth Объект проверки подлинности среды выполнения Обязательно. Сведения о проверке подлинности, необходимые для вызова среды выполнения.
run_for_functions Массив строк Необязательное. Имена функций, доступных в этой среде выполнения. Если это свойство опущено, доступны все функции, описанные средой выполнения. Указанные строковые значения могут содержать подстановочные знаки. Несколько сред выполнения не должны объявлять поддержку одной и той же функции неявно или явно.
spec Объект спецификации OpenAPI Обязательно. Содержит сведения о OpenAPI, необходимые для вызова среды выполнения.

Объект спецификации OpenAPI

Содержит сведения о OpenAPI, необходимые для вызова среды выполнения.

Объект спецификации OpenAPI содержит следующие свойства.

Свойство Тип Описание
url String Необязательный параметр. URL-адрес для получения спецификации OpenAPI, вызываемой запросом GET. Этот член является обязательным, если api_description он отсутствует.
api_description String Необязательный параметр. Строка, содержащая описание OpenAPI. Если этот элемент присутствует, url он не является обязательным и игнорируется, если он присутствует.
progress_style String Необязательный параметр. Стиль выполнения, используемый для отображения хода выполнения функции. Возможные значения: None, ShowUsage, ShowUsageWithInput, ShowUsageWithInputAndOutput.
Пример объекта спецификации OpenAPI
{
  "runtimes":
  [
    {  
      "type": "OpenApi",
      "auth": {
        "type": "None"
      },
      "spec": {
        "url": "https://example.org/api/openapi.yaml",  
      }
    }
  ]
}  

Объект проверки подлинности среды выполнения

Содержит сведения, используемые подключаемым модулем для проверки подлинности в среде выполнения.

Объект проверки подлинности среды выполнения содержит следующие свойства.

Свойство Тип Описание
type String Необязательный параметр. Указывает тип проверки подлинности, необходимый для вызова функции. Возможные значения: None, OAuthPluginVault, ApiKeyPluginVault.
reference_id String Необязательный параметр. Значение, используемое при type значении или OAuthPluginVaultApiKeyPluginVault. Значение reference_id получается независимо при предоставлении необходимых значений конфигурации проверки подлинности. Этот механизм существует для предотвращения необходимости хранения значений секретов в манифесте подключаемого модуля.
Пример объекта проверки подлинности среды выполнения
{
  "type": "OAuthPluginVault",
  "reference_id": "0123456-abcdef"
}

Объект возможностей подключаемого модуля

Описывает возможности подключаемого модуля.

Объект возможностей подключаемого модуля содержит следующие свойства.

Свойство Тип Описание
conversation_starters Массив начального объекта Conversation Необязательный параметр. Начальные параметры диалога, которые могут отображаться пользователю для получения рекомендаций по вызову подключаемого модуля.

Начальный объект conversation

Пример вопроса, на который может ответить подключаемый модуль.

Начальный объект диалога содержит следующие свойства.

Свойство Тип Описание
text String Обязательный. Текст начального текста беседы. Это свойство локализуется.
title String Необязательный параметр. Название начального окна беседы. Это свойство локализуется.
Пример начального объекта conversation
{
  "conversation_starters": [
    {
      "title": "Developer tasks",
      "text": "What issues are assigned to me?"
    }
  ]
}

Пример манифеста

Ниже приведен пример файла манифеста подключаемого модуля, который использует большинство свойств манифеста и свойств объектов, описанных в этой статье:

{
  "schema_version": "v2.2",
  "name_for_human": "Contoso Real Estate",
  "description_for_human": "Find up-to-date, detailed real estate properties for sale on the market",
  "description_for_model": "Plugin for finding properties for sale. Use it whenever a user asks about real estate properties for sale on the market. This plugin can be used to search for properties in a particular city, and with a given number of bedrooms, bathrooms, and amenities.",
  "capabilities": {
    "conversation_starters": [
      {
        "title": "Available listings",
        "text": "What listings are available in my area?"
      }
    ]
  },
  "functions": [
    {
      "name": "getListings",
      "description": "Get a list of properties matching the specified criteria",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "The city to search properties in"
          },
          "bedrooms": {
            "type": "number",
            "description": "The number of bedrooms the property should have"
          },
          "bathrooms": {
            "type": "number",
            "description": "The number of bathrooms the property should have"
          },
          "amenities": {
            "type": "array",
            "description": "The list of amenities the property should have",
            "items": {
              "type": "string",
              "description": "One amenity the property should have",
              "enum": [
                "air conditioning",
                "balcony",
                "dishwasher",
                "elevator",
                "fireplace",
                "furniture",
                "garden",
                "gym",
                "heating",
                "jacuzzi",
                "laundry room",
                "microwave",
                "no furniture",
                "parking",
                "patio",
                "sauna",
                "swimming pool",
                "terrace",
                "wi-fi"
              ]
            }
          }
        }
      },
      "returns": {
        "type": "string",
        "description": "A list of properties"
      },
      "states": {
        "reasoning": {
          "description": "`getListings` returns a list of real estate properties for sale based on the specified criteria.",
          "instructions": [
            "If the user mentions a city in their question, only search in that city by using the city parameter.",
            "If the user asks for properties with things like parking space, heating, jacuzzi, or similar amenities, use the amenities parameter to filter the results.",
            "Only use the list of amenities provided in the amenities parameter enum. If the user asked for an amenity that is not in the list, find the closest match from the list, or ignore it if no match can be found.",
            "Determine if the response contains an error field.",
            "If an error is present, provide the error code and error message from the JSON response to the user.",
            "If there is no error, extract and include as much relevant information as possible from the JSON response to meet the users needs."
          ]
        }
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "GetPublicData",
            "GetPrivateData"
          ]
        }
      }
    },
    {
      "name": "saveSearch",
      "description": "Save a search for properties for sale",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "The city to search in"
          },
          "bedrooms": {
            "type": "number",
            "description": "The number of bedrooms"
          }
        },
        "required": [
          "city"
        ]
      },
      "returns": {
        "type": "string",
        "description": "The unique ID for the saved search"
      },
      "states": {
        "responding": {
          "description": "`saveSearch` returns a unique ID that identifies the newly saved search.",
          "instructions": [
            "Examine the output of the `saveSearch` function.",
            "Extract the unique ID integer from the output and include it in your response to the user."
          ]
        }
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "ResourceStateUpdate"
          ]
        }
      }
    },
    {
      "name": "deleteSavedSearch",
      "description": "Delete a previously saved search",
      "parameters": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The unique ID of the saved search"
          }
        },
        "required": [
          "id"
        ]
      },
      "returns": {
        "type": "string",
        "description": "True if the saved search was deleted, false otherwise"
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "ResourceStateUpdate"
          ]
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "OpenApi",
      "auth": {
        "type": "none"
      },
      "run_for_functions": [
        "getListings",
        "saveSearch",
        "deleteSavedSearch"
      ],
      "spec": {
        "url": "http://contoso.com/openapi.yaml"
      }
    }
  ],
  "logo_url": "http://contoso.com/logo.png",
  "contact_email": "contact@contoso.com",
  "legal_info_url": "https://contoso.com/legal/"
}

См. также