メッセージ拡張機能のアクションコマンドを定義する

[アーティクル]
08/07/2022

重要

このセクションのコードサンプルは、Bot Framework SDK の 4.6 以降のバージョンに基づいています。以前のバージョンのドキュメントをお探しの場合は、ドキュメントの [リソース] フォルダーのメッセージ拡張機能 - v3 SDK セクションを参照してください。

注意

メッセージアクションが開始されると、添付ファイルの詳細は呼び出しアクティビティの turncontext 一部として送信されません。

アクションコマンドを使用すると、Teams のタスクモジュールと呼ばれるモーダルポップアップをユーザーに表示できます。タスクモジュールは、情報を収集または表示し、対話を処理し、Teams に情報を送信します。このドキュメントでは、操作コマンドを呼び出す場所の選択、タスクモジュールの作成、最終メッセージまたはカードの送信、App Studio を使用した操作コマンドの作成、手動での作成方法について説明します。

操作コマンドを作成する前に、次の要因を決定する必要があります。

操作コマンドはどこからトリガーできますか?
タスクモジュールはどのように作成されますか?
最終メッセージまたはカードはボットからチャネルに送信されるか、またはユーザーが送信するためにメッセージまたはカードを作成メッセージ領域に挿入しますか?

メッセージ拡張アクションコマンドを定義する方法については、次のビデオを参照してください。

操作コマンドを呼び出す場所を選択する

まず、操作コマンドを呼び出す必要がある場所を決定する必要があります。アプリマニフェストで context を指定すると、コマンドで次の複数の場所からコマンドを呼び出すことができます。

メッセージ作成領域: 作成メッセージ領域の下部にあるボタン。

コマンドコンテキスト = 入力
コマンドボックス: コマンドボックスにアプリを@メンションします。

コマンドコンテキスト = commandBox

注意

メッセージ拡張機能がコマンドボックスから呼び出された場合、会話に直接挿入されたボットメッセージで応答することはできません。
メッセージ: メッセージの ... オーバーフローメニュー経由で既存のメッセージから直接送信。

コマンドコンテキスト = メッセージ

注意

ボットへの最初の呼び出しには、その呼び出し元のメッセージを含む JSON オブジェクトが含まれます。タスクモジュールを使用してメッセージを表示する前に、メッセージを処理できます。

次の画像は、操作コマンドが呼び出される場所を示しています。

操作コマンドを呼び出す場所

タスクモジュールの作成方法を選択する

コマンドの呼び出し元の選択に加えて、ユーザーのタスクモジュールでフォームを入力する方法も選択する必要があります。タスクモジュール内でレンダリングされるフォームを作成するには、次の 3 つのオプションがあります。

静的なパラメーターの一覧: これは最も簡単なメソッドです。アプリマニフェストで Teams クライアントがレンダリングするパラメーターの一覧を定義できますが、この場合は書式設定を制御できません。
アダプティブカード: UI をより細かく制御できるアダプティブカードの使用を選択できますが、使用可能な制御および書式設定オプションは制限されます。
埋め込み Web ビュー: カスタム Web ビューをタスクモジュールに埋め込んで、UI とコントロールを完全に制御することができます。

パラメーターの静的リストを使用してタスクモジュールを作成することを選択した場合、ユーザーがタスクモジュールを送信すると、メッセージ拡張機能が呼び出されます。埋め込み Web ビューまたはアダプティブカードを使用する場合、メッセージ拡張機能はユーザーからの初期呼び出しイベントを処理し、タスクモジュールを作成してクライアントに返す必要があります。

最終メッセージの送信方法を選択する

ほとんどの場合、操作コマンドにより、メッセージの作成ボックスにカードが挿入されます。ユーザーは、チャネルやチャットに送信できます。この場合、メッセージはユーザーから送信され、ボットはカードをさらに編集または更新できません。

メッセージ拡張機能が作成ボックスまたはメッセージから直接呼び出された場合、Web サービスは最終的な応答をチャネルまたはチャットに直接挿入できます。この場合、アダプティブカードはボットから取得され、ボットはそれを更新し、必要に応じて会話スレッドに返信します。同じ ID を使用し、適切な範囲を定義して、bot オブジェクトをアプリマニフェストに追加する必要があります。

アプリマニフェストに操作コマンドを追加する

操作コマンドをアプリマニフェストに追加するには、アプリマニフェスト JSON の最上位レベルに新しい composeExtension オブジェクトを追加する必要があります。これを行うには、次のいずれかの方法を使用します。

App Studio を使用して操作コマンドを作成する
操作コマンドを手動で作成する

App Studio を使用して操作コマンドを作成する

App Studio または 開発者ポータル を使用して操作コマンドを作成できます。

警告

App Studio を使用している場合は、Teams アプリを構成、配布、管理するために開発者ポータルを試してみることをお勧めします。 App Studio は、2022 年 8 月 1 日に非推奨になりました。

App Studio

注意

操作コマンドを作成するための前提条件は、メッセージ拡張機能をすでに作成していることです。メッセージ拡張機能を作成する方法については、「メッセージ拡張機能の作成」を参照してください。

操作コマンドを作成するには

Microsoft Teams クライアントから App Studio を開き、[マニフェストエディター] タブを選択します。
App Studio でアプリパッケージをすでに作成している場合は、一覧から選択します。アプリパッケージを作成していない場合は、既存のパッケージをインポートします。
アプリパッケージをインポートしたら、[機能] で [メッセージ拡張機能] を選択します。メッセージ拡張機能を設定するためのポップアップウィンドウが表示されます。
ウィンドウで [セットアップ] を選択して、アプリエクスペリエンスにメッセージ拡張機能を含めます。次の図は、メッセージ拡張機能設定ウィンドウを表示します。
メッセージ拡張機能を作成するには、Microsoft 登録ボットが必要です。既存のボットを使用するか、新しいボットを作成できます。 [新しいボットの作成] オプションを選択し、新しいボットの名前を付けて、[作成] を選択します。次の図は、メッセージ拡張機能のボット作成を示しています。
既存のボットを使用するには、[既存のボットを使用する] を選択し、[既存のボットのいずれかを選択する] を選択してドロップダウンから既存のボットを選択し、[ボット名] を指定し、ボット ID がすでに作成されている場合は [保存] を選択するか、[別のボット ID に接続する] を選択し、[ボット名] を指定して [保存] を選択します。
メッセージ拡張機能の動作を決定するコマンドを含めるには、メッセージ拡張機能ページの [コマンド] セクション で [追加] を選択します。次の画像は、メッセージ拡張機能のコマンドの追加を表示します。
[ユーザーが Teams 内にいる間に外部サービスでアクションをトリガーできるようにする] を選択します。次の画像は、操作コマンドの選択を示しています。
一連の静的パラメーターを使用してタスクモジュールを作成するには、[コマンドの静的パラメーターのセットを定義する] を選択します。

次の画像は、操作コマンドの静的パラメーターの選択を示しています。

次の画像は、静的パラメーターの設定例を示しています。

次の画像は、静的パラメーターテストの例を示しています。
動的パラメーターを使用するには、[ボットからパラメーターの動的セットを取得する] を選択します。次の画像は、操作コマンドのパラメーターの選択を示しています。
[コマンド ID] と [タイトル] を追加します。
操作コマンドを呼び出す場所を選択します。次の画像は、操作コマンドを呼び出す場所を示しています。
[保存] を選択します。
詳細なパラメーターを追加するには、[パラメーター] セクションで [追加] ボタンを選択します。

操作コマンドを手動で作成する

操作ベースのメッセージ拡張機能コマンドをアプリマニフェストに手動で追加するには、オブジェクトの composeExtension.commands 配列に次のパラメーターを追加する必要があります。

プロパティ名	用途	必須	マニフェストの最小バージョン
`id`	このプロパティは、このコマンドに割り当てる一意の ID です。ユーザー要求には、この ID が含まれています。	はい	1.0
`title`	このプロパティはコマンド名です。この値は UI に表示されます。	はい	1.0
`type`	このプロパティは `action` である必要があります。	いいえ	1.4
`fetchTask`	このプロパティは、タスクモジュールのアダプティブカードまたは埋め込み Web ビューの `true` に設定し、パラメーターの静的な一覧、または `taskInfo` によって Web ビューを読み込む場合に `false`	いいえ	1.4
`context`	このプロパティは、メッセージ拡張機能の呼び出し元を定義する値の省略可能な配列です。使用可能な値: `message`、`compose`、`commandBox`。既定値は `["compose", "commandBox"]` です。	いいえ	1.5

パラメーターの静的リストを使用している場合は、次のパラメーターも追加する必要があります。

プロパティ名	用途	は必須ですか?	マニフェストの最小バージョン
`parameters`	このプロパティでは、コマンドのパラメーターの静的な一覧について説明します。`fetchTask` が `false` である場合にのみ使用します。	いいえ	1.0
`parameter.name`	このプロパティは、パラメーターの名前を説明します。これは、ユーザー要求でサービスに送信されます。	はい	1.0
`parameter.description`	このプロパティは、指定する必要がある値のパラメーターの目的または例を説明します。この値は UI に表示されます。	はい	1.0
`parameter.title`	このプロパティは、ユーザーフレンドリな短いパラメーターのタイトルまたはラベルです。	はい	1.0
`parameter.inputType`	このプロパティは、必要な入力の種類に設定されます。指定できる値には`text`、`textarea`、`number`、`date`、`time`、`toggle` などがあります。既定値は `text` に設定されていません。	いいえ	1.4

埋め込み Web ビューを使用している場合は、必要に応じて、ボットを taskInfo 直接呼び出さずに Web ビューをフェッチするオブジェクトを追加できます。このオプションを選択した場合、動作はパラメーターの静的な一覧を使用する動作と類似します。ボットとの最初の対話がタスクモジュール送信アクションに応答する場合。オブジェクトを使用している場合は、パラメーターfalseを taskInfo fetchTask .

プロパティ名	用途	は必須ですか?	マニフェストの最小バージョン
`taskInfo`	メッセージ拡張コマンドを使用するときにプリロードするタスクモジュールを指定します。	いいえ	1.4
`taskInfo.title`	初期タスクモジュールタイトル。	いいえ	1.4
`taskInfo.width`	タスクモジュールの幅 - ピクセル単位の数値、または `large`、`medium`、`small` などの既定のレイアウト。	いいえ	1.4
`taskInfo.height`	タスクモジュールの高さ - ピクセル単位の数値、または `large`、`medium`、`small` などの既定のレイアウト。	いいえ	1.4
`taskInfo.url`	初期 Web ビュー URL。	いいえ	1.4

アプリマニフェストの例

次のセクションは、2 つのアクションコマンドを定義する composeExtensions オブジェクトの例です。完全なマニフェストの例ではありません。完全なアプリマニフェストスキーマについては、「アプリマニフェストスキーマ」を参照してください。

...
"composeExtensions": [
  {
    "botId": "12a3c29f-1fc5-4d97-a142-12bb662b7b23",
    "canUpdateConfiguration": true,
    "commands": [
      {
        "id": "addTodo",
        "description": "Create a To Do item",
        "title": "Create To Do",
        "type": "action",
        "context": ["commandBox", "message", "compose"],
        "fetchTask": false,
        "parameters": [
          {
            "name": "Name",
            "description": "To Do Title",
            "title": "Title",
            "inputType": "text"
          },
          {
            "name": "Description",
            "description": "Description of the task",
            "title": "Description",
            "inputType": "textarea"
          },
          {
            "name": "Date",
            "description": "Due date for the task",
            "title": "Date",
            "inputType": "date"
          }
        ]
      },
      {
        "id": "reassignTodo",
        "description": "Reassign a todo item",
        "title": "Reassign a todo item",
        "type": "action",
        "fetchTask": false,
      }
    ]
  }
]
...

コードサンプル

サンプルの名前	説明	.NET	Node.js
Teams メッセージ拡張機能アクション	アクションコマンドを定義し、タスクモジュールを作成し、タスクモジュール送信アクションに応答する方法について説明します。	表示	表示

ステップバイステップのガイド

ステップバイステップガイドに従って、アクションベースのメッセージ拡張機能を構築します。

次の手順

アダプティブカードまたは埋め込み Web ビューをオブジェクトなしで taskInfo 使用する場合は、次の手順に進みます。

タスクモジュールを使用した作成と応答

パラメーターまたは埋め込み Web ビューをオブジェクトと共 taskInfo に使用する場合は、次の手順に進みます。

タスクモジュールの送信アクションへの応答

メッセージ拡張機能のアクション コマンドを定義する

操作コマンドを呼び出す場所を選択する

タスク モジュールの作成方法を選択する