チームについて話しましょう

WrikeのスタッフがMicrosoft Teamsをサービスにどのように統合したか、そしてそれが何につながったかについての小さな興味深い話と、統合プロセス自体に関する大きな技術的部分。 ちなみに、彼らはチャットがリリースされた日にこれを行う世界で最初の1つでした。

1 + 1 = 3

Wrikeでの経験では、潜在的な購入者はプロジェクト管理システムを選択するときに、手頃な価格の統合にますます関心を持っています。 実際、快適なボーナスから、製品を既存のエコシステムに適合させることが、クライアントの選択を決定する要因に変わりました。

もちろん、開発者が企業ユーザー向けの最も一般的なツールに集中することは重要であり、Microsoft製品は必然的に優先事項です。 ただし、統合のために統合を行わないことがさらに重要です。 1 + 1は、多数のソリューションがクライアントに付加価値をもたらすという意味で、3を与える必要があります。

したがって、Azure Active Directory、OneDrive、およびOffice 365との統合を一貫してサービスに追加しましたこれらの手順の最終目標は、ユーザーがアプリケーションを数分ごとに切り替えたり、ウィンドウ間で情報をコピーしたり、個人間で情報をコピーしたりしないシームレスなワークスペースを作成することですチームワークのためのツールとサービスは深byではありません。

MS Teamsは論理的な新しいステップでした。 500人以上の従業員を抱える企業の53％が企業のメッセンジャーを使用しています（ SpiceWorksデータ）。 私たちは、作業を議論しているユーザーが議論の結果をすぐに実施することが便利だと考えました。 したがって、チームはマイクロソフトと協力して、そのような状況で最も適切なサービス機能を選択し、チームインターフェイスでの有機的な実装を通して考えました。

その結果、Wrikeユーザーはメッセンジャーからプロジェクトとタスクを直接作成できるようになり、プロジェクトを新しいタブとしてチームに追加できるようになりました。 統合では、ディスカッションと並行して、タスクへの変更（ステータス、実行者、期限、コメント）の導入もサポートしています。



メッセンジャー内のタイムラインでガントチャートを表示できるため、プロジェクトの議論はより実質的で正確になり、議論の参加者の前にいます。



そしてもちろん、明らかな機会が追加されました-タスクに関する通知は、電子メールだけでなく、Teamsのメッセージでも受信できるようになりました。

この機能の開発には2か月かかりました。 この間、チームはあなたに役立つかもしれない興味深い経験を得ました。

技術面について

Microsoft Teamsのタブアプリケーションは、次のもので構成されます。

• manifest.jsonファイルとリソースファイルを含むマニフェストを含むアーカイブ。
• ページの要求を処理する外部HTTPサービス：構成、タブのメインページ、削除。

すべてのページは、Microsoft Teamsのiframe内にレンダリングされます。 タブアプリケーションのマニフェストの例は、 MSDNで説明されています 。 マニフェストスキームもあります。 執筆時点では、回路の現在のバージョンは0.4でした。

マニフェストの主なフィールド：

• Id -GUID、異なるアプリケーションまたは異なる環境に対して一意である必要があります。
• Icons -解像度が44x44および88x88で、それぞれ1.5 Kb以下のアイコン。
• configUrlは、ユーザーに最初に表示されるURLです。 アプリケーションの構成が開始されます。
• canUpdateConfigユーザーが既に追加されたアプリケーションの構成を変更できるかどうかのサイン。
• needsIdentity -Teams JS APIを通じてユーザーに関する情報を取得できます。
• validDomainsドメインが存在する信頼できるドメインの配列。 ワイルドカードが許可されます。

マニフェストとリソースを準備した後、結果のアーカイブをMicrosoft Teamsにアップロードできます。

Microsoft Teamsインフラストラクチャとの相互作用は、 Microsoft Teams JS APIライブラリによって提供されます 。 ライブラリでは次のことができます。

• Azure Oauth2またはその他のOauth2プロバイダーを介して承認のフローを実行します。
• Azure Active Directoryに関する最新のユーザー情報、チャネルID、チーム、およびグループを取得する
• タブ設定の受信と保存
• イベントのハンドラーを設定します。設定の保存、テーマの変更、タブの削除。
• タブで選択したオブジェクトへのリンクを生成してクリップボードにコピーします。

ライブラリを使用するには、ライブラリを接続し、アプリケーションの各ページで初期化する必要があります。

 <script src="https://statics.teams.microsoft.com/sdk/v0.4/js/MicrosoftTeams.min.js"></script> ... <script type="text/javascript"> microsoftTeams.initialize(); </script> 

マルチページ構成とAzure ADおよびWrikeアカウントのリンクを備えたサンプルMsTeamsアプリケーションを検討してください。

いくつかのiframe（設定、タブ）およびOauth2リダイレクトを使用したアプリケーションの詳細には、設定と、以前に追加されたタブでのアプリケーションの表示の両方について、複雑ではあるが典型的なフローが必要です。

主なプロセス：

1. ユーザーは、Microsoft Teamsに新しいタブを追加します。
2. 権限のないユーザーは、以前に追加されたタブに移動します。
3. 許可されたユーザーが以前に追加されたタブにアクセスします。

タブを追加するプロセスを次の図に示します。 青色はMicrosoft Teamsページ、緑色-アプリケーションのページ、白色-リクエストを処理するためのコードとアクションを示します。



ようこそページのページには、アプリケーションに関する基本情報と、Azure ADでの承認のフローを開始する[接続]ボタンが表示されます。

コールバックURLハンドラーは以下を行う必要があります。

• Azure ADでユーザー情報を要求します（たとえば、 Microsoft Azure AD Graph APIを使用 ）。
• 受信した情報をどう処理するかを決定します。システムに新しいアカウントを作成するか、既存のアカウントを使用します。
• たとえば、セッションCookieを発行して、システムにログインします。
• 認証が成功した場合、認証は新しいウィンドウで開始され、コールバックは認証のエンドポイントであるため、コールバックURLページは単純に閉じる必要があります。
• 承認に失敗した場合、コールバックURLページには、ユーザーに失敗の理由、たとえば、ユーザーによるアクセスの拒否、Azureアプリケーションへのアクセスの欠如などが表示されます。

設定ページは設定ページです。 タブを追加するとき、および以前に追加したタブのメニューの[構成]オプションを使用して要求されます（マニフェストでcanUpdateConfigフラグが設定されている場合）。

Azure ADのマルチテナントアプリケーションを介してOauth2承認を実行するサンプルコード（つまり、ようこそページのコード例）は次のようになります。

 <script src="https://statics.teams.microsoft.com/sdk/v0.4/js/MicrosoftTeams.min.js"></script> <input type="button" onclick="startAuth()" value="..."/> <script type="text/javascript"> microsoftTeams.initialize(); var startAuth = function() { microsoftTeams.authentication.authenticate({ url: 'https://login.windows.net/common/oauth2/authorize' + '?response_type=code%20id_token' + '&scope=openid' + '&response_mode=' + form_post + '&client_id=' + <YOUR_AZURE_APP_CLIENT_ID> + '&resource=https%3a%2f%2fgraph.windows.net' + '&nonce=' + <MS_NONCE> + '&state=' + <OAUTH2_STATE> + '&redirect_uri=' + encodeURIComponent('http://localhost/callback'), width: 700, height: 500, successCallback: onAuthSuccess, failureCallback: onAuthFailure }); }; var onAuthSuccess = function() { console.log('Auth success'); document.location.href='http://localhost/setup'; }; var onAuthFailure = function() { console.log('Auth failed'); microsoftTeams.settings.setValidityState(false); }; </script> 

パラメータ：

• redirect_uri -GETリクエストidTokenが渡されるコールバックハンドラのURL。 Azure ADのアカウントをシステム内のアカウントに接続するためのアクセストークン、リフレッシュトークン、およびユーザー情報を取得できます。
• YOUR_AZURE_APP_CLIENT_IDアプリケーション識別子。
• MS_NONCEはランダムに生成されたナンスであり、Azure Oauth2の状態に類似しています。
• OAUTH2_STATE -Oauth2状態。コールバックハンドラーで確認する必要があります。

フロー認証の開始は、Teams JS APIのmicrosoftTeams.authenticateメソッドによって提供されます。 window.openを明示的に呼び出す必要はありません。 onAuthSuccess 、 onAuthFailureは、認証ウィンドウが開かれたソースページのコンテキストで呼び出されonAuthFailure 。

タイムアウトに関してOauth2 flowを開始するより安全で信頼性の高い方法は、 OAUTH2_STATEを生成し、ユーザーをlogin.windows.netにリダイレクトするハンドラーを要求することです 。

Azure ADのアプリケーションの作成と構成の詳細については、 こちらをご覧ください 。

設定を保存するためのセットアップページのサンプルコードを以下に示します。

 <script src="https://statics.teams.microsoft.com/sdk/v0.4/js/MicrosoftTeams.min.js"></script> <input id="name" type="text" placeholder="Enter your name" onkeyup="validate()"/> <script type="text/javascript"> microsoftTeams.initialize(); var isNameValid = function() { return jQuery('#name').val().trim().length > 0; } var validate = function() { //    Save microsoftTeams.settings.setValidityState(isNameValid()); }; microsoftTeams.settings.registerOnSaveHandler(function (saveEvent) { if (!isNameValid()) { saveEvent.notifyFailure("We couldn't save your tab settings. Please enter your name."); return; } microsoftTeams.settings.setSettings({ contentUrl: 'http://localhost/tabContent', suggestedDisplayName: "Your Tab Name", websiteUrl: "http://localhost" }); saveEvent.notifySuccess(); }); </script> 

パラメータ：

• contentUrlタブが開かれたときに表示されるページのアドレス。
• suggestedDisplayNameタブの名前。
• websiteUrl -Microsoft Teamsメニューからリンクが開きます。

次のコードは、次のTeams JS APIメソッドを使用します。

• microsoftTeams.settings.setValidityState [保存]ボタンを有効または無効にします。
• microsoftTeams.settings.registerOnSaveHandler設定を保存するためのイベントハンドラー。
• saveEvent.notifyFailure 、 notifySuccess設定を保存する際の成功または失敗についてTeamsインフラストラクチャに通知します。
• microsoftTeams.settings.setSettingsタブの設定を保存します。

以前に追加されたタブへのユーザーログインのプロセスを検討します。 ここでは次のオプションが可能です。

1. ユーザーは新規であり、システムに関連付けられていません。
2. システムで認識されているが、許可されていないユーザー。
3. 許可ユーザー。

認証は「シームレス」であるため、Azure ADでの認証後にシステムのアカウントに新しいユーザーを追加するだけです。 これは、以前に追加されたタブを入力するプロセスです。



Microsoft Teams内の組織構造は次のとおりです。

• チームアカウントには多くのチームを含めることができます。
• チームは多くのチャネルを持つことができます。
• チャンネルには多くのタブを含めることができます。

タブ設定とユーザー情報は、 contextとsettings （Microsoft Teams JS APIから）を介して利用できます。

• microsoftTeams.getContext構成ページおよびタブ内のページで利用可能。
• microsoftTeams.settings.getSettings構成ページでのみ使用可能。

課題と解決策

このような構造ではどのような困難が生じる可能性がありますか？

Wrikeチームは、ユーザーがAzure ADで承認されることを決定しました。 ユーザーデータ： upn （ユーザープリンシパル名またはメール）、 teamId 、 channelIdはJS APIからアクセスできますが、このデータはバックエンド側で検証できませんteamId ADのアプリケーションが管理者権限を必要とする権限を要求する場合のみ。 これは、Azure Graph APIの機能によるものです。組織の構造に関する情報は、管理者の同意がなければ利用できません。 この方法は、Azure AD管理者のみがチャネルにタブを追加できるという点で不便です。

チャンネルに複数のタブがある場合、ユーザーがどのタブを開くtabIdません（ tabIdはありませんが、生成することはできますが、詳細は以下を参照してください）。 カスタム設定の保存はsettings.customSettingsでのみ使用できますが、 settings.customSettingページからのみタブページからsettingsアクセスすることはできません。

これらの問題を解決するには？ teamId 、 channelId 、 tabIdに関するデータ収集は、ユーザーの承認中に整理し、アプリケーションの側に保存できます。 タブ内のユーザーからのリクエストは、現在のコンテキスト（ microsoftTeams.getContext ）のデータに基づいて検証できます。

タブ識別子は、たとえば次のように構成ページに追加されたときに生成できます。

  microsoftTeams.settings.registerOnSaveHandler(function (saveEvent) { microsoftTeams.settings.getSettings(function(settings) { var tabId = generateOrGetTabId(settings); var customSettings = { tabId: tabId }; microsoftTeams.settings.setSettings({ contentUrl: 'http://localhost/tabContent?tabId=' + tabId, ... customSettings: JSON.stringify(customSettings) }); saveEvent.notifySuccess(); }) }); 

ページコードの[ settings ]タブにアクセスできないため、 contentUrl query stringパラメーターを渡します。 最初にタブを追加するときにのみtabIdを生成します。 再構成時には、以前に指定したものを使用します。 GenerateOrGetTabIdがこれを担当します。 settings.customSettingsフィールドを使用すると、生成されたtabId文字列とシリアル化されたJSONオブジェクトの両方として保存できます。

結論として、タブまたはタブ内の特定のコンテンツへのリンクを生成する方法であるdeepLinksリンクについてdeepLinksたいと思います。

執筆時点では、リンクを生成する方法は2つあります。

1. インタラクティブmicrosoftTeams.shareDeepLinkを使用します。 この場合、ユーザーは名前の入力を求められ、リンクがクリップボードにコピーされます。 このようなリンクはチャットで認識され、ユーザーが入力したテキストとしてレンダリングされ、指定されたentityIdおよびentityIdタブに移動します。 詳細な説明はこちらです。
2. 非対話型-アプリケーションID（マニフェストから）、タブのコンテキスト、および他のパラメーター（ entityId 、 entityIdなど）を考慮してリンクを形成します。 このようなリンクは、たとえばボットからのメールやメッセージなど、さまざまな通知に使用できます。

deepLinks形成方法の説明は、 MSDNにあります。 さらに、両方のメソッドはmicrosoftTeams.settings使用する必要がないため、タブページのコードで実行可能であることに注意してください。

Teams JS APIは積極的に開発しており、開発プロセス中にバージョンが0.2から0.4に変更されました。 さらに、ボットとタブのマニフェストが一般的になりました。

Wrikeとの統合には、Azure AD Graph APIとMicrosoft Graph APIも使用されました。 そのプロセスとリリース後、マイクロソフトの同僚と緊密なコミュニケーションを取り、フィードバックを考慮しました。


チーム構成へのアクセスの問題は、 Bot APIで既に対処されています 。 Deep Linksの機能の一部は、チームのリリースの少し前に公開されました。 おそらく、REST APIレベルでのチームサポートはMicrosoft Graph APIに実装されます。これは、このAPIが積極的に開発されており、Office 365のさまざまなコンポーネントとの対話を伴うためです。

ちなみに、レビュー用の新しい申請書を送信するためのフォームはこちらにあります 。 Wrikeエクスペリエンスがあなたにとって有益であり、Microsoft Teamsユーザーがチームワークのためのさらに便利なツールを入手できることを願っています。

著者について

Alexander Belyaev 、製品マネージャー。 彼は、Wrikeオーディエンスのジョブストーリーの開発（完了すべきジョブのコンセプトのフレームワーク内）を担当し、それに応じて、ユーザーが作業の典型的なシナリオのフレームワークで使用する機能を担当しています。 彼はWrike APIの開発も行っており、戦略的パートナーとの統合を担当しています。 彼は猫と禅が大好きです。

Oleg Vashenkov 、バックエンド開発者。 Microsoftとの統合のコンテキストでは、Teamsは、アカウントの承認、作成と統合、Teams内で作業するためのAPIのサポートと拡張を担当します。 彼はミニハッカソンが好きです-新しいプラットフォームやデバイスのアイデアを実現し、仕事や生活、トレーニング、チューニング、競技などのマシンのための彼自身のソリューションを試してみてください。

ここでは、Microsoft Azureを無料で試用できることをお知らせします。