Teams のワークフロー ボット

新しいアクション (ボタン) をアダプティブ カードに追加するには、JSON ファイルで定義します (src/adaptiveCards/helloworldCommandResponse.json ファイルに新しいDoSomethingアクションを追加するなど)。

次のコードは、アクションの種類 Action.Executeの例です。

{ 
  "type": "AdaptiveCard", 
  "body": [
    ...
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "DoSomething",
          "verb": "doSomething" 
        }
      ]
    },
    ...
  ]
}

Teams でアクションが呼び出されると、TeamsFx 会話 SDK が対応するアクション ハンドラーを呼び出すことができるように、verb プロパティが必要です。

呼び出されたアクションごとに新しいアダプティブ カードを返して、エンド ユーザーに応答を表示できます。 次の内容を含むdoSomethingアクションの応答としてbot/src/adaptiveCards/doSomethingResponse.json、新しいファイルを作成する必要があります。

{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "weight": "Bolder",
      "text": "A sample response to DoSomething."
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.4"
}

アダプティブ カードによって呼び出された新しいアクションは、TeamsFx SDK のクラス TeamsFxAdaptiveCardActionHandlerで処理できます。 この手順では、API の呼び出し、データの処理、ビジネスニーズに応じてその他のアクションをカスタマイズする必要があります。

    const { AdaptiveCards } = require("@microsoft/adaptivecards-tools");
    const { AdaptiveCardResponse, InvokeResponseFactory } = require("@microsoft/teamsfx");
    const responseCard = require("../adaptiveCards/doSomethingResponse.json");

    class DoSomethingActionHandler { 
    triggerVerb = "doStuff";

        async handleActionInvoked(context, message) { 
            const responseCardJson = AdaptiveCards.declare(responseCard).render(actionData);
            return InvokeResponseFactory.adaptiveCard(responseCardJson);
        }
    }

     module.exports = {

       DoSomethingActionHandler,
    }

    const { AdaptiveCards } = require("@microsoft/adaptivecards-tools");
    const { AdaptiveCardResponse, InvokeResponseFactory } = require("@microsoft/teamsfx");
    const responseCard = require("../adaptiveCards/doSomethingResponse.json");

    export class DoSomethingActionHandler {
        triggerVerb = "doSomething";

        async handleActionInvoked(context, message) { 
            const responseCardJson = AdaptiveCards.declare(responseCard).render(actionData);
            return InvokeResponseFactory.adaptiveCard(responseCardJson);
        } 
    }

ワークフロー ボット テンプレートの会話フローを有効にする、 conversationBot で各新しいカード アクションを構成する必要があります。 bot/src/internal/initialize.js(ts) ファイルに移動し、cardAction プロパティのactions配列を更新できます。

次の手順は、アクション ハンドラーを登録するのに役立ちます。

1. ファイル bot/src/internal/initialize.js(ts)を開くことができます。

2. cardAction機能を有効にするには、conversationBotの初期化を更新する必要があります。 次のコードを使用して、ハンドラー actions 配列に追加します。

         const conversationBot = new ConversationBot({ 
        ... 
        cardAction: { 
          enabled: true, 
          actions: [ 
            new DoStuffActionHandler(),
            new DoSomethingActionHandler() 
          ], 
        } 
      });
   

   注:

   ワークフロー ボット テンプレートの拡張の詳細については、「Teams でのカード アクションへの応答」を参照してください。

ユーザー固有のビューの自動更新に示すように、応答カードがベース カードから更新されると、 ユーザー固有のビューはベース カードから更新されます。 ベース カードで自動更新を有効にするには、次のようにします。

• 最初のオプションでは、SDK を使用してユーザー固有のビューの更新を有効にします。 基本カードは、コマンド応答またはカード アクション応答として送信できます。 ユーザー固有のビュー更新は、コマンド ハンドラーの handleCommandReceived 、または基本カードが返されるカード アクション ハンドラーの handleActionInvoked で有効にすることができます。 @microsoft/adaptivecards-tools ライブラリの refresh(refreshVerb, userIds, data) メソッドを使用して、ベース カードに更新セクションを挿入できます。 更新セクションを定義するには、次のプロパティを指定してください。

  1. userIds: 自動更新をトリガーできるユーザーの MRI のセット。 アダプティブ カードの更新セクション userIds リストに追加する方法の詳細については、「 名簿またはユーザー プロファイルをフェッチする」を参照してください。
  2. verb: 更新アクションを識別する文字列。
  3. data: 更新アクションに関連付ける省略可能なデータ。

  次の例では、基本カードがコマンド応答として返され、コマンド送信者など、特定のユーザーに対して自動更新できます。

           import baseCard from "../adaptiveCards/baseCard.json";
           import { AdaptiveCards } from "@microsoft/adaptivecards-tools";
  
           export class MyCommandHandler1 implements TeamsFxBotCommandHandler {
           triggerPatterns: TriggerPatterns = "helloWorld";
  
           async handleCommandReceived(context: TurnContext, message: CommandMessage): 
           Promise<string | Partial<Activity> | void> {
           const refreshVerb = "userViewRefresh";        // verb to identify the refresh action
           const userIds = [ context.activity.from.id ]; // users who will be refreshed
           const data = { key: "value"};                 // optional data associated with the action
  
           const responseCard = AdaptiveCards
             .declare(baseCard)
             .refresh(refreshVerb, userIds, data)
             .render(cardData);
  
               return MessageFactory.attachment(CardFactory.adaptiveCard(responseCard));
           }
         }
  

• 2 番目のオプションを使用すると、ユーザー固有のビューでアダプティブ カードを更新できます。 これは、 baseCard.jsonで定義されているサンプル更新アクションです。

  {
    "type": "AdaptiveCard",
    "refresh": {
      "action": {
        "type": "Action.Execute",
        "title": "Refresh",
        "verb": "userViewRefresh" ,
        "data": {
          "key": "value"
        }
      },
      "userIds": [
        "${userID}"
      ]
    },
    "body": [
      ...
    ],
    ...
  }
  
  

  カードコンテンツをレンダリングしながら、 ${userID} をコード内のユーザーMRIに置き換える必要があります。

更新動作の図に示されているuserAのresponseCard.jsonなど、特定の応答カードを更新するには、ユーザー固有のアダプティブ カードを設計する必要があります。 開始するには、次のコンテンツを含む responseCard.json を作成し、 bot/src/adaptiveCards フォルダーに保存します。

-
{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "weight": "Bolder",
      "text": "This is a user-specific view"
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.4"
}

Teams で自動的にトリガーされる更新呼び出しアクティビティを処理する TeamsFxAdaptiveCardActionHandler を実装するハンドラーを追加できます。

import responseCard from "../adaptiveCards/responseCard.json";

export class Handler1 implements TeamsFxBotCardActionHandler {
    triggerVerb: string = "userViewRefresh";

    async handleActionInvoked(context: TurnContext, actionData: any): Promise<InvokeResponse> {
      /**
       * If you have multiple userIds defined in your refresh action, for example: userIds: [ "<UserA>", "<userB>" ] ,
       * and you can return different card response for those users respectively with the following code sample.
        
        const currentUserId = context.activity.from.id;
        switch (currentUserId) {
          case "<userA's id>":
            const card1 = AdaptiveCards.declare(card1).render(actionData);
            return InvokeResponseFactory.adaptiveCard(card1);
          case "<userB's id>":
            const card1 = AdaptiveCards.declare(card2).render(actionData);
            return InvokeResponseFactory.adaptiveCard(card2);
        }
     */
      const responseCardJson = AdaptiveCards.declare(responseCard).render(actionData);
      return InvokeResponseFactory.adaptiveCard(responseCardJson);
    } 
}

更新アクション ハンドラーを bot/src/internal/initialize.js(ts) に登録するには、次のコードを使用します。

export const commandBot = new ConversationBot({
  ...
  cardAction: {
    enabled: true,
    actions: [
      new Handler1()
    ],
  }
})

通知は、アプリで外部イベントに応答してアダプティブ カードを送信する機能を追加します。 たとえば、メッセージが Event Hub に投稿されると、アプリは必要に応じてアダプティブ カードで応答できます。 通知を使用してワークフロー ボットを拡張する方法については、「 通知のカスタマイズ」を参照してください。

既定のワークフロー ボットには、コマンドと応答が付属しています。 コマンドと応答を使用してワークフロー ボットを拡張する方法の詳細については、「 コマンドと応答の追加」を参照してください。