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

[アーティクル]
09/16/2024

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

重要

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

この記事では、メッセージ拡張機能、ユースケース、機能、アクションと検索コマンド、リンク展開の概要について説明します。

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

注:

@mentioning 作成ボックスのメッセージ拡張機能はサポートされていません。
メッセージ拡張オプションは、外部ユーザーとのグループチャットではサポートされていません。

デスクトップ
モバイル

Teams デスクトップ上のメッセージ拡張機能の呼び出し場所を示すスクリーンショット。

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

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

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

メッセージ拡張機能は、ユーザーがホストする Web サービスと、Teams クライアント内で Web サービスが呼び出される場所を定義するアプリマニフェストで構成されます。 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 クライアントを離れずにすぐにアクションを実行できるようにします。次の画像は、リンクがメッセージ拡張機能に貼り付けられたとき、リンク展開機能を表示します。

リンクを展開する

リンクの展開解除