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

[アーティクル]
10/25/2023

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

重要

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

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

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

注:

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

デスクトップ
モバイル

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

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

シナリオ	例
アクションを実行して結果を会話に返すには、外部システムが必要です。	リソースの予約、予約されたタイムスロットをチャネルに知らせます。
外部システムで何かを検索し、その結果を会話と共有する必要があります。	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 ペイロードには、呼び出されたメッセージ全体が含まれます。次の画像は、メッセージ拡張機能アクションコマンドタスクモジュールを示しています。

メッセージ拡張機能アクションコマンドタスクモジュール

検索コマンド

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

カードは、メッセージの作成領域またはコマンドボックスからトリガーされますが、メッセージからはトリガーされません。メッセージからトリガーすることはできません。次の画像は、メッセージ拡張機能検索コマンドタスクモジュールを示しています。

注:

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

リンク展開

注:

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

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

リンクを展開する

リンクの展開解除