Этот браузер больше не поддерживается.
Выполните обновление до Microsoft Edge, чтобы воспользоваться новейшими функциями, обновлениями для системы безопасности и технической поддержкой.
Примечание
Расширения сообщений, созданные с помощью API (на основе API), используют веб-службу для управления пользовательскими запросами и ответами и не требуют регистрации бота. Расширения сообщений на основе API — это возможность приложения Microsoft Teams, которая интегрирует внешние API непосредственно в Teams, повышая удобство использования приложения и обеспечивая простой пользовательский интерфейс. Расширения сообщений на основе API поддерживают команды поиска и могут использоваться для получения и отображения данных из внешних служб в Teams, упрощая рабочие процессы, уменьшая необходимость переключения между приложениями. Расширения сообщений на основе API помогают приложениям напрямую взаимодействовать со сторонними данными, приложениями и службами, расширяя их возможности. С помощью расширения сообщений на основе API вы можете:
Дополнительные сведения о создании расширения для сообщений на основе API с помощью набора средств Teams см. в этом видео:
| Традиционные расширения сообщений на основе ботов | Расширения сообщений на основе API |
|---|---|
| Разработчикам необходимо создавать, развертывать и обслуживать службу для обработки команд вызова из клиента Teams. | Если API конечной службы можно описать с помощью спецификации OpenAPI, разработчики могут устранить необходимость в службе обработки среднего уровня. |
| Эта служба обрабатывает входящий запрос и вызывает конечную службу разработчика. | Teams могут напрямую использовать спецификацию OpenAPI для создания запросов и взаимодействия с конечной службой разработчика. |
На следующих изображениях показан поток запросов пользователей через расширения традиционных сообщений и расширения сообщений API:
Поток запросов пользователя с помощью традиционных расширений сообщений. Разработчик должен поддерживать настраиваемую службу обработчика бота, которая обрабатывает запросы от бота Teams. Служба обработчика отправляет запрос службе разработчика при вызове запроса.
Поток запросов пользователя с помощью расширений сообщений API. Служба обработчика, поддерживаемая разработчиком, не требуется, если взаимодействие четко описано в спецификации OpenAPI в пакете приложения.
Ниже приведена последовательность событий высокого уровня, возникающих при вызове команды запроса:
Когда пользователь вызывает команду запроса, параметры команды запроса получаются Служба Bot Teams.
Команда запроса определяется внутри файла манифеста приложения. Определение команды содержит ссылку operationId на внутри файла спецификации OpenAPI, а также сведения о параметрах, которые клиент Teams отображает для этой команды. Для справки operationId , файл в файле спецификации OpenAPI является уникальным для конкретной операции HTTP.
Затем Служба Bot Teams использует параметры, предоставленные пользователем, вместе с копией спецификации OpenAPI для связанного operationId для создания HTTP-запроса для конечной точки разработчика.
Если проверка подлинности является обязательной и настроена в манифесте. Он разрешается в соответствующий маркер или ключ. Этот токен или ключ используется в составе исходящего запроса. [Необязательно]
Служба бота Teams выполняет HTTP-запрос к службе разработчика.
Служба разработчика должна отвечать в соответствии со схемой, описанной в спецификации OpenAPI. Это формат JSON.
Клиент Teams должен отобразить результаты обратно пользователю. Чтобы преобразовать результаты JSON из предыдущего шага в пользовательский интерфейс, служба бота Teams использует шаблон отрисовки ответа для создания адаптивной карточки для каждого результата.
Адаптивные карточки отправляются клиенту, который отображает их в пользовательском интерфейсе.
Пакет определения приложения содержит различные привлекательные артефакты, которые поддерживают функциональные возможности этой функции. Прежде чем приступить к работе, убедитесь, что у вас есть базовое представление о следующих файлах:
Описание OpenAPI documenat — это принятый отраслевой стандарт для описания API. Это позволяет абстрагировать API-интерфейсы от их реализации, предоставляя определения, не зависящие от языка, которые являются как читаемыми, так и машиночитаемыми. Описание OpenAPI documenat описывает взаимодействия, поддерживаемые вашим расширением, позволяя Teams создавать запросы и взаимодействовать напрямую со службой без необходимости в службе обработки среднего уровня.
Документ с описанием OpenAPI содержит сведения для взаимодействия со службой разработчика. Убедитесь, что вы придерживаетесь следующих рекомендаций для документа OpenAPI Description (OAD):
servers.url свойства.operationId.oneOfконструкции , anyOf, allOfи not (swagger.io).Следующий код является примером документа OpenAPI Description:
openapi: 3.0.1
info:
title: OpenTools Plugin
description: A plugin that allows the user to find the most appropriate AI tools for their use cases, with their pricing information.
version: 'v1'
servers:
- url: https://gptplugin.opentools.ai
paths:
/tools:
get:
operationId: searchTools
summary: Search for AI Tools
parameters:
- in: query
name: search
required: true
schema:
type: string
description: Used to search for AI tools by their category based on the keywords. For example, ?search="tool to create music" will give tools that can create music.
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/searchToolsResponse'
"400":
description: Search Error
content:
application/json:
schema:
$ref: '#/components/schemas/searchToolsError'
components:
schemas:
searchToolsResponse:
required:
- search
type: object
properties:
tools:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the tool.
opentools_url:
type: string
description: The URL to access the tool.
main_summary:
type: string
description: A summary of what the tool is.
pricing_summary:
type: string
description: A summary of the pricing of the tool.
categories:
type: array
items:
type: string
description: The categories assigned to the tool.
platforms:
type: array
items:
type: string
description: The platforms that this tool is available on.
description: The list of AI tools.
searchToolsError:
type: object
properties:
message:
type: string
description: Message of the error.
Дополнительные сведения о написании определений OpenAPI в YAML см. в разделе Структура OpenAPI.
Манифест приложения — это схема приложения Teams, определяющая способ и место вызова расширения сообщений в клиенте Teams. Он включает в себя команды, поддерживаемые вашим расширением, и расположения, из которых к ним можно получить доступ, такие как область создания сообщений, панель команд и сообщение. Манифест ссылается на спецификацию OpenAPI и шаблон отрисовки ответа для обеспечения надлежащей функциональности.
Манифест приложения содержит определение команды запроса. Убедитесь, что вы придерживаетесь следующих рекомендаций для манифеста приложения:
1.17.composeExtensions.composeExtensionTypeapiBased.composeExtensions.apiSpecificationFile в качестве относительного пути к документу Описание OpenAPI в папке. Это связывает манифест приложения со спецификацией API.apiResponseRenderingTemplateFile в качестве относительного пути к шаблону отрисовки ответа. Это указывает расположение шаблона, используемого для отрисовки ответов API.Commands.id в манифесте приложения должно соответствовать свойству в документе operationId Описание OpenAPI.parameters.name в манифесте приложения должна соответствовать в документе parameters.name описание OpenAPI.parameters.name в манифесте приложения должна соответствовать необязательным parameters.name в документе Описание OpenAPI.Ниже приведен пример манифеста приложения с определениями для расширений сообщений на основе API:
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+ "manifestVersion": "devPreview",
"version": "1.0.0",
"id": "04805b4b-xxxx-xxxx-xxxx-4dbc1cac8f89",
"packageName": "com.microsoft.teams.extension",
"developer": {
"name": "Teams App, Inc.",
"websiteUrl": "https://www.example.com",
"privacyUrl": "https://www.example.com/termofuse",
"termsOfUseUrl": "https://www.example.com/privacy"
},
"icons": {
"color": "color.png",
"outline": "outline.png"
},
"name": {
"short": "AI tools",
"full": "AI tools"
},
"description": {
"short": "AI tools",
"full": "AI tools"
},
"accentColor": "#FFFFFF",
"composeExtensions": [
{
+ "composeExtensionType": "apiBased",
+ "authorization": {
+ "authType": "apiSecretServiceAuth ",
+ "apiSecretServiceAuthConfiguration": {
+ "apiSecretRegistrationId": "96270b0f-7298-40cc-b333-152f84321813"
+ }
+ },
+ "apiSpecificationFile": "aitools-openapi.yml",
"commands": [
{
"id": "searchTools",
"type": "query",
"context": [
"compose",
"commandBox"
],
"title": "search for AI tools",
"description": "search for AI tools",
"parameters": [
{
"name": "search",
"title": "search query",
"description": "e.g. search='tool to create music'"
}
],
+ "apiResponseRenderingTemplateFile": "response-template.json"
}
]
}
],
"validDomains": []
}
| Имя | Описание |
|---|---|
composeExtensions.composeExtensionType |
Compose тип расширения. Обновите значение на apiBased. |
composeExtensions.authorization |
Сведения об авторизации для расширения сообщений на основе API |
composeExtensions.authorization.authType |
Перечисление возможных типов авторизации. Поддерживаемые значения: none, apiSecretServiceAuthи microsoftEntra. |
composeExtensions.authorization.apiSecretServiceAuthConfiguration |
Объект, фиксирующий сведения, необходимые для проверки подлинности службы. Применимо, только если тип проверки подлинности имеет значение apiSecretServiceAuth. |
composeExtensions.authorization.apiSecretServiceAuthConfiguration.apiSecretRegistrationId |
Идентификатор регистрации возвращается, когда разработчик отправляет ключ API через портал разработчика. |
composeExtensions.apiSpecificationFile |
Ссылается на файл описания OpenAPI в пакете приложения. Включить, если тип имеет значение apiBased. |
composeExtensions.commands.id |
Уникальный идентификатор, назначенный команде поиска. Запрос пользователя включает этот идентификатор. Идентификатор должен совпадать с operationId доступным в описании OpenAPI. |
composeExtensions.commands.context |
Массив, в котором определены точки входа для расширения сообщений. Значения по умолчанию: compose и commandBox. |
composeExtensions.commands.parameters |
Определяет статический список параметров для команды . Имя должно сопоставляться с в parameters.name описании OpenAPI. Если вы ссылаетесь на свойство в схеме текста запроса, имя должно сопоставляться с properties.name параметрами запроса или . |
composeExtensions.commands.apiResponseRenderingTemplateFile |
Шаблон, используемый для форматирования ответа JSON из API разработчика в ответ адаптивной карточки. [Обязательно] |
Дополнительные сведения см. в разделе ComposeExtensions.
Шаблон отрисовки ответа — это стандартный формат, который определяет, как результаты из API отображаются в Teams. Он использует шаблоны для создания адаптивных карточек или других элементов пользовательского интерфейса на основе отклика API, обеспечивая простой и интегрированный пользовательский интерфейс в Teams. Шаблон определяет макет и стиль представляемой информации, которая может включать текст, изображения и интерактивные компоненты. Убедитесь, что вы придерживаетесь следующих рекомендаций по шаблону отрисовки ответов:
$schema , чтобы установить структуру шаблона в схеме шаблона отрисовки ответа.responseLayout : list и grid, которые определяют способ визуального представления ответа. Дополнительные сведения о макете см. в статье Реагирование на запросы пользователей.jsonPath запрашивается для массивов или, если данные для адаптивной карточки не являются корневым объектом. Например, если данные вложены в productDetails, путь JSON будет иметь значение productDetails.jsonPath в качестве пути к соответствующим данным или массиву в ответе API. Если путь указывает на массив, то каждая запись в массиве привязывается к шаблону адаптивной карточки и возвращается в виде отдельного результата.
[Необязательно]Следующий код является примером шаблона отрисовки ответа:
{
"version": "1.0",
"$schema": "developer.microsoft.com/json-schemas/teams/v1.17/MicrosoftTeams.ResponseRenderingTemplate.schema.json",
"jsonPath": "repairs",
"responseLayout": "grid",
"responseCardTemplate": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{
"type": "Container",
"items": [
{
"type": "ColumnSet",
"columns": [
{
"type": "Column",
"width": "stretch",
"items": [
{
"type": "TextBlock",
"text": "Title: ${if(title, title, 'N/A')}",
"wrap": true
},
{
"type": "TextBlock",
"text": "Description: ${if(description, description, 'N/A')}",
"wrap": true
},
{
"type": "TextBlock",
"text": "Assigned To: ${if(assignedTo, assignedTo, 'N/A')}",
"wrap": true
},
{
"type": "Image",
"url": "${image}",
"size": "Medium",
"$when": "${image != null}"
}
]
},
{
"type": "Column",
"width": "auto",
"items": [
{
"type": "Image",
"url": "${if(image, image, '')}",
"size": "Medium"
}
]
}
]
},
{
"type": "FactSet",
"facts": [
{
"title": "Repair ID:",
"value": "${if(id, id, 'N/A')}"
},
{
"title": "Date:",
"value": "${if(date, date, 'N/A')}"
}
]
}
]
}
]
},
"previewCardTemplate": {
"title": "Title: ${if(title, title, 'N/A')}",
"subtitle": "Description: ${if(description, description, 'N/A')}",
"text": "Assigned To: ${if(assignedTo, assignedTo, 'N/A')}",
"image": {
"url": "${image}",
"$when": "${image != null}"
}
}
}
Карточка предварительного просмотра
Шаблон предварительного просмотра карта в схеме шаблона отрисовки ответа используется для сопоставления ответов JSON с предварительным карта, который пользователи видят при выборе результата поиска. Затем карта предварительного просмотра разворачивается в адаптивную карточку в окне создания сообщения. Шаблон предварительной версии карта является частью шаблона отрисовки ответа, который также включает шаблон адаптивной карточки и метаданные.
Расширенная адаптивная карточка
| Свойство | Тип | Описание | Обязательный |
|---|---|---|---|
version |
string |
Версия схемы текущего шаблона отрисовки ответа. | Да |
jsonPath |
string |
Путь к соответствующему разделу в результатах, к которым должны применяться responseCardTemplate и previewCardTemplate. Если значение не задано, корневой объект обрабатывается как соответствующий раздел. Если соответствующий раздел является массивом, каждая запись сопоставляется с responseCardTemplate и previewCardTemplate. | Нет |
responseLayout |
responseLayoutType |
Указывает макет результатов во всплывающем элементе расширения сообщения. Поддерживаемые типы: list и grid. |
Да |
responseCardTemplate |
adaptiveCardTemplate |
Шаблон для создания адаптивной карточки из результирующих записей. | Да |
previewCardTemplate |
previewCardTemplate |
Шаблон для создания предварительного карта из записи результата. Результирующий карта предварительного просмотра отображается во всплывающем меню расширения сообщения. | Да |
Путь JSON необязателен, но его следует использовать для массивов или где объект, используемый в качестве данных для адаптивной карточки, не является корневым объектом. Путь JSON должен соответствовать формату, определенному Newtonsoft. Это средство можно использовать. Средство JSON можно использовать для проверки правильности пути JSON. Если путь JSON указывает на массив, то каждая запись в этом массиве привязывается к шаблону адаптивной карточки и возвращается в виде отдельных результатов.
Пример Предположим, что у вас есть следующий код JSON для списка продуктов и вы хотите создать карта результат для каждой записи.
{
"version": "1.0",
"title": "All Products",
"warehouse": {
"products": [
...
]
}
}
Как видите, массив результатов находится в разделе "products", который вложен в "warehouse", поэтому путь JSON будет "warehouse.products".
Используйте https://adaptivecards.io/designer/ для предварительного просмотра адаптивную карточку, вставив шаблон в Редактор полезных данных карточки. Возьмите пример записи ответа из массива или для объекта и вставьте ее в пример Редактор данных. Убедитесь, что карта правильно отрисовывается и соответствует вашему вкусу.
Примечание
Мы отправляем заголовок языка принятия в HTTP-запросе, который отправляется в конечную точку, определенную в документе описания OpenAPI. Язык принятия основан на языковом стандарте клиента Teams и может использоваться разработчиком для возврата локализованного ответа.
Следующие типы данных в документе описания OpenAPI преобразуются в элементы адаптивной карточки следующим образом:
string, number, integerboolean типы преобразуются в TextBlock.
Исходная схема: string, number, integerи boolean
name:
type: string
example: doggie
Целевая схема: Textblock
{
"type": "TextBlock",
"text": "name: ${if(name, name, 'N/A')}",
"wrap": true
}
array: массив преобразуется в контейнер в адаптивной карточке.
Исходная схема: array
type: array
items:
required:
- name
type: object
properties:
id:
type: integer
category:
type: object
properties:
name:
type: string
Целевая схема: Container
{
"type": "Container",
"$data": "${$root}",
"items": [
{
"type": "TextBlock",
"text": "id: ${if(id, id, 'N/A')}",
"wrap": true
},
{
"type": "TextBlock",
"text": "category.name: ${if(category.name, category.name, 'N/A')}",
"wrap": true
}
]
}
object: объект преобразуется во вложенное свойство в адаптивной карточке.
Исходная схема: object
components:
schemas:
Pet:
category:
type: object
properties:
id:
type: integer
name:
type: string
Целевая схема: вложенное свойство в адаптивной карточке
{
"type": "TextBlock",
"text": "category.id: ${if(category.id, category.id, 'N/A')}",
"wrap": true
},
{
"type": "TextBlock",
"text": "category.name: ${if(category.name, category.name, 'N/A')}",
"wrap": true
}
image: если свойство является URL-адресом изображения, оно преобразуется в элемент Image в адаптивной карточке.
Исходная схема: image
image:
type: string
format: uri
description: The URL of the image of the item to be repaired
Целевая схема: "Image"
{
"type": "Image",
"url": "${image}",
"$when": "${image != null}"
}
Отзыв о Platform Docs
Platform Docs — это проект с открытым исходным кодом. Выберите ссылку, чтобы оставить отзыв:
Обучение
Модуль
Узнайте, как улучшить взаимодействие с декларативными агентами с помощью адаптивных карточек для визуального отображения данных API. Создавайте и настраивайте шаблоны адаптивных карточек, интегрируйте их в подключаемые модули API и протестируйте настройку в Microsoft 365 Copilot. Узнайте о практических шагах по созданию и просмотру адаптивных карточек в Visual Studio Code.
Документация
Расширения для обмена сообщениями - Teams
Узнайте, как создавать расширения сообщений и сценарии, в которых они используются. Изучите примеры расширений сообщений на основе действий и поиска.
Создание расширений сообщений на основе ботов - Teams
Узнайте о расширении сообщений на основе Бота с помощью Bot Framework для взаимодействия с веб-службой из разных расположений в клиенте Teams.
Создание расширения сообщений на основе API - Teams
Узнайте, как создать или создать расширение сообщений на основе API с помощью портала разработчика для Teams, набора средств Teams для Visual Studio, Visual Studio Code и CLI.