ボットでダイアログを使用する

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

Microsoft 365 グループのヒーロー、サムネイル、コネクタであるアダプティブカードと Bot Framework カードのボタンを使用して、Microsoft Teams ボットからダイアログ (TeamsJS v1.x のタスクモジュールと呼ばれます) を呼び出します。ダイアログは、多くの場合、複数の会話ステップよりも優れたユーザーエクスペリエンスです。ボットの状態を追跡し、ユーザーがシーケンスを中断またはキャンセルできるようにします。

ダイアログを呼び出す方法は 2 つあります。

新しい呼び出しメッセージtask/fetch: Bot Framework カードのinvokeカードアクションを使用するかAction.Submit、アダプティブカードのカードアクションを使用してtask/fetch、HTML またはアダプティブカードベースのダイアログがボットから動的にフェッチされます。
ディープリンク URL: ダイアログにディープリンク構文を使用すると、Bot Framework カードのopenUrlカードアクションとアダプティブカードのAction.OpenUrlカードアクションをそれぞれ使用できます。ディープリンク URL では、ダイアログ URL またはアダプティブカード本文は、に対するサーバーラウンドトリップを回避するために既に task/fetch認識されています。

重要

各 url および fallbackUrl は、HTTPS 暗号化プロトコルを実装する必要があります。

を使用してダイアログを呼び出す `task/fetch`

invoke カードアクションまたは Action.Submit の value オブジェクトが初期化され、ユーザーがボタンを選択すると、invoke メッセージがボットに送信されます。メッセージに対する invoke HTTP 応答には、ラッパーオブジェクトに TaskInfo オブジェクトが埋め込まれています。これは、Teams がダイアログを表示するために使用します (TeamsJS v1.x ではタスクモジュールと呼ばれます)。

警告

Web バージョンの Teams (teams.microsoft.com)、Outlook (outlook.com)、Microsoft 365 (microsoft365.com) ドメインを含む Microsoft のクラウドサービスは、cloud.microsoft ドメインに移行しています。 2024 年 6 月より前に次の手順を実行して、アプリが Teams Web クライアントで引き続きレンダリングされるようにします。

TeamsJS SDK を v.2.19.0 以降に更新します。 TeamsJS SDK の最新リリースの詳細については、「 Microsoft Teams JavaScript クライアントライブラリ」を参照してください。
Teams アプリのコンテンツセキュリティポリシーヘッダーを更新して、アプリが teams.cloud.microsoft ドメインにアクセスできるようにします。 Teams アプリが Outlook と Microsoft 365 に拡張されている場合は、アプリが teams.cloud.microsoft、outlook.cloud.microsoft、m365.cloud.microsoft ドメインにアクセスできることを確認します。

タスク/フェッチ要求または応答

次の手順では、を使用 task/fetchしてダイアログ (TeamsJS v1.x のタスクモジュールと呼ばれます) を呼び出す方法について説明します。

この画像は、Bot Framework のヒーローカードと Buyinvokeカードアクションを示しています。 type プロパティの値は task/fetch であり、残りの value オブジェクトを選択できます。
ボットは invoke HTTP POST メッセージを受信します。
ボットは応答オブジェクトを作成し、それを HTTP 200 応答コードとともに POST 応答の本文に返します。応答のスキーマの詳細については、タスク/送信に関する説明を参照してください。次のコードは、ラッパーオブジェクトに埋め込まれた TaskInfo オブジェクトを含む HTTP 応答の本文の例を示しています。
```
{
  "task": {
    "type": "continue",
    "value": {
      "title": "Task module title",
      "height": 500,
      "width": "medium",
      "url": "https://contoso.com/msteams/taskmodules/newcustomer",
      "fallbackUrl": "https://contoso.com/msteams/taskmodules/newcustomer"
    }
  }
}
```
ボットのイベントとその応答は task/fetch 、Microsoft Teams JavaScript クライアントライブラリ (TeamsJS) の関数に似ています microsoftTeams.tasks.startTask() 。
Microsoft Teams によってダイアログが表示されます。

次のセクションでは、ダイアログの結果を送信する方法の詳細を説明します。

ダイアログの結果を送信する

ユーザーがダイアログを終了すると、ボットに結果を送信し直す方法は、タブで動作する方法と似ています。詳細については、「ダイアログの結果を送信する例」を参照してください。次のようないくつかの違いがあります。

HTML または JavaScript。 TaskInfo.url: ユーザーが入力した内容を検証したら、読みやすくするために、以降submitTask()と呼ばれる関数を呼び出microsoftTeams.tasks.submitTask()します。 Teams でダイアログ (TeamsJS v1.x ではタスクモジュールと呼ばれます) を閉じる場合は、パラメーターなしでを呼び出 submitTask() すことができますが、オブジェクトまたは文字列をに渡す submitHandler必要があります。最初のパラメーター result として渡します。. Teams は submitHandler を呼び出し、err は null であり、result は submitTask() に渡したオブジェクトまたは文字列です。 resultパラメータを使用して submitTask() を呼び出す場合は、appId または appId 文字列の配列を渡す必要があります。このアクションにより、Teams は結果を送信するアプリが同じであることを検証し、ダイアログを呼び出すことができます。ボットは、result を含む task/submit メッセージを受信します。詳細については、ペイロードの task/fetch および task/submitメッセージを参照してください。
TaskInfo.card であるアダプティブカード: ユーザーが入力したアダプティブカード本体は、ユーザーが Action.Submit ボタンを選択すると、task/submit メッセージを介してボットに送信されます。

次のセクションでは、メッセージに応答する方法について詳しく説明します task/submit 。

メッセージに応答します`task/submit`

ボットから呼び出されたダイアログ (TeamsJS v1.x ではタスクモジュールと呼ばれます) でユーザーが終了すると、ボットは常にメッセージを task/submit invoke 受け取ります。 task/submit メッセージに応答するときは、次のようにいくつかのオプションがあります。

HTTP 本文の応答	シナリオ
`task/submit` メッセージを無視するものはありません	最も単純な応答は、まったく応答がないことです。ユーザーがダイアログで終了したときにボットが応答する必要はありません。
{ "task": { "type": "message", "value": "Message text" } }	Teams は、ポップアップメッセージボックスに `value` の値を表示します。
{ "task": { "type": "continue", "value": <TaskInfo オブジェクト> } }	アダプティブカードのシーケンスをウィザードまたはマルチステップエクスペリエンスで連結できます。

注:

アダプティブカードをシーケンスにチェーンすることは高度なシナリオです。 Node.js サンプルアプリはそれをサポートしています。詳細については、「 Microsoft Teams ダイアログ Node.js」を参照してください。

次のセクションでは、task/fetch および task/submit メッセージのペイロードについて詳しく説明します。

メッセージと `task/submit` メッセージの`task/fetch`ペイロード

このセクションでは、ボットが task/fetch または task/submit ボットフレームワーク Activity オブジェクトを受信したときに受信するもののスキーマを定義します。次の表に、task/fetch および task/submit メッセージのペイロードのプロパティを示します。

プロパティ	説明
`type`	常に `invoke` です。
`name`	`task/fetch` または `task/submit` のいずれかです。
`value`	開発者定義のペイロードです。 `value` オブジェクトの構造は、Teams から送信されるものと同じです。ただし、この場合は異なります。 `value` であるボットフレームワークと `data` であるアダプティブカード `Action.Submit` アクションの両方からの `task/fetch` である動的フェッチのサポートが必要です。 `value` または `data` に含まれているものに加えて、チーム `context` をボットに通信する方法が必要です。 'value' と 'data' を親オブジェクトに結合します。 { "context": { "theme": "default" \|"dark" \|"contrast", }, "data": [Bot Framework カードの値フィールド] \|[アダプティブカードのデータフィールド] }

次のセクションでは、Node.js で task/fetch および task/submit 呼び出しメッセージを受信して応答する例を示します。

次のタブでは、Node.js と C# でメッセージを提供 task/fetch および task/submit 呼び出します。

Node.js
C#

handleTeamsTaskModuleFetch(context, taskModuleRequest) {
    // Called when the user selects an options from the displayed HeroCard or
    // AdaptiveCard.  The result is the action to perform.

    const cardTaskFetchValue = taskModuleRequest.data.data;
    var taskInfo = {}; // TaskModuleTaskInfo

    if (cardTaskFetchValue === TaskModuleIds.YouTube) {
        // Display the YouTube.html page
        taskInfo.url = taskInfo.fallbackUrl = this.baseUrl + '/' + TaskModuleIds.YouTube + '.html';
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.YouTube);
    } else if (cardTaskFetchValue === TaskModuleIds.CustomForm) {
        // Display the CustomForm.html page, and post the form data back via
        // handleTeamsTaskModuleSubmit.
        taskInfo.url = taskInfo.fallbackUrl = this.baseUrl + '/' + TaskModuleIds.CustomForm + '.html';
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.CustomForm);
    } else if (cardTaskFetchValue === TaskModuleIds.AdaptiveCard) {
        // Display an AdaptiveCard to prompt user for text, and post it back via
        // handleTeamsTaskModuleSubmit.
        taskInfo.card = this.createAdaptiveCardAttachment();
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.AdaptiveCard);
    }

    return TaskModuleResponseFactory.toTaskModuleResponse(taskInfo);
}

async handleTeamsTaskModuleSubmit(context, taskModuleRequest) {
    // Called when data is being returned from the selected option (see `handleTeamsTaskModuleFetch').

    // Echo the users input back.  In a production bot, this is where you'd add behavior in
    // response to the input.
    await context.sendActivity(MessageFactory.text('handleTeamsTaskModuleSubmit: ' + JSON.stringify(taskModuleRequest.data)));

    // Return TaskModuleResponse
    return {
        // TaskModuleMessageResponse
        task: {
            type: 'message',
            value: 'Thanks!'
        }
    };
}

setTaskInfo(taskInfo, uiSettings) {
    taskInfo.height = uiSettings.height;
    taskInfo.width = uiSettings.width;
    taskInfo.title = uiSettings.title;
}

protected override Task<TaskModuleResponse> OnTeamsTaskModuleFetchAsync(ITurnContext<IInvokeActivity> turnContext, TaskModuleRequest taskModuleRequest, CancellationToken cancellationToken)
{
    var asJobject = JObject.FromObject(taskModuleRequest.Data);
    var value = asJobject.ToObject<CardTaskFetchValue<string>>()?.Data;

    var taskInfo = new TaskModuleTaskInfo();
    switch (value)
    {
        case TaskModuleIds.YouTube:
            taskInfo.Url = taskInfo.FallbackUrl = _baseUrl + "/" + TaskModuleIds.YouTube;
            SetTaskInfo(taskInfo, TaskModuleUIConstants.YouTube);
            break;
        case TaskModuleIds.CustomForm:
            taskInfo.Url = taskInfo.FallbackUrl = _baseUrl + "/" + TaskModuleIds.CustomForm;
            SetTaskInfo(taskInfo, TaskModuleUIConstants.CustomForm);
            break;
        case TaskModuleIds.AdaptiveCard:
            taskInfo.Card = CreateAdaptiveCardAttachment();
            SetTaskInfo(taskInfo, TaskModuleUIConstants.AdaptiveCard);
            break;
        default:
            break;
    }

    return Task.FromResult(taskInfo.ToTaskModuleResponse());
}

protected override async Task<TaskModuleResponse> OnTeamsTaskModuleSubmitAsync(ITurnContext<IInvokeActivity> turnContext, TaskModuleRequest taskModuleRequest, CancellationToken cancellationToken)
{
    var reply = MessageFactory.Text("OnTeamsTaskModuleSubmitAsync Value: " + JsonConvert.SerializeObject(taskModuleRequest));
    await turnContext.SendActivityAsync(reply, cancellationToken);

    return TaskModuleResponseFactory.CreateResponse("Thanks!");
}

private static void SetTaskInfo(TaskModuleTaskInfo taskInfo, UISettings uIConstants)
{
    taskInfo.Height = uIConstants.Height;
    taskInfo.Width = uIConstants.Width;
    taskInfo.Title = uIConstants.Title.ToString();
}

Bot Framework カードアクションと Adaptive Card Action.Submit アクション

Bot Framework カードアクションのスキーマはアダプティブカード Action.Submit アクションとは異なり、ダイアログを呼び出す方法も異なります。の Action.Submit オブジェクトには data オブジェクトがmsteams含まれているため、カード内の他のプロパティと干渉しません。次の表は、各カードアクションの例を示しています。

Bot Framework カードアクション	Adaptive Card Action.Submit アクション
{ "type": "invoke", "title": "Buy", "value": { "type": "task/fetch", <...> } }	{ "type": "Action.Submit", "id": "btnBuy", "title": "Buy", "data": { <...>, "msteams": { "type": "task/fetch" } } }

コードサンプル

サンプルの名前	説明	.NET	Node.js	マニフェスト
ダイアログサンプル bots-V4	このサンプルでは、Bot Framework v4 と Teams タブを使用してダイアログを作成する方法を示します。	表示	表示	表示

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

Teams でダイアログボットを作成およびフェッチするには、ステップバイステップガイドに従います。

ボットでダイアログを使用する

を使用してダイアログを呼び出す `task/fetch`

ダイアログの結果を送信する

メッセージに応答します`task/submit`

メッセージと `task/submit` メッセージの`task/fetch`ペイロード

Bot Framework カードアクションと Adaptive Card Action.Submit アクション

コードサンプル

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

関連項目

フィードバック

その他のリソース

ボットでダイアログを使用する

を使用してダイアログを呼び出す task/fetch

ダイアログの結果を送信する

メッセージに応答しますtask/submit

メッセージと task/submit メッセージのtask/fetchペイロード

Bot Framework カード アクションと Adaptive Card Action.Submit アクション

コード サンプル

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

関連項目

フィードバック

その他のリソース

を使用してダイアログを呼び出す `task/fetch`

メッセージに応答します`task/submit`

メッセージと `task/submit` メッセージの`task/fetch`ペイロード

Bot Framework カードアクションと Adaptive Card Action.Submit アクション

コードサンプル

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