教學課程

您的應用程式有一項功能，自帶自己的 UI 和 UX：

在本教學課程中，您將了解：

• 如何使用 Microsoft 365 Agents Toolkit 設定新專案 (先前稱為 Teams Toolkit) 。
• 如何建置 Bot 應用程式。
• 如何部署您的應用程式。

先決條件

請確定您已安裝下列工具來建置和部署您的應用程式。

設定必要條件

安裝必要的工具之後，請設定開發環境。

安裝 Microsoft 365 代理程式工具組

Microsoft 365 Agents Toolkit (先前稱為 Teams Toolkit) 透過為應用程式佈建和部署雲端資源並發佈到 Teams Store 的工具來協助簡化開發流程。

您可以將 Agents Toolkit 與 Visual Studio Code 搭配使用，或稱為 Microsoft 365 Agents Toolkit CLI (先前稱為 TeamsFx CLI) 的命令列介面。

npm install -g @microsoft/m365agentstoolkit-cli

sudo npm install -g --unsafe-perm @microsoft/m365agentstoolkit-cli

設定您的 Teams 開發租用戶

租用戶是貴組織在 Teams 中的一個空間或容器，您可在這裡聊天、共用檔案和開會。 這個空間也是您上傳和測試應用程式的地方。 讓我們確認您是否已準備好與租用戶一起開發。

檢查 [上傳應用程式] 選項

建立自訂應用程式之後，您必須使用 [ 上傳自訂應用程式 ] 選項，將您的應用程式上傳至 Teams。 登入您的 Microsoft 365 帳戶以檢查此選項是否已啟用。

下列步驟可協助您確認您是否可以在 Teams 中上傳應用程式：

1. 在 Teams 用戶端中，選取 應用程式 圖示。

2. 選取 管理您的應用程式。

3. 選取 [ 上傳應用程式]。

4. 尋找 [ 上傳自訂應用程式] 選項。 如果顯示該選項，您可以上傳自訂應用程式。

   

建立免費的 Teams 開發人員租用戶

如果您沒有 Teams 開發人員帳戶，請加入 Microsoft 365 開發人員計畫。 這是選擇性步驟。

1. 移至 Microsoft 365 開發人員計畫。

2. 選取 [立即加入] ，並依照畫面上的指示操作。

3. 在歡迎畫面中，選取設定 E5 訂閱。

4. 設定您的系統管理員帳戶。 完成後，隨即出現下列畫面：

   

5. 使用您剛才設定的系統管理員帳戶登入 Teams。 確認您在 Teams 中有 上傳自訂應用程式選項 。

取得免費的 Azure 帳戶

如果您想要在 Azure 中託管您的應用程式或存取資源，您必須擁有 Azure 訂閱。 開始之前先建立免費帳戶。

現在您已擁有設定帳戶的所有工具。 接下來，讓我們設定您的開發環境並開始建置吧！ 先選取您要建立的應用程式。

為您的 Bot 應用程式建立專案工作區

讓我們建立您的第一個 Bot 應用程式。

Teams 應用程式的 Bot 功能會建立聊天機器人或交談機器人。 您可以使用它來執行簡單且自動化的任務，例如提供客戶服務。 Bot 會與 Web 服務交談，並協助您使用其供應項目。 您可以獲取天氣預報、進行預訂或使用對話機器人提供的任何其他服務。

當您已準備好建立這些應用程式時，您可以設定新的 Teams 專案來建立 Bot 應用程式。

在本教學課程中，您將了解：

1. 如何使用 Agents Toolkit 設定新的 Bot 專案。
2. 關於應用程式專案的目錄結構。

建立您的 Bot 專案工作區

如果先決條件齊全，讓我們開始吧！

atk new

Bot 應用程式原始程式碼導覽

腳架完成後，在 Visual Studio Code 的資源管理器中檢視專案目錄和檔案。

建置並執行您的第一個 Bot 應用程式

使用 Agents Toolkit 設定專案工作區之後，請建置 Bot 專案。 您必須登入您的 Microsoft 365 帳戶。

登入您的 Microsoft 365 帳戶

使用此帳戶登入 Teams。 如果您使用的是 Microsoft 365 開發人員計畫租用戶，則您在註冊時設定的系統管理員帳戶就是您的 Microsoft 365 帳戶。

atk account login m365

在本機建置並執行您的第一個 Bot 應用程式

若要在本機環境中建置及執行您的應用程式：

1. 選取 Visual Studio Code 中的 F5，以偵錯模式執行應用程式。

   注意

   如果 Agents Toolkit 無法檢查特定的先決條件，它會提示您檢查。

   了解當您在偵錯工具中本機執行應用程式時會發生什麼情況。

   如果您想知道，當您按 F5 鍵時，Agents Toolkit：

   1. 檢查下列所有必要條件：

   • 您已使用 Microsoft 365 帳戶登入。
   • 您的 Microsoft 365 帳戶已啟用自訂應用程式上傳功能。
   • 已安裝支援 Node.js 版本。
   • Bot 應用程式所需的連接埠可用。

   2. 安裝 npm 套件。
   3. 啟動開發人員通道以建立 HTTP 通道。
   4. 在 Microsoft Entra ID 中註冊應用程式並設定應用程式。
   5. 在 Bot Framework 中註冊 Bot 應用程式，並設定 Bot 應用程式。
   6. 在 Teams 開發人員入口網站中註冊應用程式並設定應用程式。
   7. 啟動 Bot 應用程式。
   8. 在網頁瀏覽器中啟動 Teams，並上傳自訂 Bot 應用程式。

   

   注意

   當您第一次執行應用程式時，會下載所有相依性，並建置應用程式。 當組建完成時，瀏覽器視窗會自動開啟。 此程序可能需要三到五分鐘才能完成。

   Teams 會在網頁瀏覽器中執行您的應用程式。

2. 如果出現提示，請使用您的 Microsoft 365 帳戶登入。

3. 選取 [ 新增 ] 將自訂 Bot 應用程式上傳至 Teams。

   

4. 選取 [ 開啟] 以在個人範圍內開啟應用程式。

   或者，您可以搜尋並選取所需的範圍，或從清單中選取頻道、聊天或會議，然後在對話方塊中移動以選取 [執行]。

   

   現在 Bot 已成功在 Teams 上執行！ 載入應用程式之後，隨即開啟與 Bot 的聊天工作階段。

   

   您可以輸入 welcome 以顯示介紹卡，並輸入以 learn 移至調適型卡片和機器人命令文件。

   

   您可以執行一般偵錯活動，例如設定中斷點，就像使用任何其他 Web 應用程式一樣。 開啟 bot/teamsBot.js 檔案並找到 onMessage() 方法。 在任何情況下設定中斷點。 然後，輸入一些文字。

   瞭解如果您的應用程式無法在本機執行時進行疑難排解，該如何進行疑難排解。

   若要在 Teams 中成功執行您的應用程式，請確定您已在 Teams 帳戶中啟用自訂應用程式上傳。 您可以在先決條件章節深入了解自訂應用程式上傳。

   重要

   自訂應用程式上傳可在政府社群雲端 (GCC) 中使用，且由 21Vianet 運作的 GCC High、DoD 和 Teams 不支援。

   秘訣

   在上傳自訂應用程式之前，請使用 應用程式驗證工具來檢查問題。 此工具包含在工具組中。 修正錯誤以上傳應用程式。

部署您的第一個 Teams 應用程式

您已學會使用 Bot 功能建立、組建及執行 Teams 應用程式。 最後一步是在 Azure 上部署您的應用程式。

讓我們使用 Agents Toolkit 在 Azure 上部署第一個具有機器人功能的應用程式。

登入您的 Azure 帳戶

使用此帳戶可存取 Microsoft Azure 入口網站，並佈建新的雲端資源以支援您的應用程式。

atk account login m365

atk account login azure

在 Azure 上佈建和部署您的應用程式

部署包含兩個步驟。 首先，Azure建立必要的雲端資源 (也稱為佈建) 。 然後，Azure 會將應用程式的程式碼複製到建立的雲端資源中。 在本教學課程中，您將部署 Bot 應用程式。

執行已部署的應用程式

佈建和部署步驟完成後：

1. (Ctrl+Shift+D / ⌘⇧-D 開啟偵錯面板，或從 Visual Studio Code 開啟 [檢視>執行) ]。

2. 從啟動設定下拉式清單中選取 啟動遠端 (Edge) 。

3. 選取 [開始偵錯] (F5) 。 系統會提示您將自訂 Bot 應用程式上傳至 Teams。

   

4. 選取 [新增]。

   

5. 選取 [ 開啟] 以在個人範圍內開啟應用程式。

   或者，您可以搜尋並選取所需的範圍，或從清單中選取頻道、聊天或會議，然後在對話方塊中移動以選取 [執行]。

   

   您已成功將 Bot 應用程式新增至 Teams 用戶端。

   

恭喜！

您成功了！

您已建立 Bot 應用程式。

現在您已經學會了建立基本應用程式，您可以繼續建立更複雜的應用程式。 您已完成使用 JavaScript 建置 Bot 的教學課程。

先決條件

您可以與 Bot 聊天，並檢視顯示在 Teams 中的訊息和調適型卡片。 您也可以使用活動觸發器模擬 Agents Playground 中的活動。

本逐步指南可協助您使用 Agents Toolkit 建立 AI 聊天機器人，並使用測試工具進行偵錯。 完成本指南之後，您會看到下列輸出，使用者可以在其中存取及使用 AI 聊天機器人：

為您的 AI 聊天機器人應用程式建立專案工作區

Teams 應用程式的 Bot 功能會建立聊天機器人或交談機器人。 它與 Web 服務進行通信，方便其服務的使用。 該機器人可以執行簡單的自動化任務，例如提供客戶服務。 您可以獲取天氣預報、進行預訂或使用對話機器人提供的任何其他服務。

當您已準備好建立這些應用程式時，您可以設定新的 Teams 專案來建立 AI 聊天機器人應用程式。

建立您的 Bot 專案工作區

如果先決條件齊全，讓我們開始吧！

1. 開啟 Visual Studio Code。

2. 選取 Visual Studio Code 活動列中的 Microsoft 365 代理程式工具組圖示。

3. 選取 [建立新的代理程式/應用程式]。

   

4. 選取適用於 Teams >的代理程式：Azure OpenAI> 立即在 [輸入 Azure API] 服務金鑰中輸入

   

5. 選取 Teams 的基本代理程式。 如果您的 Bot 需要不同的功能，請選取所需的選項。

   

6. 選取程式語言作為 JavaScript。

   

7. 選取 預設資料夾。

   

   若要變更預設位置，請依照下列步驟執行：

   1. 選取 [瀏覽]。

      

   2. 選取專案工作區的位置。

   3. 選取 [選取資料夾]。

      

8. 輸入適合您的應用程式名稱，然後選取 Enter 鍵。

   

   此時會出現一個對話方塊，您必須選擇 [是] 或 [否] 以信任此資料夾中檔案的作者。

   

現在，您已成功建立 AI 聊天機器人專案工作區。

Bot 應用程式原始程式碼導覽

完成腳手架之後，請在 Visual Studio Code 的 [檔案總管] 區段中探索專案目錄和檔案。

建立和執行您的 AI 聊天機器人應用程式

為您的 AI 聊天機器人建立 OpenAI 金鑰和端點

1. 移至 Azure 入口網站。

2. 選取建立資源並搜尋 Azure OpenAI。

3. 選取 [Azure OpenAI]，然後選取 [建立]。

   

4. 填寫必要詳細資料，然後選取 [下一步]。

   

5. 選取 [包括網際網路在內的所有網路都可以存取此資源] ，然後選取 [下一步]。

   

6. 填寫必要詳細資料，然後選取 [下一步]。

   

7. 選取 [建立]。

   

您已成功為 AI 聊天機器人建立金鑰和端點。

取得 Azure OpenAI 金鑰和端點

1. 選取 [前往資源]。

   

2. 從左窗格中選取 [ 金鑰和端點 ]，然後複製 [金鑰 ] 和 [端點]。 您可以複製 KEY 1 或 KEY 2。

   

   儲存 金鑰 和 端點 以供進一步使用。

3. 從左側窗格中選取 模型部署 ，然後選取 管理部署。

   

   Azure OpenAI Studio 視窗隨即出現。

4. 從左側窗格中選取 [部署] ，然後選取 [+ 建立新部署]。

   

5. 選取下列詳細資料：

   1. 從 [選取模型] 下拉式清單中選取 gpt-35-turbo。

      注意

      AI 聊天機器人僅支援 gpt-35-turbo 模型。

   2. 從 [模型版本] 下拉式清單中選取 0301 ([預設) ]。

   3. 輸入 部署名稱 ，然後選取 建立。

      

   4. 複製並儲存 部署名稱 以供進一步使用。

      

更新 Azure OpenAI 金鑰和端點

1. 在 Visual Studio Code 中開啟您的專案。

2. 在 [檔案總管] 底下，前往 env.env.playground.user > 檔案。

3. 輸入您的 SECRET_AZURE_OPENAI_API_KEY 和 SECRET_AZURE_OPENAI_ENDPOINT。

   ...
   SECRET_AZURE_OPENAI_API_KEY=<azure-openai-api-key>
   SECRET_AZURE_OPENAI_ENDPOINT=<azure-openai-endpoint>
   

4. 移至 src>app.js 檔案。

5. 註解 OpenAI 程式碼和取消註解程式碼 Azure OpenAI 。

6. 在中azureDefaultDeployment輸入您的 Azure OpenAI 部署名稱。

   
   // Use OpenAI
   // apiKey: config.openAIKey,
   // defaultModel: "gpt-3.5-turbo",
   
   azureApiKey: config.azureOpenAIKey,
   azureDefaultDeployment: "gpt-35-turbo",
   azureEndpoint: config.azureOpenAIEndpoint,
   
   

偵錯並執行您的 AI 聊天機器人應用程式

1. 在左側窗格中，選取 [執行和偵錯] (Ctrl+Shift+D) ，然後從下拉式清單中選取 [在 Agents Playground 中偵錯]。

   

2. Agents Playground 會在網頁中開啟您的 AI 聊天機器人。

   

活動觸發程序

活動觸發程式有兩種類型：

預先定義的活動觸發程序

Agents Playground 提供預先定義的活動觸發器來測試 Bot 的功能。

預先定義的活動觸發器可在 Agents Playground 的 [模擬活動] 功能表中使用。

若要模擬 [ 新增使用者 ] 活動，請遵循下列步驟：

1. 在 Agents Playground 中，移至 [模擬活動]> 新增使用者。

   

   此時會出現一個對話方塊，預覽活動處理常式。

2. 選取傳送活動。

   

   Bot 會傳送下列回應：

   

自訂活動觸發程序

您可以使用 自訂活動 來自訂活動觸發程序，例如， reactionsAdded 以符合 Bot 應用程式的需求。 Agents Playground 會自動填入活動的必要屬性。 您也可以修改活動類型並新增更多屬性。

1. 選取 模擬活動自訂>活動。

   

2. 新增 messageReaction 以自訂屬性下的 type 活動：

   {
       "type": "messageReaction",
       "reactionsAdded": [
       {
           "type": "like"
       }
       ],
       "replyToId": "d60fd1cb-3e8f-44ef-849c-404806ba1b47"
   }
   

3. 選取傳送活動。

   

   Bot 會傳送 onReactionsAdded 處理常式作為回應。

   

完成挑戰

你有這樣的輸出嗎？

恭喜！ 您已成功建立 AI 聊天機器人應用程式。 現在，您已經學會在 Agents Playground 中偵錯 AI 聊天機器人應用程式。

訊息回應可以採用下列其中一種格式：

• 歡迎訊息
• 排定的郵件
• 通知

本逐步指南可協助您從 Bot 傳送主動訊息。 您會看到下列輸出：

先決條件

請確定您已安裝下列工具來建置和部署您的應用程式。

準備開發環境

安裝必要的工具之後，請設定開發環境。

安裝 Microsoft 365 代理程式工具組

Microsoft 365 Agents Toolkit (先前稱為 Teams Toolkit) 透過為應用程式佈建和部署雲端資源並發佈到 Teams Store 的工具來協助簡化開發流程。

您可以將 Agents Toolkit 與 Visual Studio Code 搭配使用，或稱為 Microsoft 365 Agents Toolkit CLI (先前稱為 TeamsFx CLI) 的命令列介面。

npm install -g @microsoft/m365agentstoolkit-cli

sudo npm install -g --unsafe-perm @microsoft/m365agentstoolkit-cli

設定您的 Teams 開發租用戶

租用戶是貴組織在 Teams 中的一個空間或容器，您可在這裡聊天、共用檔案和開會。 這個空間也是您上傳和測試應用程式的地方。 讓我們確認您是否已準備好與租用戶一起開發。

檢查 [上傳應用程式] 選項

建立自訂應用程式之後，您必須使用 [ 上傳自訂應用程式 ] 選項，將您的應用程式上傳至 Teams。 登入您的 Microsoft 365 帳戶以檢查此選項是否已啟用。

下列步驟可協助您確認您是否可以在 Teams 中上傳應用程式：

1. 在 Teams 用戶端中，選取 應用程式 圖示。

2. 選取 管理您的應用程式。

3. 選取 [ 上傳應用程式]。

4. 尋找 [ 上傳自訂應用程式] 選項。 如果顯示該選項，您可以上傳自訂應用程式。

   

   注意

   如果您找不到上傳自訂應用程式的選項，請連絡您的 Teams 系統管理員。

建立免費的 Teams 開發人員租用戶 (選擇性)

如果您沒有 Teams 開發人員帳戶，請加入 Microsoft 365 開發人員計畫。

1. 移至 Microsoft 365 開發人員計畫。

2. 選取 [立即加入] ，並依照畫面上的指示操作。

3. 在歡迎畫面中，選取設定 E5 訂閱。

4. 設定您的系統管理員帳戶。 完成後，隨即出現下列畫面：

   

5. 使用您剛才設定的系統管理員帳戶登入 Teams。 確認您在 Teams 中有 上傳自訂應用程式選項 。

建立主動式訊息機器人

若要使用 Visual Studio Code 建置主動訊息機器人，請遵循下列步驟：

1. 開啟 Visual Studio Code。

2. 選取 Visual Studio Code 活動列中的 Microsoft 365 代理程式工具組圖示。

3. 在左窗格中，選取 [檢視範例]。

   

4. 從範例清單中選取 [ 主動式傳訊]。 已準備好進行偵錯的預建範例隨即開啟。

   

5. 選取 [建立]。

   

6. 選取 [預設資料夾] ，將專案根資料夾儲存在預設位置。

   

   如果您想要變更預設位置，請執行下列步驟：

   1. 選取 [瀏覽]。

      

   2. 選取專案工作區的位置。

   3. 選取 [選取資料夾]。

      

   主動訊息機器人會在幾秒鐘內建立，並在右下角顯示主動訊息機器人成功對話方塊，其中包含偵錯選項：

   螢幕:::

7. 選取左上角的 [執行和偵錯 ] 圖示。

8. 從下拉式清單中選取 [ (Edge) 偵錯 ] 或 [ (Chrome) 偵錯 ]。

   

   偵錯成功時，系統會提示您將主動訊息機器人上傳到本機電腦上的 Teams。

9. 選取 [新增]。

   

10. 搜尋並選取所需的範圍，或從清單中選取頻道、聊天或會議，然後在對話方塊中移動以選取 [執行]。

    

    主動訊息機器人應用程式會上傳至 Teams 用戶端，且下列訊息會顯示以回應所傳送的訊息。

    

11. 複製並貼上 URL，或瀏覽至瀏覽器中的 URL。 主動式問候訊息會觸發並在聊天中共用。

    

12. 移至 Teams。 您會收到來自 Bot 的 主動問候 訊息。

    

原始程式碼導覽

Agents Toolkit 提供建置應用程式的元件。 建立專案後，您可以在 Visual Studio Code 的 [資源管理器] 區域中檢視專案資料夾和檔案。

新的專案資料夾包含下列內容：

部署您的主動式訊息機器人

您已經學會了使用主動訊息機器人功能來建置及執行 Teams 應用程式。 讓我們使用 Agents Toolkit 在 Azure 上部署第一個具有主動訊息機器人功能的應用程式。

登入您的 Azure 帳戶

使用您的帳戶存取 Microsoft Azure 入口網站，並佈建新的雲端資源以支援您的應用程式。

1. 開啟 Visual Studio Code。

2. 開啟您建立主動訊息機器人應用程式的專案資料夾。

3. 選取 Visual Studio Code 活動列中的 Microsoft 365 代理程式工具組圖示。

4. 選取 [使用您的認證登入 Azure]。

   秘訣

   如果您已安裝 AZURE 帳戶擴充功能且使用相同的帳戶，則可以略過此步驟。

   您的預設網頁瀏覽器隨即開啟，讓您登入帳戶。

5. 出現提示時關閉瀏覽器，然後返回 Visual Studio Code。

提要欄位的 [帳戶 ] 區段會分別顯示兩個帳戶。 它也會列出可供您使用的可用 Azure 訂閱數量。 請確定您至少有一個可用的 Azure 訂閱。 如果沒有，請登出並使用其他帳戶。

將應用程式部署到 Azure

部署包含兩個步驟。 首先，建立必要的雲端資源 (也稱為佈建) 。 然後，您的應用程式程式碼會複製到建立的雲端資源中。 在本教學課程中，您將部署 Bot 應用程式。

atk new

atk provision

atk deploy

atk preview

完成挑戰

你想出這樣的東西嗎？

您已完成案例。

• 您可以每天發送通知或定期請求用戶的反饋。
• 您可以處理節流限制以避免多個通知。

您可以使用 API 型訊息擴充功能來整合商務工作流程中常用的外部服務。 例如，經常使用 CRM 系統進行客戶管理的企業，可以使用訊息擴充功能直接從 Teams 擷取和顯示客戶資料。 該應用程式透過減少在不同應用程式之間切換的需要來節省時間並提高效率。 此功能可在 Teams 可用的所有平台上受到支援，包括桌面、Web 和行動裝置。

建置訊息擴充功能的必要條件

以下是建置和部署應用程式所需的工具清單。

設定您的 Teams 開發租用戶

租用戶就像是貴組織在 Teams 中的一個空間或容器，您可以在其中聊天、共用檔案和召開會議。 此空間也是您上傳和測試自訂應用程式的地方。 讓我們確認您是否已準備好與租用戶一起開發。

檢查自訂應用程式上傳選項

建立應用程式之後，您必須在 Teams 中載入應用程式，而不要將其發佈。 此程序稱為自訂應用程式上傳。 請登入您的 Microsoft 365 帳戶以檢視此選項。

您是否已經有租用戶，而且您是否擁有系統管理員存取權？ 讓我們檢查一下您是否真的這樣做！

確認您是否可以在 Teams 中上傳自訂應用程式：

1. 在 Teams 用戶端中，選取 應用程式 圖示。

2. 選取 管理您的應用程式。

3. 選取 [ 上傳應用程式]。

4. 尋找 [ 上傳自訂應用程式] 選項。 如果您看到該選項，表示已啟用自訂應用程式上傳。

   

建立免費的 Teams 開發人員租用戶 (選擇性)

如果您沒有 Teams 開發人員帳戶，您可以免費取得。 加入 Microsoft 365 開發人員計畫！

1. 移至 Microsoft 365 開發人員計畫。

2. 選取 [立即加入] ，並依照畫面上的指示操作。

3. 在歡迎畫面中，選取設定 E5 訂閱。

4. 設定您的系統管理員帳戶。 完成後，會出現下列畫面。

   

5. 使用您剛才設定的系統管理員帳戶登入 Teams。 確認您在 Teams 中有 上傳自訂應用程式選項 。

取得免費的 Azure 帳戶

如果您想要在 Azure 中託管您的應用程式或存取資源，您必須擁有 Azure 訂閱。 開始之前先建立免費帳戶。

您已擁有設定帳戶的所有工具。 接下來，讓我們設定您的開發環境並開始建置吧！ 選取您要先建置的應用程式。

建立 OpenAPI 描述文件

OpenAPI 描述 (OAD) 是業界標準規格，概述了 OpenAPI 檔案的結構化和概述方式。 這是一種與語言無關、人類可讀的描述 API 格式。 人類和機器都可以輕鬆閱讀和書寫。 架構是機器可讀的，並以 YAML 或 JSON 表示。

若要與 API 互動，需要 OpenAPI 描述文件。 OpenAPI 描述文件必須符合下列準則：

• auth不得指定屬性。

• JSON 和 YAML 是支援的格式。

• 支援 OpenAPI 2.0 和 3.0.x 版。

• Teams 不支援 oneOf、anyOf、allOf 及 Not (swagger.io) 建構。

• 不支援為要求建構陣列，不過支援 JSON 要求主體內的巢狀物件。

• 要求主體 （如果存在） 必須是 application/Json，以確保與各種 API 相容。

• 定義屬性的 servers.url HTTPS 通訊協定伺服器 URL。

• 僅支援單一參數搜尋。

• 只允許一個沒有預設值的必要參數。

• 僅支援 POST 和 GET HTTP 方法。

• OpenAPI 描述文件必須具有 operationId。

• 沒有預設值的作業不得要求 Header 或 Cookie 參數。

• 一個命令必須只有一個參數。

• 確保 OpenAPI 描述文件中沒有遠端參考。

• 具有預設值的必要參數被視為選用。

  我們使用下列 OpenAPI 描述做為本教學課程的範例：

  OpenAPI 說明

      openapi: 3.0.1
      info:
      title: OpenTools Plugin
      description: A plugin that allows the user to find the most appropriate AI tools for their use cases, with their pricing information.
      version: 'v1'
      servers:
          - url: https://gptplugin.opentools.ai
      paths:
      /tools:
      get:
      operationId: searchTools
      summary: Search for AI Tools
          parameters:
          - in: query
            name: search
            required: true
            schema:
            type: string
            description: Used to search for AI tools by their category based on the keywords. For example, a search for "tool to create music" provides a list of tools that can create music.
          responses:
          "200":
            description: OK
            content:
            application/json:
              schema:
              $ref: '#/components/schemas/searchToolsResponse'
          "400":
            description: Search Error
            content:
            application/json:
              schema:
              ref: '#/components/schemas/searchToolsError'
          components:
          schemas:
          searchToolsResponse:
          required:
          - search
          type: object
          properties:
          tools:
          type: array
          items:
          type: object
          properties:
          name:
          type: string
          description: The name of the tool.
          opentools_url:
          type: string
          description: The URL to access the tool.
          main_summary:
          type: string
          description: A summary of what the tool is.
          pricing_summary:
          type: string
          description: A summary of the pricing of the tool.
          categories:
          type: array
          items:
          type: string
          description: The categories assigned to the tool.
          platforms:
          type: array
          items:
          type: string
          description: The platforms that this tool is available on.
          description: The list of AI tools.
          searchToolsError:
          type: object
          properties:
          message:
          type: string
          description: Message of the error.
  
  

  注意

  請確定屬性 required: true 僅適用於一個參數。 如果有多個必要參數，您可以針對其他參數將 required 屬性 required: false 更新。

您可以驗證 OpenAPI 描述文件是否有效。 若要確認，請依照下列步驟執行：

1. 請移至 Swagger 或 OpenAPI 驗證程式 ，並驗證 OpenAPI 描述文件。

2. 儲存 OpenAPI 描述文件。

3. 移至 Swagger 編輯器。

4. 在左窗格中，在編輯器中貼上 OpenAPI 描述。

5. 在右窗格中，選取 [GET]。

6. 選取 [試試看]。

7. 將 搜尋 參數的值輸入為 「工具」以創建音樂。

8. 選取 [執行]。 Swagger 編輯器會顯示含有產品清單的回應。

   

9. 移至 [伺服器回應>正文]。

10. 在 下 products，複製清單中的第一個產品，並儲存以供日後參考。

    

建立回應轉譯範本

OpenAPI 描述文件需要回應轉譯範本，讓應用程式回應 GET 或 POST 要求。 回應轉譯範本包含 [調適型卡片] 範本、[預覽] 卡片範本和中繼資料。

自適性卡片範本

若要建立調適型卡片範本，請遵循下列步驟：

1. 前往 ChatGPT ，在郵件撰寫區域中詢問下列查詢：

   
   Create an Adaptive Card Template that binds to the following response:
       "categories": [
           "Music Generation",
           "AI Detection"
       ],
       "chatbot_short_url": "https://goto.opentools.ai/c/ai-music-generator",
       "main_summary": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
       "name": "AI Music Generator",
       "opentools_url": "https://goto.opentools.ai/ai-music-generator",
       "platforms": [
           "Web",
           "App",
           "API"
       ]
   

2. 選取 傳送訊息。

3. ChatGPT 會使用繫結到範例資料的調適型卡片範本產生回應。 儲存調適型卡片範本以供日後參考。

   以下是調適型卡片範本的範例：

   自適性卡片範本

   
   {
   "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
   "type": "AdaptiveCard",
   "version": "1.4",
   "body": [
       {
       "type": "TextBlock",
       "text": "AI Music Generator",
       "weight": "Bolder",
       "size": "Large"
       },
       {
       "type": "TextBlock",
       "text": "Categories",
       "size": "Medium"
       },
       {
       "type": "TextBlock",
        "text": "Music Generation, AI Detection",
        "wrap": true
       },
       {
       "type": "TextBlock",
       "text": "Description",
       "size": "Medium"
       },
       {
       "type": "TextBlock",
       "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. AI Music Generator is powered by advanced AI technology, and it makes music production accessible to everyone.",
       "wrap": true
       },
       {
       "type": "TextBlock",
       "text": "Platform",
       "size": "Medium"
       },
       {
       "type": "TextBlock",
       "text": "Web, App, API",
       "wrap": true
       }
   ],
   "actions": [
       {
       "type": "Action.OpenUrl",
       "title": "Learn More",
       "url": "https://goto.opentools.ai/ai-music-generator"
       },
       {
       "type": "Action.OpenUrl",
       "title": "Try It",
       "url": "https://goto.opentools.ai/c/ai-music-generator"
       }
   ]
   }
   
   

4. 若要驗證產生的自適性卡片是否繫結至範例資料，請遵循下列步驟：

   1. 移至 Adaptive Card Designer。

   2. 移至 [選取主應用程式]，然後從下拉式清單中選取 [Microsoft Teams ]。

   3. 移至 [卡片承載編輯器 ]，並貼上 [自適性卡片] 範本程式碼。

   4. 移至 [範例資料編輯器 ]，並貼上您先前儲存的 GET API 回應。

      

   5. 選取 預覽模式。 自適性卡片設計工具會顯示自適性卡片，其中包含將回應繫結至範本的資料。

      

建立預覽卡片範本

預覽卡片範本可以包含 title、 subtitle及 image 屬性。 如果 API 回應沒有影像，您可以移除影像屬性。

以下是預覽卡片範本的範例：

   "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}"
    } 

回應轉譯範本

回應轉譯範本必須符合託管在 https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json的結構描述。

若要建立回應轉譯範本，請遵循下列步驟：

1. 建立 JSON 檔案，並將下列程式碼新增至該檔案：

   { 
     "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json", 
     "version": "1.0", 
     "jsonPath": "", 
     "responseLayout": "", 
     "responseCardTemplate": { 
    },
    "previewCardTemplate": {
        }
    }
   

2. 更新回應轉譯範本中的屬性，如下所示：

   #	物業名稱	值
   1.	"$schema"	"https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json"
   2.	"version"	"1.0" version 是要使用的轉譯範本版本。
   3.	"jsonPath"	"tools" jsonPath 是回應 JSON 回應中的一或多個結果的路徑。 在 API 回應中，從產品清單新增 的相關 jsonPath 資料/陣列。 在此情況下， jsonPath 它是工具。 如需如何判斷 JSON 路徑的詳細資訊，請參閱 使用 JSON 路徑查詢 JSON。
   4.	"responseLayout"	"list" responseLayout 指定附件的版面配置。 用於類型結果的回應。 支援的類型為清單和格線。 如果回應正文包含具有文字、標題和影像等多個元素的物件，則回應版面配置必須設定為 list。 如果 API 回應只包含影像或縮圖，則回應版面配置必須設定為 grid。
   5.	"responseCardTemplate"	貼上您先前儲存的自適性卡片範本程式碼。 responseCardTemplate 是將JSON回應對應至自適性卡片的自適性卡片範本。
   6.	"previewCardTemplate"	貼上您先前儲存的預覽卡範本程式碼。 previewCardTemplate 是預覽卡片範本，可用來在郵件擴充功能飛出視窗中顯示結果預覽。

3. 將回應轉譯範本儲存在您儲存 OpenAPI 描述文件的相同資料夾中。

下列程式碼是回應轉譯範本的範例：

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json",
    "version": "1.0",
    "jsonPath": "tools",
    "responseLayout": "list",
    "responseCardTemplate": {
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [
            {
            "type": "TextBlock",
            "text": "AI Music Generator",
            "weight": "Bolder",
            "size": "Large"
            },
            {
            "type": "TextBlock",
            "text": "Categories",
            "size": "Medium"
            },
            {
            "type": "TextBlock",
            "text": "Music Generation, AI Detection",
            "wrap": true
            },
            {
            "type": "TextBlock",
            "text": "Description",
            "size": "Medium"
            },
            {
            "type": "TextBlock",
            "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
            "wrap": true
            },
            {
            "type": "TextBlock",
            "text": "Platform",
            "size": "Medium"
            },
            {
            "type": "TextBlock",
            "text": "Web, App, API",
            "wrap": true
            }
        ],
        "actions": [
            {
            "type": "Action.OpenUrl",
            "title": "Learn More",
            "url": "https://goto.opentools.ai/ai-music-generator"
            },
            {
            "type": "Action.OpenUrl",
            "title": "Try It",
            "url": "https://goto.opentools.ai/c/ai-music-generator"
            }
        ]
    },
    "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}"
    } 
}

建立應用程式資訊清單

現在，您需要建立應用程式資訊清單 (先前稱為 Teams 應用程式資訊清單) 。 應用程式資訊清單會說明您的應用程式如何整合至 Microsoft Teams 產品。

建立 Teams 應用程式資訊清單

若要建立資訊清單，請遵循下列步驟：

1. 建立新的 JSON 檔案。 您的應用程式資訊清單必須符合 應用程式資訊清單結構描述中定義的結構描述 1.20 版本。

2. 將下列程式碼新增至 JSON 檔案：

   應用程式資訊清單

   {
    "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.schema.json",
    "manifestVersion": "1.20",
    "version": "1.0.3",
    "id": "<<YOUR-MICROSOFT-APP-ID>>",
    "packageName": "com.microsoft.teams.extension",
    "developer": {
        "name": "Teams App, Inc.",
        "websiteUrl": "https://www.example.com",
        "privacyUrl": "https://www.example.com/termofuse",
        "termsOfUseUrl": "https://www.example.com/privacy"
    },
    "icons": {
        "color": "color.png",
        "outline": "outline.png"
    },
    "name": {
        "short": "Search ME API",
        "full": "Search ME API full"
    },
    "description": {
        "short": "product app for testing API Message Extensions",
        "full": "product app for testing API Message Extensions"
    },
    "accentColor": "#FFFFFF",
    "composeExtensions": [
        {
            "composeExtensionType": "",
            "apiSpecificationFile": "",
            "commands": [
                {
                    "context": [
                        "compose"
                    ],
                    "type": "query",
                    "title": "API for fetching Klarna.",
                    "id": "",
                    "parameters": [
                        {
                            "name": "",
                            "title": "",
                            "description": ""
                        }
                    ],
                    "description": "",
                    "apiResponseRenderingTemplateFile": ""
                }
            ]
        }
    ],
    "permissions": [
        "identity",
        "messageTeamMembers"
    ],
    "validDomains": []
   }
   

3. 更新應用程式資訊清單屬性，如下所示：

   • <<YOUR-MICROSOFT-APP-ID>>取代為 Bot 的 Microsoft 應用程式識別碼。
   • 將 的值 composeExtensionType 更新為 apiBased。
   • 將 的 apiSpecificationFile 值更新為 OpenAPI 描述檔案的路徑。
   • 將 的值 commands.id 更新為 searchTools。
   • 將 的值 commands.title 更新為 Search for AI Tools。
   • 將 的值 commands.description 更新為 Search for AI Tools。
   • 將 的值 parameters.name 更新為 search。 如果沒有參數，則值必須是查詢參數，或者 properties.name 如果參考要求主體架構中的屬性。
   • 更新為 apiResponseRenderingTemplateFile 回應轉譯範本檔案的路徑。
   • 將 的 validDomains 值更新為 service URL OpenAPI 描述檔案中定義的端點。

4. 將 Teams 應用程式資訊清單儲存在儲存 OpenAPI 描述文件和回應轉譯範本的相同資料夾中。

   • 您需要彩色影像和外框影像。 這些影像應該包含在資料夾中，並在 Teams 應用程式資訊清單中參照。

   • 將資料夾的內容壓縮。 zip 檔案必須包含下列檔案：

     • OpenAPI 描述文件
     • 回應轉譯範本
     • 應用程式資訊清單
     • 色彩圖示
     • 大綱圖示

將自訂應用程式上傳至 Teams

登入 Teams 測試環境以在 Teams 中測試您的應用程式。 若要在 Teams 中上傳自訂應用程式，請遵循下列步驟：

1. 移至 Microsoft Teams 並使用您的測試租用戶認證登入。

2. 移至 [應用程式] [管理>您的應用程式>] [上傳應用程式]。

3. 選取 [上傳自訂的應用程式]。

4. 選取建立的 zip 檔案，然後選取 [ 開啟]。

5. 選取 [新增]。

   

6. 選取 [開啟]。

   

7. 移至聊天，然後選取 + 郵件撰寫區域，然後搜尋您的應用程式。

8. 選取應用程式並進行搜尋查詢。

   

9. 應用程式會在聊天視窗中以 [調適型卡片] 回應。

10. 選取 [傳送]。

    

恭喜！ 你成功了！ 您已了解如何使用 OpenAPI 描述文件建立 API 型訊息擴充功能。

基於動作的訊息擴充功能的主要特點：

• 向使用者顯示強制回應快顯視窗，以收集或顯示資訊。
• 從撰寫郵件區域、命令方塊或從郵件觸發動作命令。

此逐步指南可協助您建立 Teams 動作型訊息擴充功能，以從撰寫訊息和訊息區域啟動動作。 在本教學課程結束時，您可以達成下列輸出：

先決條件

請確定您已安裝下列工具並設定開發環境：

設定本機環境

1. 開啟 Microsoft-Teams-Samples。

2. 選取 [代碼]。

3. 從下拉式功能表中，選取 [使用 GitHub Desktop 開啟]。

   

4. 選取 [複製]。

註冊 Microsoft Entra 應用程式

下列步驟可協助您在 Azure 入口網站中建立及註冊您的 Bot：

• 建立並註冊您的 Azure 應用程式。
• 建立用戶端密碼以啟用 Bot 的 SSO 驗證。
• 新增 Teams 頻道以部署 Bot。
• 使用建議的) 或 ngrok (開發人員通道建立到 Web 伺服器端點的通道。
• 將訊息端點新增至您建立的開發通道。

新增應用程式註冊

1. 移至 Azure 入口網站。

2. 選取應用程式註冊。

   

3. 選取 [+ 新增註冊]。

   

4. 輸入您應用程式的名稱。

5. 選取 [任何組織目錄中的帳戶] ([任何Microsoft Entra ID租用戶 - 多租用戶) ]。

6. 選取 [註冊]。

   

   您的應用程式已在 Microsoft Entra ID 中註冊。 應用程式概觀頁面隨即顯示。

   

   注意

   將 應用程式 (用戶端 的應用程式識別碼儲存) 和 目錄 (租用戶) 識別碼 ，以供進一步使用。

建立通道

請遵循下列兩種方法之一建立通道。

ngrok http --host-header=localhost 3978

新增 Web 驗證

1. 在左側窗格的 [管理] 底下，選取 [驗證]。

2. 選取 [新增平台>Web]。

   

3. 輸入應用程式的重新導向 URI，方法是附加 auth-end 至完整網域名稱。 例如， https://your-devtunnel-domain/auth-end 或 https://your-ngrok-domain/auth-end。

4. 在 [隱含授權和混合式流程] 底下，選取 [存取權杖 ] 和 [識別碼權杖] 核取方塊。

5. 選取 [設定]。

   

6. 在 [Web] 下，選取 [新增 URI]。

7. 輸入 https://token.botframework.com/.auth/web/redirect。

8. 選取 [儲存]。

   

建立用戶端密碼

1. 在左側窗格的 [管理] 底下，選取 [憑證 & 秘密]。

2. 在 [用戶端密碼] 底下，選取 [+ 新增用戶端密碼]。

   

   新增 用戶端密碼 視窗隨即出現。

3. 輸入 描述。

4. 選取 [新增]。

   

5. 在 [值] 底下，選取 [複製到剪貼簿] 以儲存用戶端密碼值以供進一步使用。

   

新增 API 權限

1. 在左窗格中，選取 API 權限。

2. 選取 [+ 新增權限]。

   

3. 選取 [Microsoft Graph]。

4. 選取 [委派的權限]。

5. 選取 [使用者>User.Read]。

6. 選取 [新增權限]。

   

   注意

   • 如果應用程式未獲得 IT 系統管理員同意，使用者必須在第一次使用應用程式時提供同意。
   • 只有當 Microsoft Entra 應用程式已在不同的租用戶中註冊時，使用者才需要同意 API 權限。

新增應用程式識別碼 URI

1. 在左側窗格的 [管理] 底下，選取 [ 公開 API]。

2. 在 應用程式識別碼 URI 旁邊，選取 [新增]。

   

3. 以api://botid-{AppID}格式更新應用程式識別碼 URI，然後選取 [儲存]。

   

新增範圍

1. 在左側窗格的 [管理] 底下，選取 [ 公開 API]。

2. 選取 [+ 新增範圍]。

   

3. 輸入 access_as_user 做為 範圍名稱。

4. 在 [ 誰可以同意？] 底下，選取 [系統管理員和使用者]。

5. 更新其餘欄位的值，如下所示：

   • 輸入 Teams 可以存取使用者的設定檔作為管理員同意顯示名稱。

   • Enter 允許 Teams 以目前使用者身分呼叫應用程式的 Web API，作為管理員同意描述。

   • 輸入 Teams 可以存取使用者設定檔，並代表使用者提出要求 ，作為 使用者同意顯示名稱。

   • 輸入 [允許 Teams 以與使用者相同的權限呼叫此應用程式的 API ] 作為使用者 同意描述。

6. 確定 [狀態 ] 已設定為 [已啟用]。

7. 選取 [新增範圍]。

   下圖顯示欄位和值：

   

   注意

   範圍名稱必須與應用程式識別碼 URI 相符，/access_as_user並在結尾附加。

   

新增用戶端應用程式

1. 在左側窗格的 [管理] 底下，選取 [ 公開 API]。

   在 [授權的用戶端應用程式] 底下，識別您要為應用程式的 Web 應用程式授權的應用程式。

2. 選取 [+ 新增用戶端應用程式]。

   

3. 新增 Teams 行動裝置或桌面和 Teams Web 應用程式。

   1. 對於 Teams 行動裝置或桌面版：將 用戶端識別碼 輸入為 1fec8e78-bce4-4aaf-ab1b-5451cc387264。

      

   2. 針對 Teams Web：將 用戶端識別碼 輸入為 5e3ce6c0-2b1f-4285-8d4b-75ee78787346。

      

4. 選取 [ 授權範圍 ] 核取方塊。

5. 選取 [新增應用程式]。

   

   下圖顯示 用戶端識別碼：

   

建立您的 Bot

建立 Azure Bot 資源

1. 移至 [首頁]。

2. 選取 [+ 建立資源]。

3. 在搜尋方塊中，輸入 Azure Bot。

4. 選取 Enter。

5. 選取 Azure Bot。

6. 選取 [建立]。

   

7. 在 [Bot 控點] 中輸入機器人名稱。

8. 從下拉式清單中選取您的 訂閱 。

9. 從下拉式清單中選取您的 資源群組 。

   

   如果您沒有現有的資源群組，您可以建立新的資源群組。 若要建立新的資源群組，請遵循下列步驟：

   1. 選取 [建立新項目]。
   2. 輸入資源名稱，然後選取 [確定]。
   3. 從 [新增資源群組位置] 下拉式清單選取位置。

   

10. 在 [定價] 底下，選取 [變更方案]。

    

11. 選取 FO Free>Select。

    

12. 在 [Microsoft 應用程式識別碼] 底下，選取 [ 應用程式類型 ] 做 為 [多租用戶]。

13. 在 建立類型中，選取 使用現有的應用程式註冊。

14. 輸入 應用程式識別碼。

    注意

    您無法建立多個具有相同 Microsoft 應用程式識別碼的 Bot。

15. 選取 [檢閱 + 建立]。

    

16. 驗證通過之後，選取 [建立]。

    Bot 需要幾分鐘的時間來佈建。

17. 選取 [移至資源]。

    

    您已成功建立 Azure Bot。

    

新增 Teams 頻道

1. 在左窗格中，選取 頻道。

2. 在 [可用頻道] 底下，選取 [Microsoft Teams]。

   

3. 選取核取方塊以接受 服務條款。

4. 選取 [同意]。

   

5. 選取 [套用]。

   

新增訊息端點

使用下列其中一種方式來新增訊息端點：

設定應用程式設定和資訊清單檔案

1. 移至複製存放庫中的 appsettings.json 檔案。

   

2. 開啟 appsettings.json 檔案並更新下列資訊：

   • 設定 "MicrosoftAppId" 為 Bot 的 Microsoft 應用程式識別碼。
   • 設定 "MicrosoftAppPassword" 為 Bot 的用戶端密碼識別碼 值。
   • 設定 ConnectionName 為 OAuth 連線名稱。
   • 設定 "MicrosoftAppType" 為 MultiTenant。
   • 設定 "MicrosoftAppTenantId" 為 常見。

   

3. 移至複製存放庫中的 manifest.json 檔案。

   

4. 開啟 manifest.json 檔案並更新下列變更：

   • 以您的 Microsoft 應用程式識別碼取代所有出現的項目"{TODO: MicrosoftAppId}"。
   • 設定 "<<domain-name>>" 為您的 ngrok 或開發人員通道網域。

   

建置及執行服務

若要建置及執行服務，請使用 Visual Studio 或命令列。

    dotnet run

將動作訊息擴充功能應用程式新增至 Teams

1. 在複製的存放庫中，移至 範例>msgext-action>csharp>TeamsAppManifest。

2. 使用下列位於 Manifest 資料夾中的檔案建立 .zip：

   • manifest.json
   • icon-outline.png
   • icon-color.png

   

3. 在 Teams 用戶端中，選取 應用程式 圖示。

4. 選取 管理您的應用程式。

5. 選取 [ 上傳應用程式]。

6. 尋找 [ 上傳自訂應用程式] 選項。 如果您看到該選項，表示已啟用自訂應用程式上傳。

   

   注意

   如果您找不到上傳自訂應用程式的選項，請與您的 Teams 系統管理員連絡。

7. 選取 [ 開啟 ] 以上傳您在 TeamsAppManifest 資料夾中建立的 messaging.zip 檔案。

   

8. 選取 [新增]。

   

9. 選取 [ 開啟] 以在個人範圍內開啟應用程式。

   或者，您可以搜尋並選取所需的範圍，或從清單中選取頻道、聊天或會議，然後在對話方塊中移動以選取 [執行]。

   

在 Teams 中與應用程式互動

1. 從撰寫方塊命令清單中選取 [建立卡片 ] 命令。

   

2. 在強制回應快顯視窗中輸入您的資訊。

   

3. 選取 [提交]。

   

4. 從溢位功能表中選取 [其他選項] (...) 。

5. 選取 [其他動作>] [共用郵件]。

   

6. 如果您想要包含影像，請選取 [在英雄卡片中包含影像 ] 核取方塊，然後選取 [提交]。

   

完成挑戰

你想出這樣的東西嗎？

您已完成開始使用 [動作訊息擴充功能 ] 應用程式的教學課程！

根據 Bot 所參與的交談，Bot 的行為會有所不同：

• 頻道和群組聊天交談中的 Bot 需要使用者使用 @mention Bot。
• 一對一交談中的 Bot 不需要 @mention。 使用者傳送的所有訊息都會路由傳送至 Bot。

本逐步指南可協助您使用 SSO 驗證建立 Bot。 您會看到下列輸出：

建置 Bot 的必要條件

請確定您已安裝下列工具並設定開發環境：

設定 Teams 開發租用戶

租用戶就像是一個空間或容器，您可以在其中為組織在 Teams 中聊天、共用檔案和開會。 您也可以上傳並測試自訂應用程式。

檢查自訂應用程式上傳選項

建立應用程式之後，您必須在 Teams 中載入應用程式，而不要將其發佈。 此程序稱為自訂應用程式上傳。 請登入您的 Microsoft 365 帳戶以檢視此選項。

您是否已經有租用戶，而且您是否擁有系統管理員存取權？ 讓我們檢查一下您是否真的這樣做！

若要驗證 Teams 中的自訂上傳應用程式：

1. 在 Teams 用戶端中，選取 應用程式 圖示。

2. 選取 管理您的應用程式。

3. 選取 [ 上傳應用程式]

4. 尋找 [ 上傳自訂應用程式] 選項。 如果您看到該選項，表示已啟用自訂應用程式上傳。

   

建立免費的 Teams 開發人員租用戶

如果您沒有 Teams 開發人員帳戶，您可以免費取得。 加入 Microsoft 365 開發人員計畫！

1. 移至 Microsoft 365 開發人員計畫。

2. 選取 [立即加入] ，並依照畫面上的指示操作。

3. 在歡迎畫面中，選取 [ 設定 E5 訂閱]。

4. 設定系統管理員帳戶。 完成後，將顯示下列畫面。

   

5. 使用您剛設定的新系統管理員帳戶登入 Teams。 確認您在 Teams 中有 上傳自訂應用程式選項 。

設定本機環境

請依照下列步驟複製存放庫：

1. 開啟 Microsoft-Teams-Samples。

2. 選取 [代碼]。

3. 從下拉式功能表中，選取 [使用 GitHub Desktop 開啟]。

   

4. 選取 [複製]。

註冊 Microsoft Entra 應用程式

下列步驟可協助您在 Azure 入口網站中建立及註冊您的 Bot：

• 建立並註冊您的 Azure 應用程式。
• 建立用戶端密碼以啟用 Bot 的 SSO 驗證。
• 新增 Teams 頻道以部署 Bot。
• 使用建議的) 或 ngrok (開發人員通道建立到 Web 伺服器端點的通道。
• 將訊息端點新增至您建立的開發通道。

新增應用程式註冊

1. 移至 Azure 入口網站。

2. 選取應用程式註冊。

   

3. 選取 [+ 新增註冊]。

   

4. 輸入您應用程式的名稱。

5. 視需要選取租用戶選項。

6. 選取 [註冊]。

   

   您的應用程式已在 Microsoft Entra ID 中註冊。 應用程式概觀頁面隨即顯示。

   

   注意

   將 應用程式 (用戶端 的應用程式識別碼儲存) 和 目錄 (租用戶) 識別碼 ，以供進一步使用。

建立通道

請遵循下列兩種方法之一建立通道。

ngrok http --host-header=localhost 3978

新增 Web 驗證

1. 在左側窗格的 [管理] 底下，選取 [驗證]。

2. 選取 [新增平台>Web]。

   

3. 輸入應用程式的重新導向 URI，方法是附加 auth-end 至完整網域名稱。 例如， https://your-devtunnel-domain/auth-end 或 https://your-ngrok-domain/auth-end。

4. 在 [隱含授權和混合式流程] 底下，選取 [存取權杖 ] 和 [識別碼權杖] 核取方塊。

5. 選取 [設定]。

   

6. 在 [Web] 下，選取 [新增 URI]。

7. 輸入 https://token.botframework.com/.auth/web/redirect。

8. 選取 [儲存]。

   

建立用戶端密碼

1. 在左側窗格的 [管理] 底下，選取 [憑證 & 秘密]。

2. 在 [用戶端密碼] 底下，選取 [+ 新增用戶端密碼]。

   

   新增 用戶端密碼 視窗隨即出現。

3. 輸入 描述。

4. 選取 [新增]。

   

5. 在 [值] 底下，選取 [複製到剪貼簿] 以儲存用戶端密碼值以供進一步使用。

   

新增 API 權限

1. 在左窗格中，選取 API 權限。

2. 選取 [+ 新增權限]。

   

3. 選取 [Microsoft Graph]。

4. 選取 [委派的權限]。

5. 選取 [使用者>User.Read]。

6. 選取 [新增權限]。

   

   注意

   • 如果應用程式未獲得 IT 系統管理員同意，使用者必須在第一次使用應用程式時提供同意。
   • 只有當 Microsoft Entra 應用程式已在不同的租用戶中註冊時，使用者才需要同意 API 權限。

新增應用程式識別碼 URI

1. 在左側窗格的 [管理] 底下，選取 [ 公開 API]。

2. 在 應用程式識別碼 URI 旁邊，選取 [新增]。

   

3. 以api://botid-{AppID}格式更新應用程式識別碼 URI，然後選取 [儲存]。

   

新增範圍

1. 在左側窗格的 [管理] 底下，選取 [ 公開 API]。

2. 選取 [+ 新增範圍]。

   

3. 輸入 access_as_user 做為 範圍名稱。

4. 在 [ 誰可以同意？] 底下，選取 [系統管理員和使用者]。

5. 更新其餘欄位的值，如下所示：

   1. 輸入 Teams 可以存取使用者的設定檔作為管理員同意顯示名稱。

   2. Enter 允許 Teams 以目前使用者身分呼叫應用程式的 Web API，作為管理員同意描述。

   3. 輸入 Teams 可以存取使用者設定檔，並代表使用者提出要求 ，作為 使用者同意顯示名稱。

   4. 輸入 [允許 Teams 以與使用者相同的權限呼叫此應用程式的 API ] 作為使用者 同意描述。

6. 確定 [狀態 ] 已設定為 [已啟用]。

7. 選取 [新增範圍]。

   下圖顯示欄位和值：

   

   注意

   範圍名稱必須與應用程式識別碼 URI 相符，/access_as_user並在結尾附加。

   

新增用戶端應用程式

1. 在左側窗格的 [管理] 底下，選取 [ 公開 API]。

   在 [授權的用戶端應用程式] 底下，識別您要為應用程式的 Web 應用程式授權的應用程式。

2. 選取 [+ 新增用戶端應用程式]。

   

3. 新增 Teams 行動裝置或桌面和 Teams Web 應用程式。

   1. 對於 Teams 行動裝置或桌面版：將 用戶端識別碼 輸入為 1fec8e78-bce4-4aaf-ab1b-5451cc387264。

      

   2. 針對 Teams Web：將 用戶端識別碼 輸入為 5e3ce6c0-2b1f-4285-8d4b-75ee78787346。

      

4. 選取 [ 授權範圍 ] 核取方塊。

5. 選取 [新增應用程式]。

   

   下圖顯示 用戶端識別碼：

   

更新資訊清單

1. 在左窗格中，選取 [資訊清單]。

2. 設定 [收件者2] requestedAccessTokenVersion 的值，然後選取 [儲存]。

   

建立您的 Bot

建立 Azure Bot 資源

1. 移至 [首頁]。

2. 選取 [+ 建立資源]。

3. 在搜尋方塊中，輸入 Azure Bot。

4. 選取 Enter。

5. 選取 Azure Bot。

6. 選取 [建立]。

   

7. 在 [Bot 控點] 中輸入機器人名稱。

8. 從下拉式清單中選取您的 訂閱 。

9. 從下拉式清單中選取您的 資源群組 。

   

   如果您沒有現有的資源群組，您可以建立新的資源群組。 若要建立新的資源群組，請遵循下列步驟：

   1. 選取 [建立新項目]。
   2. 輸入資源名稱，然後選取 [確定]。
   3. 從 [新增資源群組位置] 下拉式清單選取位置。

   

10. 在 [定價] 底下，選取 [變更方案]。

    

11. 選取 FO Free>Select。

    

12. 在 [Microsoft 應用程式識別碼] 底下，選取 [ 應用程式類型 ] 做 為 [多租用戶]。

13. 在 建立類型中，選取 使用現有的應用程式註冊。

14. 輸入 應用程式識別碼。

    注意

    您無法建立多個具有相同 Microsoft 應用程式識別碼的 Bot。

15. 選取 [檢閱 + 建立]。

    

16. 驗證通過之後，選取 [建立]。

    Bot 需要幾分鐘的時間來佈建。

17. 選取 [移至資源]。

    

    您已成功建立 Azure Bot。

    

新增 Teams 頻道

1. 在左窗格中，選取 頻道。

2. 在 [可用頻道] 底下，選取 [Microsoft Teams]。

   

3. 選取核取方塊以接受 服務條款。

4. 選取 [同意]。

   

5. 選取 [套用]。

   

新增訊息端點

使用下列其中一種方式來新增訊息端點：

新增 OAuth 連線設定

1. 在左窗格中，選取 設定。

2. 選取 新增 OAuth 連線設定。

3. 在 [新增連線設定] 底下，更新下列詳細資料：

   • 名稱：輸入新連線設定的名稱。 您可以在 Bot 服務程式碼的設定中使用該名稱。
   • 服務提供者：從下拉式清單中選取 [Azure Active Directory v2]。
   • 用戶端識別碼：更新您的 Microsoft 應用程式識別碼。
   • 用戶端密碼： 更新用戶端密碼 值。
   • 權杖交換 URL：更新 應用程式識別碼 URI。
   • 租用戶識別碼： 輸入 Common。
   • 範圍： 輸入 User.Read。

4. 選取 [儲存]。

   

設定應用程式設定和資訊清單檔案

1. 移至複製存放庫中的 appsettings.json 檔案。

   

2. 開啟 appsettings.json 檔案並更新下列資訊：

   • 設定 "MicrosoftAppId" 為 Bot 的 Microsoft 應用程式識別碼。
   • 設定 "MicrosoftAppPassword" 為 Bot 的用戶端密碼識別碼 值。
   • 設定 ConnectionName 為 OAuth 連線名稱。
   • 設定 "MicrosoftAppType" 為 MultiTenant。
   • 設定 "MicrosoftAppTenantId" 為 常見。

   

3. 移至複製存放庫中的 manifest.json 檔案。

   

4. 開啟 manifest.json 檔案並更新下列變更：

   • 以您的 Microsoft 應用程式識別碼取代所有出現的項目"{TODO: MicrosoftAppId}"。
   • 設定 "<<domain-name>>" 為您的 ngrok 或開發人員通道網域。

   

建置及執行服務

1. 開啟 Visual Studio。

2. 移至 [檔案>]、[開啟>專案/解決方案...]

   

3. 從 bot-conversation-sso-quickstart>csharp_dotnetcore 資料夾，選取 BotConversationSsoQuickstart.sln 檔案。

   

4. 選取 F5 以執行專案。

5. 如果出現 [安全性警告] 對話方塊，請選取 [是]。

   

   網頁隨即開啟，並顯示一則訊息「 您的 Bot 已準備就緒！」。

   注意

   只有當您瀏覽至 localhost URL 時，才會顯示此頁面。

   

   疑難排解

   如果您收到 「找不到套件」 錯誤，請依照下列步驟執行：

   1. 移至 [工具]、[>NuGet] 、[套件管理員>]、[套件管理員設定]。
   2. 在出現的 [選項] 視窗中，選取 [NuGet 套件管理員>套件來源]。
   3. 選取 [新增]。
   4. 在 [名稱] 中輸入， nuget.org 並在 [來源] 中輸入 https://api.nuget.org/v3/index.json。
   5. 選取 [更新]，然後 [確定]。
   6. 重建您的專案。

在 Teams 中上傳 Bot

1. 在複製的存放庫中，移至 Microsoft-Teams-Samples>samples>bot-conversation-sso-quickstart>csharp_dotnetcore>TeamsApp>appPackage。

2. 使用下列位於 appPackage 資料夾中的檔案來建立 .zip 檔案：

   • manifest.json
   • outline.png
   • color.png

   

3. 前往 Microsoft Teams。

   1. 在 Teams 用戶端中，選取 應用程式。
   2. 選取 管理您的應用程式。
   3. 選取 [ 上傳應用程式]。
   4. 尋找 [ 上傳自訂應用程式] 選項。

   

4. 選取 [ 開啟 ] 以上傳您在 [資訊清單 ] 資料夾中建立的 .zip 檔案。

   

5. 選取 [ 新增 ] 以將 Bot 新增至您的聊天。

   

6. 選取 [開啟]。

   

   您可以傳送訊息來與 Bot 互動。 Bot 會交換 SSO 權杖，並代表您呼叫圖形 API。 除非您傳送訊息要求登出，否則它會讓您保持登入狀態。

7. 傳送訊息給 bot。 交談機器人第一次要求同意。

8. 針對桌面： 選取 [繼續] 以將存取 Bot 的權限授與 Teams 用戶端。

   

   注意

   現在您已使用 Bot 應用程式設定 SSO，這是您唯一需要給予同意的時間。

9. 行動裝置：選取 [接受]。

   注意

   現在您已在行動裝置中使用 Bot 應用程式設定 SSO，這是您唯一需要提供同意的時間。

   

你想出這樣的東西嗎？

您已完成以開始使用 SSO 驗證建置 Bot 的教學課程。

本逐步指南可協助您使用 Visual Studio Code 中的 Agents Toolkit 建立訊息擴充功能 Teams 應用程式。 完成本指南之後，您會看到下列輸出：

先決條件

請確定您已安裝下列工具來建置和部署您的應用程式。

準備開發環境

安裝必要的工具之後，請設定開發環境。

安裝 Microsoft 365 代理程式工具組

Microsoft 365 Agents Toolkit (先前稱為 Teams Toolkit) 透過為應用程式佈建和部署雲端資源並發佈到 Teams Store 的工具來協助簡化開發流程。

您可以將 Agents Toolkit 與 Visual Studio Code 搭配使用，或稱為 Microsoft 365 Agents Toolkit CLI (先前稱為 TeamsFx CLI) 的命令列介面。

npm install -g @microsoft/m365agentstoolkit-cli

sudo npm install -g --unsafe-perm @microsoft/m365agentstoolkit-cli

設定您的 Teams 開發租用戶

租用戶是貴組織在 Teams 中的一個空間或容器，您可在這裡聊天、共用檔案和開會。 這個空間也是您上傳和測試應用程式的地方。 讓我們確認您是否已準備好與租用戶一起開發。

檢查 [上傳應用程式] 選項

建立自訂應用程式之後，您必須使用 [ 上傳自訂應用程式 ] 選項，將您的應用程式上傳至 Teams。 登入您的 Microsoft 365 帳戶以檢查此選項是否已啟用。

下列步驟可協助您確認您是否可以在 Teams 中上傳應用程式：

1. 在 Teams 用戶端中，選取 應用程式 圖示。

2. 選取 管理您的應用程式。

3. 選取 [ 上傳應用程式]。

4. 尋找 [ 上傳自訂應用程式] 選項。 如果顯示該選項，您可以上傳自訂應用程式。

   

   注意

   如果您找不到上傳自訂應用程式的選項，請連絡您的 Teams 系統管理員。

建立免費的 Teams 開發人員租用戶 (選擇性)

如果您沒有 Teams 開發人員帳戶，請加入 Microsoft 365 開發人員計畫。

1. 移至 Microsoft 365 開發人員計畫。

2. 選取 [立即加入] ，並依照畫面上的指示操作。

3. 在歡迎畫面中，選取設定 E5 訂閱。

4. 設定您的系統管理員帳戶。 完成後，隨即出現下列畫面：

   

5. 使用您剛才設定的系統管理員帳戶登入 Teams。 確認您在 Teams 中有 上傳自訂應用程式選項 。

取得免費的 Azure 帳戶

如果您想要在 Azure 中託管您的應用程式或存取資源，您必須擁有 Azure 訂閱。 開始之前先建立免費帳戶。

建立訊息擴充應用程式的專案工作區

現在，讓我們建立您的第一個訊息擴充應用程式。

訊息擴充功能可讓您透過按鈕和表單與 Web 服務互動。 直接在 Teams 用戶端中使用郵件撰寫區、命令方塊或訊息，在外部系統中搜尋和啟動動作。 訊息延伸模組仰賴 Bot 來提供使用者與您的程式碼之間的對話。

Teams 訊息擴充功能有兩種類型：

• 搜尋命令：您可以搜尋外部系統，並將結果以卡片的形式插入到訊息中。
• 動作命令：您可以向使用者顯示強制回應快顯視窗，以收集或顯示資訊。 然後，您可以處理他們的互動，並將資訊傳回 Teams。

讓我們使用搜尋命令建立訊息擴充功能應用程式。 首先，設定新的 Teams 專案，以建立訊息擴充功能應用程式。

在本教學課程中，您將了解：

1. 如何使用 Agents Toolkit 設定新的訊息擴充專案。
2. 關於應用程式專案的目錄結構。

建立您的訊息擴充專案工作區

如果先決條件齊全，讓我們開始吧！

訊息擴充應用程式原始程式碼導覽

訊息擴充功能會使用 Bot Framework 透過交談與您的服務互動。 搭建腳手架後，在 [資源管理器] 下檢視專案目錄和檔案。

建置並執行您的第一個訊息擴充應用程式

使用 Agents Toolkit 設定專案工作區之後，就可以建立專案了。 您必須登入您的 Microsoft 365 帳戶。

登入您的 Microsoft 365 帳戶

使用您在加入 Microsoft 365 開發人員計畫時所建立的系統管理員帳戶登入。

在本機環境中組建及執行您的應用程式

現在您可以在本機組建和偵錯您的第一個 Teams 訊息擴充功能應用程式。

在本機組建並執行您的應用程式

1. 選取 Visual Studio Code 中的 F5 鍵，以偵錯模式執行應用程式。

   注意

   如果 Agents Toolkit 無法驗證特定的先決條件，則會提示您檢查。

   
   
   了解當您在偵錯工具中本機執行應用程式時會發生什麼情況。

   當您選取 F5 時，Agents Toolkit 會執行下列功能：

   1. 檢查下列必要條件：

      1. 您已使用 Microsoft 365 帳戶登入。
      2. 您的 Microsoft 365 帳戶已啟用自訂應用程式上傳功能。
      3. 已安裝支援 Node.js 版本。
      4. Bot 應用程式所需的連接埠可用。

   2. 安裝 npm 套件

   3. 啟動開發人員通道以建立 HTTP 通道。

   4. 在 Microsoft Entra ID 中註冊應用程式並設定應用程式。

   5. 在 Bot Framework 中註冊 Bot 應用程式並設定應用程式。

   6. 在 Teams 開發人員入口網站中註冊應用程式並設定應用程式。

   7. 啟動本機託管的訊息擴充功能應用程式。

   8. 在網頁瀏覽器中啟動 Teams，並上傳 Teams 應用程式。

   

   當您第一次偵錯應用程式時，Teams 會下載相依性並建置應用程式。 此程序可能需要 3 到 5 分鐘完成。

2. 建置完成後，Teams 會在瀏覽器視窗中開啟。 如果出現提示，請使用您的 Microsoft 365 帳戶登入。

3. 此時會開啟一個對話方塊，讓您將訊息擴充功能應用程式新增至 Teams。 選取 [新增]。

   

   Teams 會載入訊息擴充功能應用程式。

   

   由於訊息擴充功能應用程式仰賴 Bot 來啟用使用者與 Web 服務之間的通訊，因此您的應用程式會載入 Bot 的聊天功能。

   • 如果您在建立訊息擴充功能應用程式之前已建立 Bot 應用程式，Teams 會在您建立的 Bot 應用程式中載入訊息擴充功能。 可以看到 Bot 應用程式先前的聊天訊息。
   • 如果您已先建立訊息擴充功能，Teams 會在 Teams 上開啟的最新聊天中載入您的應用程式。

測試您的應用程式

您的應用程式第一次載入時，訊息擴充應用程式會開啟供您測試。 此範例應用程式可讓您從軟體登錄中搜尋開放原始碼 npm 套件。

如何執行搜尋查詢

如何開啟訊息擴充功能應用程式

您在上一個步驟中測試了訊息擴充功能應用程式的搜尋功能。 現在，了解開啟訊息擴充功能應用程式的不同方式。

瞭解如果您的應用程式無法在本機執行時進行疑難排解

若要在 Teams 中執行您的應用程式，您必須擁有允許自訂應用程式上傳的 Microsoft 365 開發帳戶。 您可以在 [先決條件] 章節深入了解自訂應用程式上傳。

部署您的第一個 Teams 應用程式

讓我們使用 Agents Toolkit 在 Azure 上部署您的第一個訊息擴充功能應用程式。

登入您的 Azure 帳戶

登入您的 Azure 帳戶以存取 Microsoft Azure 入口網站，並佈建新的雲端資源以支援您的應用程式。

將應用程式部署到 Azure

部署包含兩個步驟。 首先，建立必要的雲端資源 (也稱為佈建) 。 然後，您的應用程式程式碼會複製到建立的雲端資源中。 您將在本教學課程中部署訊息擴充功能應用程式。

執行已部署的應用程式

佈建和部署步驟完成後，請移至 [ 執行和偵錯 ] (Ctrl+Shift+D ，或在 Agents Toolkit 中 檢視 > [執行) ]。

1. 選取 [執行和偵錯 ] 下拉式功能表。

2. 選取 [ 在 Teams (Edge) 啟動遠端 ]。

3. 選取 ▷ 按鈕。

   

4. 此時會開啟一個對話方塊，將已部署的應用程式安裝到 Teams。 選取 [新增]。

   

   Teams 會在最近的聊天中開啟訊息擴充功能應用程式。

   

了解將應用程式部署到 Azure 時會發生什麼情況

部署前，應用程式會在本機執行。

• 後端使用 Azure Functions 核心工具執行。
• 應用程式 HTTP 端點，Microsoft Teams 載入應用程式的地方，會在本機執行。

部署程序包含兩個步驟。 您可以在作用中的 Azure 訂閱上佈建資源，然後將應用程式的後端和前端程式碼部署或上傳到 Azure。

• 後端 （如果已設定） 會使用各種 Azure 服務，包括 Azure App 服務 和 Azure 儲存。
• 前端應用程式會部署至專為靜態 Web 主機所設定的 Azure 儲存帳戶。

恭喜

您已完成使用 JavaScript 建置訊息擴充應用程式的教學課程！

你想出這樣的東西嗎？

本逐步指南可協助您使用 Microsoft 365 Agents Toolkit (先前稱為 Teams Toolkit) 建立索引標籤。 完成本指南之後，您會看到下列輸出：

建置應用程式的必要條件

以下是建置及部署 Teams 應用程式時需要安裝的工具清單。

安裝代理程式工具組

Agents Toolkit 可透過為您的應用程式建立專案基架的工具來協助簡化開發程序。 它會為所有選定的功能建立必要的目錄結構，並將所需的檔案準備好建置專案。

您可以下載最新的 Visual Studio 安裝程式。 Agents Toolkit 可作為 Visual Studio 中的擴充功能使用。

在快顯的工作負載視窗中開啟 Visual Studio 安裝程式之後：

1. 選取 ASP.NET 和 Web 開發。

2. 在 安裝詳細資料>[選用] 底下，選取 [Microsoft Teams 開發工具]。

3. 選取 [安裝]。

   

4. 選取 啟動。 Visual Studio 2022 應用程式視窗隨即出現。

   

5. 移至 [擴充功能]>[管理擴充功能]。

   

   [管理擴充功能] 視窗隨即出現：

   

6. 在左窗格中，選取 [已安裝]。 可以使用 Microsoft 365 代理程式工具組 擴充功能。

   

設定您的 Teams 開發租用戶

租用戶就像是貴組織在 Teams 中的一個空間或容器，您可以在其中聊天、共用檔案和開會。 此空間也是您上傳和測試自訂應用程式的地方。 讓我們確認您是否已準備好與租用戶一起開發。

檢查自訂應用程式上傳選項

建立應用程式之後，您必須在 Teams 中載入應用程式，而不要將其發佈。 此程序稱為自訂應用程式上傳。 請登入您的 Microsoft 365 帳戶以檢視此選項。

您是否已經有租用戶和系統管理員存取權？ 讓我們檢查一下您是否這樣做了！

確認您是否可以在 Teams 中上傳自訂應用程式：

1. 開啟 Microsoft Teams，選取 [ 應用程式 ] 圖示。

2. 選取 管理您的應用程式。

3. 選取 [ 上傳應用程式]。

4. 尋找 [ 上傳自訂應用程式] 選項。 如果您看到該選項，表示已啟用自訂應用程式上傳。

   

建立免費的 Teams 開發人員租用戶 (選擇性)

如果您沒有 Teams 帳戶，您可以免費取得。 加入 Microsoft 365 開發人員計畫！

1. 移至 Microsoft 365 開發人員計畫。

2. 選取 [立即加入] ，並依照畫面上的指示操作。

3. 在歡迎畫面中，選取 [ 設定 E5 訂閱]。

4. 設定您的系統管理員帳戶。 完成後，隨即出現下列畫面：

   

5. 使用您所設定的系統管理員帳戶登入 Teams。 確認您已在 Teams 中擁有上傳 自訂應用程式 選項。

取得免費的 Azure 帳戶

如果您想要在 Azure 中託管您的應用程式或存取資源，您必須擁有 Azure 訂閱。 開始之前先建立免費帳戶。

現在您已擁有設定帳戶的所有工具。 接下來，讓我們設定您的開發環境並開始建置吧！ 先選取您要建立的應用程式。

使用 C sharp 建立索引標籤應用程式的專案工作區

從建立您的第一個應用程式，開始 Microsoft Teams 應用程式開發。 此應用程式使用索引標籤功能。 如果先決條件齊全，讓我們開始吧！

下列步驟可協助您在 Visual Studio 中為索引標籤應用程式建立專案工作區：

1. 開啟 Visual Studio。

2. 選取 [新增專案]。

   

3. 在搜尋方塊中，輸入 Teams。

4. 接下來選取 [Microsoft 365 代理程式>]。

   

5. 輸入下列詳細資料以設定新專案。

6. 在 [專案名稱] 中輸入必要的專案名稱。

7. 選取儲存專案檔案和資料夾所需的位置。

8. 選取 [建立]。

   

9. 選取 [ 索引標籤>建立]。

   

Teams 索引標籤應用程式會在幾秒鐘內建立。

使用 C sharp 建立和執行您的第一個索引標籤應用程式

使用 Agents Toolkit 設定專案工作區之後，請建置索引標籤應用程式。

登入您的 Microsoft 365 帳戶

使用您的 Microsoft 365 帳戶來登入 Teams。 如果您使用的是 Microsoft 365 開發人員計畫租用戶，則您在註冊時設定的系統管理員帳戶就是您的 Microsoft 365 帳戶。

1. 在方案總管中，在 [解決方案 MyTeamsApp] 底下，以滑鼠右鍵按一下 [MyTeamsApp]。

2. 選取 Microsoft 365 代理程式工具組>選取 Microsoft 365 帳戶。

   

3. 選取 [Microsoft 365 帳戶>繼續]。

   

在 Visual Studio 中本機組建並執行應用程式

若要在本機建置及執行您的應用程式：

1. 選取 [偵錯]> [開始偵錯]，或選取 F5。

   

   Visual Studio 會啟動偵錯程序，並在瀏覽器中開啟 Teams Web 用戶端。 如果出現提示，請使用您的 Microsoft 365 帳戶登入。

2. 選取 [新增]。

   

3. 選取 [ 開啟] 以在個人範圍內開啟應用程式。

或者，您可以搜尋並選取所需的範圍，或從清單中選取頻道或聊天，然後在對話方塊中移動以選取 [執行]。

恭喜，您的第一個索引標籤應用程式已在 Teams 上執行！

您已使用 C# 成功建立索引標籤應用程式。 Agents Toolkit 已將必要的鷹架新增至應用程式的目錄結構。 教學課程現已完成。

此逐步指南可協助您建立索引標籤和訊息擴充功能，以啟用 Microsoft Entra SSO 驗證。 您會看到下列輸出：

新增 SSO 至應用程式的必要條件

請確定您已安裝下列工具並設定開發環境：

設定本機環境

1. 開啟 Microsoft-Teams-Samples。

2. 選取 [代碼]。

3. 從下拉式功能表中，選取 [使用 GitHub Desktop 開啟]。

   

4. 選取 [複製]。

註冊 Microsoft Entra 應用程式

下列步驟可協助您在 Azure 入口網站中建立及註冊您的 Bot：

• 建立並註冊您的 Azure 應用程式。
• 建立用戶端密碼以啟用 Bot 的 SSO 驗證。
• 新增 Teams 頻道以部署 Bot。
• 使用建議的) 或 ngrok (開發人員通道建立到 Web 伺服器端點的通道。
• 將訊息端點新增至您建立的開發通道。

新增應用程式註冊

1. 移至 Azure 入口網站。

2. 選取應用程式註冊。

   

3. 選取 [+ 新增註冊]。

   

4. 輸入您應用程式的名稱。

5. 選取 [任何組織目錄中的帳戶] ([任何Microsoft Entra ID租用戶 - 多租用戶) ]。

6. 選取 [註冊]。

   

   您的應用程式已在 Microsoft Entra ID 中註冊。 應用程式概觀頁面隨即顯示。

   

   注意

   將 應用程式 (用戶端 的應用程式識別碼儲存) 和 目錄 (租用戶) 識別碼 ，以供進一步使用。

建立通道

選取下列其中一種方式來建立通道：

ngrok http --host-header=localhost xxxx

新增 Web 驗證

1. 在左側窗格的 [管理] 底下，選取 [驗證]。

2. 選取 [新增平台>Web]。

   

3. 輸入應用程式的重新導向 URI，方法是附加 auth-end 至完整網域名稱。 例如， https://your-devtunnel-domain/auth-end 或 https://your-ngrok-domain/auth-end。

4. 在 [隱含授權和混合式流程] 底下，選取 [存取權杖 ] 和 [識別碼權杖] 核取方塊。

5. 選取 [設定]。

   

6. 在 [Web] 下，選取 [新增 URI]。

7. 輸入 https://token.botframework.com/.auth/web/redirect。

8. 選取 [儲存]。

   

建立用戶端密碼

1. 在左側窗格的 [管理] 底下，選取 [憑證 & 秘密]。

2. 在 [用戶端密碼] 底下，選取 [+ 新增用戶端密碼]。

   

   新增 用戶端密碼 視窗隨即出現。

3. 輸入 描述。

4. 選取 [新增]。

   

5. 在 [值] 底下，選取 [複製到剪貼簿] 以儲存用戶端密碼值以供進一步使用。

   

新增 API 權限

1. 在左窗格中，選取 API 權限。

2. 選取 [+ 新增權限]。

   

3. 選取 [Microsoft Graph]。

4. 選取 [委派的權限]。

5. 選取 [使用者>User.Read]。

6. 選取 [新增權限]。

   

   注意

   • 如果應用程式未獲得 IT 系統管理員同意，使用者必須在第一次使用應用程式時提供同意。
   • 只有當 Microsoft Entra 應用程式已在不同的租用戶中註冊時，使用者才需要同意 API 權限。

新增應用程式識別碼 URI

1. 在左側窗格的 [管理] 底下，選取 [ 公開 API]。

2. 在 應用程式識別碼 URI 旁邊，選取 [新增]。

   

3. 以 api://your-devtunnel-domain/botid-{AppID} OR api://your-ngrok-domain/botid-{AppID} 格式更新應用程式識別碼 URI，然後選取 [儲存]。

   

   下圖顯示網域名稱：

   

新增範圍

1. 在左側窗格的 [管理] 底下，選取 [ 公開 API]。

2. 選取 [+ 新增範圍]。

   

3. 輸入 access_as_user 做為 範圍名稱。

4. 在 [ 誰可以同意？] 底下，選取 [系統管理員和使用者]。

5. 更新其餘欄位的值，如下所示：

   • 輸入 Teams 可以存取使用者的設定檔作為管理員同意顯示名稱。

   • Enter 允許 Teams 以目前使用者身分呼叫應用程式的 Web API，作為管理員同意描述。

   • 輸入 Teams 可以存取使用者設定檔，並代表使用者提出要求 ，作為 使用者同意顯示名稱。

   • 輸入 [允許 Teams 以與使用者相同的權限呼叫此應用程式的 API ] 作為使用者 同意描述。

6. 確定 [狀態 ] 已設定為 [已啟用]。

7. 選取 [新增範圍]。

   下圖顯示欄位和值：

   

   注意

   範圍名稱必須與應用程式識別碼 URI 相符，/access_as_user並在結尾附加。

   

新增用戶端應用程式

1. 在左側窗格的 [管理] 底下，選取 [ 公開 API]。

   在 [授權的用戶端應用程式] 底下，識別您要為應用程式的 Web 應用程式授權的應用程式。

2. 選取 [+ 新增用戶端應用程式]。

   

3. 新增 Teams 行動裝置或桌面和 Teams Web 應用程式。

   1. 對於 Teams 行動裝置或桌面版：將 用戶端識別碼 輸入為 1fec8e78-bce4-4aaf-ab1b-5451cc387264。

      

   2. 針對 Teams Web：將 用戶端識別碼 輸入為 5e3ce6c0-2b1f-4285-8d4b-75ee78787346。

      

4. 選取 [ 授權範圍 ] 核取方塊。

5. 選取 [新增應用程式]。

   

   下圖顯示 用戶端識別碼：

   

更新資訊清單

1. 在左窗格中，選取 [資訊清單]。

2. 設定 [收件者2] requestedAccessTokenVersion 的值，然後選取 [儲存]。

   

建立 Bot

建立 Azure Bot 資源

1. 移至 [首頁]。

2. 選取 [+ 建立資源]。

3. 在搜尋方塊中，輸入 Azure Bot。

4. 選取 Enter。

5. 選取 Azure Bot。

6. 選取 [建立]。

   

7. 在 [Bot 控點] 中輸入機器人名稱。

8. 從下拉式清單中選取您的 訂閱 。

9. 從下拉式清單中選取您的 資源群組 。

   

   如果您沒有現有的資源群組，您可以建立新的資源群組。 若要建立新的資源群組，請遵循下列步驟：

   1. 選取 [建立新項目]。
   2. 輸入資源名稱，然後選取 [確定]。
   3. 從 [新增資源群組位置] 下拉式清單選取位置。

   

10. 在 [定價] 底下，選取 [變更方案]。

    

11. 選取 FO Free>Select。

    

12. 在 [Microsoft 應用程式識別碼] 底下，選取 [ 應用程式類型 ] 做 為 [多租用戶]。

13. 在 建立類型中，選取 使用現有的應用程式註冊。

14. 輸入 應用程式識別碼。

    注意

    您無法建立多個具有相同 Microsoft 應用程式識別碼的 Bot。

15. 選取 [檢閱 + 建立]。

    

16. 驗證通過之後，選取 [建立]。

    Bot 需要幾分鐘的時間來佈建。

17. 選取 [移至資源]。

    

    您已成功建立 Azure Bot。

    

新增 Teams 頻道

1. 在左窗格中，選取 頻道。

2. 在 [可用頻道] 底下，選取 [Microsoft Teams]。

   

3. 選取核取方塊以接受 服務條款。

4. 選取 [同意]。

   

5. 選取 [套用]。

   

若要新增訊息端點

新增 OAuth 連線設定

1. 在左窗格中，選取 設定。

2. 選取 新增 OAuth 連線設定。

3. 在 [新增連線設定] 底下，更新下列詳細資料：

   • 名稱：輸入新連線設定的名稱。 您可以在 Bot 服務程式碼的設定中使用該名稱。
   • 服務提供者：從下拉式清單中選取 [Azure Active Directory v2]。
   • 用戶端識別碼：更新您的 Microsoft 應用程式識別碼。
   • 用戶端密碼： 更新用戶端密碼 值。
   • 權杖交換 URL：更新 應用程式識別碼 URI。
   • 租用戶識別碼： 輸入 Common。
   • 範圍： 輸入 User.Read。

4. 選取 [儲存]。

   

設定應用程式設定

1. 移至複製存放庫中的 appsettings.json 檔案。

   

2. 在 Visual Studio 中開啟 appsettings.json 檔案。

3. 更新下列資訊：

   • 取代 "MicrosoftAppId" 為 Bot 的 Microsoft 應用程式識別碼。
   • "MicrosoftAppPassword"取代為 Bot 的用戶端密碼 值。
   • 取代 "SiteUrl" 為您的 ngrok URL。
   • "ConnectionName"取代為 OAuth 連線設定的名稱。
   • 取代 "TenantId" 為使用應用程式之租用戶的租用戶識別碼。
   • 取代 "ClientId" 為 Bot 的 Microsoft 應用程式識別碼。
   • "AppSecret"取代為 Bot 的用戶端密碼 值。
   • 以 的api://*******.ngrok.io/botid-{AppID}格式取代"ApplicationIdURI"。

   

設定資訊清單檔案

1. 移至複製存放庫中的 manifest.json 檔案。

   

2. 在 Visual Studio 中開啟 manifest.json 檔案，並進行下列變更：

   • DOMAIN-NAME取代為您的 ngrok URL。

   • YOUR-MICROSOFT-APP-ID取代為 Bot 的 Microsoft 應用程式識別碼。

     注意

     視案例 [YOUR-MICROSOFT-APP-ID] 而定，且 [DOMAIN-NAME] 可能會發生多次。

   • 取代 resource 為 api://*******.ngrok.io/botid-{AppID}。
     

     

建置及執行服務

若要建置及執行服務，請使用 Visual Studio 或命令列。

dotnet run