次の方法で共有


カード アクション

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 アクションには、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"
}

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

アダプティブ カードでは、次の 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.Submitdata オブジェクトで msteams プロパティを使用して、既存の Bot Framework アクションをサポートすることもできます。 datamsteams プロパティを定義すると、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
        }
    ]
}

Disabled

Teams の [送信] ボタンが無効になっているアダプティブ カードを示すスクリーンショット。

Enabled (有効)

Teams の [送信] ボタンが有効になっているアダプティブ カードを示すスクリーンショット。

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

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

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

    • 要求が多すぎます

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

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

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

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

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

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

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

    成功メッセージを表示しない場合は、属性 hidemsTeamsfeedback プロパティの 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 カードの書式設定 このサンプルでは、条件付きで有効なボタンを示します。 表示 表示 該当なし 該当なし 該当なし

次の手順

関連項目