カード アクション
Microsoft Teamsでボットとメッセージ拡張機能によって使用されるカードは、次のアクティビティ CardAction
の種類をサポートします。
注:
CardAction
アクションは、コネクタから使用する場合のMicrosoft 365 グループのコネクタ カードのpotentialActions
とは異なります。
タイプ | 操作 |
---|---|
openUrl |
URL を既定のブラウザーで開きます。 |
messageBack |
ボタンを選択するか、またはカードをタップしたユーザーからのメッセージおよびペイロードをボットに送信します。 別のメッセージをチャット ストリームに送信します。 |
imBack |
ボタンを選択するか、またはカードをタップしたユーザーからのメッセージをボットに送信します。 ユーザーからボットに送信されたこのメッセージは、すべての会話参加者に表示されます。 |
invoke |
ボタンを選択するか、またはカードをタップしたユーザーからのメッセージおよびペイロードをボットに送信します。 このメッセージは表示されません。 |
signin |
OAuth フローを開始し、ボットがセキュリティで保護されたサービスに接続できるようにします。 |
注:
- Teams は、前のテーブルに記載されていない
CardAction
タイプをサポートしていません。 - Teams は
potentialActions
プロパティをサポートしていません。 - カード アクションは、Bot Framework や Azure Bot Service のおすすめの操作とは異なります。
- カード アクションをメッセージ拡張機能の一部として使用している場合、カードがチャネルに送信されるまでアクションは機能しません。 カードがメッセージの作成ボックスに入っている間は、アクションは機能しません。
アクション タイプ openUrl
openUrl
アクション タイプでは、既定のブラウザーで起動する URL を指定します。
注:
- ボットは、どのボタンが選択されたかに関する通知を受け取りません。
- URL では、数値を含むコンピューター名はサポートされていません。 たとえば、 userhostname123 などのホスト名はサポートされていません。
openUrl
を使用すると、以下のプロパティを含むアクションを作成することができます。
プロパティ | 説明 |
---|---|
title |
ボタンのラベルとして表示されます。 |
value |
このフィールドには、完全でかつ適切に形成された URL が含まれる必要があります。 |
次のコードは JSON での openUrl
アクション タイプの一例を示します。
{
"type": "openUrl",
"title": "Tabs in Teams",
"value": "https://msdn.microsoft.com/microsoft-teams/tabs"
}
アクション タイプ messageBack
messageBack
を使用すると、以下のプロパティを含む完全にカスタマイズされたアクションを作成することができます。
プロパティ | 説明 |
---|---|
title |
ボタンのラベルとして表示されます。 |
displayText |
省略可能。 アクションが実行されたときに、チャット ストリームでユーザーが使用します。 このテキストはボットに送信されません。 |
value |
アクションが実行された場合に、ボットに送信されます。 固有の識別子や JSON オブジェクトなど、アクションのコンテキストをエンコードすることができます。 |
text |
アクションが実行された場合に、ボットに送信されます。 このプロパティを使用して、ボット開発を簡略化します。 コードでは、トップレベルのプロパティをチェックして、ボット ロジックをディスパッチすることができます。 |
messageBack
の柔軟性は、displayText
を使用しないだけでは、コードが履歴に表示されるユーザー メッセージを残すことができないことを意味します。
次のコードは JSON での messageBack
アクション タイプの一例を示します。
{
"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
には、カード アクションの発信元であるメッセージ ID が含まれます。 これは、メッセージを更新する場合に使用します。
以下のコードは、受信メッセージの一例を示しています。
{
"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
フィールドはシンプルな文字列です。 書式設定や隠し文字のサポートはありません。
次のコードは JSON での imBack
アクション タイプの一例を示します。
{
"type": "imBack",
"title": "More",
"value": "Show me more"
}
アクション タイプ invoke
invoke
アクションは、ダイアログ (TeamsJS v1.x のタスク モジュールと呼ばれます) を呼び出すときに使用されます。
invoke
アクションには、type
、title
、value
の 3 つのプロパティが含まれています。
invoke
を使用すると、以下のプロパティを含むアクションを作成することができます。
プロパティ | 説明 |
---|---|
title |
ボタンのラベルとして表示されます。 |
value |
このプロパティには、文字列、文字列化された JSON オブジェクト、または JSON オブジェクトを含めることができます。 |
次のコードは JSON での invoke
アクション タイプの一例を示します。
{
"type": "invoke",
"title": "Option 1",
"value": {
"option": "opt1"
}
}
ユーザーがボタンを選択した場合、ボットはいくつかの追加情報を含む value
オブジェクトを受け取ります。
注:
アクティビティ タイプは、activity.Type == "invoke"
である message
の代わりに invoke
です。
受信した起動メッセージの例
上位の replyToId
プロパティには、カード アクションの発信元であるメッセージ ID が含まれます。 これは、メッセージを更新する場合に使用します。
以下のコードは、受信する起動メッセージの一例を示しています。
{
"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 は、アダプティブ カードでのみ使用されるアダプティブ カード アクションをサポートしています。
次のコードは JSON での signin
アクション タイプの一例を示します。
{
"type": "signin",
"title": "Click me for signin",
"value": "https://signin.com"
}
アダプティブ カード アクション
アダプティブ カードでは、次の 6 種類のアクションがサポートされています。
- Action.OpenUrl: 指定した URL を開きます。
- Action.Submit: 送信アクションの結果をボットに送信します。
-
Action.ShowCard: ダイアログを呼び出し、サブカードをそのダイアログにレンダリングします。 これは、
ShowCardActionMode
が popup に設定されている場合にのみ処理する必要があります。 - Action.ToggleVisibility: カード内の 1 つ以上の要素を表示または非表示にします。
- Action.Execute: 入力フィールドを収集し、オプションのデータ フィールドとマージし、クライアントにイベントを送信します。
- Action.ResetInputs: アダプティブ カード内の入力の値をリセットします。
Action.Submit
Action.Submit
type は、入力の収集、 data
プロパティの結合、ボットへのイベントの送信に使用されます。 ユーザーが送信アクションを選択すると、Teams はメッセージ アクティビティをボットに送信します。これには、カード ペイロードで定義されているすべての入力フィールドと非表示データのキーと値のペアのユーザーの入力が含まれます。
アダプティブ カード スキーマでは、Action.Submit の data
プロパティは、 string
または object
です。 送信アクションは、データ プロパティごとに異なる動作をします。
-
string
: 文字列送信アクションは、ユーザーからボットにメッセージを自動的に送信し、会話履歴に表示されます。 -
object
: オブジェクト送信アクションは、非表示のデータを含むボットに、ユーザーから非表示のメッセージを自動的に送信します。 オブジェクトの送信アクションは、text プロパティが空の間にアクティビティの value プロパティを設定します。
Action.Submit は Bot Framework アクションと同じです。 アダプティブ カード Action.Submit
のペイロードを変更して、Action.Submit
の data
オブジェクトで msteams
プロパティを使用して、既存の Bot Framework アクションをサポートすることもできます。
data
で msteams
プロパティを定義すると、Teams クライアントによってAction.Submit
の動作が定義されます。
msteams
プロパティがスキーマで定義されていない場合、Action.Submit
は通常の Bot Framework 呼び出しアクションと同様に機能します。送信アクションによってボットへの呼び出しがトリガーされ、ボットは入力フィールドで定義されているすべての入力値でペイロードを受け取ります。
注:
- ボットは、ユーザーが [ 保存] や [ 送信] などのボタンを使用してアダプティブ カードでアクションを送信しない限り、ユーザー入力を受け取りません。 たとえば、ボットでは、ユーザーが送信しない限り、複数の選択肢からオプションを選択したり、フォーム内のフィールドに入力したりするなどのユーザー アクションは考慮されません。
- Bot Framework アクションを使用してデータに
msteams
を追加しても、アダプティブ カード ダイアログでは機能しません。 - Teams では、プライマリまたは破壊的な
ActionStyle
はサポートされていません。 - アプリには、呼び出しメッセージに応答する 5 秒があります。
例
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
プロパティを使用すると、ユーザーが必要な入力の少なくとも 1 つの値を変更するまでアクション ボタンを無効にすることができます。 このプロパティは、 Action.Submit
アクションと Action.Execute
アクションでのみ使用できます。 条件付きで有効なボタンの場合、 isEnabled
プロパティが false
に設定されている場合、アクションは入力に関係なく無効になります。
conditionallyEnabled
プロパティの定義方法を次に示します。
プロパティ | 型 | 必須 | 説明 |
---|---|---|---|
conditionallyEnabled |
ブール型 | ✔️ | ユーザーが少なくとも 1 つの必須入力を入力した場合にのみ、アクションが有効かどうかを制御します。 |
次のカードペイロードは、条件付きで有効なボタンを示しています。
{
"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
}
]
}
フォームの完了に関するフィードバック
アダプティブ カードを使用してフォーム入力候補のフィードバックを作成できます。 ボットへの応答の送信中に、アダプティブ カードにフォーム完了メッセージが表示されます。 メッセージには、エラーまたは成功の 2 種類があります。
エラー: ボットに送信された応答が失敗すると、 問題が発生し、[再試行] というメッセージが表示されます。 エラーは、次のようなさまざまな理由で発生します。
要求が多すぎます
同じ会話に対する複数の同時操作
サービス依存関係の問題
ゲートウェイ タイムアウト
成功: ボットに送信された応答が成功すると、 アプリ に送信された応答 メッセージが表示されます。
[ 閉じる ] を選択するか、チャットを切り替えてメッセージを無視できます。
成功メッセージを表示しない場合は、属性
hide
をmsTeams
feedback
プロパティのtrue
に設定します。 次に例を示します。"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 | カードの書式設定 | このサンプルでは、条件付きで有効なボタンを示します。 | 表示 | 表示 | 該当なし | 該当なし | 該当なし |
次の手順
関連項目
Platform Docs