Données organisationnelles : récupération de fichiers, conversations et envoi de messages à Teams

Dans l’environnement numérique d’aujourd’hui, les utilisateurs travaillent avec un large éventail de données organisationnelles, notamment des e-mails, des conversations, des fichiers, des événements de calendrier, etc. Cela peut entraîner des changements de contexte fréquents ( basculement entre les tâches ou les applications) qui peuvent perturber le focus et réduire la productivité. Par exemple, un utilisateur travaillant sur un projet peut avoir besoin de passer de son application actuelle à Outlook pour trouver des détails essentiels dans un e-mail ou passer à OneDrive Entreprise pour rechercher un fichier associé. Cette action d’arrière-plan interrompt le focus et perd du temps qui pourrait être mieux consacré à la tâche en main.

Pour améliorer l’efficacité, vous pouvez intégrer des données organisationnelles directement dans les applications que les utilisateurs utilisent tous les jours. En apportant des données organisationnelles à vos applications, les utilisateurs peuvent accéder et gérer les informations de manière plus transparente, réduire les changements de contexte et améliorer la productivité. En outre, cette intégration fournit des insights et un contexte précieux, ce qui permet aux utilisateurs de prendre des décisions éclairées et de travailler plus efficacement.

Dans cet exercice, vous allez :

• Découvrez comment le composant web mgt-search-results dans le Kit de ressources Microsoft Graph peut être utilisé pour rechercher des fichiers.
• Découvrez comment appeler Microsoft Graph directement pour récupérer des fichiers à partir de OneDrive Entreprise et des messages de conversation à partir de Microsoft Teams.
• Découvrez comment envoyer des messages de conversation à des canaux Microsoft Teams à l’aide de Microsoft Graph.

Utilisation de la fonctionnalité de données organisationnelles

1. Dans un exercice précédent , vous avez créé une inscription d’application dans Microsoft Entra ID et démarré le serveur d’applications et le serveur d’API. Vous avez également mis à jour les valeurs suivantes dans le .env fichier.

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

   Vérifiez que vous avez terminé l’exercice précédent avant de continuer.

2. Revenez au navigateur (http://localhost:4200). Si vous n’avez pas encore connecté, sélectionnez Se connecter dans l’en-tête et connectez-vous avec un utilisateur à partir de votre locataire Microsoft 365 Developer.

   Remarque

   Outre l’authentification de l’utilisateur, le composant web mgt-login récupère également un jeton d’accès qui peut être utilisé par Microsoft Graph pour accéder aux fichiers, conversations, e-mails, événements de calendrier et autres données organisationnelles. Le jeton d’accès contient les étendues (autorisations) telles que Chat.ReadWrite, Files.Read.Allet d’autres que vous avez vues précédemment :

   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. Sélectionnez Afficher le contenu associé pour la ligne Adatum Corporation dans le datagrid. Cela entraîne la récupération des données organisationnelles telles que des fichiers, des conversations, des e-mails et des événements de calendrier à l’aide de Microsoft Graph. Une fois les données chargées, elles sont affichées sous la grille de données dans une interface à onglets. Il est important de mentionner que vous ne voyez pas de données à ce stade, car vous n’avez pas encore ajouté de fichiers, de conversations, d’e-mails ou d’événements de calendrier pour l’utilisateur dans votre client développeur Microsoft 365. Nous allons corriger cela à l’étape suivante.

   

4. Votre client Microsoft 365 peut ne pas avoir de données organisationnelles associées pour Adatum Corporation à ce stade. Pour ajouter des exemples de données, effectuez au moins l’une des actions suivantes :

   • Ajoutez des fichiers en visitant et en vous connectant https://onedrive.com à l’aide de vos informations d’identification de locataire Microsoft 365 Developer.

     • Sélectionnez Mes fichiers dans le volet de navigation gauche.
     • Sélectionnez + Ajouter un nouveau dossier, puis chargez le dossier dans le menu.
     • Sélectionnez le dossier de documents openai-acs-msgraph/customer dans le projet que vous avez cloné.

     

   • Ajoutez des messages de conversation et des événements de calendrier en visitant et en vous connectant https://teams.microsoft.com à l’aide de vos informations d’identification de locataire Microsoft 365 Developer.

     • Sélectionnez Teams dans le volet de navigation gauche.

     • Sélectionnez une équipe et un canal.

     • Sélectionnez Démarrer un billet.

     • Entrez la nouvelle commande passée pour Adatum Corporation pour l’objet et tout texte supplémentaire que vous souhaitez ajouter dans le corps du message. Sélectionnez le bouton Publier .

       N’hésitez pas à ajouter des messages de conversation supplémentaires qui mentionnent d’autres entreprises utilisées dans l’application, telles que Adventure Works Cycles, Contoso Pharmaceuticals et Tailwind Traders.

       

     • Sélectionnez Calendrier dans le volet de navigation gauche.

     • Sélectionnez Nouvelle réunion.

     • Entrez « Rencontrer Adatum Corporation à propos de la planification du projet » pour le titre et le corps.

     • Cliquez sur Enregistrer.

       

   • Ajoutez des e-mails en visitant et en vous connectant https://outlook.com à l’aide de vos informations d’identification de locataire Microsoft 365 Developer.

     • Sélectionnez Nouveau courrier.

     • Entrez votre adresse e-mail personnelle dans le champ À .

     • Entrez la nouvelle commande passée pour Adatum Corporation pour le sujet et tout ce que vous souhaitez pour le corps.

     • Sélectionnez Envoyer.

       

5. Revenez à l’application dans le navigateur et actualisez la page. Sélectionnez à nouveau Afficher le contenu associé pour la ligne Adatum Corporation . Vous devez maintenant voir les données affichées dans les onglets en fonction des tâches que vous avez effectuées à l’étape précédente.

6. Examinons le code qui active la fonctionnalité de données organisationnelles dans l’application. Pour récupérer les données, la partie côté client de l’application utilise le jeton d’accès récupéré par le composant mgt-login que vous avez examiné précédemment pour effectuer des appels aux API Microsoft Graph.

Exploration du code de recherche de fichiers

Conseil / Astuce

Si vous utilisez Visual Studio Code, vous pouvez ouvrir des fichiers directement en sélectionnant :

• Windows/Linux : Ctrl + P
• Mac : Cmd + P

Tapez ensuite le nom du fichier que vous souhaitez ouvrir.

1. Commençons par examiner la façon dont les données de fichier sont récupérées à partir de OneDrive Entreprise. Ouvrez files.component.html et prenez un moment pour examiner le code. Le chemin complet du fichier est client/src/app/files/files.component.html.

2. Recherchez le composant mgt-search-results et notez les attributs suivants :

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

   Le composant mgt-search-results fait partie du Kit de ressources Microsoft Graph et, comme l’indique le nom, il est utilisé pour afficher les résultats de recherche à partir de Microsoft Graph. Le composant utilise les fonctionnalités suivantes dans cet exemple :

   • L’attribut class est utilisé pour spécifier que la search-results classe CSS doit être appliquée au composant.

   • L’attribut entity-types est utilisé pour spécifier le type de données à rechercher. Dans ce cas, la valeur est driveItem utilisée pour rechercher des fichiers dans OneDrive Entreprise.

   • L’attribut queryString est utilisé pour spécifier le terme de recherche. Dans ce cas, la valeur est liée à la searchText propriété qui est passée au composant fichiers lorsque l’utilisateur sélectionne Afficher le contenu associé pour une ligne dans le datagrid. Les crochets autour queryString indiquent que la propriété est liée à la searchText valeur.

   • L’événement dataChange se déclenche lorsque les résultats de la recherche changent. Dans ce cas, une fonction cliente nommée dataChange() est appelée dans le composant fichiers et les données d’événement sont transmises à la fonction. Les parenthèses autour dataChange indiquent que l’événement est lié à la dataChange() fonction.

   • Étant donné qu’aucun modèle personnalisé n’est fourni, le modèle par défaut intégré mgt-search-results est utilisé pour afficher les résultats de la recherche.

     

3. Une alternative à l’utilisation de composants tels que mgt-search-results consiste à appeler des API Microsoft Graph directement à l’aide de code. Pour voir comment cela fonctionne, ouvrez le fichier graph.service.ts et recherchez la searchFiles() fonction. Le chemin complet du fichier est client/src/app/core/graph.service.ts.

   • Vous remarquerez qu’un query paramètre est passé à la fonction. Il s’agit du terme de recherche passé lorsque l’utilisateur sélectionne Afficher le contenu associé d’une ligne dans le datagrid. Si aucun terme de recherche n’est passé, un tableau vide est retourné.

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

   • Un filtre est ensuite créé qui définit le type de recherche à effectuer. Dans ce cas, le code recherche des fichiers dans OneDrive Entreprise est donc driveItem utilisé comme vous l’avez vu précédemment avec le mgt-search-results composant. Il s’agit de la même chose que le passage driveItem au entity-types composant mgt-search-results que vous avez vu précédemment. Le query paramètre est ensuite ajouté au queryString filtre avec ContentType:Document.

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

   • Un appel est ensuite effectué à l’API Microsoft Graph à l’aide /search/query de la Providers.globalProvider.graph.client.api() fonction. L’objet filter est transmis à la post() fonction qui envoie les données à l’API.

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

   • Les résultats de la recherche sont ensuite itérés à travers pour localiser hits. Chacun hit contient des informations sur un document trouvé. Une propriété nommée resource contient les métadonnées du document et est ajoutée au files tableau.

     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);
                 }
             }
         }
     }
     

   • Le files tableau est ensuite retourné à l’appelant.

     return files;
     

4. En examinant ce code, vous pouvez voir que le composant web mgt-search-results que vous avez exploré précédemment fait beaucoup de travail pour vous et réduit considérablement la quantité de code que vous devez écrire ! Toutefois, il peut y avoir des scénarios où vous souhaitez appeler Directement Microsoft Graph pour avoir plus de contrôle sur les données envoyées à l’API ou sur la façon dont les résultats sont traités.

5. Ouvrez le fichier files.component.ts et recherchez la search() fonction. Le chemin complet du fichier est client/src/app/files/files.component.ts.

   Bien que le corps de cette fonction soit commenté en raison du composant mgt-search-results utilisé, la fonction peut être utilisée pour effectuer l’appel à Microsoft Graph lorsque l’utilisateur sélectionne Afficher le contenu associé pour une ligne dans le datagrid. La search() fonction appelle searchFiles() graph.service.ts et lui transmet le query paramètre (nom de l’entreprise dans cet exemple). Les résultats de la recherche sont ensuite affectés à la data propriété du composant.

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

   Le composant fichiers peut ensuite utiliser la data propriété pour afficher les résultats de la recherche. Vous pouvez gérer cela à l’aide de liaisons HTML personnalisées ou à l’aide d’un autre contrôle Microsoft Graph Toolkit nommé mgt-file-list. Voici un exemple de liaison de la data propriété à l’une des propriétés du composant nommées files et gérant l’événement itemClick lorsque l’utilisateur interagit avec un fichier.

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

6. Que vous choisissiez d’utiliser le composant mgt-search-results affiché précédemment ou que vous écriviez du code personnalisé pour appeler Microsoft Graph dépend de votre scénario spécifique. Dans cet exemple, le composant mgt-search-results est utilisé pour simplifier le code et réduire la quantité de travail que vous devez effectuer.

Exploration du code de recherche des messages de conversation Teams

1. Revenez à graph.service.ts et recherchez la searchChatMessages() fonction. Vous verrez qu’il est similaire à la searchFiles() fonction que vous avez examinée précédemment.

   • Il publie des données de filtre dans l’API de /search/query Microsoft Graph et convertit les résultats en un tableau d’objets qui ont des informations sur le teamIdterme channelIdde recherche, et messageId qui correspondent au terme de recherche.
   • Pour récupérer les messages du canal Teams, un deuxième appel est effectué à l’API /teams/${chat.teamId}/channels/${chat.channelId}/messages/${chat.messageId} et au teamId, channelIdet messageId est passé. Cette opération renvoie les détails complets du message.
   • Des tâches de filtrage supplémentaires sont effectuées et les messages résultants sont retournés par searchChatMessages() l’appelant.

2. Ouvrez le fichier chats.component.ts et recherchez la search() fonction. Le chemin complet du fichier est client/src/app/conversations/chats.component.ts. La search() fonction appelle searchChatMessages() graph.service.ts et lui transmet le query paramètre.

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

   Les résultats de la recherche sont affectés à la data propriété du composant et de la liaison de données sont utilisés pour itérer dans le tableau de résultats et afficher les données. Cet exemple utilise un composant de carte Matériel Angular pour afficher les résultats de la recherche.

   @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>
   }
   

   

Envoi d’un message à un canal Microsoft Teams

1. Outre la recherche de messages de conversation Microsoft Teams, l’application permet également à un utilisateur d’envoyer des messages à un canal Microsoft Teams. Pour ce faire, appelez le /teams/${teamId}/channels/${channelId}/messages point de terminaison de Microsoft Graph.

   

2. Dans le code suivant, vous verrez qu’une URL est créée qui inclut les valeurs et teamId les channelId valeurs. Les valeurs des variables d’environnement sont utilisées pour l’ID d’équipe et l’ID de canal dans cet exemple, mais ces valeurs peuvent également être récupérées dynamiquement à l’aide de Microsoft Graph. La body constante contient le message à envoyer. Une requête POST est ensuite effectuée et les résultats sont retournés à l’appelant.

   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. L’utilisation de ce type de fonctionnalité dans Microsoft Graph offre un excellent moyen d’améliorer la productivbité utilisateur en permettant aux utilisateurs d’interagir directement avec Microsoft Teams à partir de l’application qu’ils utilisent déjà.

Étape suivante

Données organisationnelles : récupération d’e-mails et d’événements de calendrier