The Will Will Web

記載著 Will 在網路世界的學習心得與技術分享

使用 Teams Toolkit 開發 Teams 應用程式:起手式

前幾年若要開發 Teams 應用程式的門檻非常高,你必須查看非常多的文件之後,還不知道怎樣完成第一個測試用的應用程式。但是微軟近期發佈了 Teams Toolkit 擴充套件,可以說大幅降低了首次開發 Teams apps 的難度,許多繁瑣的過程與背景知識,透過 VS Code 的 Teams Toolkit 擴充套件或 TeamsFx CLI 命令列工具,就可以非常簡易的建置出開發環境,若要部署到 Azure 也都有相對應的工具與命令可以使用。今天這篇文章我就來跟大家分享開發 Teams App 的起手式。

通常我們要開始學習如何開發 Teams App 大概會有以下步驟:

  1. 準備 Microsoft 365 組織與調整 Teams apps 原則設定
  2. 準備 Teams app 所需的開發工具
  3. 瞭解 Teams app 的 "Capabilities" (能力)
  4. 建立 Teams app 應用程式
  5. 修改範例程式碼以符合你的需求
  6. 預覽 / 測試 Teams 應用程式
  7. 部署 Teams 應用程式

今天這篇文章的重點,將會專注在 1, 2, 3, 4, 6, 7 等步驟。

準備 Microsoft 365 組織與調整 Teams apps 原則設定

  1. 準備一個 Microsoft 365 組織 (Tenant)

    Prepare your Microsoft 365 tenant - Teams | Microsoft Docs

    你若沒有 Microsoft 365 可用,可以申請免費的 Microsoft 365 Developer Program 即可開始開發!

  2. 到 Teams admin center 設定 Teams apps 原則 (允許上傳自訂的 Teams 應用程式)

    Prepare accounts to build Teams apps

準備 Teams app 所需的開發工具

  • Visual Studio Code

    主要的開發工具

    choco install vscode -y
    
  • Teams Toolkit extension

    主要的開發工具擴充套件

    code --install-extension TeamsDevApp.ms-teams-vscode-extension
    
  • Node.js LTS

    choco install nodejs-lts -y
    
  • TeamsFx CLI

    主要的 CI/CD 與透過命令列發行應用程式的工具,可大幅降低首次開發 Teams App 的上手門檻!

    npm install -g @microsoft/teamsfx-cli
    

瞭解 Teams App 的 "Capabilities" (能力)

在開發你的第一個 Teams 應用程式之前,你可能要先瞭解你可以拿 Teams App 來開發些什麼應用,然後再來學習用什麼樣的工具來開發!

基本上,Teams App 的 Capabilities 有以下三種:

  1. Tabs (索引標籤)

    這種 Teams 應用程式主要跑在 Teams 聊天室頻道中的索引標籤 (Tabs),簡單來說,這種類型的 Teams App 就是一個 Web 網頁而已,你只要會 HTML, CSS, JS 就可以開發出一個 Teams App,即便你是使用純前端的框架 (Angular, Vue, React) 也都可以實現 Tabs 類型的應用。

    這種 Teams App 主要應用於 查詢資訊 或是提供 單人多人 相同功能的使用情境。例如:查詢個人的特休剩餘天數、查詢團隊的 CI 的成功率。

    image

    你可能會搭配 TeamsFx SDKTeams JavaScript client SDK 來開發這些頁面。

  2. Bots (聊天機器人)

    這種 Teams 應用程式主要就是透過文字聊天的方式,提供對談式互動介面,讓使用者可以跟機器人說話,做到一些自動化工作。

    這種 Teams App 主要應用於 聊天機器人用戶 之間的「一對一」對話互動。例如:員工請假、查詢資訊、回報工時記錄、...等等。

    如果該聊天機器人安裝在頻道中,所有的跟機器人的互動都會讓所有人看見,是一種相當透明的互動方式。

    這部分你可能會用到 TeamsFx SDKBot Framework SDK 來開發這些聊天機器人。

  3. Messaging extension (訊息擴展)

    這種 Teams 應用程式主要是透過「搜尋」、「行為」或「對話」,在原本的訊息上插入一些額外的資訊,你可能會透過 Adaptive Cards 來設計複雜的版面。例如你可以在訊息內容的下方自動加上一些按鈕或欄位,增加訊息的表達能力與互動能力。

    訊息擴展類型的應用,大致可以分成三種類型:

    1. 分析輸入的內容,自動添加額外的附加資訊 (例如: 輸入網址會自動加上網頁預覽的摘要資訊)

      image

    2. 輸入訊息時,可以透過互動的方式,在訊息中加入額外的資訊

      image

    3. 在 Teams 的搜尋框輸入 / 時,可以出現的選項,這也是透過 Messaging extension 來提供的

      image

一個 Teams app 可以同時包含多種 "Capabilities" (能力)!

建立 Teams app 應用程式

  1. 建立一個空資料夾

    mkdir G:\Projects
    cd G:\Projects
    
  2. 直接從專案範本建立全新專案

    teamsfx new template hello-world-tab
    
    cd hello-world-tab
    
    code .
    
  3. 開啟 VS Code 之後直接按下 F5 快速鍵,就可以立即啟動本機開發伺服器,並開啟 Teams 網站後自動上傳 Teams app 自訂應用程式

    你可以直接將 Teams app 新增至指定的「頻道」或「聊天室」即可安裝完成:

    image

    此時你就可以開始使用這個 Tabs (索引標籤) 來使用 Teams app 應用程式,整個流程一鼓作氣、一氣呵成,對開發人員來說非常友善。

部署 Teams 應用程式

透過 TeamsFx CLI 可以非常方便的幫你設定好 Teams app 所有必須的各種資源,其中包含 Teams 所屬的 Microsoft 365 組織 (Tenant) 必須先註冊一個 App registration (Service Principal),還有自動建立執行 Teams app 網站/API 所需的 Azure 資源。

  1. 設定 Azure AD 與建立必要的 Azure 資源

    由於 Teams app 本身必須先在 Azure AD 註冊一個應用程式才能運作,這個步驟牽涉到 OAuth 2.0 的相關知識,對大多數開發人員來說過於陌生,所以這個步驟已經被包含在 teamsfx provision 命令之中,開發過程已經大幅簡化。

    另外,為了要能夠有個地方可以執行你的 Teams app,你會需要在 Azure 建立一些重要的資源,例如 Storage, App Service Plan, Function App, ... 等等。

    注意: Microsoft 365 的 Azure AD 與 Azure 資源的 Azure AD 可以不一樣,事實上,你的 Teams app 就算要安裝在 AWS 或地端機房也都是可以的。

    首先,你必須先透過 Azure CLI 登入 Azure 組織,登入後才會讓你選取你想要部署的訂用帳戶 (Subscription)。

    az login
    

    以下這個步驟首先會請你登入 Teams 所在的 Microsoft 365 組織 (Azure AD),因為他需要在你的 Azure AD 建立一個 服務主體 (Service Principal) 物件。然後會直接詢問你要選用哪一個 Azure 訂用帳戶 (Subscription),然後讓你建立 資源群組 (Resource Group) 並設定資料中心地區 (Location),接著就會全自動幫你建立好必要的 Azure 資源,並且會幫你產生一個 Teams Package 檔案 (appPackage.dev.zip)。

    teamsfx provision
    

    image

    注意: 這裡建立的 appPackage.dev.zip 很重要,壓縮檔內有一個 manifest.json 定義了 Teams app 所有的必要資訊,包含 Tabs 要顯示的網頁網址與 Teams app 權限。其實所有的 Teams app 要部署的時候,所有的檔案都是放在網站上,上架 Teams app 就只要準備 manifest.json 即可,因此你可以將網站部署到任何地方,不一定要部署到 Azure 雲端平台。

  2. 部署 Teams 應用程式到 Azure

    teamsfx deploy
    
  3. 上傳自訂應用程式

    直接從 Teams Client 點擊左下角的「應用程式」>「上傳自訂應用程式」,並將 Teams app 新增至指定的「頻道」或「聊天室」之中:

    上傳自訂應用程式

    安裝好之後,就可以點開 My Tab (索引標籤) 就可以看到頁面,並且使用者可以按下 Authorize 按鈕來取得使用者的基本資訊。

    image

    這裡的 Authorize 按鈕所呼叫的程式,事實上是透過 OAuth 2.0 向 Microsoft Graph 取得一個 accessToken,然後透過這個 accessToken 取得使用者資料,你也可以透過同樣的流程,許得該使用者在 Microsoft 365 中的任何資料,過程中走的就是 OAuth 2.0 的授權流程。

專案機會

我們公司使用 Office 365 已經非常多年,多年前我們從 Slack 全面轉換到 Teams 平台,一開始不太會用,還會覺得有些地方實在設計的很爛。但是用了一段時間才發現,這套設計的理念與架構,其實跟 Slack 不太一樣,很多時候不能相比。我們公司現在已經很少使用沒有效率的 E-mail 來協作,公司內部所有的協調工作,全都透過 Teams 完成,而且專案的資訊全部都集中的 Teams 的團隊與頻道中,所有的溝通過程、會議、錄影、教學、檔案共享、文件管理,與任何第三方資訊 (Azure Boards, PR 通知, Trello, ...) 也都可以全部整合在一起,甚至於連常見的重開網站、開啟防火牆、遠端 VM 開關機、查詢 VPN 資訊、...等功能,也都可以非常方便的在 Teams 完成,完全不需要外開網頁,而且所有資訊都是透明化的,對於組織的溝通效率大幅提升,人越多的公司應該會越有感覺。

由於 Teams app 的開發門檻已經降低許多,可以想見的,這個領域的專案開發需求應該會有不小的市場,只是還需要一些時間醞釀,大家其實還沒發現 Teams 如何改善組織效率的方法。如果你的公司也有在使用或正在考慮使用 Teams,是可以想想看客製化 Teams app 可以為你的公司帶來什麼協作效率的提升,如果有機會的話,可以找我們幫你們開發完全客製化的 Teams 應用程式,大幅提昇組織的工作效率,降低各種繁文縟節的無形損耗。

相關連結