メッセージの拡張機能のビルド

メッセージ拡張機能を使用すると、ユーザーは Microsoft Teams クライアント内のボタンとフォームを使用して Web サービスと連携できます。 ユーザーは、外部システムのメッセージ作成領域、コマンド ボックスから、またはメッセージから直接、操作を検索したり、開始したりできます。 これらの操作の結果は、リッチフォーマットのカードとして Teams クライアントに返すことができます。

Important

メッセージ拡張機能は、 Government Community Cloud (GCC)、GCC-High、および国防総省 (DOD) 環境で使用できます。

このドキュメントでは、メッセージ拡張機能、さまざまなシナリオで実行されるタスク、メッセージ拡張機能、アクションおよび検索コマンドの機能、リンク展開の概要について説明します。

次の図は、メッセージ拡張機能を呼び出すことができる場所を示しています。

注:

@mentioning 作成ボックスのメッセージ拡張機能はサポートされていません。

メッセージ拡張機能が使用されるシナリオ

シナリオ
アクションを実行して結果を会話に返すには、外部システムが必要です。 リソースの予約、予約されたタイム スロットをチャネルに知らせます。
外部システムで何かを検索し、その結果を会話と共有する必要があります。 Azure DevOps で作業項目を検索し、アダプティブ カードとしてグループと共有します。
外部システムで複数のステップまたは大量の情報を含む複雑なタスクを完了し、その結果を会話と共有する必要があります。 Teams のメッセージに基づいてトラッキング システムにバグを作成し、そのバグを Bob に割り当て、そのバグの詳細情報が記載されたカードを会話スレッドに送信します。

メッセージ拡張機能のしくみを理解する

メッセージ拡張機能は、ホストする Web サービスと、Web サービスが呼び出される Teams クライアント内の場所を指定するアプリ マニフェストで構成されます。 Web サービスは Bot Framework のメッセージング スキーマとセキュリティで保護された通信プロトコルを利用するため、Bot Framework で Web サービスをボットとして登録する必要があります。

注:

Web サービスを手動で作成することはできますが、 Bot Framework SDK を使用してプロトコルを操作することをお勧めします。

アプリ マニフェスト (以前は Teams アプリ マニフェストと呼ばれる) では、1 つのメッセージ拡張機能が最大 10 個の異なるコマンドで定義されています。 各コマンドは、アクションや検索などの型と、呼び出されるクライアント内の場所を定義します。 呼び出しの場所には、メッセージの作成領域、コマンド バー、メッセージが含まれます。 呼び出し時に、Web サービスは、すべての関連情報を含む JSON ペイロードを含む HTTPS メッセージを受信します。 JSON ペイロードで応答して、有効にする次の操作を Teams クライアントに通知します。

メッセージ拡張コマンドの種類

メッセージ拡張機能のコマンドには、操作コマンドと検索コマンドの 2 種類があります。 メッセージ拡張機能のコマンドの種類は、Web サービスで利用可能な UI 要素と操作フローを定義します。 認証や構成などの特定の操作は、両方のコマンドの種類で使用できます。

操作コマンド

アクション コマンドは、情報を収集または表示するためのモーダル ポップアップをユーザーに表示するために使用されます。 ユーザーがフォームを送信すると、Web サービスはメッセージを会話に直接挿入するか、新規作成メッセージ領域に挿入することで応答します。 その後、ユーザーはメッセージを送信できます。 より複雑なワークフローでは、複数のフォームをリンクできます。

アクション コマンドは、メッセージの作成領域、コマンド ボックス、またはメッセージからトリガーされます。 コマンドがメッセージから呼び出されると、ボットに送信された最初の JSON ペイロードには、呼び出されたメッセージ全体が含まれます。 次の図は、メッセージ拡張アクション コマンド ダイアログ (TeamsJS v1.x のタスク モジュールと呼ばれます) を表示しています。

メッセージ拡張アクション コマンド ダイアログ

検索コマンド

検索コマンドを使用すると、ユーザーは検索ボックスを介して手動で外部システムを検索したり、監視対象ドメインへのリンクを新規作成メッセージ領域に貼り付けたり、検索結果をメッセージに挿入したりできます。 単純な検索コマンド フローでは、最初の呼び出しメッセージには、ユーザーによって送信された検索文字列が含まれます。 カードのリストとカードのプレビューで応答します。 Teams クライアントは、ユーザーのカード プレビューのリストをレンダリングします。 ユーザーがリストからカードを選択すると、フルサイズのカードがメッセージ作成領域に挿入されます。

カードは、メッセージの作成領域またはコマンド ボックスからトリガーされますが、メッセージからはトリガーされません。 メッセージからトリガーすることはできません。 次の図は、メッセージ拡張機能の検索コマンド ダイアログを表示します。

メッセージ拡張機能検索コマンド

注:

カードの詳細については、「カードとは」を参照してください。

注:

リンクの展開は、ボットベースのメッセージ拡張機能でのみサポートされます。

作成メッセージ領域に URL を貼り付けると、Web サービスが呼び出されます。 この機能は、リンク展開として知られています。 特定のドメインを含む URL が新規作成メッセージ領域に貼り付けられたとき、呼び出しを受信するようにサブスクライブできます。 Web サービスは URL を詳細なカードに展開し、標準の Web サイト プレビュー カードよりも多くの情報を提供できます。 ボタンを追加して、ユーザーが Teams クライアントを離れずにすぐにアクションを実行できるようにします。 次の画像は、リンクがメッセージ拡張機能に貼り付けられたとき、リンク展開機能を表示します。

リンクを展開する

リンクの展開解除

メッセージの拡張機能のビルド

メッセージ拡張機能を作成する方法がまだない場合は、次の 2 つの方法があります。

  • API (API ベース) を使用してメッセージ拡張機能をビルドする: 既存の API からメッセージ拡張機能を簡単に作成できます。 このメソッドには OpenAPI Description (OAD) ドキュメントが必要です。

  • Bot Framework (ボットベース) を使用してメッセージ拡張機能を構築する: 1 対 1 の会話エクスペリエンスが必要な場合は、ボットから新しいメッセージ拡張機能を作成できます。

次の表は、開始するメッセージ拡張機能の種類を選択するのに役立ちます。

API ベースのメッセージ拡張機能

  • 作成と保守が簡単かつ迅速に行えます。
  • メッセージ拡張機能では API が使用されます。
  • ボット ロジック用の追加のコードやリソースは必要ありません。
  • メッセージ拡張機能が Web サービスと通信するだけで済み、複雑なロジックや状態管理が不要なシナリオに最適です。
  • トラフィックは Azure ボット インフラストラクチャに依存しないため、民営化されます。
  • 検索コマンドをサポートします。

ボットベースのメッセージ拡張機能

  • 柔軟性が高くなります。
  • メッセージ拡張機能では、Bot Framework が使用されます。
  • ボットの完全な機能を活用できます。
  • メッセージ拡張機能が複数のサービスと通信したり、複雑なロジックやユーザー操作を管理したり、セッション間で状態を維持したりする必要があるシナリオに最適です。
  • アクション コマンド、検索コマンド、リンクの展開をサポートします。

デシジョン ツリーを示すスクリーンショット。これは、ユーザーが API ベースとボットベースのメッセージ拡張機能を選択するのに役立ちます。

メッセージ拡張機能の作成を開始するオプションを選択します。

[OpenAPI] アイコン タイルを示すスクリーンショット。

Bot Framework タイルを示すスクリーンショット。

コード サンプル

サンプルの名前 説明 .NET Node.js Python マニフェスト
操作ベースのコマンドを使用したメッセージ拡張機能 このサンプルでは、アクション コマンドを定義し、ダイアログを作成し、ダイアログ送信アクションに応答する方法を示します。 表示 表示 表示 表示
検索ベースのコマンドを使用したメッセージ拡張機能 このサンプルでは、検索ベースのメッセージ拡張機能を構築する方法を示します。 nuget パッケージを検索し、検索ベースのメッセージング拡張機能で結果を表示します。 表示 表示 表示 表示
メッセージ拡張機能アクション プレビュー このサンプルでは、Bot Framework v4 を使用してメッセージング拡張機能でアクション プレビューを使用する方法を示します。 表示 表示 該当なし 表示
タスク スケジュール用のメッセージ拡張機能操作 このサンプルでは、メッセージ拡張アクション コマンドからタスクをスケジュールし、スケジュールされた日時にアラーム カードを取得する方法を示します。 表示 表示 該当なし 表示