расширение сообщений API-Based для начинающих
Примечание.
- Расширения сообщений на основе API поддерживают только команды поиска.
- Набор средств Teams поддерживает спецификацию OpenAPI версии 2.0 и 3.0.x.
Расширения сообщений, созданные с помощью API (на основе API), значительно расширяют функциональные возможности приложений Teams, позволяя им взаимодействовать с внешними службами. Это помогает упростить рабочие процессы, уменьшая потребность в переключении между различными приложениями.
Расширение сообщений API можно использовать для интеграции внешних служб, которые обычно используются в бизнес-рабочем процессе. Например, компания, которая часто использует систему CRM для управления клиентами, может использовать расширение обмена сообщениями для получения и отображения данных клиентов непосредственно из Teams. Уменьшая необходимость переключения между различными приложениями, пользователь экономит время и улучшает работу. Расширение сообщений на основе API поддерживается в классических, веб-клиентах и мобильных клиентах Teams.
Предварительные условия
Ниже приведен список средств, необходимых для создания и развертывания приложений.
| Установка | Для использования... |
|---|---|
| Набор средств Teams | Расширение Microsoft Visual Studio Code, которое создает шаблон проекта для вашего приложения. Используйте последнюю версию. |
| Microsoft Teams | Microsoft Teams позволяет взаимодействовать со всеми пользователями, с которыми вы работаете, с помощью приложений для чата, собраний и звонков в одном месте. |
| Node.js | Серверной среды выполнения JavaScript. Дополнительные сведения см . вNode.js таблице совместимости версий для типа проекта. |
| Microsoft Edge (рекомендуется) или Google Chrome | Браузера со средствами разработчика. |
| Visual Studio Code; | Сред сборки JavaScript, TypeScript или SharePoint Framework (SPFx). Используйте версию 1.55 или более позднюю. |
| Учетная запись разработчика Microsoft 365 | Доступ к учетной записи Teams с соответствующими разрешениями для установки приложения. |
| Портал разработчика Teams | Веб-портал для настройки, администрирования и публикации приложения Teams в организации или Microsoft Teams Store. |
| Документ OpenAPI Description (OAD) | Документ, описывающий возможности API. Дополнительные сведения см. в разделе Описание OpenAPI. |
Подготовка среды разработки
После установки необходимых средств настройте среду разработки.
Установка набора средств Teams
Набор средств Teams помогает упростить процесс разработки с помощью инструментов для подготовки и развертывания облачных ресурсов для приложения, публикации в Магазине Teams и многого другого.
Вы можете использовать набор средств с Visual Studio Code или CLI (интерфейс командной строки), который называется Teamsapp.
Откройте Visual Studio Code и выберите представление Расширения (CTRL+SHIFT+X️ / ⇧-X или View > Extensions).
В поле поиска введите Набор средств Teams.
Выберите Установить рядом с набором средств Teams.
Значок Набора средств Teams отображается на панели действий Visual Studio Code.
Набор средств Teams также можно найти в Visual Studio Code Marketplace.
Примечание.
Последняя версия Набора средств Teams — версия 5.
Настройка клиента разработки Teams
Клиент — это как пространство или контейнер для вашей организации в Teams, где вы общаетесь в чате, обмениваются файлами и выполняете собрания. В этом пространстве также можно отправить и протестировать пользовательское приложение. Давайте проверим, готовы ли вы к разработке с помощью клиента.
Проверка параметра отправки пользовательских приложений
После создания приложения необходимо загрузить это приложение в Teams, не распространяя его. Этот процесс называется отправкой пользовательского приложения. Войдите в учетную запись Microsoft 365, чтобы просмотреть этот параметр.
Примечание.
Отправка пользовательских приложений необходима для предварительного просмотра и тестирования приложений в локальной среде Teams. Если он не включен, вы не сможете просматривать и тестировать приложение в локальной среде Teams.
У вас уже есть клиент и есть ли у вас доступ администратора? Давайте проверка, если вы действительно делаете!
Проверьте, можно ли отправить пользовательское приложение в Teams:
В клиенте Teams щелкните значок Приложения .
Выберите Управление приложениями
Выберите Отправить приложение.
Найдите параметр Отправить пользовательское приложение. Если параметр отображается, включена отправка пользовательских приложений.
Примечание.
Если вы не найдете параметр для отправки пользовательского приложения, обратитесь к администратору Teams.
Создание бесплатного клиента разработчика Teams (необязательно)
Если у вас нет учетной записи разработчика Teams, ее можно получить бесплатно. Присоединяйтесь к программе для разработчиков Microsoft 365!
Перейдите в программу для разработчиков Microsoft 365.
Выберите Присоединиться и следуйте инструкциям на экране.
На экране приветствия выберите Настроить подписку E5.
Настройте свою учетную запись администратора. После завершения отобразится следующий экран.
Войдите в Teams с помощью только что настроенной учетной записи администратора. Убедитесь, что у вас есть параметр Отправить пользовательское приложение в Teams.
Получение бесплатной учетной записи Azure
Если вы хотите разместить приложение или получить доступ к ресурсам в Azure, у вас должна быть подписка Azure. Перед началом работы создайте бесплатную учетную запись.
Теперь у вас есть все средства для настройки учетной записи. Теперь давайте настроим среду разработки и приступим к сборке! Выберите приложение, которое вы хотите создать первым.
Создание расширения сообщений на основе API
После настройки рабочей области проекта с помощью Набора средств Teams создайте проект бота. Убедитесь, что вы вошли в учетную запись Microsoft 365.
Вход в учетную запись Microsoft 365
Используйте эту учетную запись для входа в Teams. Если вы используете клиент программы разработчика Microsoft 365, учетная запись администратора, настроенная при регистрации, — это учетная запись Microsoft 365.
Откройте Visual Studio Code.
Щелкните значок Набора средств
Teams на боковой панели.Выберите Войти в M365.
Откроется веб-браузер по умолчанию, чтобы позволить вам войти в учетную запись.
Войдите в учетную запись Microsoft 365, используя свои учетные данные.
Закройте браузер при появлении запроса и вернитесь к Visual Studio Code.
Вернитесь к набору средств Teams в Visual Studio Code.
Используйте эту учетную запись для входа в Teams. Если вы используете клиент программы разработчика Microsoft 365, учетная запись администратора, настроенная при регистрации, — это учетная запись Microsoft 365.
Теперь вы можете создать приложение и запустить его локально!
Создание документа с описанием OpenAPI
Описание OpenAPI (OAD) — это стандартная спецификация, которая описывает структуру и структуру файлов OpenAPI. Это не зависящий от языка, доступный для чтения формат для описания API. Это легко для чтения и записи как для людей, так и для машин. Схема является машиночитаемой и представлена в YAML или JSON.
Перед созданием расширения сообщений на основе API необходимо иметь документ Описание OpenAPI (OAD). Спецификация API должна соответствовать следующим критериям:
- Свойство
authне должно указываться. - Поддерживаемые форматы — JSON и YAML.
- Поддерживаются версии OpenAPI 2.0 и 3.0.x.
- Teams не поддерживает конструкции oneOf, anyOf, allOf и не (swagger.io).
- Создание массивов для запроса не поддерживается, однако поддерживаются вложенные объекты в тексте запроса JSON.
- Текст запроса, если он присутствует, должен быть приложением или Json, чтобы обеспечить совместимость с широким спектром API.
- Определите URL-адрес сервера протокола HTTPS для
servers.urlсвойства. - Поддерживается только поиск по одному параметру.
- Допускается только один обязательный параметр без значения по умолчанию.
- Поддерживаются только методы HTTP POST и GET.
- Документ Описание OpenAPI должен иметь
operationId. - Операция не должна иметь обязательных параметров header или cookie без значений по умолчанию.
- Команда должна иметь ровно один параметр.
- Убедитесь, что в документе Описание OpenAPI отсутствуют удаленные ссылки.
- Обязательный параметр со значением по умолчанию считается необязательным.
В качестве примера для этого руководства мы использовали следующее описание OpenAPI:
Документ с описанием OpenAPI
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" gives 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.
Примечание.
Набор средств Teams поддерживает спецификацию OpenAPI версии 2.0 и 3.0.x.
Теперь, когда у вас есть документ с описанием OpenAPI, для него также требуется шаблон отрисовки ответа, чтобы приложение отвечало на запросы GET или POST. Шаблон отрисовки ответа состоит из шаблона адаптивной карточки, шаблона предварительного просмотра карта и метаданных. Если вы создаете приложение с помощью набора средств Teams или портала разработчика для Teams, шаблон отрисовки ответа извлекается из документа Описание OpenAPI автоматически.
Следующий код является примером шаблона отрисовки ответа:
Шаблон отрисовки ответа
{
"version": "1.0.0",
"jsonPath": "tools",
"responseLayout": "list",
"responseCardTemplate": {
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{
"type": "TextBlock",
"text": "${if(name, name, 'N/A')}",
"size": "Large",
"weight": "Bolder",
"wrap": true
},
{
"type": "TextBlock",
"text": "Categories: ${join(categories, ', ')}",
"size": "Small",
"isSubtle": true,
"wrap": true
},
{
"type": "TextBlock",
"text": "${if(main_summary, main_summary, 'N/A')}",
"size": "Medium",
"wrap": true
},
{
"type": "TextBlock",
"text": "Supported Platforms: ${join(platforms, ', ')}",
"size": "Small",
"isSubtle": true,
"wrap": true
},
{
"type": "TextBlock",
"text": "Pricing Summary:",
"size": "Medium",
"weight": "Bolder",
"wrap": true
},
{
"type": "TextBlock",
"text": "${if(pricing_summary, pricing_summary, 'N/A')}",
"size": "Small",
"wrap": true
}
],
"actions": [
{
"type": "Action.OpenUrl",
"title": "Learn More",
"url": "${opentools_url}",
"$when": "${opentools_url != null}"
},
{
"type": "Action.OpenUrl",
"title": "Chat with Chatbot",
"url": "${chatbot_short_url}",
"$when": "${chatbot_short_url != null}"
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
},
"previewCardTemplate": {
"title": "${if(name, name, 'N/A')}"
}
}
Теперь можно создать расширение для сообщений, использующее документ Описание OpenAPI. Чтобы создать расширение am message с помощью документа Описание OpenAPI, выполните следующие действия.
Откройте Visual Studio Code.
Щелкните значок Набора средств
Teams на панели действий Visual Studio Code.Выберите Создать новое приложение.
Выберите Расширение сообщений.
Выбор настраиваемых результатов поиска
Выберите Начать с документа описания OpenAPI.
Нажмите кнопку Обзор и выберите документ Описание OpenAPI, сохраненный ранее. Появится список API, доступных в документе.
Выберите API в списке и нажмите кнопку ОК.
Выберите Папка по умолчанию , чтобы сохранить корневую папку проекта в расположении по умолчанию.
Вы также можете изменить расположение по умолчанию, выполнив следующие действия.
Нажмите кнопку Обзор.
Выберите расположение рабочей области проекта.
Выберите выбрать папку.
Введите подходящее имя для приложения и нажмите клавишу ВВОД.
Откроется диалоговое окно. Выберите Да, я доверяю авторам или Нет, я не доверяю авторам на основе ваших требований.
Приложение Teams с возможностью расширения сообщений на основе API будет создано за несколько секунд.
После создания приложения набор средств Teams отображает следующее сообщение:
Выберите Локальная отладка , чтобы просмотреть проект.
После завершения формирования шаблонов просмотрите каталоги и файлы проектов в разделе Обозреватель в Visual Studio Code.
| Имя папки | Содержание |
|---|---|
env/.env.dev.user |
Файл конфигурации для локальной среды, используемый teamsapp.yml для настройки правил подготовки и развертывания. |
appPackage |
Файлы шаблонов манифеста приложения и значки приложений (color.png и outline.png). |
appPackage/manifest.json |
Манифест приложения для запуска приложения в локальной и удаленной среде. |
appPackage/apiSpecificationFiles/openapi.yml |
Файл описания, содержащий структуру и синтаксис API в описании OpenAPI. |
appPackage/responseTemplates |
Шаблон отрисовки ответа, который состоит из шаблона адаптивной карточки, предварительного просмотра карта шаблона и метаданных. |
teamsapp.yml |
Это проект набора средств main Teams, который определяет свойства и определения этапов конфигурации. |
Совет
Ознакомьтесь с ботами за пределами Teams, прежде чем интегрировать свой первый бот в Teams.
Подготовка приложения
Чтобы подготовить приложение в Azure, выполните приведенные далее действия.
Перейдите в набор средств Teams и в левой области выберите Запуск и отладка (CTRL+SHIFT+D).
Выберите Запустить удаленное приложение в Teams (Edge) в раскрывающемся списке конфигурация запуска.
Набор средств Teams подготавливает приложение в Azure и развертывает его в Teams.
Примечание.
При первой подготовке приложения это займет несколько минут. Последующие условия выполняются быстрее.
Перейдите в сообщение чата и щелкните значок Действия и приложения . Во всплывающем меню найдите свое приложение.
Выберите приложение из списка и активируйте команды поиска из области создания сообщений.
Teams отправляет результат поиска в виде адаптивной карточки в сообщении чата.
Выполнение задачи
Ты придумала что-то вроде этого?
Поздравляем!
Вы сделали это! Вы создали расширение сообщений на основе API.
Возникла проблема с этим разделом? Если это так, отправьте нам отзыв, чтобы мы исправили этот раздел.
Platform Docs