みなさんこんにちは〜。この記事は、Microsoft Teams 開発の初心者向けガイド第３弾になります。前回の2つのチュートリアル ( タブの開発と Bot 開発）も楽しんでもらえていたらうれしいです。

今回は、Teams UI からのユーザからのアクションで検索結果やメッセージを書き出す方法について説明します。

Teams アプリの作成にはいくつもの方法やツールがあるのですが、このチュートリアルでは、コンセプトを学んでもらうことを重視したいので、最低限のコードと最小限のツールセットを使用しています。また、マイクロソフト Azure から環境をセットアップすることもできますが、今回はそのプロセスを使わず、気軽に学んでもらえるようにブラウザ上でコードを実行していきます。

このチュートリアルでは、メッセージング・エクステンション (Messaging Extensions / メッセージング拡張機能)という機能をつかった開発について紹介します。

メッセージング拡張機能には、アクションと検索という 2 種類があるのですが、今回は「アクション・コマンド」（操作コマンド）について紹介します。

チームの機能: 「アクション・コマンド」

アクション・コマンドを使用すると、情報を収集または表示するためのモーダルポップアップをユーザーに表示できます。フォームを送信すると、アプリ、つまり Web サービスは、メッセージを会話に直接挿入したり、メッセージ作成ボックスに挿入してユーザーの選択でグループにメッセージを送信できるようにしたりできます。

メッセージ・アクションをつかって、メッセージ内容をモールスコードに変換するサービスを作る！

いまから作成していくアプリは、ユーザーが選んだ任意のメッセージに含まれるテキストを抽出してモールスコードに変換する、というものです。

アプリの動作は次のとおりです。

ユーザーがメッセージをマウスオーバーしてメッセージメニューを開き、「そのほかの操作」(More actions) メニューからモールス bot を選択
ユーザーからの操作がトリガーされると、ペイロードがメッセージングエンドポイントに送信。 (/api/messages)
fetchTask の呼び出し。ここでメッセージテキストデータが抽出されます。
ポップアップダイアログが表示されます。ユーザーは必要に応じてテキストコンテンツを編集し、送信
アプリは、テキストをモールスコードに変換し、コンテンツを返信として表示
ユーザーは結果をクライアントに新規メッセージとして送信

結果は次のようになります。

📓 必須科目

Teams にアプリをインストールできるようにするには、組織の管理者がアクセス許可を付与する必要があります。
それ以外の場合は、無料のMicrosoft 365 開発者プログラム に登録しましょう。このプログラムでは、開発者テナントのサンドボックス、サンプルデータパックに付属しているモックユーザーデータなどが使え、サブスクリプションはなどでもリニューアルできます。

開発の許可がある Teams テナント、または開発専用テナント (M365 開発者プログラムにサインアップしよう)
App Studio - チームクライアントのアプリメニューからアプリを探し、テナントのワークスペースにインストールしてね
JavaScript の基礎知識

👾 このチュートリアルで使用する技術

Node.js
Microsoft Bot Framework
Adaptive Cards for building some UI snippets

アクションの構築

🎏 コードサンプルの取得

このチュートリアルシリーズでは、プロジェクトのコードのホスティングと実行を簡略化するために、サードパーティのツール、Glitchを使用しています。

Glitch は、node.jsコードを記述して実行できるWebベースのIDEなので、少なくとも今のところ、localhostのトンネル、デプロイを気にすることなく、Teamsアプリ開発の概念と基本を学ぶことに集中できます。

まず、この Glitch プロジェクトの remix ができるリンク、または下のボタンをクリックしてください。リミックスとは GitHub で言うところのリポジトのをフォークのようなようなもので、自分用のプロジェクトのコピーが生成されるため、元のコードに影響なく自分用に好きなように変更できます。

さて、自分専用プロジェクトのリポを取得すると、自動的に独自のWebサーバーURLを取得します。たとえば、生成されたプロジェクトは、３単語ほどでできたランダムな語で構成されています。たとえばそのプロジェクト名が achieved-diligent-bell だったら、ウェブサーバーのURLは https://achieved-diligent-bell.glitch.me になります。必要に応じて名前をカスタマイズすることもできます。

⚙️ App Configuration: App Studioを使ってアプリマニフェストを作成

Teams アプリパッケージの基本については前のチュートリアルを参照してください。

🎛 App Studio を使う

App Studio 上部の Manifest Editor（マニフェストエディター）タブをクリックし、Create a new app（新しいアプリの作成]）を選択します。必要事項を入力してください。

そして App ID を生成してください。

🔖 メッセージ・エクステンションの設定

左側のメニューから、 Capabilities > Massaging Extensions を選択

先に進み、設定するボタンをクリック。

名前を付けます。

🔐 App credentials

ボット名の横にある ID ('2cd53e8a-e698-4exx-...' のように見える) をコピーし、隠しファイルである.envファイルに環境変数として貼り付けます ('.env-sample' の名前を '.env' に変更します)。

App Passwordsの下で新規パスワードを生成し、それをコピーし、これも .envファイルに貼り付けます。

これらの情報は、bot アダプターを初期化するために使用されます。(index.js を参照してください。

(上記の画面画像のステップ3は、このすぐ後に説明します。)

🎬 アクションの設定

Messaging Endpoint で、サーバーを入力します。今回は、Glitch サーバ上でコードを動かしているので、 https://[your project].glitch.me/api/messages のように自分のプロジェクト名が入った URL がサーバとなります。

Command までスクロールし [Add] をクリック

ダイアログボックスで
1. Allow users to trigger actions in external service... を選択
2. Fetch a dynamic set of parameters from your bot を選択
3. command ID と title text を入力。 Massage チェックボックスを選択 (他のチェックボックスが事前に選択されている場合は、そのチェックボックスをオフにします。) 残りは空白のままにして保存します。

📦 App manifest パッケージをインストール

Finish > Test and distribute へ行きます。

エラーが発生した場合は、それを修正してください、そうでなければ、Install をクリックしてください。

また、'manifest.json' を含む zip ファイルと、後でインストールまたは配布する 2 つのアイコンイメージをダウンロードすることもできます。

コードサンプルをそのままリミックスしている限り、この bot は既に動作するはずでが、試してみる前に、これがどのようにコーディングされているかを簡単に説明してみます。

🤖 Microsoft Bot Framework

マイクロソフトボットフレームワークは、インテリジェントなエンタープライズグレードのボットを構築できるオープンソースSDKです。

この SDK は、Teams だけでなく、Web やモバイルチャット、Skype、Facebook、Amazon Alexa、Slack、Twilio など、幅広い種類のチャットボットで動作するように設計された強力なプラットフォームです。

🔧 Initiating the bot service

まず、Glitch コードサンプル Repo に 2 つの JS ファイルがあります。 index.js and bots.js です。

ここでは、Express を使用して HTTP サーバーを設定し、HTTP リクエストをルーティングしています。サービスを開始する方法は、前の Bots チュートリアルと同じですが、これは初期化とボットアダプタの作成について、もう一度要約したコードが下のようになります。

// Import bot services
const { BotFrameworkAdapter } = require('botbuilder');

// Bot's main dialog
const { ReverseBot } = require('./bot');

// App credentials from .env
const adapter = new BotFrameworkAdapter({
  appId: process.env.MicrosoftAppId,
  appPassword: process.env.MicrosoftAppPassword
});

// Create the main dialog
const myBot = new MorseBot();

注:この例では、私はボットビルダーのバージョン4.10.0を使用しています。コードが期待どおりに動作しない場合は、使用しているバージョンを確認してください!

🦉 Bot ロジックへの要求の転送

Express を使用して、着信リクエストをリッスンするルーティングを処理します。

app.post('/api/messages', (req, res) => {
  adapter.processActivity(req, res, async context => {
    await myBot.run(context);
  });
});

前の手順で、 App Studio で URL を設定しました。/api/messages は、クライアント要求に応答するアプリケーションのエンドポイント URL です。

🙋‍♀️ リクエストの処理

エンドポイントで要求を受信し、ボットロジックに転送すると、アプリは要求のコンテクストを受け取り、bots.js でカスタム応答を作成します。

要求に対する適切なハンドラーを作成するために拡張された TeamsActivityHandler を参照してください。

class ReverseBot extends TeamsActivityHandler {

  // ユーザからのアクションによってトリガー
  handleTeamsMessagingExtensionFetchTask(context, action) {
    /*
         ここで表示するダイアログのコンテンツを adaptive card UI (modal dialog)を作成。
         ユーザがダイアログを確認して送信。
    */
  }

// FetchTask からユーザによって送信されたらトリガー
  handleTeamsMessagingExtensionSubmitAction(context, action) {
    // display the result 
  }

TeamsActivityHandler は、メッセージイベント (*例えば onMembersAdded メソッドが会話にメンバーが追加されるたびに呼び出される) などのメッセージを処理し、返信を送信するチーム固有のクラスです。

ここでは、ユーザがメッセージに対しアクションを起こすと、handleTeamsMessagingExtensionFetchTask がトリガーされ、ボットが元のメッセージに関する情報を受け取ります。

これらについてはドキュメント「タスクモジュールを作成して送信する」でもっと詳しく学ぶことができます。

📇 アダプティブカードを使用したモーダルダイアログの表示

ダイアログ UI は、 Microsoft のオープンソースである　アダプティブカードを使って JSON で UI を構築することができます。アダプティブカードは、Teams の他、Outlook のアクション可能なメッセージ、Cortana スキルなどさまざまな Microsoft ファミリーのサービスの開発で使うことができます。

handleTeamsMessagingExtensionFetchTask が呼び出されると、メッセージコンテンツテキストを取得し、応答としてダイアログとしてアダプティブカードに表示します。

アダプティブカードとコンテンツを定義するには:

const card = {
  type: 'AdaptiveCard',
  version: '1.0'
};

card.body = [
        { type: 'TextBlock', text: 'The message to be encoded to Morse code:', weight: 'bolder'},
        { id: 'editedMessage', type: 'Input.Text', value: content },
      ];
      card.actions = [{
        data: { submitLocation: 'messagingExtensionFetchTask'},
        title: 'Encode to Morse!',
        type: 'Action.Submit'
      }];

const adaptiveCard = CardFactory.adaptiveCard(card);

return {
      task: {
        type: 'continue',
        value: {
          card: adaptiveCard
        }
      }
    };

抽出されたメッセージテキストを type: 'Input.Text' で表示し、ユーザーがモールスコード化するテキストを編集できるようにします。

完全なコードを表示するには、グリッチのコードサンプルの bot.js ファイルを参照してください。

📮 ユーザーの送信を処理する

ユーザーがタスクモジュールを送信すると、handleTeamsMessagingExtensionSubmitAction がトリガーされ、Web サービスはコマンド ID とパラメーター値が設定されたオブジェクトを受け取ります。

このサンプルコードでは、カスタムデータ editedMessage が存在するかどうかだけを確認します。その場合は、値（ここでは文字列) を取得し、それをモールスに変換して、新しいメッセージとして作成するコンテンツを表示します。

async handleTeamsMessagingExtensionSubmitAction(context, action) {

    if(action.data.editedMessage) {
      const text = action.data.editedMessage;
      const morseText = await encodeToMorse(text);

  return {
    composeExtension: {
    type: 'result',
      attachmentLayout: 'list',
      attachments: [
        // the message UI component here
      ]
    }
  }

}

bots.js に示されているコードサンプルでは、結果メッセージを作成するために Bot Framework に付属のサムネイルカードと呼ばれるシンプルなUI カードを使用していますが、もちろん前述のアダプティブカードも使用できます。

🤖💬 メッセージアクションを試してみる

それでは、アクションを試してみましょう!
Teams クライアントに移動し、リッチフォーマットや画像ではない、シンプルテキストで構成されたメッセージのいずれかをクリックしてみてください。

すべてが期待どおりに動作する場合は、任意のテキストメッセージをモールスコードに変換できるはずです。

🎉

チュートリアルを楽しんでいただけましたか？モールス・コードへの変換は正直、あまり普段役に立つものではないでしょうけれど、みなさんはもっと良いユースケースを見つけて素晴らしいアプリを作成することを願っています!

次のチュートリアルでは、検索コマンドである別の種類のメッセージング拡張機能を構築する方法について説明します。次回お会いしましょう 👋

🇺🇸 この記事を英語で読みたいという方は dev.to のリンクからどうぞ！

📚 Learn more

MS Teams Documentation - メッセージング・エクステンション
Microsoft Bot Frameworks
Bot Services Documentation - How bot works?
アダプティブカード
[完全無料で] Microsoft Teams で動くオレオレ bot を 1 時間で作る - Azure からボットを作っていきます
Microsoft @ Qiita