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

今回は、Teams UI からのユーザからのアクションで検索結果やメッセージを書き出す方法について説明します。
Image may be NSFW.
Clik here to view.
Teams アプリの作成にはいくつもの方法やツールがあるのですが、このチュートリアルでは、コンセプトを学んでもらうことを重視したいので、最低限のコードと最小限のツールセットを使用しています。また、マイクロソフト Azure から環境をセットアップすることもできますが、今回はそのプロセスを使わず、気軽に学んでもらえるようにブラウザ上でコードを実行していきます。

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

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

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

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

Image may be NSFW.
Clik here to view.

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

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

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

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

結果は次のようになります。
Image may be NSFW.
Clik here to view.

📓 必須科目

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 で言うところのリポジトのをフォークのようなようなもので、自分用のプロジェクトのコピーが生成されるため、元のコードに影響なく自分用に好きなように変更できます。
Image may be NSFW.
Clik here to view.
さて、自分専用プロジェクトのリポを取得すると、自動的に独自の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 を生成してください。
Image may be NSFW.
Clik here to view.

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

左側のメニューから、 Capabilities > Massaging Extensionsを選択
Image may be NSFW.
Clik here to view.
先に進み、設定するボタンをクリック。
Image may be NSFW.
Clik here to view.
名前を付けます。

🔐 App credentials

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

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

これらの情報は、bot アダプターを初期化するために使用されます。(index.js を参照してください。
Image may be NSFW.
Clik here to view.
(上記の画面画像のステップ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チェックボックスを選択 (他のチェックボックスが事前に選択されている場合は、そのチェックボックスをオフにします。) 残りは空白のままにして保存します。
Image may be NSFW.
Clik here to view.
Image may be NSFW.
Clik here to view.
Image may be NSFW.
Clik here to view.

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

Finish > Test and distributeへ行きます。

エラーが発生した場合は、それを修正してください、そうでなければ、Installをクリックしてください。
Image may be NSFW.
Clik here to view.
また、'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 servicesconst{BotFrameworkAdapter}=require('botbuilder');// Bot's main dialogconst{ReverseBot}=require('./bot');// App credentials from .envconstadapter=newBotFrameworkAdapter({appId:process.env.MicrosoftAppId,appPassword:process.env.MicrosoftAppPassword});// Create the main dialogconstmyBot=newMorseBot();

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

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

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

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

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

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

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

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

classReverseBotextendsTeamsActivityHandler{// ユーザからのアクションによってトリガー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が呼び出されると、メッセージコンテンツテキストを取得し、応答としてダイアログとしてアダプティブカードに表示します。
Image may be NSFW.
Clik here to view.

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

constcard={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'}];constadaptiveCard=CardFactory.adaptiveCard(card);return{task:{type:'continue',value:{card:adaptiveCard}}};

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

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

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

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

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

asynchandleTeamsMessagingExtensionSubmitAction(context,action){if(action.data.editedMessage){consttext=action.data.editedMessage;constmorseText=awaitencodeToMorse(text);return{composeExtension:{type:'result',attachmentLayout:'list',attachments:[// the message UI component here]}}}

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

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

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

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