Действия карточек

Карточки, используемые ботами и расширениями для обмена сообщениями в Teams, поддерживают следующие типы действий CardAction:

Примечание

Действия CardAction отличаются от potentialActions для карточек соединителей Office 365 при их использовании из соединителей.

Тип Действие
openUrl Открывает URL-адрес в браузере по умолчанию.
messageBack Отправляет боту сообщение и полезные данные от пользователя, нажавшего кнопку или коснувшегося карточки. Отправляет отдельное сообщение в поток чата.
imBack Отправляет боту сообщение от пользователя, нажавшего кнопку или коснувшегося карточки. Это сообщение от пользователя боту отображается для всех участников беседы.
invoke Отправляет боту сообщение и полезные данные от пользователя, нажавшего кнопку или коснувшегося карточки. Это сообщение не отображается.
signin Инициирует поток OAuth, позволяя ботам подключаться к защищенным службам.

Примечание

  • Teams не поддерживает типы CardAction, не указанные в предыдущей таблице.
  • Teams не поддерживает свойство potentialActions.
  • Действия с карточками отличаются от рекомендуемых действий в Bot Framework или службе Azure Bot. Рекомендуемые действия не поддерживаются в Microsoft Teams. Если вы хотите, чтобы в сообщении бота Teams появлялись кнопки, используйте карточку.
  • Если вы используете действие карточки в расширении для обмена сообщениями, эти действия не будут работать, пока карточка не будет отправлена в канал. Действия не работают, пока карточка находится в окне составления сообщения.

Тип действия openUrl

Тип действия openUrl указывает URL-адрес, который необходимо открыть в браузере по умолчанию.

Примечание

Бот не получает уведомления о том, какая нажата кнопка.

С помощью openUrl вы можете создать действие со следующими свойствами:

Свойство Описание
title Отображается как метка кнопки.
value Это поле должно содержать полный и правильно оформленный URL-адрес.

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

{
    "type": "openUrl",
    "title": "Tabs in Teams",
    "value": "https://msdn.microsoft.com/microsoft-teams/tabs"
}

Тип действия messageBack

С помощью messageBack вы можете создать полностью настроенное действие со следующими свойствами:

Свойство Описание
title Отображается как метка кнопки.
displayText Необязательное. Применяется пользователем в потоке чата при выполнении действия. Этот текст не отправляется вашему боту.
value Отправляется боту при выполнении действия. Вы можете закодировать контекст для действия, например уникальные идентификаторы или объект JSON.
text Отправляется боту при выполнении действия. Используйте это свойство, чтобы упростить разработку бота. Ваш код может проверить одно свойство верхнего уровня для выполнения логики бота.

Гибкость messageBack означает, что ваш код не может оставить видимое сообщение пользователя в журнале, просто не используя displayText.

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

{
  "buttons": [
    {
    "type": "messageBack",
    "title": "My MessageBack button",
    "displayText": "I clicked this button",
    "text": "User just clicked the MessageBack button",
    "value": "{\"property\": \"propertyValue\" }"
    }
  ]
}

Свойство value может быть сериализованной строкой JSON или объектом JSON.

Пример входящего сообщения

replyToId содержит идентификатор сообщения, от которого поступило действие карточки. Используйте его, если вы хотите обновить сообщение.

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

{
   "text":"User just clicked the MessageBack button",
   "value":{
      "property":"propertyValue"
   },
   "type":"message",
   "timestamp":"2017-06-22T22:38:47.407Z",
   "id":"f:5261769396935243054",
   "channelId":"msteams",
   "serviceUrl":"https://smba.trafficmanager.net/amer-client-ss.msg/",
   "from":{
      "id":"29:102jd210jd010icsoaeclaejcoa9ue09u",
      "name":"John Smith"
   },
   "conversation":{
      "id":"19:malejcou081i20ojmlcau0@thread.skype;messageid=1498171086622"
   },
   "recipient":{
      "id":"28:76096e45-119f-4736-859c-6dfff54395f7",
      "name":"MyBot"
   },
   "entities":[
      {
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "America/Los_Angeles",
        "type": "clientInfo" 
      }
   ],
   "channelData":{
      "channel":{
         "id":"19:malejcou081i20ojmlcau0@thread.skype"
      },
      "team":{
         "id":"19:12d021jdoijsaeoaue0u@thread.skype"
      },
      "tenant":{
         "id":"bec8e231-67ad-484e-87f4-3e5438390a77"
      }
   },
        "replyToId": "1575667808184",
}

Тип действия imBack

Действие imBack вызывает обратное сообщение боту, как если бы пользователь ввел его в обычном сообщении чата. Ваш пользователь и все остальные пользователи канала могут видеть ответ, отправленный с использованием кнопки.

С помощью imBack вы можете создать действие со следующими свойствами:

Свойство Описание
title Отображается как метка кнопки.
value Это поле должно содержать текстовую строку, используемую в чате и, следовательно, отправляемую обратно боту. Это текст сообщения, который вы обрабатываете в боте для выполнения нужной логики.

Примечание

Поле value является простой строкой. Форматирование и скрытые символы не поддерживаются.

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

{
    "type": "imBack",
    "title": "More",
    "value": "Show me more"
}

Тип действия invoke

Действие invoke используется для вызова модулей задач.

Действие invoke содержит три свойства: type, title и value.

С помощью invoke вы можете создать действие со следующими свойствами:

Свойство Описание
title Отображается как метка кнопки.
value Это свойство может содержать строку, строковый объект JSON или объект JSON.

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

{
    "type": "invoke",
    "title": "Option 1",
    "value": {
        "option": "opt1"
    }
}

Когда пользователь нажимает кнопку, бот получает объект value с некоторой дополнительной информацией.

Примечание

Тип действия invoke, а не message, т. е. activity.Type == "invoke".

Пример входящего сообщения invoke

Свойство replyToId верхнего уровня содержит идентификатор сообщения, от которого поступило действие карточки. Используйте его, если вы хотите обновить сообщение.

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

{
    "type": "invoke",
    "value": {
        "option": "opt1"
    },
    "timestamp": "2017-02-10T04:11:19.614Z",
    "localTimestamp": "2017-02-09T21:11:19.614-07:00",
    "id": "f:6894910862892785420",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
    "from": {
        "id": "29:1Eniglq0-uVL83xNB9GU6w_G5a4SZF0gcJLprZzhtEbel21G_5h-
    NgoprRw45mP0AXUIZVeqrsIHSYV4ntgfVJQ",
        "name": "John Doe"
    },
    "conversation": {
        "id": "19:97b1ec61-45bf-453c-9059-6e8984e0cef4_8d88f59b-ae61-4300-bec0-caace7d28446@unq.gbl.spaces"
    },
    "recipient": {
        "id": "28:8d88f59b-ae61-4300-bec0-caace7d28446",
        "name": "MyBot"
    },
    "entities": [
        {
            "locale": "en-US",
            "country": "US",
            "platform": "Web",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "channel": {
            "id": "19:dc5ba12695be4eb7bf457cad6b4709eb@thread.skype"
        },
        "team": {
            "id": "19:712c61d0ef384e5fa681ba90ca943398@thread.skype"
        },
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "replyToId": "1575667808184"
}

Тип действия signin

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

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

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

{
"type": "signin",
"title": "Click me for signin",
"value": "https://signin.com"
}

Действия адаптивных карточек

Адаптивные карточки поддерживают четыре типа действий:

Кроме того, вы можете изменить полезные данные адаптивной карточки Action.Submit для поддержки существующих действий Bot Framework с помощью свойства msteams в объекте data, относящемся к Action.Submit. Следующий раздел посвящен использованию существующих действий Bot Framework с адаптивными карточками.

Примечание

Добавление msteams к данным с помощью действия Bot Framework не работает с модулем задач адаптивной карточки.

Адаптивные карточки с действием messageBack

Чтобы включить действие messageBack в адаптивную карточку, включите в объект msteams следующую информацию:

Примечание

При необходимости можно включить в объект data дополнительные скрытые свойства.

Свойство Описание
type Установите значение messageBack.
displayText Необязательное. Применяется пользователем в потоке чата при выполнении действия. Этот текст не отправляется вашему боту.
value Отправляется боту при выполнении действия. Вы можете закодировать контекст для действия, например уникальные идентификаторы или объект JSON.
text Отправляется боту при выполнении действия. Используйте это свойство, чтобы упростить разработку бота. Ваш код может проверить одно свойство верхнего уровня для выполнения логики бота.

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

{
  "type": "Action.Submit",
  "title": "Click me for messageBack",
  "data": {
    "msteams": {
        "type": "messageBack",
        "displayText": "I clicked this button",
        "text": "text to bots",
        "value": "{\"bfKey\": \"bfVal\", \"conflictKey\": \"from value\"}"
    }
  }
}

Адаптивные карточки с действием imBack

Чтобы включить действие imBack в адаптивную карточку, включите в объект msteams следующую информацию:

Примечание

При необходимости можно включить в объект data дополнительные скрытые свойства.

Свойство Описание
type Установите значение imBack.
value Строка, которую необходимо вернуть в чат.

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

{
  "type": "Action.Submit",
  "title": "Click me for imBack",
  "data": {
    "msteams": {
        "type": "imBack",
        "value": "Text to reply in chat"
    }
  }
}

Адаптивные карточки с действием signin

Чтобы включить действие signin в адаптивную карточку, включите в объект msteams следующую информацию:

Примечание

При необходимости можно включить в объект data дополнительные скрытые свойства.

Свойство Описание
type Установите значение signin.
value В качестве значения задайте URL-адрес для перенаправления.

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

{
  "type": "Action.Submit",
  "title": "Click me for signin",
  "data": {
    "msteams": {
        "type": "signin",
        "value": "https://signin.com"
    }
  }
}

Адаптивные карточки с действием invoke

Чтобы включить действие invoke в адаптивную карточку, включите в объект msteams следующую информацию:

Примечание

При необходимости можно включить в объект data дополнительные скрытые свойства.

Свойство Описание
type Установите значение task/fetch.
data Задайте значение.

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

{
  "type": "Action.Submit",
  "title": "submit",
  "data": {
    "msteams": {
        "type": "task/fetch"
    }
  }
}

Следующий код представляет собой пример адаптивных карточек с действием invoke и дополнительными полезными данными:

{
  "type": "Action.Submit",
  "title": "submit"
  "data": {
    "msteams": {
        "type": "task/fetch"
    },
    "Value1": "some value"
  }
}

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

См. также