Универсальная модель действий

Статья
08/29/2023

Контекст

Адаптивные карточки — это независимые от платформы фрагменты пользовательского интерфейса, созданные с использованием упрощенного формата JSON, которые могут совместно использоваться приложениями и службами. Адаптивные карточки не только адаптируются к интерфейсу основного элемента, но также предоставляют широкие возможности взаимодействия. Дополнительные сведения об адаптивных карточках см. на сайте adaptivecards.io.

По мере роста популярности адаптивных карточек разные основные элементы начали поддерживать различные модели действий, что привело к фрагментации. Чтобы решить эту проблему, группы разработчиков Teams, Outlook и адаптивных карточек создали совместимую между основными элементами универсальную модель действий бота. Это привело к следующему:

Обобщению ботов и Bot Framework в качестве способа реализации сценариев на основе адаптивных карточек для Teams (боты) и Outlook (сообщение с действиями).
Реализации Action.Execute в качестве замены для Action.Submit (сейчас используется ботами) и для Action.Http (сейчас используется сообщениями с действиями).
Популярные функции, поддерживаемые только сообщениями, доступными для ботов, а именно:
- Возможность обновления карточки на момент ее отображения.
- Возможность возвращать обновленную карточку, которая сразу же отображается в клиенте, с помощью действий метода Action.Execute.

Дополнительные сведения о сообщениях с действиями в Outlook см. в этой документации.

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

Перед добавлением `Action.Execute`	С добавлением `Action.Execute`

Источник: адаптивные карточки @ Microsoft Build 2020

В оставшейся части этого документа описана универсальная модель действий бота в контексте Teams и Outlook. Если вы уже используете адаптивные карточки в Teams с ботом, вы можете использовать тот же бот с небольшими изменениями для поддержки Action.Execute. Если вы используете сообщения с действиями в Outlook, потребуется разработать бот, поддерживающий Action.Execute. В настоящее время поддержка клиентов Outlook для универсальной модели действий бота находится в активной разработке.

Схема

ВАЖНО

Универсальная модель действий бота появилась в схеме адаптивных карточек версии 1.4. Чтобы использовать эти новые возможности, свойство version адаптивной карточки должно иметь значение 1.4 или выше, как показано в приведенных ниже примерах. Обратите внимание, что это сделает адаптивную карточку несовместимой со старыми клиентами (Outlook или Teams), которые не поддерживают универсальную модель действий бота.

Если вы используете свойство refresh или Action.Execute и указываете версию карточки <1.4, произойдет следующее:

Клиент Поведение

Outlook Ваша карточка НЕ БУДЕТ работать. refresh не будет учитываться, а Action.Execute не будет преобразоваться для просмотра. Ваша карточка может быть полностью отклонена.

Команды Ваша карточка МОЖЕТ не работать (refresh может не учитываться, а действия Action.Execute могут не преобразоваться для просмотра) в зависимости от версии клиента Teams.

Чтобы обеспечить максимальную совместимость в Teams, рекомендуется указать действия Action.Execute с помощью действия Action.Submit в свойстве fallback.

Дополнительные сведения см. в разделе Обратная совместимость ниже.

Клиент	Поведение
Outlook	Ваша карточка НЕ БУДЕТ работать. `refresh` не будет учитываться, а `Action.Execute` не будет преобразоваться для просмотра. Ваша карточка может быть полностью отклонена.
Команды	Ваша карточка МОЖЕТ не работать (`refresh` может не учитываться, а действия `Action.Execute` могут не преобразоваться для просмотра) в зависимости от версии клиента Teams. Чтобы обеспечить максимальную совместимость в Teams, рекомендуется указать действия `Action.Execute` с помощью действия `Action.Submit` в свойстве `fallback`.

Action.Execute

При разработке адаптивных карточек используйте Action.Execute вместо Action.Submit и Action.Http. Схема для Action.Execute весьма похожа на схему Action.Submit.

Пример JSON

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

Свойства

Свойство	Тип	Обязательно	Описание
type	`"Action.Execute"`	Да	Этот параметр должен содержать значение `"Action.Execute"`.
Глагол	строка	Нет	Удобная строка, которую разработчик может использовать для указания действия
data	`string`, `object`	No	Начальные данные, с которыми будут объединяться поля ввода. По сути, это скрытые свойства.
title	`string`	No	Метка для кнопки или ссылки, которые представляют это действие.
iconUrl	`uri`	No	Необязательный значок, отображаемый для действия в сочетании с заголовком. Поддерживает универсальный код ресурса (URI) данных в адаптивных карточках версии 1.2 и выше
style	`ActionStyle`	No	Управляет стилем действия, которое влияет на отображение действия, его произношение и т. д.
fallback	`<action object>`, `"drop"`	No	Описывает, что делать, если Action.Execute не поддерживается клиентом, отображающим карточку.
requires	`Dictionary<string>`	No	Ряд пар "ключ-значение", указывающих компоненты, необходимые элементу с соответствующей минимальной версией. Если компонент отсутствует или имеет несоответствующую версию, активируется резервный элемент.

Механизм обновления

Помимо Action.Execute, теперь поддерживается новый механизм обновления, что позволяет создавать адаптивные карточки, которые автоматически обновляются на момент их отображения. Благодаря этому пользователи всегда будут видеть актуальные данные. Запрос на утверждение — это типичный вариант использования обновления. После утверждения пользователям не предоставляется карточка с запросом на утверждение, когда он уже выполнен. Вместо этого предоставляются сведения о времени утверждения запроса и о том, кем он был утвержден.

Чтобы разрешить автоматическое обновление адаптивной карточки, укажите свойство refresh, которое встраивает action с типом Action.Execute, а также массив userIds.

Свойство	Тип	Обязательно	Описание
action	`"Action.Execute"`	Да	Должен быть экземпляром действия с типом `"Action.Execute"`.
userIds	`Array<string>`	Да	Массив `MRI` пользователей, для которых должно быть включено автоматическое обновление. ВАЖНО! Если свойство перечисления `userIds` не включено в раздел `refresh` карточки, она не будет автоматически обновляться при отображении. Вместо этого пользователю будет предоставлена кнопка, позволяющая выполнить обновление вручную. Это происходит потому, что чаты или каналы в Teams могут содержать большое количество участников. Если несколько участников одновременно просматривают канал, безусловное автоматическое обновление приведет к большому количеству одновременных вызовов бота, которые не будут масштабироваться. Для устранения потенциальной проблемы масштабирования всегда следует включать свойство `userIds`, чтобы указать, какие пользователи должны получать автоматическое обновление (сейчас доступно максимум 60 идентификаторов пользователей). Дополнительные сведения см. в разделе userIds в свойстве refresh. Обратите внимание, что свойство `userIds` не учитывается в Outlook, а свойство `refresh` всегда учитывается автоматически. В Outlook нет проблем c масштабированием, так как пользователи обычно будут просматривать карту в разное время.

Пример JSON

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "originator":"c9b4352b-a76b-43b9-88ff-80edddaa243b",
  "version": "1.4",
  "refresh": {
    "action": {
      "type": "Action.Execute",
      "title": "Submit",
      "verb": "personalDetailsCardRefresh"
    },
    "userIds": []
  },
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    { 
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

Важное замечание для разработчиков сообщений с действиями Outlook

При разработке сценариев сообщений с действиями Outlook необходимо указать свойство originator адаптивной карточки. originator — это глобальный уникальный идентификатор, созданный на момент, когда бот подписывается на канал Outlook. Он используется Outlook для проверки того, что адаптивная карточка была отправлена авторизованным ботом. Адаптивная карточка не будет преобразована для просмотра в Outlook, если originator отсутствует. originator не учитывается в Teams.

Действие Invoke `adaptiveCard/action`

Когда в клиенте выполняется Action.Execute (будь то действие обновления или действие, явно выполненное пользователем с помощью нажатия кнопки), к боту применяется новый тип действия Invoke — adaptiveCard/action. Типичный запрос действия Invoke adaptiveCard/action будет выглядеть следующим образом:

Формат запроса

{ 
  "type": "invoke",
  "name": "adaptiveCard/action",

  // ... other properties omitted for brevity

  "value": { 
    "action": { 
      "type": "Action.Execute", 
      "id": "abc", 
      "verb": "def",
      "data": { ... } 
    },
    "trigger": "automatic | manual" 
  }
}

Поле	Description
value.action	Копия действия, как определено в адаптивной карточке. Как и в случае с `Action.Submit`, свойство `data` действия включает в себя значения различных входных данных в карточке, если таковые имеются.
value.trigger	Указывает, было ли действие вызвано явным (нажатием кнопки пользователем) или неявным образом (автоматическое обновление).

Формат ответа

Если бот действительно обработал входящее действие Invoke adaptiveCard/action (т. е. если код бота участвовал в обработке запроса), код состояния ответа HTTP, возвращаемый ботом, должен быть равен 200, а текст ответа HTTP должен иметь следующий формат:

{ 
    "statusCode": <number (200 – 599)>, 
    "type": "<string>", 
    "value": "<object>"
}

Поле	Description
statusCode	Код состояния ответа HTTP, равный 200, не обязательно означает, что бот смог успешно обработать запрос. Клиентское приложение всегда ДОЛЖНО учитывать свойство `statucCode` в тексте ответа, чтобы узнать, как бот обработал запрос. `statusCode` — это число в диапазоне от 200 до 599, которое отражает кодовые значения состояния HTTP и является подсостоянием результата обработки действия Invoke ботом. Отсутствующее, неопределенное значение или значение null для `statusCode` подразумевает состояние 200 (успешно).
type	Набор хорошо известных строковых констант, описывающих ожидаемую форму свойства Value.
значение	Объект, относящийся к типу текста ответа

Поддерживаемые коды состояния

В следующей таблице перечислены допустимые значения для statusCode, type и value в тексте ответа бота:

Код состояния	Тип	Схема значений	Примечания
200	`application/vnd.microsoft.card.adaptive`	`Adaptive Card`	Запрос был успешно обработан, и ответ включает в себя адаптивную карточку, которую клиент должен отобразить на месте текущей.
200	`application/vnd.microsoft.activity.message`	`string`	Запрос был успешно обработан, и ответ содержит сообщение, которое должен отобразить клиент.
400	`application/vnd.microsoft.error`	Объект Error (TODO: требуется ссылка)	Входящий запрос недопустим.
401	`application/vnd.microsoft.activity.loginRequest`	OAuthCard (TODO: требуется ссылка)	Клиент должен запросить проверку подлинности у пользователя.
401	`application/vnd.microsoft.error.inccorectAuthCode`	null	Состояние проверки подлинности, переданное клиентом, было неправильным, и проверка подлинности не выполнена.
412	`application/vnd.microsoft.error.preconditionFailed`	Объект Error (TODO: требуется ссылка)	Сбой потока проверки подлинности единого входа.
500	`application/vnd.microsoft.error`	Объект Error (TODO: требуется ссылка)	Произошла непредвиденная ошибка.

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

Используйте Action.Execute вместо Action.Submit. Чтобы обновить существующий сценарий в Teams, замените все экземпляры Action.Submit на Action.Execute. Сведения об обновлении существующего сценария в Outlook см. в разделе "Обратная совместимость" ниже.
Для карточек, отображаемых в Outlook, добавьте поле originator. См. пример JSON выше.
Добавьте предложение refresh к адаптивной карточке, если вы хотите использовать механизм автоматического обновления или если ваш сценарий предполагает использование представлений для определенных пользователей. Не забудьте указать свойство userIds, чтобы определить, какие пользователи (максимум 60) будут получать автоматические обновления.
Обработайте запросы действия Invoke adaptiveCard/action в боте.
Каждый раз, когда бот должен вернуть новую карточку в результате обработки Action.Execute, можно использовать контекст запроса действия Invoke для создания карточек определенного пользователя. Убедитесь, что ответ соответствует схеме ответа, указанной выше.

обратная совместимость

Outlook

Новая универсальная модель действий Action.Execute — это устаревшая модель действий Action.Http, которая в настоящее время используется в сообщениях Outlook, где действия кодируются в адаптивной карточке как явные вызовы HTTP. Модель Action.Execute позволяет разработчикам реализовывать сценарии, которые эффективно работают как в Outlook, так и в Teams. Сценарии с сообщениями с действиями могут использовать либо модель Action.Http, либо новую модель Action.Execute (но не обе). Сценарии, использующие универсальную модель Action.Execute, должны быть реализованы в виде ботов и подписаться на канал Outlook Actionable Messages.

Важные примечания

Сценарии, реализованные с помощью универсальной модели Action.Execute, не совместимы с более старыми версиями Outlook.

В настоящее время ведется работа над тем, чтобы существующие сценарии сообщений с действиями могли плавно перейти к использованию универсальной модели Action.Execute.

Команды

Чтобы карточки были обратно совместимыми и работали для пользователей более ранних версий Teams, действия Action.Execute должны содержать свойство fallback, определенное как Action.Submit. Бот должен быть написан таким образом, чтобы он мог обрабатывать как Action.Execute, так и Action.Submit. Обратите внимание, что бот не может вернуть новую карточку при обработке Action.Submit, поэтому резервное поведение с помощью Action.Submit приведет к снижению производительности работы пользователя.

Важное примечание

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

В приведенном ниже примере обратите внимание, что свойство version карточки имеет значение 1.2, а Action.Execute определяется с помощью Action.Submit в качестве fallback. При преобразовании для просмотра в клиенте Teams, поддерживающем адаптивные карточки версии 1.4, Action.Execute будет отображаться и работать должным образом. В клиентах Teams, не поддерживающих адаптивные карточки версии 1.4, преобразовываться для просмотра вместо Action.Execute будет Action.Submit.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": {
            "type": "Action.Submit",
            "title": "Submit"
          }  
        }
      ]
    }
  ]
}

Универсальная модель действий

Контекст

Схема

ВАЖНО

Action.Execute

Механизм обновления

Важное замечание для разработчиков сообщений с действиями Outlook

Действие Invoke `adaptiveCard/action`

Формат запроса

Формат ответа

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

обратная совместимость

Outlook

Важные примечания

Команды

Важное примечание

Ссылки

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

Универсальная модель действий

Контекст

Схема

ВАЖНО

Action.Execute

Механизм обновления

Важное замечание для разработчиков сообщений с действиями Outlook

Действие Invoke adaptiveCard/action

Формат запроса

Формат ответа

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

обратная совместимость

Outlook

Важные примечания

Команды

Важное примечание

Ссылки

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

Действие Invoke `adaptiveCard/action`