タスクモジュールの送信アクションに応答する

[アーティクル]
03/22/2023

重要

このセクションのコードサンプルは、v4.6 以降のバージョンの Bot Framework SDK に基づいています。以前のバージョンのドキュメントをお探しの場合は、ドキュメントの Resources フォルダーにあるメッセージ拡張機能 - v3 SDK セクションを参照してください。

このドキュメントでは、ユーザーのタスクモジュール送信アクションなどのアクションコマンドに対するアプリの応答について説明します。ユーザーがタスクモジュールを送信すると、Web サービスはコマンド ID とパラメーター値を含む composeExtensions/submitAction 呼び出しメッセージを受信します。アプリには、呼び出しに応答する 5 秒があります。

対応には、以下のオプションがあります。

応答なし: 送信アクションを使用して、外部システムでプロセスをトリガーし、ユーザーにはフィードバックを提供しません。これは、実行時間の長いプロセスに役立ち、フィードバックを代替的に提供する場合に便利です。たとえば、プロアクティブメッセージを使用してフィードバックを送信できます。
別のタスクモジュール: 複数のステップがある操作の一部として、追加のタスクモジュールで応答します。
カードによる応答: ユーザーが操作したり、メッセージに挿入したりできるカードで応答できます。
ボットからのアダプティブカード: アダプティブカードを会話に直接挿入します。
ユーザーに認証を要求します。
追加の構成をユーザーに要求します。

アプリが 5 秒以内に応答しない場合、Teams クライアントは要求を 2 回再試行してから、 アプリに到達できませんというエラーメッセージを送信します。タイムアウト後にボットが応答した場合、応答は無視されます。

注:

ボットが呼び出し要求に応答した後、アプリは実行時間の長いアクションを延期する必要があります。実行時間の長いアクションの結果は、メッセージとして配信できます。
アプリには、呼び出しメッセージに応答する 5 秒があります。

認証または構成の場合、ユーザーがプロセスを完了すると、元の呼び出しが Web サービスに再送信されます。次の表は、メッセージ拡張機能の呼び出し場所 commandContext に基づいて、使用可能な応答の種類を示しています。

応答の種類	作成	コマンドバー	メッセージ
カードの応答	✔️	✔️	✔️
別のタスクモジュール	✔️	✔️	✔️
アダプティブカードを使用したボット	✔️	❌	✔️
応答なし	✔️	✔️	✔️

注:

[Action.Submit through ME card] を選択すると、composeExtensions という名前の呼び出しアクティビティが送信されます。値は通常のペイロードと等しくなります。
会話を通して Action.Submit を選択すると、値は通常のペイロードと等しくなる onCardButtonClicked という名前のメッセージアクティビティを受け取ります。

アプリに会話ボットが含まれている場合は、会話にボットをインストールし、タスクモジュールを読み込みます。ボットは、タスクモジュールの追加のコンテキストを取得するのに役立ちます。会話型ボットをインストールするには、「会話型ボットのインストールを要求する」を参照してください。

submitAction 呼び出しイベント

呼び出しメッセージを受信する例を次に示します。

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken) {
  //code to handle the submit action
}

class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
  constructor() {
  handleTeamsMessagingExtensionSubmitAction(context, action) {
  
  //code to handle the submit action
    }
  }
}

次の例は、受け取る JSON オブジェクトです。この commandContext パラメーターは、メッセージ拡張機能がトリガーされた場所を示します。 data オブジェクトには、パラメーターとしてフォーム上のフィールドと、ユーザーが送信した値が含まれます。 JSON オブジェクトでは、最も関連性の高いフィールドが強調表示されます。

{
  "name": "composeExtension/submitAction",
  "imdisplayname": "Bob Smith",
  "serviceUrl": "https://smba.trafficmanager.net/amer/",
  "value": {
    "commandId": "giveKudos",
    "commandContext": "compose",
    "context": {
      "theme": "default"
    },
    "data": {
      "id": "submitButton",
      "formField1": "formField1_value",
      "formField2": "formField2_value",
      "formField3": "formField3_value"
    }
  },
  "conversation": {
    "id": "19:7705841b240044b297123ad7f9c99217@thread.skype"
  }
}

メッセージ作成領域にカードを挿入して応答する

composeExtensions/submitAction の要求に応答する最も一般的な方法は、作成メッセージ領域にカードを挿入することです。ユーザーは、カードを会話に送信します。カードの使用に関する詳細については、「カードとカードアクション」を参照してください。

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
    var response = new MessagingExtensionActionResponse
    {
        ComposeExtension = new MessagingExtensionResult
        {
            AttachmentLayout = "list",
            Type = "result",
        },
    };
    var createCardData = ((JObject)action.Data).ToObject<CreateCardData>();
var card = new HeroCard
{
     Title = createCardData.Title,
     Subtitle = createCardData.Subtitle,
     Text = createCardData.Text,
};
    var attachments = new List<MessagingExtensionAttachment>();
    attachments.Add(new MessagingExtensionAttachment
    {
        Content = card,
        ContentType = HeroCard.ContentType,
        Preview = card.ToAttachment(),
    });
    response.ComposeExtension.Attachments = attachments;
    return response;
}

class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
  handleTeamsMessagingExtensionSubmitAction(context, action) {
    const data = action.data;
    const heroCard = CardFactory.heroCard(data.title, data.text);
    heroCard.content.subtitle = data.subTitle;
    const attachment = { contentType: heroCard.contentType, content: heroCard.content, preview: heroCard };

    return {
      composeExtension: {
        type: 'result',
        attachmentLayout: 'list',
        attachments: [
          attachment
        ]
      }
    }
  }
}

{
  "composeExtension": {
    "attachmentLayout": "list",
    "type": "result",
    "attachments": [
      {
        "preview": {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "title": "formField1_value",
            "subtitle": "formField2_value",
            "text": "formField3_value"
          }
        },
        "contentType": "application/vnd.microsoft.card.hero",
        "content": {
          "title": "formField1_value",
          "subtitle": "formField2_value",
          "text": "formField3_value"
        }
      }
    ]
  }
}

別のタスクモジュールで応答する

追加のタスクモジュールを使用して submitAction イベントに応答するように選択できます。これは、次のシナリオで役立ちます。

大量の情報を収集する。
ユーザー入力に基づいて情報コレクションを動的に変更する。
ユーザーが送信した情報を検証し、問題が発生した場合は、エラーメッセージでフォームを再送信します。

対応方法は、としての最初のfetchTaskイベントへの対応と同じです。 Bot Framework SDK を使用している場合は、両方の送信アクションに対して同じイベントトリガーが発生します。これを機能させるには、正しい応答を決定するロジックを追加する必要があります。

アダプティブカードを使用したボットの応答

注:

アダプティブカードを使用してボットの応答を取得する前提条件は、bot オブジェクトをアプリマニフェストに追加し、ボットに必要なスコープを定義する必要があるということです。ボットのメッセージ拡張機能と同じ ID を使用します。

また、ボットを使用してアダプティブカードを含むメッセージをチャネルに挿入することで、submitAction に応答することもできます。ユーザーは、メッセージを送信する前にプレビューできます。これは、アダプティブカード応答を作成する前にユーザーから情報を収集するシナリオや、他のユーザーが応答した後にカードを更新する場合に便利です。

次のシナリオは、アプリ Polly がチャネル会話に構成手順を含めずに投票を構成する方法を示しています。

投票を構成するには、以下の操作を行います。

ユーザーは、タスクモジュールを呼び出すメッセージ拡張機能を選択します。
ユーザーは、タスクモジュールを使用して投票を構成します。
タスクモジュールを送信した後、アプリは提供された情報を使用してアダプティブカードとして投票を構築し、クライアントに botMessagePreview 応答として送信します。
その後、ユーザーは、ボットがチャネルに挿入する前に、アダプティブカードメッセージをプレビューできます。アプリがチャネルのメンバーでない場合は、を選択 Send して追加します。
注:
- ユーザーは Edit にメッセージを選択して、元のタスクモジュールに返すこともできます。
- アダプティブカードとの対話では、メッセージの送信前に変更されます。
ユーザーがを選択 Sendすると、ボットはチャネルにメッセージを投稿します。

最初の送信アクションに応答する

タスクモジュールは、ボットがチャネルに送信するカードのプレビューを使用して、最初の composeExtensions/submitAction メッセージに応答する必要があります。ユーザーは送信前にカードを確認し、ボットが既にインストールされている場合は会話にボットをインストールしてみてください。

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  dynamic createCardData = ((JObject) action.Data).ToObject(typeof(JObject));
  var response = new MessagingExtensionActionResponse
  {
    ComposeExtension = new MessagingExtensionResult
    {
      Type = "botMessagePreview",
      ActivityPreview = MessageFactory.Attachment(new Attachment
      {
        Content = new AdaptiveCard("1.0")
        {
          Body = new List<AdaptiveElement>()
          {
            new AdaptiveTextBlock() { Text = "FormField1 value was:", Size = AdaptiveTextSize.Large },
            new AdaptiveTextBlock() { Text = Data["FormField1"] as string }
          },
          Height = AdaptiveHeight.Auto,
          Actions = new List<AdaptiveAction>()
          {
            new AdaptiveSubmitAction
            {
              Type = AdaptiveSubmitAction.TypeName,
              Title = "Submit",
              Data = new JObject { { "submitLocation", "messagingExtensionFetchTask" } },
            },
          }
        },
        ContentType = AdaptiveCard.ContentType
      }) as Activity
    }
  };

  return response;
}

class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
  handleTeamsMessagingExtensionSubmitAction(context, action) {
    const submittedData = action.data;
    const adaptiveCard = CardFactory.adaptiveCard({
      actions: [
        { type: 'Action.Submit', title: 'Submit', data: { submitLocation: 'messagingExtensionSubmit' } }
      ],
      body: [
          { text: 'Adaptive Card from Task Module', type: 'TextBlock', weight: 'bolder' },
          { text: `${ submittedData.Question }`, type: 'TextBlock', id: 'Question' },
          { id: 'Answer', placeholder: 'Answer here...', type: 'Input.Text' },
        {
          choices: [
            { title: submittedData.Option1, value: submittedData.Option1 },
            { title: submittedData.Option2, value: submittedData.Option2 },
            { title: submittedData.Option3, value: submittedData.Option3 }
          ],
          id: 'Choices',
          isMultiSelect: submittedData.MultiSelect,
          style: 'expanded',
          type: 'Input.ChoiceSet'
        }
      ],
      type: 'AdaptiveCard',
      version: '1.0'
    });
    return {
      composeExtension: {
        activityPreview: MessageFactory.attachment(adaptiveCard, null, null, InputHints.ExpectingInput),
        type: 'botMessagePreview'
      }
    };
  }
}

注:

activityPreview には、1 つのアダプティブカード添付ファイルを含む message アクティビティが含まれている必要があります。 << Card Payload >> の値は、送信するカードのプレースホルダーです。

{
  "composeExtension": {
    "type": "botMessagePreview",
    "activityPreview": {
      "type": "message",
      "attachments":  [
        {
          "contentType": "application/vnd.microsoft.card.adaptive",
          "content": << Card Payload >>
        }
      ]
    }
  }
}

botMessagePreview によるイベントの送信と編集

メッセージ拡張機能は、composeExtensions/submitAction 呼び出しの 2 つの新しい種類である value.botMessagePreviewAction = "send" と value.botMessagePreviewAction = "edit" に応答する必要があります。

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionBotMessagePreviewEditAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  //handle the event
}

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionBotMessagePreviewSendAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  //handle the event
}

class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
  handleTeamsMessagingExtensionBotMessagePreviewEdit(context, action) {

    //handle the event
  }
  
  handleTeamsMessagingExtensionBotMessagePreviewSend(context, action) {

    //handle the event
  }
}

{
  "name": "composeExtension/submitAction",
  "type": "invoke",
  "conversation": { "id": "19:c366b75791784100b6e8b515fd55b063@thread.skype" },
  "imdisplayname": "Pranav Smith",
  ...
  "value": {
    "botMessagePreviewAction": "edit | send",
    "botActivityPreview": [
      {
        "type": "message/card",
        "attachments": [
          {
            "content":
              {
                "type": "AdaptiveCard",
                "body": [{<<card payload>>}]
              },
            "contentType" : "application/vnd.microsoft.card.adaptive"
          }
        ],
        "context": { "theme": "default" }
      }
    ],
  }
}

botMessagePreview の編集に応答する

[編集] を選択してユーザーが送信する前にカードを編集した場合は、value.botMessagePreviewAction = edit を含む composeExtensions/submitAction の呼び出しを受信します。対話を開始した最初の composeExtensions/fetchTask 呼び出しに応答して、送信したタスクモジュールを返すことで応答します。ユーザーは、元の情報を再入力してプロセスを開始できます。使用可能な情報を使用して、ユーザーが最初からすべての情報を入力する必要がないようにタスクモジュールを更新します。最初の fetchTask イベントへの応答に関する詳細については、「最初の fetchTask イベントに応答する」を参照してください。

botMessagePreview 送信に応答する

ユーザーが [送信] を選択すると、value.botMessagePreviewAction = send を含む composeExtensions/submitAction の呼び出しを受信します。 Web サービスは、アダプティブカードを使用したプロアクティブメッセージを作成して会話に送信し、呼び出しに返信する必要があります。

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionBotMessagePreviewSendAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  var activityPreview = action.BotActivityPreview[0];
  var attachmentContent = activityPreview.Attachments[0].Content;
  var previewedCard = JsonConvert.DeserializeObject<AdaptiveCard>(attachmentContent.ToString(),
          new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore });
  
  previewedCard.Version = "1.0";

  var responseActivity = Activity.CreateMessageActivity();
  Attachment attachment = new Attachment()
  {
    ContentType = AdaptiveCard.ContentType,
    Content = previewedCard
  };
  responseActivity.Attachments.Add(attachment);
  
  // Attribute the message to the user on whose behalf the bot is posting
  responseActivity.ChannelData = new {
    OnBehalfOf = new []
    {
      new
      {
        ItemId = 0,
        MentionType = "person",
        Mri = turnContext.Activity.From.Id,
        DisplayName = turnContext.Activity.From.Name
      }  
    }
  };
  
  await turnContext.SendActivityAsync(responseActivity);

  return new MessagingExtensionActionResponse();
}

class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
    async handleTeamsMessagingExtensionBotMessagePreviewSend(context, action) {
      // The data has been returned to the bot in the action structure.
      const activityPreview = action.botActivityPreview[0];
      const attachmentContent = activityPreview.attachments[0].content;
      const userText = attachmentContent.body[1].text;
      const choiceSet = attachmentContent.body[3];

      const submitData = {
        MultiSelect: choiceSet.isMultiSelect ? 'true' : 'false',
        Option1: choiceSet.choices[0].title,
        Option2: choiceSet.choices[1].title,
        Option3: choiceSet.choices[2].title,
        Question: userText
      };

      const adaptiveCard = CardFactory.adaptiveCard({
        actions: [
          { type: 'Action.Submit', title: 'Submit', data: { submitLocation: 'messagingExtensionSubmit' } }
        ],
        body: [
          { text: 'Adaptive Card from Task Module', type: 'TextBlock', weight: 'bolder' },
          { text: `${ submitData.Question }`, type: 'TextBlock', id: 'Question' },
          { id: 'Answer', placeholder: 'Answer here...', type: 'Input.Text' },
          {
            choices: [
                { title: submitData.Option1, value: submitData.Option1 },
                { title: submitData.Option2, value: submitData.Option2 },
                { title: submitData.Option3, value: submitData.Option3 }
            ],
            id: 'Choices',
            isMultiSelect: submitData.MultiSelect,
            style: 'expanded',
            type: 'Input.ChoiceSet'
          }
        ],
        type: 'AdaptiveCard',
        version: '1.0'
      });
      const responseActivity = { type: 'message', attachments: [adaptiveCard], channelData: {
          onBehalfOf: [
              { itemId: 0, mentionType: 'person', mri: context.activity.from.id, displayname: context.activity.from.name }
          ]
      }};

      await context.sendActivity(responseActivity);
    }
}

次の json のような新しい composeExtensions/submitAction メッセージが表示されます。

{
  "name": "composeExtension/submitAction",
  "type": "invoke",
  "conversation": { "id": "19:c366b75791784100b6e8b515fd55b063@thread.skype" },
  "imdisplayname": "Pranav Smith",
  ...
  "value": {
    "botMessagePreviewAction": "send",
    "botActivityPreview": [
      {
        "type": "message/card",
        "attachments": [
          {
            "content":
              {
                "type": "AdaptiveCard",
                "body": [{<<card payload>>}]
              },
            "contentType" : "application/vnd.microsoft.card.adaptive"
          }
        ],
        "context": { "theme": "default" }
      }
    ],
  }
}

ボットメッセージのユーザー属性

ボットがユーザーに代わってメッセージを送信するシナリオでは、メッセージをそのユーザーに帰属させることでエンゲージメントを高め、より自然な対話フローを示すのに役立ちます。この機能を使用すると、ボットから送信されたメッセージを、送信先のユーザーに属性付けできます。

次の画像では、画像の左側は、ユーザー属性を持たないボットによって送信されたカードメッセージであり、画像の右側は、ユーザー属性を持つボットによって送信されるカードです。

ユーザー属性ボット

チームでユーザー属性を使用するには、Teams に送信される Activity ペイロードで ChannelData に OnBehalfOf メンションエンティティを追加する必要があります。

C#/.NET
JSON

    OnBehalfOf = new []
    {
      new
      {
        ItemId = 0,
        MentionType = "person",
        Mri = turnContext.Activity.From.Id,
        DisplayName = turnContext.Activity.From.Name
      }  
    }

{
    "text": "Hello World!",
    "ChannelData": {
        "OnBehalfOf": [{
            "itemid": 0,
            "mentionType": "person",
            "mri": "29:orgid:89e6508d-6c0f-4ffe-9f6a-b58416d965ae",
            "displayName": "Sowrabh N R S"
        }]
    }
}

エンティティスキーマの `OnBehalfOf` 詳細

次のセクションは、OnBehalfOf 配列内のエンティティの説明です。

フィールド	種類	説明
`itemId`	整数	アイテムの識別について説明します。その値は `0` にする必要があります。
`mentionType`	String	"ユーザー" のメンションについて説明します。
`mri`	String	メッセージが送信されたユーザーのメッセージリソース識別子 (MRI)。メッセージの送信者名は、"ボット名>を使用した<ユーザー>"< として表示されます。
`displayName`	String	ユーザーの名前。ケース名の解決が利用できない場合にフォールバックとして使用されます。

コードサンプル

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

次のステップ

検索コマンドを定義する

タスクモジュールの送信アクションに応答する

submitAction 呼び出しイベント

メッセージ作成領域にカードを挿入して応答する

別のタスクモジュールで応答する

アダプティブカードを使用したボットの応答

最初の送信アクションに応答する

botMessagePreview によるイベントの送信と編集

botMessagePreview の編集に応答する

botMessagePreview 送信に応答する

ボットメッセージのユーザー属性

エンティティスキーマの `OnBehalfOf` 詳細

コードサンプル

次のステップ

関連項目

その他のリソース

その他のリソース

タスク モジュールの送信アクションに応答する

submitAction 呼び出しイベント

メッセージ作成領域にカードを挿入して応答する

別のタスク モジュールで応答する

アダプティブ カードを使用したボットの応答

最初の送信アクションに応答する

botMessagePreview によるイベントの送信と編集

botMessagePreview の編集に応答する

botMessagePreview 送信に応答する

ボット メッセージのユーザー属性

エンティティ スキーマの OnBehalfOf 詳細

コード サンプル

次のステップ

関連項目

その他のリソース

その他のリソース

タスクモジュールの送信アクションに応答する

別のタスクモジュールで応答する

アダプティブカードを使用したボットの応答

ボットメッセージのユーザー属性

エンティティスキーマの `OnBehalfOf` 詳細

コードサンプル