カードアクション

[アーティクル]
04/24/2024

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

次のコードは C# での openUrl アクションタイプの一例を示します。

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

次のコードは JavaScript での openUrl アクションタイプの一例を示します。

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

アクションタイプ 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 オブジェクトを指定できます。

次のコードは C# での messageBack アクションタイプの一例を示します。

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

次のコードは JavaScript での messageBack アクションタイプの一例を示します。

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

受信メッセージの例

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

次のコードは C# での imBack アクションタイプの一例を示します。

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

次のコードは JavaScript での imBack アクションタイプの一例を示します。

CardFactory.actions([
{
    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 です。

次のコードは C# での invoke アクションタイプの一例を示します。

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

次のコードは Node.js での invoke アクションタイプの一例を示します。

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

受信した起動メッセージの例

上位の 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"
}

次のコードは C# での signin アクションタイプの一例を示します。

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

次のコードは JavaScript での signin アクションタイプの一例を示します。

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

アダプティブカードアクション

アダプティブカードは、次の 4 つのアクションタイプをサポートします。

Action.OpenUrl: 指定した URL を開きます。
Action.Submit: 送信アクションの結果をボットに送信します。
Action.ShowCard: ダイアログを呼び出し、そのダイアログにサブカードをレンダリングします。これは、 ShowCardActionMode が popup に設定されている場合にのみ処理する必要があります。
Action.ToggleVisibility: カード内の 1 つ以上の要素を表示または非表示にします。
Action.Execute: 入力フィールドを収集し、オプションのデータフィールドとマージし、クライアントにイベントを送信します。

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": "Robin Liao",
   "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"
}

次のセクションでは、アダプティブカードで既存の Bot Framework アクションを使用する方法について詳しく説明します。

フォームの完了に関するフィードバック

アダプティブカードを使用してフォーム入力候補のフィードバックを作成できます。ボットへの応答の送信中に、アダプティブカードにフォーム完了メッセージが表示されます。メッセージには、エラーまたは成功の 2 種類があります。

エラー: ボットに送信された応答が失敗すると、 問題が発生し、[再試行] というメッセージが表示されます。エラーは、次のようなさまざまな理由で発生します。
- 要求が多すぎます
- 同じ会話に対する複数の同時操作
- サービス依存関係の問題
- ゲートウェイタイムアウト
成功: ボットに送信された応答が成功すると、 アプリに送信された応答 メッセージが表示されます。

[ 閉じる ] を選択するか、チャットを切り替えてメッセージを無視できます。

成功メッセージを表示しない場合は、属性 hide を msTeamsfeedback プロパティの 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	アダプティブカード	複数ターンダイアログでカードを使用して、名前と年齢のユーザー入力を取得する方法を示します。	表示	表示	表示	表示	該当なし

注:

メディア要素は、Teams のアダプティブカードではサポートされていません。

次の手順

アダプティブカードのユニバーサルアクション

次の方法で共有

カードアクション

アクションタイプ openUrl

アクションタイプ messageBack

受信メッセージの例

アクションタイプ imBack

アクションタイプ invoke

受信した起動メッセージの例

アダプティブカードアクション

Action.Submit

例

フォームの完了に関するフィードバック

messageBack アクションを備えたアダプティブカード

imBack アクションを備えたアダプティブカード

invoke アクションを備えたアダプティブカード

コードサンプル

次の手順

関連項目

フィードバック

その他のリソース

次の方法で共有

カード アクション

アクション タイプ openUrl

アクション タイプ messageBack

受信メッセージの例

アクション タイプ imBack

アクション タイプ invoke

受信した起動メッセージの例

アクションの種類のサインイン

アダプティブ カード アクション

Action.Submit

例

フォームの完了に関するフィードバック

messageBack アクションを備えたアダプティブ カード

imBack アクションを備えたアダプティブ カード

サインイン アクションを使用したアダプティブ カード

invoke アクションを備えたアダプティブ カード

コード サンプル

次の手順

関連項目

フィードバック

その他のリソース

カードアクション

アクションタイプ openUrl

アクションタイプ messageBack

アクションタイプ imBack

アクションタイプ invoke

アダプティブカードアクション

messageBack アクションを備えたアダプティブカード

imBack アクションを備えたアダプティブカード

サインインアクションを使用したアダプティブカード

invoke アクションを備えたアダプティブカード

コードサンプル