Расширение сообщений на основе API

Статья
10/28/2024

Примечание.

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

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

Получение информации в режиме реального времени, например последних новостей о запуске продукта.
Получение информации на основе знаний, например файлов проектирования моей команды в Figma

Дополнительные сведения о создании расширения для сообщений на основе 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 (OAD)
Манифест приложения
Шаблон отрисовки ответа

Описание OpenAPI (OAD)

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

Документ с описанием OpenAPI содержит сведения для взаимодействия со службой разработчика. Убедитесь, что вы придерживаетесь следующих рекомендаций для документа OpenAPI Description (OAD):

Поддерживаются версии OpenAPI 2.0 и 3.0.x.
Поддерживаемые форматы — JSON и YAML.
Текст запроса, если он присутствует, должен иметь значение application/Json.
Определите URL-адрес сервера протокола HTTPS для servers.url свойства.
Поддерживаются только методы HTTP POST и GET.
Документ Описание OpenAPI должен иметь operationId.
Допускается только один обязательный параметр без значения по умолчанию.
Обязательный параметр со значением по умолчанию считается необязательным.
Пользователи не должны вводить параметр для заголовка или файла cookie.
Операция не должна иметь обязательный заголовок или параметры файла cookie без значений по умолчанию.
Убедитесь, что в документе Описание OpenAPI отсутствуют удаленные ссылки.
Создание массивов для запроса не поддерживается; однако вложенные объекты в тексте запроса JSON поддерживаются.
Teams не поддерживает oneOfконструкции , anyOf, allOfи not (swagger.io).

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

Пример документа с описанием 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" 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.
Убедитесь, что имя параметров для каждой команды в манифесте приложения точно совпадает с соответствующим именем параметра, определенного для операции в документе Описание OpenAPI.
Шаблон отрисовки ответа должен быть определен для каждой команды, которая используется для преобразования ответов из API.
Описание команд и параметров не должно превышать 128 символов.

Ниже приведен пример манифеста приложения с определениями для расширений сообщений на основе 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.

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

Примечание.

Teams поддерживает адаптивные карточки до версии 1.5. При использовании конструктора адаптивных карточек обязательно измените целевую версию на 1.5.

Шаблон отрисовки ответа — это стандартный формат, который определяет, как результаты из API отображаются в Teams. Он использует шаблоны для создания адаптивных карточек или других элементов пользовательского интерфейса на основе отклика API, обеспечивая простой и интегрированный пользовательский интерфейс в Teams. Шаблон определяет макет и стиль представляемой информации, которая может включать текст, изображения и интерактивные компоненты. Убедитесь, что вы придерживаетесь следующих рекомендаций по шаблону отрисовки ответов:

Определите URL-адрес ссылки на схему в свойстве $schema , чтобы установить структуру шаблона в схеме шаблона отрисовки ответа.
Поддерживаемые значения для responseLayout : list и grid, которые определяют способ визуального представления ответа. Дополнительные сведения о макете см. в статье Реагирование на запросы пользователей.
Объект jsonPath запрашивается для массивов или, если данные для адаптивной карточки не являются корневым объектом. Например, если данные вложены в productDetails, путь JSON будет иметь значение productDetails.
Определите jsonPath в качестве пути к соответствующим данным или массиву в ответе API. Если путь указывает на массив, то каждая запись в массиве привязывается к шаблону адаптивной карточки и возвращается в виде отдельного результата. [Необязательно]
Получите пример ответа для проверки шаблона отрисовки ответа. Это служит в качестве теста, чтобы убедиться, что шаблон работает должным образом.
Используйте такие средства, как Fiddler или Postman, чтобы вызвать API и убедиться, что запрос и ответ действительны. Этот шаг имеет решающее значение для устранения неполадок и подтверждения правильности работы API.
С помощью Designer адаптивной карточки можно привязать ответ 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 с предварительным карта, который пользователи видят при выборе результата поиска. Затем карта предварительного просмотра разворачивается в адаптивную карточку в окне создания сообщения. Шаблон предварительной версии карта является частью шаблона отрисовки ответа, который также включает шаблон адаптивной карточки и метаданные.

Снимок экрана: пример расширения создания, отображающего массив карточек предварительного просмотра при поиске определенного слова. В этом случае при поиске

Расширенная адаптивная карточка

Пример того, как выглядит адаптивная карточка, развернутая после выбора пользователем предварительного карта. На адаптивной карточке отображаются значения Title, Full Description, AssignedTo, RepairId и Date.

Параметры

Свойство	Тип	Описание	Обязательный
`version`	`string`	Версия схемы текущего шаблона отрисовки ответа.	Да
`jsonPath`	`string`	Путь к соответствующему разделу в результатах, к которым должны применяться responseCardTemplate и previewCardTemplate. Если значение не задано, корневой объект обрабатывается как соответствующий раздел. Если соответствующий раздел является массивом, каждая запись сопоставляется с responseCardTemplate и previewCardTemplate.	Нет
`responseLayout`	`responseLayoutType`	Указывает макет результатов во всплывающем элементе расширения сообщения. Поддерживаемые типы: `list` и `grid`.	Да
`responseCardTemplate`	`adaptiveCardTemplate`	Шаблон для создания адаптивной карточки из результирующих записей.	Да
`previewCardTemplate`	`previewCardTemplate`	Шаблон для создания предварительного карта из записи результата. Результирующий карта предварительного просмотра отображается во всплывающем меню расширения сообщения.	Да

Путь JSON

Путь JSON необязателен, но его следует использовать для массивов или где объект, используемый в качестве данных для адаптивной карточки, не является корневым объектом. Путь JSON должен соответствовать формату, определенному Newtonsoft. Это средство можно использовать. Средство JSON можно использовать для проверки правильности пути JSON. Если путь JSON указывает на массив, то каждая запись в этом массиве привязывается к шаблону адаптивной карточки и возвращается в виде отдельных результатов.

Пример Предположим, что у вас есть следующий код JSON для списка продуктов и вы хотите создать карта результат для каждой записи.

{
   "version": "1.0",
   "title": "All Products",
   "warehouse": {
      "products": [
        ...
      ]
   }
}

Как видите, массив результатов находится в разделе "products", который вложен в "warehouse", поэтому путь JSON будет "warehouse.products".

Используйте https://adaptivecards.io/designer/ для предварительного просмотра адаптивной карточки, вставив шаблон в полезные данные карточки Редактор, а затем возьмите пример записи ответа из массива или для объекта и вставьте ее в редактор "Те же данные" справа. Убедитесь, что карта правильно отрисовывается и соответствует вашему вкусу. Teams поддерживает карточки до версии 1.5, а конструктор поддерживает версию 1.6.

Преобразование схемы OpenAPI

Примечание.

Мы отправляем заголовок языка принятия в 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}"
    }
```

Следующее действие

Создание расширения сообщений на основе API

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

Расширение сообщений на основе API

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

Описание OpenAPI (OAD)

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

Параметры

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

Параметры

Путь JSON

Преобразование схемы OpenAPI

Следующее действие

Дополнительные ресурсы