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

Статья
11/07/2024

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

Примечание.

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

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

Примечание.

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

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

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

Примечание.

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

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

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

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

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

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

var button = new CardAction()
{
    Type = ActionTypes.OpenUrl,
    Title = "Tabs in Teams",
    Value = "https://learn.microsoft.com/microsoftteams/platform/"
};

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

CardFactory.actions([
{
    type: 'openUrl',
    title: 'Tabs in Teams',
    value: 'https://learn.microsoft.com/microsoftteams/platform/'
}])

Тип действия 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.

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

var button = new CardAction()
{
    Type = ActionTypes.MessageBack,
    Title = "My MessageBack button",
    DisplayText = "I clicked this button",
    Text = "User just clicked the MessageBack button",
    Value = "{\"property\": \"propertyValue\" }"
};

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

CardFactory.actions([
{
    type: 'messageBack',
    title: "My MessageBack button",
    displayText: "I clicked this button",
    text: "User just clicked the MessageBack button",
    value: {property: "propertyValue" }
}])

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

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"
}

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

var button = new CardAction()
{
    Type = ActionTypes.ImBack,
    Title = "More",
    Value = "Show me more"
};

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

CardFactory.actions([
{
    type: "imBack",
    title: "More",
    value: "Show me more"
}])

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

Действие invoke используется для вызова диалогов (называемых модулями задач в TeamsJS версии 1.x).

Действие 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 в C#:

var button = new CardAction()
{
    Title = "Option 1",
    Type = "invoke",
    Value = "{\"option\": \"opt1\"}"
};

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

CardFactory.actions([
{
    type: "invoke",
    title: "Option 1",
    value: {
        option: "opt1"
    }
}])

Пример входящего сообщения 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 инициирует поток OAuth, который позволяет ботам подключаться к защищенным службам. Дополнительные сведения см. в статье о потоке проверки подлинности в ботах.

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

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

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

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

var button = new CardAction()
{
    Type = ActionTypes.Signin,
    Title = "Click me for signin",
    Value = "https://signin.com"
};

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

CardFactory.actions([
{
    type: "signin",
    title: "Click me for signin",
    value: "https://signin.com"
}])

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

Адаптивные карточки поддерживают следующие шесть типов действий:

Action.OpenUrl: открывает указанный URL-адрес.
Action.Submit: отправляет боту результат действия отправки.
Action.ShowCard: вызывает диалоговое окно и отображает вложенную карта в этом диалоге. Обработать это нужно только в том случае, если ShowCardActionMode задано всплывающее окно.
Action.ToggleVisibility: отображает или скрывает один или несколько элементов в карта.
Action.Execute: собирает входные поля, объединяется с необязательным полем данных и отправляет событие клиенту.
Action.ResetInputs: сбрасывает значения входных данных в адаптивной карточке.

Action.Submit

Action.Submit тип используется для сбора входных данных, объединения data свойств и отправки события боту. Когда пользователь выбирает действие отправки, Teams отправляет боту действие сообщения, которое включает входные данные пользователя в парах "ключ-значение" для всех полей ввода и скрытые данные, определенные в полезных данных карта.

В схеме адаптивной карточки свойством data Action.Submit является string или object. Действие отправки ведет себя по-разному для каждого свойства данных:

string: действие отправки строки автоматически отправляет боту сообщение от пользователя и отображается в журнале бесед.
object: действие отправки объекта автоматически отправляет боту невидимое сообщение от пользователя, содержащее скрытые данные. Действие отправки объекта заполняет свойство value действия, а свойство text пусто.

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

Примечание.

Бот не получает входные данные пользователя, если пользователь не отправляет свои действия в адаптивной карточке с помощью кнопки, например Сохранить или Отправить. Например, бот не рассматривает действия пользователя, такие как выбор варианта из нескольких вариантов или заполнение полей в форме, в качестве входных данных, если пользователь не отправит их.
Добавление msteams к данным с помощью действия Bot Framework не работает с диалоговым окном адаптивной карточки.
Основной или разрушительный ActionStyle не поддерживается в Teams.
У вашего приложения есть пять секунд, чтобы ответить на сообщение вызова.

Пример

Ниже приведен пример полезных Action.Submit данных карта.

Полезные данные состоят из поля "id": "text-1" текстового ввода и скрытых полезных данных "hiddenKey": 123.45.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "fallbackText": "fallback text for sample 01",
  "speak": "This is adaptive card sample 1",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "id": "text-1",
          "type": "Input.Text"
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "data": {
        "hiddenKey": 123.45
      }
    }
  ]
}

Снимок экрана: пример адаптивной карточки с кнопкой

Ниже приведен пример входящего действия бота, когда пользователь вводит что-то в поле ввода и выбирает Отправить. Атрибут value включает входные данные пользователя в свойстве text-1 и скрытые полезные данные в свойстве hiddenKey :


{
 "type": "message",
 "timestamp": "2023-07-18T23:45:41.699Z",
 "localTimestamp": "2023-07-18T16:45:41.699-07:00",
 "id": "f:9eb18f56-2259-8fa4-7dfc-111ffff58e67",
 "channelId": "msteams",
 "serviceUrl": "https://smba.trafficmanager.net/amer/",
 "from": {
   "id": "29:1E0NZYNZFQOCUI8zM9NY_EhlCsWgNbLGTHUNdBVX2ob8SLjhltEhQMPi07Gr6MLScFeS8SrKH1WGvJSiVKThnyw",
   "name": "Megan Bowen",
   "aadObjectId": "97b1ec61-45bf-453c-9059-6e8984e0cef4"
 },
 "conversation": {
   "conversationType": "personal",
   "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
   "id": "a:1H-RowZ3FrIheyjTupPnoCC6JvOLB5pCWms1xwqvAJG97j61D18EuSennYZE6tyfbQrnfIN3uIcwpOx73mg10hHp_uoTMMQlXhXosIu_q7QVCaYiW6Ch3bPWAitUw4aSX"
 },
 "recipient": {
   "id": "28:159e1c0f-15ef-4597-a8c6-44ba1fd89b78",
   "name": "Mushroom"
 },
 "entities": [
   {
     "locale": "en-US",
     "country": "US",
     "platform": "Web",
     "timezone": "America/Los_Angeles",
     "type": "clientInfo"
   }
 ],
 "channelData": {
   "tenant": {
     "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
   },
   "source": {
     "name": "message"
   },
   "legacy": {
     "replyToId": "1:1XFuAl7wF96vl6iAQk9tqus0uFrB89uujGpld-Qm-XEw"
   }
 },
 "replyToId": "1689723936016",
 "value": {
   "hiddenKey": 123.45,
   "text-1": "HELLO"
 },
 "locale": "en-US",
 "localTimezone": "America/Los_Angeles"
}

Условное включение кнопок действий

Свойство можно использовать для conditionallyEnabled отключения кнопок действий до тех пор, пока пользователь не изменит значение хотя бы одного из необходимых входных данных. Это свойство можно использовать только с Action.Submit действиями и Action.Execute . Если для кнопки с условным включением isEnabled задано значение false, действия отключаются независимо от входных данных.

Вот как conditionallyEnabled определяется свойство:

Свойство	Тип	Обязательный	Описание
`conditionallyEnabled`	Логический	✔️	Определяет, включено ли действие, только если пользователь заполнил хотя бы один необходимый вход.

В следующем карта полезных данных показана кнопка с условной включенной кнопкой:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
        {
            "type": "Input.Text",
            "placeholder": "Placeholder text",
            "label": "Required text input",
            "isRequired": true,
            "id": "text"
        },
        {
            "type": "Input.Date",
            "label": "Required date input",
            "isRequired": true,
            "id": "date"
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Submit",
            "conditionallyEnabled": true
        },
        {
            "type": "Action.Submit",
            "title": "Permanently disabled button",
            "isEnabled": false
        }
    ]
}

Disabled

Enabled

Отзывы о завершении формы

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

Ошибка. Если ответ, отправленный боту, не удается, что-то пошло не так, появится сообщение Повторите попытку . Ошибка возникает по различным причинам, например:
- Слишком много запросов
- Несколько одновременных операций в одной беседе
- Проблема с зависимостью службы
- Истекло время ожидания шлюза (Gateway Timeout)
Успешно. При успешном выполнении ответа, отправленного боту, появится сообщение о том, что ваш ответ отправлен в приложение .

Вы можете выбрать Закрыть или переключить чат, чтобы закрыть сообщение.

Если вы не хотите отображать сообщение об успешном выполнении, задайте атрибуту hide значение true в свойстве msTeamsfeedback . Ниже приведен пример:
```
   "content": {
       "type": "AdaptiveCard",
       "title": "Card with hidden footer messages",
       "version": "1.0",
       "actions": [
       {
           "type": "Action.Submit",
           "title": "Submit",
           "msTeams": {
               "feedback": {
               "hide": true
               }
           }
       }
       ]
   } 
```

Дополнительные сведения о карточках и карточках в ботах см. в документации по карточкам.

Адаптивные карточки с действием 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 объект следующие сведения:

Примечание.

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

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

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

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

Чтобы включить 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"
    }
  }
}

Свойство	Описание
`type`	Установите значение `invoke`.
`value`	Задайте отображаемое значение.

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

[
  {
    "type": "Action.Submit",
    "title": "submit with object value",
    "data": {
      "ab": "xy",
      "msteams": {
        "type": "invoke",
        "value": { "a": "b" }
      }
    }
  },
  {
    "type": "Action.Submit",
    "title": "submit with stringified json value",
    "data": {
      "ab": "xy",
      "msteams": {
        "type": "invoke",
        "value": "{ \"a\": \"b\"}"
      }
    }
  }
]

Примеры кода

S.No.	Карточка	Описание	.NET	Node.js	Python	Java	Манифест
1	Действия адаптивной карточки	В этом примере показаны различные действия, поддерживаемые адаптивными карточками.	Просмотр	Просмотр	Недоступно	Недоступно	Просмотр
2	Использование карточек	Представляет все типы карта, включая эскизы, аудио, мультимедиа и т. д. Создано на основе приветствия пользователя и бота с несколькими запросами путем представления карта с кнопками в приветственном сообщении, которое направляется в соответствующее диалоговое окно.	Просмотр	Просмотр	Просмотр	Просмотр	Н/Д
3	Адаптивные карточки	Демонстрирует, как в многоэтапном диалоговом окне можно использовать карта для получения ввода пользователем имени и возраста.	Просмотр	Просмотр	Просмотр	Просмотр	Н/Д
4	Форматирование карточки	В этом примере демонстрируется условно включенная кнопка.	Просмотр	Просмотр	Недоступно	Недоступно	Недоступно

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

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

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

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

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

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

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

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

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

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

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

Action.Submit

Пример

Условное включение кнопок действий

Отзывы о завершении формы

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

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

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

Примеры кода

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

См. также

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

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

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

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

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

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

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

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

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

Тип действия для входа

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

Action.Submit

Пример

Условное включение кнопок действий

Отзывы о завершении формы

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

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

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

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

Примеры кода

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

См. также

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