Dati dell'organizzazione: recupero di file, chat e invio di messaggi a Teams

Nell'ambiente digitale di oggi gli utenti lavorano con un'ampia gamma di dati aziendali, tra cui messaggi di posta elettronica, chat, file, eventi del calendario e altro ancora. Questo può portare a frequenti cambiamenti di contesto, passando tra attività o applicazioni, che possono interrompere lo stato attivo e ridurre la produttività. Ad esempio, un utente che lavora su un progetto potrebbe dover passare dall'applicazione corrente a Outlook per trovare i dettagli cruciali in un messaggio di posta elettronica o passare a OneDrive for Business per trovare un file correlato. Questa azione indietro e indietro interrompe lo stato attivo e sprecare tempo che potrebbe essere meglio speso per l'attività a portata di mano.

Per migliorare l'efficienza, è possibile integrare i dati aziendali direttamente nelle applicazioni che gli utenti usano quotidianamente. Inserendo i dati aziendali nelle applicazioni, gli utenti possono accedere e gestire le informazioni in modo più semplice, riducendo al minimo i cambiamenti di contesto e migliorando la produttività. Inoltre, questa integrazione fornisce informazioni dettagliate e contesto preziose, consentendo agli utenti di prendere decisioni informate e lavorare in modo più efficace.

In questo esercizio si eseguiranno le seguenti operazioni:

• Informazioni su come usare il componente Web mgt-search-results in Microsoft Graph Toolkit per cercare i file.
• Informazioni su come chiamare Microsoft Graph direttamente per recuperare file da OneDrive for Business e messaggi di chat da Microsoft Teams.
• Informazioni su come inviare messaggi di chat ai canali di Microsoft Teams usando Microsoft Graph.

Uso della funzionalità Dati dell'organizzazione

1. In un esercizio precedente è stata creata una registrazione dell'app in Microsoft Entra ID e sono stati avviati il server applicazioni e il server API. Nel file sono stati aggiornati anche i valori .env seguenti.

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

   Assicurarsi di aver completato l'esercizio precedente prima di continuare.

2. Tornare al browser (http://localhost:4200). Se non è già stato eseguito l'accesso, selezionare Accedi nell'intestazione e accedere con un utente dal tenant di Microsoft 365 Developer.

   Annotazioni

   Oltre all'autenticazione dell'utente, il componente Web mgt-login recupera anche un token di accesso che può essere usato da Microsoft Graph per accedere a file, chat, messaggi di posta elettronica, eventi del calendario e altri dati dell'organizzazione. Il token di accesso contiene gli ambiti (autorizzazioni), ad esempio Chat.ReadWrite, Files.Read.Alle altri elementi illustrati in precedenza:

   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. Selezionare Visualizza contenuto correlato per la riga Adatum Corporation nella griglia di dati. Ciò causerà il recupero di dati aziendali, ad esempio file, chat, messaggi di posta elettronica ed eventi del calendario tramite Microsoft Graph. Una volta caricati, i dati verranno visualizzati sotto la griglia di dati in un'interfaccia a schede. È importante ricordare che a questo punto non vengono visualizzati dati poiché non sono ancora stati aggiunti file, chat, messaggi di posta elettronica o eventi del calendario per l'utente nel tenant per sviluppatori di Microsoft 365. È possibile correggere questo problema nel passaggio successivo.

   

4. Il tenant di Microsoft 365 potrebbe non avere dati aziendali correlati per Adatum Corporation in questa fase. Per aggiungere alcuni dati di esempio, eseguire almeno una delle azioni seguenti:

   • Aggiungere file visitando https://onedrive.com e accedendo usando le credenziali del tenant di Microsoft 365 Developer.

     • Selezionare My files (File personali ) nel riquadro di spostamento sinistro.
     • Selezionare + Aggiungi nuovo e quindi Caricamento cartelle dal menu.
     • Selezionare la cartella openai-acs-msgraph/customer documents dal progetto clonato.

     

   • Aggiungere messaggi di chat ed eventi del calendario visitando https://teams.microsoft.com e accedendo usando le credenziali del tenant di Microsoft 365 Developer.

     • Selezionare Teams nel riquadro di spostamento sinistro.

     • Selezionare un team e un canale.

     • Selezionare Avvia un post.

     • Immettere Nuovo ordine effettuato per Adatum Corporation per l'oggetto e qualsiasi testo aggiuntivo che si desidera aggiungere nel corpo del messaggio. Selezionare il pulsante Pubblica .

       È possibile aggiungere altri messaggi di chat che menzionano altre aziende usate nell'applicazione, ad esempio Adventure Works Cycles, Contoso Pharmaceuticals e Tailwind Traders.

       

     • Selezionare Calendario nel riquadro di spostamento a sinistra.

     • Selezionare Nuova riunione.

     • Immettere "Meet with Adatum Corporation about project schedule" (Riunione con Adatum Corporation sulla pianificazione del progetto) per il titolo e il corpo.

     • Seleziona Salva.

       

   • Aggiungere messaggi di posta elettronica visitando https://outlook.com e accedendo usando le credenziali del tenant di Microsoft 365 Developer.

     • Selezionare Nuovo messaggio di posta elettronica.

     • Immettere l'indirizzo di posta elettronica personale nel campo A .

     • Immettere Nuovo ordine effettuato per Adatum Corporation per l'oggetto e tutto ciò che si desidera per il corpo.

     • Seleziona Invia.

       

5. Tornare all'applicazione nel browser e aggiornare la pagina. Selezionare di nuovo Visualizza contenuto correlato per la riga Adatum Corporation . Verranno ora visualizzati i dati visualizzati nelle schede a seconda delle attività eseguite nel passaggio precedente.

6. Si esaminerà ora il codice che abilita la funzionalità dei dati dell'organizzazione nell'applicazione. Per recuperare i dati, la parte lato client dell'applicazione usa il token di accesso recuperato dal componente mgt-login esaminato in precedenza per effettuare chiamate alle API Microsoft Graph.

Esplorazione del codice di ricerca dei file

Suggerimento

Se si usa Visual Studio Code, è possibile aprire direttamente i file selezionando:

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

Digitare quindi il nome del file che si desidera aprire.

1. Si inizierà esaminando il modo in cui i dati dei file vengono recuperati da OneDrive for Business. Aprire files.component.html e esaminare il codice. Il percorso completo del file è client/src/app/files/files.component.html.

2. Individuare il componente mgt-search-results e prendere nota degli attributi seguenti:

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

   Il componente mgt-search-results fa parte di Microsoft Graph Toolkit e, come suggerisce il nome, viene usato per visualizzare i risultati della ricerca da Microsoft Graph. Il componente usa le funzionalità seguenti in questo esempio:

   • L'attributo class viene usato per specificare che la search-results classe CSS deve essere applicata al componente.

   • L'attributo entity-types viene usato per specificare il tipo di dati da cercare. In questo caso, il valore viene driveItem usato per cercare i file in OneDrive for Business.

   • L'attributo queryString viene usato per specificare il termine di ricerca. In questo caso, il valore viene associato alla searchText proprietà che viene passata al componente file quando l'utente seleziona Visualizza contenuto correlato per una riga nella griglia di dati. Le parentesi quadre intorno queryString indicano che la proprietà è associata al searchText valore .

   • L'evento dataChange viene generato quando i risultati della ricerca cambiano. In questo caso, una funzione cliente denominata dataChange() viene chiamata nel componente file e i dati dell'evento vengono passati alla funzione. La parentesi intorno dataChange indica che l'evento è associato alla dataChange() funzione.

   • Poiché non viene fornito alcun modello personalizzato, viene usato il modello predefinito in mgt-search-results per visualizzare i risultati della ricerca.

     

3. Un'alternativa all'uso di componenti come mgt-search-results consiste nel chiamare direttamente le API Microsoft Graph usando il codice. Per informazioni sul funzionamento, aprire il file graph.service.ts e individuare la searchFiles() funzione. Il percorso completo del file è client/src/app/core/graph.service.ts.

   • Si noterà che un query parametro viene passato alla funzione . Questo è il termine di ricerca passato quando l'utente seleziona Visualizza contenuto correlato per una riga nella griglia di dati. Se non viene passato alcun termine di ricerca, viene restituita una matrice vuota.

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

   • Viene quindi creato un filtro che definisce il tipo di ricerca da eseguire. In questo caso il codice cerca i file in OneDrive for Business, quindi driveItem viene usato esattamente come illustrato in precedenza con il mgt-search-results componente. Si tratta dello stesso driveItem passaggio a entity-types nel componente mgt-search-results visualizzato in precedenza. Il query parametro viene quindi aggiunto al queryString filtro insieme ContentType:Documenta .

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

   • Viene quindi effettuata una chiamata all'API /search/query Microsoft Graph usando la Providers.globalProvider.graph.client.api() funzione . L'oggetto filter viene passato alla post() funzione che invia i dati all'API.

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

   • I risultati della ricerca vengono quindi sottoposti a iterazione per individuare hits. Ognuno hit contiene informazioni su un documento trovato. Una proprietà denominata resource contiene i metadati del documento e viene aggiunta alla files matrice.

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

   • La files matrice viene quindi restituita al chiamante.

     return files;
     

4. Esaminando questo codice è possibile notare che il componente Web mgt-search-results esplorato in precedenza esegue molte operazioni e riduce significativamente la quantità di codice da scrivere. Tuttavia, potrebbero esserci scenari in cui si vuole chiamare direttamente Microsoft Graph per avere un maggiore controllo sui dati inviati all'API o sul modo in cui vengono elaborati i risultati.

5. Aprire il file files.component.ts e individuare la search() funzione. Il percorso completo del file è client/src/app/files/files.component.ts.

   Anche se il corpo di questa funzione è impostato come commento a causa del componente mgt-search-results in uso, è possibile usare la funzione per effettuare la chiamata a Microsoft Graph quando l'utente seleziona Visualizza contenuto correlato per una riga nella griglia di dati. La search() funzione chiama searchFiles() in graph.service.ts e vi passa il query parametro (il nome della società in questo esempio). I risultati della ricerca vengono quindi assegnati alla data proprietà del componente.

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

   Il componente file può quindi usare la data proprietà per visualizzare i risultati della ricerca. È possibile gestirlo usando associazioni HTML personalizzate o usando un altro controllo di Microsoft Graph Toolkit denominato mgt-file-list. Ecco un esempio di associazione della data proprietà a una delle proprietà del componente denominate files e alla gestione dell'evento itemClick quando l'utente interagisce con un file.

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

6. Se si sceglie di usare il componente mgt-search-results mostrato in precedenza o scrivere codice personalizzato per chiamare Microsoft Graph dipenderà dallo scenario specifico. In questo esempio, il componente mgt-search-results viene usato per semplificare il codice e ridurre la quantità di lavoro da eseguire.

Esplorazione del codice di ricerca dei messaggi di chat di Teams

1. Tornare a graph.service.ts e individuare la searchChatMessages() funzione. Si noterà che è simile alla searchFiles() funzione esaminata in precedenza.

   • Inserisce i dati di filtro nell'API di /search/query Microsoft Graph e converte i risultati in una matrice di oggetti con informazioni su teamId, channelIde messageId che corrispondono al termine di ricerca.
   • Per recuperare i messaggi del canale di Teams, viene eseguita una seconda chiamata all'API /teams/${chat.teamId}/channels/${chat.channelId}/messages/${chat.messageId} e teamIdvengono passati , channelIde messageId . In questo modo vengono restituiti i dettagli completi del messaggio.
   • Vengono eseguite attività di filtro aggiuntive e i messaggi risultanti vengono restituiti dal searchChatMessages() chiamante.

2. Aprire il file chats.component.ts e individuare la search() funzione. Il percorso completo del file è client/src/app/chats/chats.component.ts. La search() funzione chiama searchChatMessages() in graph.service.ts e passa il query parametro a esso.

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

   I risultati della ricerca vengono assegnati alla data proprietà del componente e il data binding viene usato per scorrere la matrice di risultati ed eseguire il rendering dei dati. In questo esempio viene usato un componente scheda Materiale Angular per visualizzare i risultati della ricerca.

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

   

Invio di un messaggio a un canale di Microsoft Teams

1. Oltre alla ricerca di messaggi di chat di Microsoft Teams, l'applicazione consente anche a un utente di inviare messaggi a un canale di Microsoft Teams. Questa operazione può essere eseguita chiamando l'endpoint /teams/${teamId}/channels/${channelId}/messages di Microsoft Graph.

   

2. Nel codice seguente si noterà che viene creato un URL che include i teamId valori e channelId . I valori delle variabili di ambiente vengono usati per l'ID team e l'ID del canale in questo esempio, ma questi valori possono essere recuperati dinamicamente anche usando Microsoft Graph. La body costante contiene il messaggio da inviare. Viene quindi effettuata una richiesta POST e i risultati vengono restituiti al chiamante.

   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'uso di questo tipo di funzionalità in Microsoft Graph offre un ottimo modo per migliorare la productività degli utenti consentendo agli utenti di interagire con Microsoft Teams direttamente dall'applicazione in uso.

Passaggio successivo

Dati dell'organizzazione: recupero di messaggi di posta elettronica ed eventi del calendario