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

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

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

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

新しい呼び出しメッセージ task/fetch: Bot Framework カードの invokeカードアクションを使用するか、アダプティブカードの Action.Submitカードアクションを使用して、HTML またはアダプティブカードベースのダイアログがボットから動的にフェッチされます。 task/fetch。
ディープリンク 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 ではタスクモジュールと呼ばれます)。

警告

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

TeamsJS ライブラリを v.2.19.0 以降に更新します。 TeamsJS の最新リリースの詳細については、「 Microsoft Teams JavaScript クライアントライブラリ」を参照してください。
アプリのコンテンツセキュリティポリシー (CSP) ヘッダーを定義している場合は、 frame-ancestors ディレクティブを更新して、 *.cloud.microsoft ドメインを含めます。移行中に下位互換性を確保するには、CSP ヘッダーに既存の frame-ancestors 値を保持します。この方法により、既存および将来の Microsoft 365 ホストアプリケーションの両方でアプリが引き続き動作し、以降の変更の必要性が最小限に抑えられます。

アプリの CSP ヘッダーの frame-ancestors ディレクティブで次のドメインを更新します。

https://*.cloud.microsoft

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

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

この画像は、購入invokeカードアクションを含む Bot Framework ヒーローカードを示しています。 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ダイアログが表示されます。

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

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

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

TaskInfo.urlされた HTML または JavaScript: ユーザーが入力した内容を検証したら、読みやすくするために、以降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 サンプルアプリはそれをサポートしています。詳細については、「ダイアログ Node.jsMicrosoft Teams」を参照してください。

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

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

このセクションでは、ボットが 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/fetch`メッセージと`task/submit` メッセージのペイロード

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

コードサンプル

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

関連項目

その他のリソース

次の方法で共有

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

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

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

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

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

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

コード サンプル

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

関連項目

その他のリソース

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

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

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

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

コードサンプル

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