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

[アーティクル]
02/12/2024

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

操作コマンドはどこからトリガーできますか?
ダイアログ (TeamsJS v1.x ではタスクモジュールと呼ばれます) はどのように作成されますか?
最終的なメッセージまたはカードはボットからチャネルに送信されますか、それともユーザーが送信するメッセージまたはカードが作成メッセージ領域に挿入されていますか?

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

まず、操作コマンドを呼び出す必要がある場所を決定する必要があります。アプリマニフェスト (以前は Teams アプリマニフェストと呼ばれる) で context プロパティを指定すると、次の 1 つ以上の場所からコマンドを呼び出すことができます。

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

コマンドコンテキスト = compose
コマンドボックス: コマンドボックスで/ を使用します。たとえば、 /your-app-name です。従来の Teams を使用している場合は、コマンドボックスの @mentioning によってアクションコマンドが呼び出されます。たとえば、 @your-app-name です。

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

注:

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

コマンドコンテキスト = message
注:
- ボットへの最初の呼び出しには、その呼び出し元のメッセージを含む JSON オブジェクトが含まれます。ダイアログを表示する前にメッセージを処理できます。
- ユーザーが省略記号 ....を選択すると、オーバーフローメニューが表示されます。ただし、既定では、組織またはサードパーティのアプリに対して作成されたアプリのメッセージアクションは表示されません。ユーザーが [ その他のアクション] を選択すると、メッセージアクションが表示され、必要なオプションが選択されます。それぞれのメッセージアクションがオーバーフローメニューに表示されます。オーバーフローメニューには、最新の 3 つのメッセージアクションが表示されます。表示するメッセージアクションをピン留めすることはできません。

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

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

ダイアログの作成方法を選択する

コマンドの呼び出し元を選択するだけでなく、ユーザーのダイアログでフォームを設定する方法も選択する必要があります。ダイアログ内でレンダリングされるフォームを作成するには、次の 3 つのオプションがあります。

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

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

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

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

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

開発者ポータルを使用してアクションコマンドを作成する

Teams ツールキットと Teams 用開発者ポータルを使用して、アクションコマンドを作成できます。

Teams ツールキット
Teams の開発者ポータル

Teams Toolkit を使用してアクションベースのメッセージ拡張機能を作成するには、次の手順に従います。

Visual Studio Code を開きます。
左側のウィンドウで、[ Teams ツールキット] を選択します。
[ 新しいアプリの作成] を選択します。
[ メッセージ拡張機能] を選択します。
[ 入力から収集] と [データの処理] を選択します。
プログラミング言語を選択します。
[ 既定のフォルダー] を選択します。
アプリの名前を入力し、[Enter] を選択 します。

Teams Toolkit によってプロジェクトがスキャフォールディングされ、アクションメッセージ拡張機能が作成されます。

コードスニペット

次のコードは、メッセージ拡張機能のアクションベースの例を示しています。

C#
Node.js

protected override Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionFetchTaskAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
        {
            // Handle different actions using switch.
            switch (action.CommandId)
            {
                case "HTML":
                    return new MessagingExtensionActionResponse
                    {
                        Task = new TaskModuleContinueResponse
                        {
                            Value = new TaskModuleTaskInfo
                            {
                                Height = 200,
                                Width = 400,
                                Title = "Task Module HTML Page",
                                Url = baseUrl + "/htmlpage.html",
                            },
                        },
                    };
                default:
                    string memberName = "";
                    var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);
                    memberName = member.Name;
                    return new MessagingExtensionActionResponse
                    {
                        Task = new TaskModuleContinueResponse
                        {
                            Value = new TaskModuleTaskInfo
                            {
                                Card = <<AdaptiveAction card json>>,
                                Height = 200,
                                Width = 400,
                                Title = $"Welcome {memberName}",
                            },
                        },
                    };
            }
        }

サンプルコードリファレンス

// Invoked when a Messaging Extension Fetch activity is received from the connector.
    async handleTeamsMessagingExtensionFetchTask(context, action) {
        switch (action.commandId) {
            case 'Static HTML':
                return staticHtmlPage();
        }
    }

    staticHtmlPage(){
        return {
            task: {
                type: 'continue',
                value: {
                    width: 450,
                    height: 125,
                    title: 'Dialog Static HTML',
                    url: `${baseurl}/StaticPage.html`
                }
            }
        };
    }

コードサンプル

サンプルの名前	説明	.NET	Node.js	マニフェスト
Teams メッセージ拡張機能アクション	このサンプルでは、アクションコマンドを定義し、ダイアログを作成し、ダイアログ送信アクションに応答する方法を示します。	表示	表示	表示
メッセージ拡張機能アクションプレビュー	このサンプルでは、Bot Framework v4 を使用してメッセージング拡張機能でアクションプレビューを使用する方法を示します。	表示	表示	表示

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

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

次の手順

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

[作成と送信] ダイアログ

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

ダイアログ送信アクションに応答する

次の方法で共有

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

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

ダイアログの作成方法を選択する

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

開発者ポータルを使用してアクションコマンドを作成する

コードスニペット

コードサンプル

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

次の手順

関連項目

その他のリソース

次の方法で共有

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

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

ダイアログの作成方法を選択する

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

開発者ポータルを使用してアクション コマンドを作成する

コード スニペット

コード サンプル

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

次の手順

関連項目

その他のリソース

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

開発者ポータルを使用してアクションコマンドを作成する

コードスニペット

コードサンプル

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