Teams のワークフローボット

[アーティクル]
04/04/2023

ワークフローボットを使用すると、ユーザーはアダプティブカードと対話できます。アダプティブカードアクションハンドラーを使用すると、アダプティブカードが Teams アプリで会話できるようになります。インシデント管理、チケット発行、承認ワークフロー、プロジェクト管理カードなどのユーザーエクスペリエンスを強化するために、ユーザーが複数のシナリオでワークフローボットを作成できます。ワークフローボットを使用して作業項目を作成して割り当て、コンテンツを Azure DevOps または Jira システムに同期できます。

ワークフローボットは、さまざまなスコープに応じて、チーム、グループチャット、または個人用アプリにインストールできます。既定のコマンドロジックはアダプティブカードを返します。このロジックは、ビジネス要件を使用してカスタマイズできます。カスタマイズするには、既存の API を呼び出す必要があります。

利点:

会話のコンテキストを離れることなく、ビジネスプロセスと反復的なワークフローを自動化します。
追加のカードを送信することなく、さまざまなカードを介して順次ワークフローを使用するユーザーをサポートします。
ユーザー固有の最新のビューを提供します。
TeamsFx SDK を使用してプログラミングモデルを簡略化します。

注:

アプリを追加するときに、インストールする機能を選択できます。詳細については、「既定のインストールオプションを構成する」を参照してください。

ユーザーによってトリガーされるアダプティブカードに応答するワークフローボットを作成できます。 TeamsFx SDK を利用するアダプティブカードアクションハンドラーは、ユーザーによってトリガーされるアダプティブカードユニバーサルアクション Action.Execute を実行できます。スレッド内のこの各カードアクションに応答して、アダプティブカードアクションハンドラーは別のアダプティブカードを送信します。

カードアクションハンドラー

ワークフローボットの作成を簡略化するために、TeamsFx SDK にはアダプティブカードアクションハンドラーが用意されています TeamsFxAdaptiveCardActionHandler。 Bot Framework を学習せずに、ワークフローボットの開発にのみ焦点を当ててカードアクションに応答できます。

次の図は、TeamsFx SDK を使用してアダプティブカードアクションに応答する方法を示しています。

アクションカード: ユーザーが呼び出DoStuffすことができるアクションを定義するカード。
カードアクションハンドラー: ユーザーが対応するカードアクションを呼び出したときにトリガーされます。これはtriggerVerbアダプティブカードアクションのverbプロパティと同じです。応答カードを送信してアクションに応答できます。
応答カード: ユーザーがアクションカードからアクションを呼び出したときにアクションに応答するカード。

TeamsFx SDK でカードアクションを処理するには、各カードアクションハンドラーでインターフェイスを実装するTeamsFxAdaptiveCardActionHandler必要があります。

-
TeamsFxAdaptiveCardActionHandler 
{
    /**
     * The verb defined in adaptive card action that can trigger this handler.
     */
    triggerVerb: string;

    /**
     * Specify the behavior for how the card response will be sent in Teams conversation.
     * The default value is `AdaptiveCardResponse.ReplaceForInteractor`, which means the card
     * response will replace the current one only for the interactor.
     */
    adaptiveCardResponse?: AdaptiveCardResponse;
    
    /**
     * The handler function that will be invoked when the action is fired.
     * @param context The turn context.
     * @param actionData The contextual data that associated with the action.
     */
    handleActionInvoked(context: TurnContext, actionData: any): Promise<InvokeResponse>;
}

初期化をカスタマイズする

ワークフローボットは、独自のアダプターで初期化することも、初期化後にカスタマイズすることもできます。既定の初期化はにあります bot/src/internal/initialize.js(ts)。

初期化ロジックは、次に更新できます。

独自BotFrameworkAdapterのを使用するように設定options.adapterします。
複数のコマンドハンドラーを含むように設定 options.command.commands します。
複数のアクションハンドラーを含むように設定 options.cardAction.actions します。
複数ConversationBotの機能を有効にするように設定options.{feature}.enabledします。

初期化のカスタマイズの詳細については、「その他の初期化カスタマイズ」を参照してください。

カードアクションを追加する

JavaScript と TypeScript でカードアクションを追加するには、次の手順に従います。

1. アダプティブカードにアクションを追加する

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

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

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

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

注:

他のボットと競合する可能性がある一般的な文字列を使用している場合は、動詞プロパティにグローバル一意の文字列を指定してください。これにより、予期しない動作を回避できます。

2. 新しいアダプティブカードで対応する

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

{
  "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"
}

注:

ビジネスニーズに応じてカードレイアウトを設計できます。アダプティブカードデザイナーに関するページを参照してください。

3. アクションハンドラーを追加する

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

JavaScript
TypeScript

新しいファイル bot/src/cardActions/doSomethingActionHandler.jsを作成できます。

    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,
    }

新しいファイル bot/src/cardActions/doSomethingActionHandler.tsを作成できます。

    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);
        } 
    }

注:

triggerVerb は、アクションの verb プロパティです。
actionData はアクションに関連付けられたデータであり、動的ユーザー入力や、アクションの data プロパティで提供されるコンテキストデータが含まれる場合があります。
アダプティブカードが返された場合、既存のカードは既定でそれに置き換えられます。

4. アクションハンドラーを登録する

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

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

ファイル bot/src/internal/initialize.js(ts)を開くことができます。
機能を有効にするにはcardAction、初期化を更新する必要がありますconversationBot。次のコードを actions 使用して、ハンドラーを配列に追加します。
```
      const conversationBot = new ConversationBot({ 
     ... 
     cardAction: { 
       enabled: true, 
       actions: [ 
         new DoStuffActionHandler(),
         new DoSomethingActionHandler() 
       ], 
     } 
   });
```
注:

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

アクション応答をカスタマイズする

ハンドラーのプロパティを adaptiveCardResponse 使用して、ボットがアダプティブカードをユーザーに送信する方法をカスタマイズできます。カスタマイズする 3 つのオプションを次に示します。

応答カードは、現在のカードに置き換えられます。ここで、アクションをトリガーする対話機能のボタンが定義されています。会話のユーザーは、既定で元のアクションカードAdaptiveCardResponse.ReplaceForInteractorを表示できます。
応答カードは、チャット内のすべてのユーザーのアクションカードに置き換えられ、応答をカードAdaptiveCardResponse.ReplaceForAll表示できます。
応答カードは、アクションカードを置き換えることができない別のメッセージとして会話に送信されます。チャット内のすべてのユーザーは、カードAdaptiveCardResponse.NewForAll応答を表示できます。

テキストメッセージで応答する

また、アクションの応答にアダプティブカードを使用するのではなく、テキストメッセージで応答InvokeResponseFactory.textMessageカードできます。

async handleActionInvoked(context: TurnContext, actionData: any): Promise<InvokeResponse> {
    return InvokeResponseFactory.textMessage("This is a sample card action response!");
}

Teams では、次の応答メッセージが表示されます。

スクリーンショットは、応答カードサンプルを示しています。

エラーメッセージで応答する

エラー応答メッセージをクライアントに返す場合は、を適用 InvokeResponseFactory.errorResponse して、呼び出し応答を作成できます。次の図は、アダプティブカードのエラーメッセージを示しています。

エラー応答メッセージを示すスクリーンショット。

注:

呼び出し応答形式の詳細については、「応答形式」を参照してください。

アダプティブカードのコンテンツをカスタマイズする

ファイル src/adaptiveCards/helloworldCommand.json を編集して、アダプティブカードを好みに合わせてカスタマイズできます。このファイル src/cardModels.ts は、アダプティブカードのデータを入力するために使用されるデータ構造を定義します。

モデルとアダプティブカードの間のバインドは、アダプティブカード内のに${title}マップされるなど、CardData.title名前の一致によって行われます。プロパティとそのバインドを追加、編集、または削除して、ニーズに合わせてアダプティブカードをカスタマイズできます。

アプリケーションに必要な場合は、新しいカードを追加することもできます。と FactSetを使用して動的コンテンツのリストまたはテーブルを使用してさまざまな種類のアダプティブカードをColumnSet構築するには、「TeamsFx-Samples」を参照してください。

ユーザー固有のビューへの自動更新

アダプティブカードが Teams チャネルまたはグループチャットで送信されると、すべてのユーザーが同じカードコンテンツを表示できます。アダプティブカードユニバーサルアクションの新しい更新モデルを使用すると、ユーザーはユーザー固有のビューを使用できます。自動更新により、承認、投票作成者コントロール、チケット作成、インシデント管理、プロジェクト管理カードなどのシナリオも容易になります。次の図は、モデルでユーザー固有のビューを提供する方法を refresh 示しています。

図は、ユーザー固有の自動更新モデルを示しています。

基本カード: ボットは、カードの基本バージョンを含むメッセージを送信します。この基本カードは、ボット通知、コマンド応答、またはその他のカードアクション応答として送信できます。会話のすべてのメンバーは、同じ応答を表示できます。ベースカードは、ベースカードのプロパティでrefresh定義userIdされているユーザーに自動的に更新されます。
更新動作: ユーザーがメッセージを表示すると、Teams クライアントは最後の更新応答の 1 分後に自動的に更新をトリガーします。ユーザー固有のビューハンドラーが呼び出され、特定のユーザーUserAのカードビューResponse Cardが返されます。会話内の他のユーザーは引き続きベースカードを表示できます。

次の図は、Teams でのユーザー固有のビューの表示方法を示しています。

ユーザー固有のビューを追加する

次の手順は、TeamsFx SDK を使用してユーザー固有のビューを追加するのに役立ちます。

1. 基本アダプティブカードで更新を有効にする

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

最初のオプションでは、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": [
    ...
  ],
  ...
}
```
カードコンテンツをレンダリングしながら、コード内のユーザー MRI に置き換える${userID}必要があります。

2. ユーザー固有のアダプティブカードを追加する

更新動作を図に示すなどresponseCard.jsonuserA、特定の応答カードを更新するには、ユーザー固有のアダプティブカードを設計する必要があります。開始するには、次のコンテンツを含むを 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"
}

3. カードアクションハンドラーを追加してビューを更新する

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);
    } 
}

4. アクションハンドラーを登録する

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

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

Microsoft Graph にアクセスする

既にサインインしている Teams ユーザーの Microsoft Graph データにアクセスする必要があるコマンドに応答する場合は、Teams ユーザートークンを使用してシングルサインオン (SSO) することで応答できます。 Teams ツールキットを使用して Teams アプリにシングルサインオンを追加する方法について詳しくは、こちらをご覧ください。

既存の API に接続する

Teams に送信するデータを取得するには、多くの場合、既存の API に接続する必要があります。 Teams Toolkit を使用すると、既存の API の認証を簡単に構成および管理できます。詳細については、既存のサードパーティ API を統合する方法に関するページを参照してください。

よく寄せられる質問

通知を使用してワークフローボットを拡張する方法

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

コマンドと応答を使用してワークフローボットを拡張する方法

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

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

Teams ワークフローボットを構築するには、ステップバイステップガイドに従います。

Teams のワークフローボット

カードアクションハンドラー

初期化をカスタマイズする

カードアクションを追加する

アクション応答をカスタマイズする

テキストメッセージで応答する

エラーメッセージで応答する

アダプティブカードのコンテンツをカスタマイズする

ユーザー固有のビューへの自動更新

ユーザー固有のビューを追加する

Microsoft Graph にアクセスする

既存の API に接続する

よく寄せられる質問

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

関連項目

フィードバック

その他のリソース

Teams のワークフロー ボット

カード アクション ハンドラー

初期化をカスタマイズする

カードアクションを追加する

アクション応答をカスタマイズする

テキスト メッセージで応答する

エラー メッセージで応答する

アダプティブ カードのコンテンツをカスタマイズする

ユーザー固有のビューへの自動更新

ユーザー固有のビューを追加する

Microsoft Graph にアクセスする

既存の API に接続する

よく寄せられる質問

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

関連項目

フィードバック

その他のリソース

Teams のワークフローボット

カードアクションハンドラー

テキストメッセージで応答する

エラーメッセージで応答する

アダプティブカードのコンテンツをカスタマイズする

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