Расширение сообщений на основе API — руководство - Teams

Примечание.

Расширения сообщений на основе API поддерживают только команды поиска.

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

Расширения сообщений на основе API можно использовать для интеграции внешних служб, которые обычно используются в бизнес-рабочем процессе. Например, компания, которая часто использует систему CRM для управления клиентами, может использовать расширение сообщений для получения и отображения данных клиентов непосредственно из Teams. Это приложение помогает экономить время и повышает эффективность, уменьшая потребность в переключении между различными приложениями. Эта функция поддерживается на всех платформах, где доступна Teams, включая настольные компьютеры, веб-приложения и мобильные устройства.

Предварительные условия

Осталось 16 мин

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

Установка	Для использования...
Microsoft Teams	Microsoft Teams для совместной работы со всеми пользователями через приложения для чата, собраний или звонков — все в одном месте.
Microsoft Edge (рекомендуется) или Google Chrome	Браузера со средствами разработчика.
Visual Studio Code;	Сред сборки JavaScript, TypeScript или SharePoint Framework (SPFx). Используйте версию 1.55 или более позднюю.
Учетная запись разработчика Microsoft 365	Доступ к учетной записи Teams с соответствующими разрешениями для установки приложения.
Учетная запись Azure	Доступ к ресурсам Azure.
Документ OpenAPI Description (OAD)	Документ, описывающий возможности API. Дополнительные сведения см. в разделе Описание OpenAPI.

Настройка клиента разработки Teams

Клиент — это как пространство или контейнер для вашей организации в Teams, где вы общаетесь в чате, обмениваются файлами и выполняете собрания. В этом пространстве также можно отправить и протестировать пользовательское приложение. Давайте проверим, готовы ли вы к разработке с помощью клиента.

Проверка параметра отправки пользовательских приложений

После создания приложения необходимо загрузить это приложение в Teams, не распространяя его. Этот процесс называется отправкой пользовательского приложения. Войдите в учетную запись Microsoft 365, чтобы просмотреть этот параметр.

Примечание.

Отправка пользовательских приложений необходима для предварительного просмотра и тестирования приложений в локальной среде Teams. Если он не включен, вы не сможете просматривать и тестировать приложение в локальной среде Teams.

У вас уже есть клиент и есть ли у вас доступ администратора? Давайте проверка, если вы действительно делаете!

Проверьте, можно ли отправить пользовательское приложение в Teams:

В клиенте Teams щелкните значок Приложения .
Выберите Управление приложениями
Выберите Отправить приложение.
Найдите параметр Отправить пользовательское приложение. Если параметр отображается, включена отправка пользовательских приложений.

Примечание.

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

Создание бесплатного клиента разработчика Teams (необязательно)

Если у вас нет учетной записи разработчика Teams, ее можно получить бесплатно. Присоединяйтесь к программе для разработчиков Microsoft 365!

Перейдите в программу для разработчиков Microsoft 365.
Выберите Присоединиться и следуйте инструкциям на экране.
На экране приветствия выберите Настроить подписку E5.
Настройте свою учетную запись администратора. После завершения отобразится следующий экран.
Войдите в Teams с помощью только что настроенной учетной записи администратора. Убедитесь, что у вас есть параметр Отправить пользовательское приложение в Teams.

Получение бесплатной учетной записи Azure

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

У вас есть все средства для настройки учетной записи. Теперь давайте настроим среду разработки и приступим к сборке! Выберите приложение, которое вы хотите создать первым.

Создание документа с описанием OpenAPI

Осталось 15 мин

Описание OpenAPI

Описание OpenAPI (OAD) — это стандартная спецификация, которая описывает структуру и структуру файлов OpenAPI. Это не зависящий от языка, доступный для чтения формат для описания API. Это легко для чтения и записи как для людей, так и для машин. Схема является машиночитаемой и представлена в YAML или JSON.

Для взаимодействия с API требуется документ Описание OpenAPI. Документ Описание OpenAPI должен соответствовать следующим критериям:

Свойство 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.
Для операции не должны требоваться параметры заголовка или файла 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, a search for "tool to create music" provides a list of 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.

Примечание.

Убедитесь, что required: true свойство доступно только для одного параметра. Если есть несколько обязательных параметров, можно обновить требуемое свойство до required: false для остальных параметров.

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

Перейдите в раздел Проверяющий элемент Swagger/OpenAPI и проверьте документ Описание OpenAPI.
Сохраните документ Описание OpenAPI.
Перейдите в раздел Swagger Редактор.
В левой области вставьте описание OpenAPI в редактор.
В области справа выберите GET.
Выберите Попробовать.
Введите значения параметра поиска в поле Инструмент для создания музыки.
Выберите Выполнить. Редактор swagger отображает ответ со списком продуктов.
Перейдите в разделТекст ответа>сервера.
В разделе productsскопируйте первый продукт из списка и сохраните его для дальнейшего использования.

Создание шаблона отрисовки ответа

Осталось 10 мин

Для документа Описание OpenAPI требуется шаблон отрисовки ответа, чтобы приложение отвечало на запросы GET или POST. Шаблон отрисовки ответа состоит из шаблона адаптивной карточки, шаблона предварительного просмотра карта и метаданных.

Шаблон адаптивной карточки

Чтобы создать шаблон адаптивной карточки, выполните следующие действия.

Перейдите к ChatGPT и запросите следующий запрос в области создания сообщения:

 Create an Adaptive Card Template that binds to the following response:
     "categories": [
         "Music Generation",
         "AI Detection"
     ],
     "chatbot_short_url": "https://goto.opentools.ai/c/ai-music-generator",
     "main_summary": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
     "name": "AI Music Generator",
     "opentools_url": "https://goto.opentools.ai/ai-music-generator",
     "platforms": [
         "Web",
         "App",
         "API"
     ]

Выберите Отправить сообщение.

ChatGPT создает ответ с шаблоном адаптивной карточки, который привязывается к образцу данных. Сохраните шаблон адаптивной карточки для дальнейшего использования.

Ниже приведен пример шаблона адаптивной карточки:

Шаблон адаптивной карточки

{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.4",
"body": [
    {
    "type": "TextBlock",
    "text": "AI Music Generator",
    "weight": "Bolder",
    "size": "Large"
    },
    {
    "type": "TextBlock",
    "text": "Categories",
    "size": "Medium"
    },
    {
    "type": "TextBlock",
    "text": "Music Generation, AI Detection",
    "wrap": true
    },
    {
    "type": "TextBlock",
    "text": "Description",
    "size": "Medium"
    },
    {
    "type": "TextBlock",
    "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. AI Music Generator is powered by advanced AI technology, and it makes music production accessible to everyone.",
    "wrap": true
    },
    {
    "type": "TextBlock",
    "text": "Platform",
    "size": "Medium"
    },
    {
    "type": "TextBlock",
    "text": "Web, App, API",
    "wrap": true
    }
],
"actions": [
    {
    "type": "Action.OpenUrl",
    "title": "Learn More",
    "url": "https://goto.opentools.ai/ai-music-generator"
    },
    {
    "type": "Action.OpenUrl",
    "title": "Try It",
    "url": "https://goto.opentools.ai/c/ai-music-generator"
    }
]
}

Чтобы проверить, привязывается ли созданная адаптивная карточка к образцу данных, выполните следующие действия.
1. Перейдите в раздел Адаптивная карточка Designer.
2. Перейдите в раздел Выбор ведущего приложения и выберите Microsoft Teams в раскрывающемся списке.
3. Перейдите в редактор полезных данных карточки и вставьте код шаблона адаптивной карточки.
4. Перейдите в редактор примеров данных и вставьте ранее сохраненный ответ GET API.
5. Выберите Режим предварительного просмотра. Конструктор адаптивных карточек отображает адаптивную карточку с данными, которые привязывают ответ к шаблону.

Создание шаблона предварительной версии карта

Шаблон предварительного просмотра карта может содержать titleсвойства и subtitleimage . Если в ответе API нет изображения, можно удалить свойство image.

Ниже приведен пример шаблона предварительной версии карта:

Предварительный просмотр шаблона карта

   "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}",
    }

Создайте условие if для title и subtitle, где:

Если имя существует, бот использует его.
Если имя не существует, бот использует na.

Например, "title": "Name: ${if(name, name, 'N/A')}". Сохраните шаблон предварительной версии карта для дальнейшего использования.

Шаблон отрисовки ответа

Шаблон отрисовки ответа должен соответствовать схеме, размещенной в https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.ResponseRenderingTemplate.schema.json.

Чтобы создать шаблон отрисовки ответа, выполните следующие действия.

Создайте JSON-файл и добавьте в файл следующий код:

{ 
  "version": "1.0.0", 
  "$schema": "<URL_REFERENCE_TO_SCHEMA>", 
  "jsonPath": "", 
  "responseLayout": "", 
  "responseCardTemplate": { 
 },
 "previewCardTemplate": {
     }
 }

Обновите свойства в шаблоне отрисовки ответа следующим образом:
1. "version": "1.0.0"
2. "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
3. "jsonPath": "tools"
  
  jsonPath — это путь к одному или нескольким результатам в ответе JSON ответа. Добавьте в jsonPath соответствующий массив данных или массив из списка продуктов в ответе API. В этом случае jsonPath это средства is. Дополнительные сведения об определении пути JSON см. в разделе Запрос JSON с помощью пути JSON.
4. "responseLayout": "list"
  
  responseLayout указывает макет вложений. Используется для ответов типа result. Поддерживаемые типы: список и сетка. Если текст ответа содержит объект с несколькими элементами, такими как текст, заголовок и изображение, то макет ответа должен иметь значение list. Если ответ API содержит только изображения или эскизы, то для макета ответа необходимо задать значение grid.
5. "responseCardTemplate": вставьте код шаблона адаптивной карточки, сохраненный ранее.
  
  responseCardTemplate — это шаблон адаптивной карточки для сопоставления ответа JSON с адаптивной карточкой.
6. "previewCardTemplate": вставьте код шаблона предварительной версии карта, сохраненный ранее.
  
  previewCardTemplate— это предварительная версия карта шаблон используется для отображения результатов предварительного просмотра во всплывающем элементе расширения сообщения.
Сохраните шаблон отрисовки ответа в той же папке, что и документ Описание OpenAPI.

Следующий код является примером шаблона отрисовки ответа:

Шаблон отрисовки ответа

{
        "version": "devPreview",
        "jsonPath": "tools",
        "responseLayout": "list",
        "responseCardTemplate": {
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.4",
    "body": [
        {
        "type": "TextBlock",
        "text": "AI Music Generator",
        "weight": "Bolder",
        "size": "Large"
        },
        {
        "type": "TextBlock",
        "text": "Categories",
        "size": "Medium"
        },
        {
        "type": "TextBlock",
        "text": "Music Generation, AI Detection",
        "wrap": true
        },
        {
        "type": "TextBlock",
        "text": "Description",
        "size": "Medium"
        },
        {
        "type": "TextBlock",
        "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
        "wrap": true
        },
        {
        "type": "TextBlock",
        "text": "Platform",
        "size": "Medium"
        },
        {
        "type": "TextBlock",
        "text": "Web, App, API",
        "wrap": true
        }
    ],
    "actions": [
        {
        "type": "Action.OpenUrl",
        "title": "Learn More",
        "url": "https://goto.opentools.ai/ai-music-generator"
        },
        {
        "type": "Action.OpenUrl",
        "title": "Try It",
        "url": "https://goto.opentools.ai/c/ai-music-generator"
        }
    ]
    },
    "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}",
    } 
    }

Создание манифеста приложения

Осталось 5 мин

Теперь необходимо создать манифест приложения (ранее — манифест приложения Teams). Манифест приложения описывает, как приложение интегрируется с продуктом Microsoft Teams.

Создание манифеста приложения Teams

Чтобы создать манифест, выполните следующие действия.

Создайте json-файл. Манифест приложения должен соответствовать схеме, определенной в схеме манифеста общедоступной предварительной версии приложения для разработчиков.

Добавьте следующий код в JSON-файл:

Манифест приложения

{
 "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
 "manifestVersion": "devPreview",
 "version": "1.0.3",
 "id": "<<YOUR-MICROSOFT-APP-ID>>",
 "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": "Search ME API",
     "full": "Search ME API full"
 },
 "description": {
     "short": "product app for testing API Message Extensions",
     "full": "product app for testing API Message Extensions"
 },
 "accentColor": "#FFFFFF",
 "composeExtensions": [
     {
         "composeExtensionType": "",
         "apiSpecificationFile": "",
         "commands": [
             {
                 "context": [
                     "compose"
                 ],
                 "type": "query",
                 "title": "API for fetching Klarna.",
                 "id": "",
                 "parameters": [
                     {
                         "name": "",
                         "title": "",
                         "description": ""
                     }
                 ],
                 "description": "",
                 "apiResponseRenderingTemplateFile": ""
             }
         ]
     }
 ],
 "permissions": [
     "identity",
     "messageTeamMembers"
 ],
 "validDomains": []
}

Обновите свойства манифеста приложения следующим образом:
- Замените <<YOUR-MICROSOFT-APP-ID>> идентификатором приложения Майкрософт бота.
- Обновите значение для composeExtensionType на apiBased.
- Обновите значение для apiSpecificationFile до пути к файлу описания OpenAPI.
- Обновите значение для commands.id на searchTools.
- Обновите значение для commands.title на Search for AI Tools.
- Обновите значение для commands.description на Search for AI Tools.
- Обновите значение для parameters.name на search. Если параметров нет, то значения должны быть параметрами запроса или properties.name , если они ссылаются на свойство в схеме текста запроса.
- Обновите в файле apiResponseRenderingTemplateFile шаблона отрисовки ответа путь.
- Обновите значение для validDomains до конечной точки, service URL определенной в файле описания OpenAPI.
Сохраните манифест приложения Teams в той же папке, где вы сохранили документ Описание OpenAPI и шаблон отрисовки ответа.
- Вам потребуется цветное изображение и изображение контура. Эти изображения должны быть включены в папку и ссылаться на них в манифесте приложения Teams.
- Запакуйте содержимое папки в zip-файл. ZIP-файл должен содержать следующие файлы:
  - Документ с описанием OpenAPI
  - Шаблон отрисовки ответа
  - Манифест приложения
  - Цветной значок
  - Контурный значок

Отправка пользовательского приложения в Teams

Осталось 2 мин

Войдите в тестовую среду Teams, чтобы протестировать приложение в Teams. Чтобы отправить пользовательское приложение в Teams, выполните следующие действия.

Перейдите в Microsoft Teams и выполните вход, используя учетные данные тестового клиента.
Перейдите в раздел Приложения>Управление приложением>Отправка приложения.
Выберите Отправить настроенное приложение.
Выберите созданный ZIP-файл и нажмите кнопку Открыть.
Нажмите Добавить.
Выберите Открыть.
Перейдите в чат, выберите + в области создания сообщения и найдите свое приложение.
Выберите приложение и выполните поисковый запрос.
Приложение отвечает адаптивной карточкой в окне чата.
Нажмите кнопку Отправить.