💬 Microsoft Teams 開発の初心者向けガイド その3: メッセージ・エクステンション

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

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

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

---

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

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

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

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

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

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

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

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

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

📓 必須科目

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