次の方法で共有


カード アクション

Microsoft Teams のボットとメッセージ拡張機能で使用されるカードは、次のアクティビティ CardAction の種類をサポートしています。

注:

コネクタCardActionからpotentialActions使用する場合、Microsoft 365 グループのコネクタ カードのアクションは異なります。

タイプ 操作
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 アクションには、typetitlevalue の 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"
}

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

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

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

Action.Submit

Action.Submit type は、入力の収集、プロパティの data 結合、ボットへのイベントの送信に使用されます。 ユーザーが送信アクションを選択すると、Teams はメッセージ アクティビティをボットに送信します。これには、カード ペイロードで定義されているすべての入力フィールドと非表示データのキーと値のペアのユーザーの入力が含まれます。

アダプティブ カード スキーマでは、dataAction.Submit のプロパティは、 または のいずれかobjectですstring。 送信アクションは、データ プロパティごとに異なる動作をします。

  • string: 文字列送信アクションは、ユーザーからボットにメッセージを自動的に送信し、会話履歴に表示されます。
  • object: オブジェクト送信アクションは、非表示のデータを含むボットに、ユーザーから非表示のメッセージを自動的に送信します。 オブジェクトの送信アクションは、text プロパティが空の間にアクティビティの value プロパティを設定します。

Action.Submit は Bot Framework アクションと同じです。 アダプティブ カード Action.Submitのペイロードを変更して、Action.Submitdata オブジェクトで 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 種類があります。

  • エラー: ボットに送信された応答が失敗すると、 問題が発生し、[再試行] というメッセージが表示されます。 エラーは、次のようなさまざまな理由で発生します。

    • 要求が多すぎます

    • 同じ会話に対する複数の同時操作

    • サービス依存関係の問題

    • ゲートウェイ タイムアウト

      アダプティブ カードのエラー メッセージを示すスクリーンショット。

  • 成功: ボットに送信された応答が成功すると、 アプリ に送信された応答 メッセージが表示されます。

    アダプティブ カードの成功メッセージを示すスクリーンショット。

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

    成功メッセージを表示しない場合は、 プロパティで msTeamsfeedback 属性hideを に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 含めます。

注:

必要に応じて、data オブジェクトに追加の隠しプロパティを含めることができます。

プロパティ 説明
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 のアダプティブ カードではサポートされていません。

次の手順

関連項目