組織數據：擷取檔案、聊天和傳送訊息給Teams

在現今的數字環境中，使用者會使用各式各樣的組織數據，包括電子郵件、聊天、檔案、行事曆活動等等。 這可能會導致頻繁的內容班次—在工作或應用程式之間切換，這可能會中斷焦點並減少生產力。 例如，處理項目的使用者可能需要從目前的應用程式切換至 Outlook，以在電子郵件中尋找重要詳細數據，或切換至 商務用 OneDrive 以尋找相關檔案。 這種來回動作會干擾焦點，浪費時間，以便更好地花在手邊的任務。

為了提高效率，您可以將組織數據直接整合到使用者每天使用的應用程式。 藉由將組織數據帶入您的應用程式，使用者可以更順暢地存取和管理資訊，將內容轉移降至最低，並提升生產力。 此外，這項整合提供寶貴的見解和內容，讓用戶能夠做出明智的決策，並更有效率地工作。

在本練習中，您將會：

• 瞭解 Microsoft Graph 工具組中 的 mgt-search-results Web 元件如何用來搜尋檔案。
• 瞭解如何直接呼叫 Microsoft Graph，以從 Microsoft Teams 擷取 商務用 OneDrive 和聊天訊息的檔案。
• 瞭解如何使用 Microsoft Graph 將聊天訊息傳送至 Microsoft Teams 頻道。

使用組織數據功能

1. 在 先前的練習 中，您已在 entra ID Microsoft中建立應用程式註冊，並啟動應用程式伺服器和 API 伺服器。 您也會更新檔案中的 .env 下列值。

   ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
   TEAM_ID=<TEAMS_TEAM_ID>
   CHANNEL_ID=<TEAMS_CHANNEL_ID>
   

   請確定您已完成先前的 練習 ，再繼續進行。

2. 返回瀏覽器 （http://localhost:4200）。 如果您尚未登入，請在標頭中選取 [ 登入 ]，然後從您的 Microsoft 365 開發人員租使用者使用使用者登入。

   備註

   除了驗證使用者之外， mgt 登入 Web 元件也會擷取存取令牌，Microsoft Graph 可用來存取檔案、聊天、電子郵件、行事歷事件和其他組織數據。 存取權杖包含範圍（許可權），例如 Chat.ReadWrite您稍早看到的、 Files.Read.All和其他專案：

   Providers.globalProvider = new Msal2Provider({
       clientId: ENTRAID_CLIENT_ID, // retrieved from .env file
       scopes: ['User.Read', 'Presence.Read', 'Chat.ReadWrite', 'Calendars.Read', 
                'ChannelMessage.Read.All', 'ChannelMessage.Send', 'Files.Read.All', 'Mail.Read']
   });
   

3. 選取 datagrid 中 Adatum Corporation 數據列的 [檢視相關內容]。 這會導致使用 Microsoft Graph 擷取組織數據，例如檔案、聊天、電子郵件和行事曆事件。 一旦數據載入，它就會顯示在索引標籤式介面的 datagrid 下方。 請務必提及，您目前可能看不到任何數據，因為您尚未為Microsoft 365 開發人員租使用者中的使用者新增任何檔案、聊天、電子郵件或行事歷事件。 讓我們在下一個步驟中修正此問題。

   

4. 您Microsoft 365 租使用者目前可能沒有任何相關組織數據給 Adatum Corporation 。 若要新增一些範例數據，請至少執行下列其中一個動作：

   • 造訪 https://onedrive.com 並使用您的 Microsoft 365 開發人員租用戶認證來新增檔案。

     • 選取左側導覽中的 [我的檔案 ]。
     • 從功能表中選取 [+ 新增 ]，然後選取 [ 資料夾上傳 ]。
     • 從您複製的項目選取 openai-acs-msgraph/customer documents 資料夾。

     

   • 使用您的 Microsoft 365 開發人員租使用者認證來流覽 https://teams.microsoft.com 並登入，以新增聊天訊息和行事曆事件。

     • 選取左側導覽中的 Teams 。

     • 選取小組和頻道。

     • 選取 [開始文章]。

     • 針對主旨輸入 Adatum Corporation 的新訂單 ，以及您想要在訊息本文中新增的任何其他文字。 選取 [過帳] 按鈕。

       您可以隨意新增其他聊天訊息，以提及應用程式中使用的其他公司，例如 Adventure Works Cycles、 Contoso Pharmaceuticals 和 Tailwind Traders。

       

     • 選取左側導覽中的 [ 行事曆 ]。

     • 選取 [新增會議]。

     • 輸入標題和本文的「與 Adatum Corporation 關於專案排程的會面」。

     • 選取 [儲存]。

       

   • 造訪 https://outlook.com 並使用您的 Microsoft 365 開發人員租用戶認證來新增電子郵件。

     • 選取 [新增郵件]。

     • 在 [ 收 件者] 欄位中輸入您的個人電子郵件位址。

     • 針對主體輸入 Adatum Corporation 的新訂單 ，以及您想要本文的任何專案。

     • 選擇 傳送。

       

5. 返回瀏覽器中的應用程式，然後重新整理頁面。 針對 Adatum Corporation 數據列再次選取 [檢視相關內容]。 您現在應該會看到索引標籤中顯示的數據，視您在上一個步驟中執行的工作而定。

6. 讓我們探索可在應用程式中啟用組織數據功能的程序代碼。 若要擷取數據，應用程式的用戶端部分會使用您稍早查看 的 mgt-login 元件所擷取的存取令牌，來呼叫 Microsoft Graph API。

探索檔案搜尋程序代碼

1. 讓我們從查看如何從 商務用 OneDrive 擷取檔案數據開始。 開啟 files.component.html ，並花點時間查看程序代碼。 檔案的完整路徑 client/src/app/files/files.component.html。

2. 找出 mgt-search-results 元件，並記下下列屬性：

   <mgt-search-results 
       class="search-results" 
       entity-types="driveItem" 
       [queryString]="searchText"
       (dataChange)="dataChange($any($event))" 
   />
   

   mgt-search-results 元件是 Microsoft Graph 工具組的一部分，如其名稱所示，它用來顯示來自 Microsoft Graph 的搜尋結果。 此元件在此範例中使用下列功能：

   • 屬性 class 是用來指定 search-results CSS 類別應該套用至元件。

   • entity-types屬性是用來指定要搜尋的數據類型。 在此情況下，值是driveItem用來搜尋 商務用 OneDrive 中的檔案。

   • 屬性 queryString 是用來指定搜尋字詞。 在此情況下，當用戶選取 datagrid 中數據列的 [searchText] 時，值會系結至傳遞至檔案元件的屬性。 周圍的 queryString 方括弧表示 屬性系結至 searchText 值。

   • 搜尋 dataChange 結果變更時引發事件。 在此情況下，會在檔案dataChange()呼叫名為 的客戶函式，並將事件數據傳遞至函式。 周圍的 dataChange 括號表示事件系結至 函 dataChange() 式。

   • 由於未提供任何自定義範本，因此內建 mgt-search-results 的預設範本會用來顯示搜尋結果。

     

3. 使用 mgt-search-results 等元件的替代方法是直接使用程式代碼呼叫Microsoft Graph API。 若要查看運作方式，請開啟 graph.service.ts 檔案並找出 函 searchFiles() 式。 檔案的完整路徑是 client/src/app/core/graph.service.ts。

   • 您會發現 query 參數會傳遞至 函式。 這是在用戶選取 datagrid 中數據列的 [ 檢視相關內容 ] 時傳遞的搜尋字詞。 如果未傳遞任何搜尋字詞，則會傳回空陣列。

     async searchFiles(query: string) {
         const files: DriveItem[] = [];
         if (!query) return files;
     
         ...
     }
     

   • 接著會建立篩選條件，以定義要執行的搜尋類型。 在此情況下，程式代碼會搜尋 商務用 OneDrive 中的檔案，因此driveItem會如同您稍早在mgt-search-results元件中看到的一樣使用。 這與您稍早看到的 mgt-search-resultsdriveItem傳遞entity-types至 相同。 然後，參數query會與 一起queryString新增至ContentType:Document篩選。

     const filter = {
         "requests": [
             {
                 "entityTypes": [
                     "driveItem"
                 ],
                 "query": {
                     "queryString": `${query} AND ContentType:Document`
                 }
             }
         ]
     };
     

   • 接著會使用 /search/query 函式對 Providers.globalProvider.graph.client.api() Microsoft Graph API 進行呼叫。 物件 filter 會傳遞至 post() 會將數據傳送至 API 的函式。

     const searchResults = await Providers.globalProvider.graph.client.api('/search/query').post(filter);
     

   • 搜尋結果接著會逐一查看以找出 hits。 每個 hit 都包含找到之文件的相關信息。 名為 resource 的屬性包含檔元數據，並新增至 files 陣列。

     if (searchResults.value.length !== 0) {
         for (const hitContainer of searchResults.value[0].hitsContainers) {
             if (hitContainer.hits) {
                 for (const hit of hitContainer.hits) {
                     files.push(hit.resource);
                 }
             }
         }
     }
     

   • 接著會將 files 數位傳回給呼叫端。

     return files;
     

4. 查看此程式代碼，您可以看到您稍早探索的 mgt-search-results Web 元件會為您執行許多工作，並大幅減少您必須撰寫的程式代碼數量！ 不過，在某些情況下，您可能想要直接呼叫 Microsoft Graph，以更充分掌控傳送至 API 的數據，或處理結果的方式。

5. 開啟 files.component.ts 檔案並找出 函 search() 式。 檔案的完整路徑是 client/src/app/files/files.component.ts。

   雖然此函式的主體因為正在使用 mgt-search-results 元件而批注化，但是當用戶選取 datagrid 中數據列的 [ 檢視相關內容 ] 時，該函式可用來呼叫 Microsoft Graph。 函search()式searchFiles()呼叫 ，並將 參數傳遞給query它（在此範例中為公司的名稱）。 搜尋的結果接著會指派給 data 元件的 屬性。

   override async search(query: string) {
       this.data = await this.graphService.searchFiles(query);
   }
   

   然後 data ，檔案元件可以使用 屬性來顯示搜尋結果。 您可以使用自定義 HTML 系結，或使用名為 mgt-file-list的另一個 Microsoft Graph 工具組控件來處理此作業。 以下是將 屬性系結 data 至其中一個名為 的元件屬性 files ，並在使用者與檔案互動時處理 itemClick 事件的範例。

   <mgt-file-list (itemClick)="itemClick($any($event))" [files]="data"></mgt-file-list>
   

6. 不論您選擇使用稍早顯示的 mgt-search-results 元件，還是撰寫自定義程式碼來呼叫 Microsoft Graph 將取決於您的特定案例。 在此範例中， mgt-search-results 元件可用來簡化程序代碼，並減少您必須執行的工作量。

探索 Teams 聊天訊息搜尋程式代碼

1. 返回 graph.service.ts 並找出 函 searchChatMessages() 式。 您會看到它與您先前查看的 searchFiles() 函式類似。

   • 它會將篩選數據張貼至 Microsoft Graph 的 /search/query API，並將結果轉換成物件數位，其中包含 、 和 teamId 符合搜尋字詞的資訊channelIdmessageId。
   • 若要擷取 Teams 頻道訊息，系統會對 API 進行 /teams/${chat.teamId}/channels/${chat.channelId}/messages/${chat.messageId} 第二次呼叫，並 teamId傳遞 、 channelId和 messageId 。 這會傳回完整的訊息詳細數據。
   • 系統會執行其他篩選工作，並將產生的訊息從 searchChatMessages() 傳回給呼叫端。

2. 開啟 chats.component.ts 檔案並找出 函 search() 式。 檔案的完整路徑是 client/src/app/chats/chats.component.ts。 函search()式searchChatMessages()呼叫 ，並將 參數傳遞給query它。

   override async search(query: string) {
       this.data = await this.graphService.searchChatMessages(query);
   }
   

   搜尋的結果會指派給 data 元件的屬性，而數據系結則用來逐一查看結果陣列並轉譯數據。 此範例會使用 Angular 材質卡片 元件來顯示搜尋結果。

   @if (this.data.length) {
       <div>
           @for (chatMessage of this.data;track chatMessage.id) {
               <mat-card>
                   <mat-card-header>
                       <mat-card-title [innerHTML]="chatMessage.summary"></mat-card-title>
                       <!-- <mat-card-subtitle [innerHTML]="chatMessage.body"></mat-card-subtitle> -->
                   </mat-card-header>
                   <mat-card-actions>
                       <a mat-stroked-button color="basic" [href]="chatMessage.webUrl" target="_blank">View Message</a>
                   </mat-card-actions>
               </mat-card>
           }
       </div>
   }
   

   

將訊息傳送至 Microsoft Teams 頻道

1. 除了搜尋 Microsoft Teams 聊天訊息之外，應用程式也允許使用者將訊息傳送至 Microsoft Teams 頻道。 呼叫 Microsoft Graph 的端點即可完成此作業 /teams/${teamId}/channels/${channelId}/messages 。

   

2. 在下列程序代碼中，您會看到已建立包含 teamId 和 channelId 值的 URL。 環境變數值用於此範例中的小組標識碼和通道標識碼，但這些值也可以使用 Microsoft Graph 動態擷取。 常 body 數包含要傳送的訊息。 接著會提出POST要求，並將結果傳回給呼叫端。

   async sendTeamsChat(message: string): Promise<TeamsDialogData> {
       if (!message) new Error('No message to send.');
       if (!TEAM_ID || !CHANNEL_ID) new Error('Team ID or Channel ID not set in environment variables. Please set TEAM_ID and CHANNEL_ID in the .env file.');
   
       const url = `https://graph.microsoft.com/v1.0/teams/${TEAM_ID}/channels/${CHANNEL_ID}/messages`;
       const body = {
           "body": {
               "contentType": "html",
               "content": message
           }
       };
       const response = await Providers.globalProvider.graph.client.api(url).post(body);
       return {
           id: response.id,
           teamId: response.channelIdentity.teamId,
           channelId: response.channelIdentity.channelId,
           message: response.body.content,
           webUrl: response.webUrl,
           title: 'Send Teams Chat'
       };
   }
   

3. 在 Microsoft Graph 中運用這種類型的功能，可讓使用者直接從已使用的應用程式與 Microsoft Teams 互動，藉此增強用戶產品性。

後續步驟