みなさんこんにちは〜。この記事は、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] をクリック
ダイアログ ボックスで
- Allow users to trigger actions in external service... を選択
- Fetch a dynamic set of parameters from your bot を選択
-
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