Integrare le funzionalità openAI, comunicazione e dati dell'organizzazione in un'app line-of-business

Livello: intermedio

Questa esercitazione illustra come Azure OpenAI, Servizi di comunicazione di Azure e Microsoft Graph/Microsoft Graph Toolkit possono essere integrati in un'applicazione Line of Business (LOB) per migliorare la produttività degli utenti, elevare l'esperienza utente e portare le app LINEB al livello successivo. Le funzionalità principali nell'applicazione includono:

• Intelligenza artificiale: consentire agli utenti di porre domande in linguaggio naturale e convertire le risposte in SQL che possono essere usate per eseguire query su un database, consentire agli utenti di definire regole che possono essere usate per generare automaticamente messaggi di posta elettronica e SMS e scoprire come usare il linguaggio naturale per recuperare i dati dalle origini dati personalizzate. Azure OpenAI viene usato per queste funzionalità.
• Comunicazione: abilitare le chiamate telefoniche in-app ai clienti e la funzionalità Email/SMS usando Servizi di comunicazione di Azure.
• Dati dell'organizzazione: eseguire il pull dei dati aziendali correlati che gli utenti potrebbero avere bisogno (documenti, chat, messaggi di posta elettronica, eventi del calendario) mentre collaborano con i clienti per evitare il cambio di contesto. Fornire l'accesso a questo tipo di dati aziendali riduce la necessità che l'utente passi a Outlook, Teams, OneDrive, altre app personalizzate, il telefono e così via, poiché i dati e le funzionalità specifici necessari vengono forniti direttamente nell'app. Microsoft Graph e Microsoft Graph Toolkit vengono usati per questa funzionalità.

L'applicazione è una semplice app di gestione dei clienti che consente agli utenti di gestire i clienti e i dati correlati. È costituito da un front-end compilato con TypeScript che chiama le API back-end per recuperare i dati, interagire con la funzionalità di intelligenza artificiale, inviare messaggi di posta elettronica/SMS ed eseguire il pull dei dati dell'organizzazione. Ecco una panoramica della soluzione dell'applicazione illustrata in questa esercitazione:

L'esercitazione illustra il processo di configurazione delle risorse di Azure e Microsoft 365 necessarie. Verrà anche illustrato il codice usato per implementare le funzionalità di intelligenza artificiale, comunicazione e dati dell'organizzazione. Anche se non sarà necessario copiare e incollare il codice, alcuni degli esercizi avranno la modificare il codice per provare diversi scenari.

Cosa si creerà in questa esercitazione

Scegli la tua avventura

È possibile completare l'intera esercitazione dall'inizio alla fine o completare argomenti specifici di interesse. L'esercitazione è suddivisa negli argomenti seguenti:

• Clonare l'esercizio del progetto (esercizio obbligatorio).
• Esercizi di intelligenza artificiale: creare una risorsa OpenAI di Azure e usarla per convertire il linguaggio naturale in SQL, generare messaggi di posta elettronica/SMS e usare i propri dati e documenti.
• Esercizi di comunicazione: creare una risorsa Servizi di comunicazione di Azure e usarla per effettuare chiamate telefoniche dall'app e inviare messaggi di posta elettronica/SMS.
• Esercizi sui dati dell'organizzazione: creare una registrazione dell'app Microsoft Entra ID in modo che Microsoft Graph e Microsoft Graph Toolkit possano essere usati per autenticare ed eseguire il pull dei dati dell'organizzazione nell'applicazione.

Prerequisiti

• Node - Node 20+ and npm 10+ will be used for this project
• git
• Visual Studio Code (anche se Visual Studio Code è consigliato, è possibile usare qualsiasi editor)
• Sottoscrizione di Azure
• Tenant per sviluppatori di Microsoft 365
• Docker Desktop o un altro runtime del contenitore conforme a OCI (Open Container Initiative), ad esempio Podman o nerdctl in grado di eseguire un contenitore.

Tecnologie Microsoft Cloud usate in questa esercitazione

• Servizi di comunicazione di Azure
• Servizio OpenAI di Azure
• Microsoft Entra ID
• Microsoft Graph
• Microsoft Graph Toolkit

Clonare il progetto

• 132 minuti rimanenti

Il progetto di codice usato in questa esercitazione è disponibile all'indirizzo https://github.com/microsoft/MicrosoftCloud. Il repository del progetto include sia il codice lato client che il codice lato server necessari per eseguire il progetto, consentendo di esplorare le funzionalità integrate correlate all'intelligenza artificiale (IA), alla comunicazione e ai dati dell'organizzazione. Inoltre, il progetto funge da risorsa per incorporare funzionalità simili nelle proprie applicazioni.

In questo esercizio si eseguiranno le seguenti operazioni:

• Clonare il repository GitHub.
• Aggiungere un file con estensione env nel progetto e aggiornarlo.

Prima di procedere, assicurarsi di disporre di tutti i prerequisiti installati e configurati come descritto nella sezione Prerequisiti di questa esercitazione .

Clonare il repository GitHub e creare un .env file

1. Eseguire il comando seguente per clonare il repository GitHub di Microsoft Cloud nel computer.

   git clone https://github.com/microsoft/MicrosoftCloud
   

2. Aprire la cartella MicrosoftCloud/samples/openai-acs-msgraph in Visual Studio Code.

   Nota

   Anche se in questa esercitazione si userà Visual Studio Code, è possibile usare qualsiasi editor di codice per lavorare con il progetto di esempio.

3. Si notino le cartelle e i file seguenti:

   • client: codice dell'applicazione lato client.
   • server: codice API lato server.
   • docker-compose.yml: usato per eseguire un database PostgreSQL locale.

4. Rinominare . env.example nella radice del progetto in .env.

5. Aprire il file con estensione env e esaminare le chiavi incluse:

   ENTRAID_CLIENT_ID=
   TEAM_ID=
   CHANNEL_ID=
   OPENAI_API_KEY=
   OPENAI_ENDPOINT=
   OPENAI_MODEL=gpt-4o
   OPENAI_API_VERSION=2024-05-01-preview
   POSTGRES_USER=
   POSTGRES_PASSWORD=
   ACS_CONNECTION_STRING=
   ACS_PHONE_NUMBER=
   ACS_EMAIL_ADDRESS=
   CUSTOMER_EMAIL_ADDRESS=
   CUSTOMER_PHONE_NUMBER=
   API_PORT=3000
   AZURE_AI_SEARCH_ENDPOINT=
   AZURE_AI_SEARCH_KEY=
   AZURE_AI_SEARCH_INDEX=
   

6. Aggiornare i valori seguenti in .env. Questi valori verranno usati dal server API per connettersi al database PostgreSQL locale.

   POSTGRES_USER=web
   POSTGRES_PASSWORD=web-password
   

7. Dopo aver creato il progetto, è possibile provare alcune delle funzionalità dell'applicazione e scoprire come vengono compilate. Selezionare il pulsante Avanti sotto per continuare o passare a un esercizio specifico usando il sommario.

Intelligenza artificiale: creare una risorsa OpenAI di Azure e distribuire un modello

• 127 minuti rimanenti

Per iniziare a usare Azure OpenAI nelle applicazioni, è necessario creare un servizio Azure OpenAI e distribuire un modello che può essere usato per eseguire attività come la conversione del linguaggio naturale in SQL, la generazione di contenuti di messaggi di posta elettronica/SMS e altro ancora.

In questo esercizio si eseguiranno le seguenti operazioni:

• Creare una risorsa del servizio OpenAI di Azure.
• Distribuire un modello.
• Aggiornare il file con estensione env con i valori della risorsa del servizio Azure OpenAI.

Creare una risorsa del servizio OpenAI di Azure

1. Visitare il portale di Azure nel browser e accedere.

2. Immettere openai nella barra di ricerca nella parte superiore della pagina del portale e selezionare Azure OpenAI nelle opzioni visualizzate.

   

3. Selezionare Crea sulla barra degli strumenti.

   Nota

   Anche se questa esercitazione è incentrata su Azure OpenAI, se si dispone di una chiave API OpenAI e si vuole usarla, è possibile ignorare questa sezione e passare direttamente alla sezione Aggiornare il file con estensione env del progetto di seguito. Assegnare la chiave API OpenAI a OPENAI_API_KEY nel file con estensione env (è possibile ignorare qualsiasi altra .env istruzione correlata a OpenAI).

4. I modelli OpenAI di Azure sono disponibili in aree specifiche. Vedere il documento di disponibilità del modello OpenAI di Azure per informazioni sulle aree che supportano il modello gpt-4o usato in questa esercitazione.

5. Eseguire le attività seguenti:

   • Seleziona la tua sottoscrizione di Azure.
   • Selezionare il gruppo di risorse da usare (crearne uno nuovo, se necessario).
   • Selezionare un'area in cui il modello gpt-4o è supportato in base al documento esaminato in precedenza.
   • Immettere il nome della risorsa. Deve essere un valore univoco.
   • Selezionare il piano tariffario Standard S0 .

6. Selezionare Avanti fino a visualizzare la schermata Rivedi e invia. Seleziona Crea.

7. Dopo aver creato la risorsa OpenAI di Azure, passare a essa e selezionare Gestione risorse -->Chiavi ed Endpoint .

8. Individuare i valori KEY 1 e Endpoint . Nella sezione successiva verranno usati entrambi i valori, quindi copiarli in un file locale.

   

9. Selezionare Gestione risorse -> Distribuzioni del modello.

10. Selezionare il pulsante Gestisci distribuzioni per passare ad Azure OpenAI Studio.

11. Selezionare Distribuisci modello -->Distribuisci modello di base sulla barra degli strumenti.

    

12. Selezionare gpt-4o nell'elenco dei modelli e selezionare Conferma.

    Nota

    Azure OpenAI supporta diversi tipi di modelli. Ogni modello può essere usato per gestire scenari diversi.

13. Verrà visualizzata la finestra di dialogo seguente. Esaminare i valori predefiniti forniti.

    

14. Modificare il valore Tokens per Minute Rate Limit (migliaia) in 100.000. In questo modo sarà possibile effettuare più richieste al modello ed evitare di raggiungere il limite di frequenza durante l'esecuzione dei passaggi seguenti.

15. Seleziona Distribuisci.

16. Dopo aver distribuito il modello, selezionare Playgrounds -->Chat.

17. L'elenco a discesa Distribuzione dovrebbe visualizzare il modello gpt-4o .

    

18. Leggere il testo del messaggio di sistema fornito. Questo indica al modello come agire come l'utente interagisce con esso.

19. Individuare la casella di testo nell'area di chat e immettere Riepiloga qual è l'intelligenza artificiale generativa e come può essere usata. Selezionare Invio per inviare il messaggio al modello e generare una risposta.

20. Sperimentare con altre richieste e risposte. Ad esempio, immettere Specificare una breve cronologia relativa alla capitale della Francia e notare la risposta generata.

Aggiornare il file del .env progetto

1. Tornare a Visual Studio Code e aprire il .env file nella radice del progetto.

2. Copiare il valore KEY 1 dalla risorsa OpenAI di Azure e assegnarlo a OPENAI_API_KEY nel file con estensione env che si trova nella radice della cartella openai-acs-msgraph :

   OPENAI_API_KEY=<KEY_1_VALUE>
   

3. Copiare il valore *Endpoint e assegnarlo a OPENAI_ENDPOINT nel file con estensione env . Rimuovere il / carattere dalla fine del valore, se presente.

   OPENAI_ENDPOINT=<ENDPOINT_VALUE>
   

   Nota

   Si noterà che i valori per OPENAI_MODEL e OPENAI_API_VERSION sono già impostati nel file con estensione env . Il valore del modello è impostato su gpt-4o che corrisponde al nome di distribuzione del modello creato in precedenza in questo esercizio. La versione dell'API è impostata su un valore supportato definito nella documentazione di riferimento di Azure OpenAI.

4. Salvare il file con estensione env.

Avviare i servizi applicazioni

È il momento di avviare i servizi dell'applicazione, tra cui il database, il server API e il server Web.

1. Nei passaggi seguenti verranno create tre finestre del terminale in Visual Studio Code.

   

2. Fare clic con il pulsante destro del mouse sul file con estensione env nell'elenco dei file di Visual Studio Code e scegliere Apri nel terminale integrato. Assicurarsi che il terminale si trova nella radice del progetto, openai-acs-msgraph , prima di continuare.

3. Scegliere una delle opzioni seguenti per avviare il database PostgreSQL:

   • Se Docker Desktop è installato e in esecuzione, eseguire docker-compose up nella finestra del terminale e premere INVIO.

   • Se si dispone di Podman con podman-compose installato e in esecuzione, eseguire podman-compose up nella finestra del terminale e premere INVIO.

   • Per eseguire il contenitore PostgreSQL direttamente usando Docker Desktop, Podman, nerdctl o un altro runtime del contenitore installato, eseguire il comando seguente nella finestra del terminale:

     • Mac, Linux o sottosistema Windows per Linux (WSL):

       [docker | podman | nerdctl] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v $(pwd)/data:/var/lib/postgresql/data -p 5432:5432 postgres
       

     • Windows con PowerShell:

       [docker | podman] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v ${PWD}/data:/var/lib/postgresql/data -p 5432:5432 postgres
       

4. Dopo l'avvio del contenitore di database, premere l'icona + nella barra degli strumenti del terminale di Visual Studio Code per creare una seconda finestra del terminale.

   

5. cdnella cartella server/typescript ed eseguire i comandi seguenti per installare le dipendenze e avviare il server API.

   • npm install
   • npm start

6. Premere di nuovo l'icona + nella barra degli strumenti del terminale di Visual Studio Code per creare una terza finestra del terminale.

7. cdnella cartella client ed eseguire i comandi seguenti per installare le dipendenze e avviare il server Web.

   • npm install
   • npm start

8. Verrà avviato un browser e si passerà a http://localhost:4200.

   

Intelligenza artificiale: linguaggio naturale in SQL

• 122 minuti rimanenti

La citazione "Just because you can't mean you should" è una guida utile quando si pensa alle funzionalità di intelligenza artificiale. Ad esempio, il linguaggio naturale di Azure OpenAI per SQL consente agli utenti di eseguire query di database in inglese normale, che può essere uno strumento potente per migliorare la produttività. Tuttavia, potente non significa sempre appropriato o sicuro. Questo esercizio illustra come usare questa funzionalità di intelligenza artificiale e illustra anche considerazioni importanti da tenere presente prima di decidere di implementarla.

Di seguito è riportato un esempio di query in linguaggio naturale che può essere usata per recuperare i dati da un database:

Get the the total revenue for all companies in London.

Con i prompt appropriati, Azure OpenAI convertirà questa query in SQL che può essere usata per restituire i risultati dal database. Di conseguenza, gli utenti non tecnici, tra cui business analyst, marketer e dirigenti, possono recuperare più facilmente informazioni preziose dai database senza aggrapparsi a una sintassi SQL complessa o affidarsi a reti di dati e filtri vincolati. Questo approccio semplificato può aumentare la produttività eliminando la necessità di richiedere assistenza agli esperti tecnici.

Questo esercizio fornisce un punto di partenza che consente di comprendere il funzionamento del linguaggio naturale per SQL, di presentare alcune considerazioni importanti, di considerare vantaggi e svantaggi e di mostrare il codice da iniziare.

In questo esercizio si eseguiranno le seguenti operazioni:

• Usare le istruzioni GPT per convertire il linguaggio naturale in SQL.
• Sperimentare con diverse richieste GPT.
• Usare sql generato per eseguire una query sul database PostgreSQL avviato in precedenza.
• Restituire i risultati della query da PostgreSQL e visualizzarli nel browser.

Per iniziare, provare a usare prompt GPT diversi che possono essere usati per convertire il linguaggio naturale in SQL.

Uso della funzionalità Linguaggio naturale per SQL

1. Nell'esercizio precedente è stato avviato il database, le API e l'applicazione. È stato aggiornato anche il .env file. Se questi passaggi non sono stati completati, seguire le istruzioni alla fine dell'esercizio prima di continuare.

2. Tornare al browser (http://localhost:4200) e individuare la sezione Query personalizzata della pagina sotto la griglia di dati. Si noti che è già incluso un valore di query di esempio: ottenere i ricavi totali per tutti gli ordini. Raggruppare per società e includere la città.

   

3. Selezionare il pulsante Esegui query. Questa operazione passerà la query in linguaggio naturale dell'utente ad Azure OpenAI che lo convertirà in SQL. La query SQL verrà quindi usata per eseguire query sul database e restituire eventuali risultati potenziali.

4. Eseguire la query personalizzata seguente:

   Get the total revenue for Adventure Works Cycles. Include the contact information as well.
   

5. Visualizzare la finestra del terminale che esegue il server API in Visual Studio Code e notare che viene visualizzata la query SQL restituita da Azure OpenAI. I dati JSON vengono usati dalle API lato server per eseguire query sul database PostgreSQL. Tutti i valori stringa inclusi nella query vengono aggiunti come valori di parametro per evitare attacchi SQL injection:

   { 
       "sql": "SELECT c.company, c.city, c.email, SUM(o.total) AS revenue FROM customers c INNER JOIN orders o ON c.id = o.customer_id WHERE c.company = $1 GROUP BY c.company, c.city, c.email", 
       "paramValues": ["Adventure Works Cycles"] 
   }
   

6. Tornare al browser e selezionare Reimposta dati per visualizzare di nuovo tutti i clienti nella griglia dati.

Esplorazione del linguaggio naturale nel codice SQL

1. Dopo aver visto il linguaggio naturale in azione per la funzionalità SQL, si esaminerà il modo in cui viene implementato.

2. Aprire il file server/apiRoutes.ts e individuare la generateSql route. Questa route API viene chiamata dall'applicazione lato client in esecuzione nel browser e usata per generare SQL da una query in linguaggio naturale. Dopo aver recuperato la query SQL, viene usata per eseguire query sul database e restituire i risultati.

   router.post('/generateSql', async (req, res) => {
       const userPrompt = req.body.prompt;
   
       if (!userPrompt) {
           return res.status(400).json({ error: 'Missing parameter "prompt".' });
       }
   
       try {
           // Call Azure OpenAI to convert the user prompt into a SQL query
           const sqlCommandObject = await getSQLFromNLP(userPrompt);
   
           let result: any[] = [];
           // Execute the SQL query
           if (sqlCommandObject && !sqlCommandObject.error) {
               result = await queryDb(sqlCommandObject) as any[];
           }
           else {
               result = [ { query_error : sqlCommandObject.error } ];
           }
           res.json(result);
       } catch (e) {
           console.error(e);
           res.status(500).json({ error: 'Error generating or running SQL query.' });
       }
   });
   

   Si noti la funzionalità seguente nella generateSql route:

   • Recupera il valore della query utente da req.body.prompt e lo assegna a una variabile denominata userPrompt. Questo valore verrà usato nel prompt GPT.
   • Chiama una funzione per convertire il getSQLFromNLP() linguaggio naturale in SQL.
   • Passa il codice SQL generato a una funzione denominata queryDb che esegue la query SQL e restituisce i risultati dal database.

3. Aprire il file server/openAI.ts nell'editor e individuare la getSQLFromNLP() funzione. Questa funzione viene chiamata dalla generatesql route e viene usata per convertire il linguaggio naturale in SQL.

   async function getSQLFromNLP(userPrompt: string): Promise<QueryData> {
       // Get the high-level database schema summary to be used in the prompt.
       // The db.schema file could be generated by a background process or the 
       // schema could be dynamically retrieved.
       const dbSchema = await fs.promises.readFile('db.schema', 'utf8');
   
       const systemPrompt = `
       Assistant is a natural language to SQL bot that returns a JSON object with the SQL query and 
       the parameter values in it. The SQL will query a PostgreSQL database.
   
       PostgreSQL tables with their columns:    
   
       ${dbSchema}
   
       Rules:
       - Convert any strings to a PostgreSQL parameterized query value to avoid SQL injection attacks.
       - Return a JSON object with the following structure: { "sql": "", "paramValues": [] }
   
       Examples:
   
       User: "Display all company reviews. Group by company."      
       Assistant: { "sql": "SELECT * FROM reviews", "paramValues": [] }
   
       User: "Display all reviews for companies located in cities that start with 'L'."
       Assistant: { "sql": "SELECT r.* FROM reviews r INNER JOIN customers c ON r.customer_id = c.id WHERE c.city LIKE 'L%'", "paramValues": [] }
   
       User: "Display revenue for companies located in London. Include the company name and city."
       Assistant: { 
           "sql": "SELECT c.company, c.city, SUM(o.total) AS revenue FROM customers c INNER JOIN orders o ON c.id = o.customer_id WHERE c.city = $1 GROUP BY c.company, c.city", 
           "paramValues": ["London"] 
       }
   
       User: "Get the total revenue for Adventure Works Cycles. Include the contact information as well."
       Assistant: { 
           "sql": "SELECT c.company, c.city, c.email, SUM(o.total) AS revenue FROM customers c INNER JOIN orders o ON c.id = o.customer_id WHERE c.company = $1 GROUP BY c.company, c.city, c.email", 
           "paramValues": ["Adventure Works Cycles"] 
       }
       `;
   
       let queryData: QueryData = { sql: '', paramValues: [], error: '' };
       let results = '';
   
       try {
           results = await callOpenAI(systemPrompt, userPrompt);
           if (results) {
               console.log('results', results);
               const parsedResults = JSON.parse(results);
               queryData = { ...queryData, ...parsedResults };
               if (isProhibitedQuery(queryData.sql)) {
                   queryData.sql = '';
                   queryData.error = 'Prohibited query.';
               }
           }
       } catch (error) {
           console.log(error);
           if (isProhibitedQuery(results)) {
               queryData.sql = '';
               queryData.error = 'Prohibited query.';
           } else {
               queryData.error = results;
           }
       }
   
       return queryData;
   }
   

   • Un userPrompt parametro viene passato alla funzione . Il userPrompt valore è la query in linguaggio naturale immessa dall'utente nel browser.
   • Un systemPrompt definisce il tipo di assistente di intelligenza artificiale da usare e le regole da seguire. Ciò consente ad Azure OpenAI di comprendere la struttura del database, le regole da applicare e come restituire le query e i parametri SQL generati.
   • Viene chiamata una funzione denominata callOpenAI() e i systemPrompt valori e userPrompt vengono passati.
   • I risultati vengono controllati per assicurarsi che non siano inclusi valori non consentiti nella query SQL generata. Se vengono trovati valori non consentiti, la query SQL viene impostata su una stringa vuota.

4. Esaminiamo il prompt del sistema in modo più dettagliato:

   const systemPrompt = `
     Assistant is a natural language to SQL bot that returns a JSON object with the SQL query and 
     the parameter values in it. The SQL will query a PostgreSQL database.
   
     PostgreSQL tables with their columns:    
   
     ${dbSchema}
   
     Rules:
     - Convert any strings to a PostgreSQL parameterized query value to avoid SQL injection attacks.
     - Return a JSON object with the following structure: { "sql": "", "paramValues": [] }
   
     Examples:
   
     User: "Display all company reviews. Group by company."      
     Assistant: { "sql": "SELECT * FROM reviews", "paramValues": [] }
   
     User: "Display all reviews for companies located in cities that start with 'L'."
     Assistant: { "sql": "SELECT r.* FROM reviews r INNER JOIN customers c ON r.customer_id = c.id WHERE c.city LIKE 'L%'", "paramValues": [] }
   
     User: "Display revenue for companies located in London. Include the company name and city."
     Assistant: { 
       "sql": "SELECT c.company, c.city, SUM(o.total) AS revenue FROM customers c INNER JOIN orders o ON c.id = o.customer_id WHERE c.city = $1 GROUP BY c.company, c.city", 
       "paramValues": ["London"] 
     }
   
     User: "Get the total revenue for Adventure Works Cycles. Include the contact information as well."
     Assistant: { 
       "sql": "SELECT c.company, c.city, c.email, SUM(o.total) AS revenue FROM customers c INNER JOIN orders o ON c.id = o.customer_id WHERE c.company = $1 GROUP BY c.company, c.city, c.email", 
       "paramValues": ["Adventure Works Cycles"] 
     }
   `;
   

   • Viene definito il tipo di assistente di intelligenza artificiale da usare. In questo caso un "linguaggio naturale per il bot SQL".

   • I nomi e le colonne delle tabelle nel database sono definiti. Lo schema generale incluso nel prompt è disponibile nel file server/db.schema e ha un aspetto simile al seguente.

     - customers (id, company, city, email)
     - orders (id, customer_id, date, total)
     - order_items (id, order_id, product_id, quantity, price)
     - reviews (id, customer_id, review, date, comment)
     

     Suggerimento

     È possibile prendere in considerazione la creazione di viste di sola lettura che contengono solo gli utenti di dati possono eseguire query usando il linguaggio naturale in SQL.

   • Viene definita una regola per convertire qualsiasi valore stringa in un valore di query con parametri per evitare attacchi SQL injection.

   • Una regola viene definita per restituire sempre un oggetto JSON con la query SQL e i valori dei parametri in esso contenuti.

   • Vengono forniti i prompt utente di esempio e i valori di parametri e query SQL previsti. Questo è detto apprendimento "pochi colpi". Anche se i moduli APM vengono sottoposti a training su grandi quantità di dati, possono essere adattati alle nuove attività con solo alcuni esempi. Un approccio alternativo è l'apprendimento "zero-shot" in cui non viene fornito alcun esempio e si prevede che il modello generi i valori di query e parametri SQL corretti.

5. La getSQLFromNLP() funzione invia al sistema e all'utente richieste a una funzione denominata callOpenAI() che si trova anche nel file server/openAI.ts . La callOpenAI() funzione determina se il servizio OpenAI di Azure o il servizio OpenAI deve essere chiamato controllando le variabili di ambiente. Se nelle variabili di ambiente sono disponibili una chiave, un endpoint e un modello, viene chiamato OpenAI di Azure. In caso contrario, viene chiamato OpenAI.

   function callOpenAI(systemPrompt: string, userPrompt: string, temperature = 0, useBYOD = false) {
       const isAzureOpenAI = OPENAI_API_KEY && OPENAI_ENDPOINT && OPENAI_MODEL;
   
       if (isAzureOpenAI) {
           if (useBYOD) {
               return getAzureOpenAIBYODCompletion(systemPrompt, userPrompt, temperature);
           }
           return getAzureOpenAICompletion(systemPrompt, userPrompt, temperature);
       }
   
       return getOpenAICompletion(systemPrompt, userPrompt, temperature);
   }
   

   Nota

   Anche se in questa esercitazione ci si concentrerà su Azure OpenAI, se si specifica solo un OPENAI_API_KEY valore nel file con estensione env , l'applicazione userà invece OpenAI. Se si sceglie di usare OpenAI invece di Azure OpenAI, in alcuni casi potrebbero verificarsi risultati diversi.

6. Individuare la getAzureOpenAICompletion() funzione .

   async function getAzureOpenAICompletion(systemPrompt: string, userPrompt: string, temperature: number): Promise<string> {
       const completion = await createAzureOpenAICompletion(systemPrompt, userPrompt, temperature);
       let content = completion.choices[0]?.message?.content?.trim() ?? '';
       console.log('Azure OpenAI Output: \n', content);
       if (content && content.includes('{') && content.includes('}')) {
           content = extractJson(content);
       }
       return content;
   }
   

   Questa funzione esegue le operazioni seguenti:

   • Parametri:

     • systemPrompt, userPrompte temperature sono i parametri principali.
       • systemPrompt: informa il modello OpenAI di Azure del ruolo e le regole da seguire.
       • userPrompt: contiene le informazioni fornite dall'utente, ad esempio l'input del linguaggio naturale o le regole per la generazione dell'output.
       • temperature: determina il livello di creatività della risposta del modello. Un valore più elevato genera output più creativi.

   • Generazione completamento:

     • La funzione chiama createAzureOpenAICompletion() con systemPrompt, userPrompte temperature per generare un completamento.
     • Estrae il contenuto dalla prima scelta nel completamento, tagliando eventuali spazi vuoti aggiuntivi.
     • Se il contenuto contiene strutture simili a JSON (indicate dalla presenza di { e }), estrae il contenuto JSON.

   • Registrazione e valore restituito:

     • La funzione registra l'output di Azure OpenAI nella console.
     • Restituisce il contenuto elaborato come stringa.

7. Individuare la createAzureOpenAICompletion() funzione .

   async function createAzureOpenAICompletion(systemPrompt: string, userPrompt: string, temperature: number, dataSources?: any[]): Promise<any> {
       const baseEnvVars = ['OPENAI_API_KEY', 'OPENAI_ENDPOINT', 'OPENAI_MODEL'];
       const byodEnvVars = ['AZURE_AI_SEARCH_ENDPOINT', 'AZURE_AI_SEARCH_KEY', 'AZURE_AI_SEARCH_INDEX'];
       const requiredEnvVars = dataSources ? [...baseEnvVars, ...byodEnvVars] : baseEnvVars;
       checkRequiredEnvVars(requiredEnvVars);
   
       const config = { 
           apiKey: OPENAI_API_KEY,
           endpoint: OPENAI_ENDPOINT,
           apiVersion: OPENAI_API_VERSION,
           deployment: OPENAI_MODEL
       };
       const aoai = new AzureOpenAI(config);
       const completion = await aoai.chat.completions.create({
           model: OPENAI_MODEL, // gpt-4o, gpt-3.5-turbo, etc. Pulled from .env file
           max_tokens: 1024,
           temperature,
           response_format: {
               type: "json_object",
           },
           messages: [
               { role: 'system', content: systemPrompt },
               { role: 'user', content: userPrompt }
           ],
           // @ts-expect-error data_sources is a custom property used with the "Azure Add Your Data" feature
           data_sources: dataSources
       });
       return completion;
   }
   
   function checkRequiredEnvVars(requiredEnvVars: string[]) {
       for (const envVar of requiredEnvVars) {
           if (!process.env[envVar]) {
               throw new Error(`Missing ${envVar} in environment variables.`);
           }
       }
   }
   

   Questa funzione esegue le operazioni seguenti:

   • Parametri:

     • systemPrompt, userPrompte temperature sono i parametri principali descritti in precedenza.
     • Un parametro facoltativo dataSources supporta la funzionalità "Azure Bring Your Own Data", che verrà illustrata più avanti in questa esercitazione.

   • Controllo variabili di ambiente:

     • La funzione verifica la presenza di variabili di ambiente essenziali, generando un errore se manca.

   • Oggetto Configuration:

     • Un config oggetto viene creato usando i valori del .env file (OPENAI_API_KEY, OPENAI_ENDPOINT, OPENAI_API_VERSION, OPENAI_MODEL). Questi valori vengono usati per costruire l'URL per chiamare Azure OpenAI.

   • Istanza di AzureOpenAI:

     • Viene creata un'istanza di AzureOpenAI usando l'oggetto config. Il AzureOpenAI simbolo fa parte del openai pacchetto, che deve essere importato all'inizio del file.

   • Generazione di un completamento:

     • La chat.completions.create() funzione viene chiamata con le proprietà seguenti:
       • model: specifica il modello GPT (ad esempio, gpt-4o, gpt-3.5-turbo) come definito nel .env file.
       • max_tokens: definisce il numero massimo di token per il completamento.
       • temperature: imposta la temperatura di campionamento. I valori più alti (ad esempio, 0,9) producono risposte più creative, mentre i valori inferiori (ad esempio, 0) producono risposte più deterministiche.
       • response_format: definisce il formato di risposta. In questo caso, è impostato per restituire un oggetto JSON. Per altre informazioni sulla modalità JSON, vedere la documentazione di riferimento di Azure OpenAI.
       • messages: contiene i messaggi per la generazione di completamenti della chat. Questo esempio include due messaggi: uno dal sistema (definizione di comportamento e regole) e uno dall'utente (contenente il testo della richiesta).

   • Return Value (Valore restituito):

     • La funzione restituisce l'oggetto di completamento generato da Azure OpenAI.

8. Impostare come commento le righe seguenti nella getSQLFromNLP() funzione :

   // if (isProhibitedQuery(queryData.sql)) { 
   //     queryData.sql = '';
   // }
   

9. Salvare openAI.ts. Il server API ricompila automaticamente il codice TypeScript e riavvia il server.

10. Tornare al browser e immettere Selezionare tutti i nomi di tabella dal database nell'input query personalizzata. Selezionare Esegui query. Vengono visualizzati i nomi delle tabelle?

11. Tornare alla getSQLFromNLP() funzione nel server/openAI.ts e aggiungere la regola seguente nella Rules: sezione del prompt di sistema e quindi salvare il file.

    - Do not allow the SELECT query to return table names, function names, or procedure names.
    

12. Tornare al browser ed eseguire le attività seguenti:

    • Immettere Selezionare tutti i nomi di tabella dal database nell'input query personalizzata. Selezionare Esegui query. Vengono visualizzati i nomi delle tabelle?
    • Immettere Selezionare tutti i nomi di funzione dal database. Nell'input query personalizzata e selezionare di nuovo Esegui query . Vengono visualizzati i nomi delle funzioni?

13. DOMANDA: un modello seguirà sempre le regole definite nel prompt?

    RISPOSTA: No! È importante notare che i modelli OpenAI possono restituire risultati imprevisti in occasione che potrebbero non corrispondere alle regole definite. È importante pianificarlo nel codice.

14. Tornare al server/openAI.ts e individuare la isProhibitedQuery() funzione. Questo è un esempio di codice post-elaborazione che può essere eseguito dopo che Azure OpenAI restituisce i risultati. Si noti che imposta la sql proprietà su una stringa vuota se nella query SQL generata vengono restituite parole chiave non consentite. In questo modo, se vengono restituiti risultati imprevisti da Azure OpenAI, la query SQL non verrà eseguita sul database.

    function isProhibitedQuery(query: string): boolean {
        if (!query) return false;
    
        const prohibitedKeywords = [
            'insert', 'update', 'delete', 'drop', 'truncate', 'alter', 'create', 'replace',
            'information_schema', 'pg_catalog', 'pg_tables', 'pg_proc', 'pg_namespace', 'pg_class',
            'table_schema', 'table_name', 'column_name', 'column_default', 'is_nullable',
            'data_type', 'udt_name', 'character_maximum_length', 'numeric_precision',
            'numeric_scale', 'datetime_precision', 'interval_type', 'collation_name',
            'grant', 'revoke', 'rollback', 'commit', 'savepoint', 'vacuum', 'analyze'
        ];
        const queryLower = query.toLowerCase();
        return prohibitedKeywords.some(keyword => queryLower.includes(keyword));
    }
    

    Nota

    È importante notare che questo è solo il codice demo. Potrebbero essere presenti altre parole chiave non consentite necessarie per coprire i casi d'uso specifici se si sceglie di convertire il linguaggio naturale in SQL. Si tratta di una funzionalità che è necessario pianificare e usare con attenzione per assicurarsi che vengano restituite e eseguite solo query SQL valide sul database. Oltre alle parole chiave non consentite, è anche necessario tenere conto della sicurezza.

15. Tornare al server/openAI.ts e rimuovere il commento dal codice seguente nella getSQLFromNLP() funzione. Salvare il file.

    if (isProhibitedQuery(queryData.sql)) { 
        queryData.sql = '';
    }
    

16. Rimuovere la regola seguente da systemPrompt e salvare il file.

    - Do not allow the SELECT query to return table names, function names, or procedure names.
    

17. Tornare al browser, immettere Selezionare di nuovo tutti i nomi di tabella dal database nell'input query personalizzata e selezionare il pulsante Esegui query .

18. Vengono visualizzati i risultati della tabella? Anche senza la regola, il isProhibitedQuery() codice di post-elaborazione impedisce l'esecuzione del tipo di query nel database.

19. Come illustrato in precedenza, l'integrazione del linguaggio naturale in SQL in applicazioni line-of-business può essere molto utile per gli utenti, ma offre un proprio set di considerazioni.

    Vantaggi:

    • Familiarità con l'utente: questa funzionalità può rendere l'interazione del database più accessibile agli utenti senza competenze tecniche, riducendo la necessità di conoscenze SQL e accelerando potenzialmente le operazioni.

    • Maggiore produttività: analisti aziendali, marketer, dirigenti e altri utenti non tecnici possono recuperare informazioni preziose dai database senza dover affidarsi a esperti tecnici, aumentando così l'efficienza.

    • Ampia applicazione: usando modelli linguistici avanzati, le applicazioni possono essere progettate per soddisfare un'ampia gamma di utenti e casi d'uso.

    Considerazioni:

    • Sicurezza: una delle principali preoccupazioni è la sicurezza. Se gli utenti possono interagire con i database usando il linguaggio naturale, è necessario adottare misure di sicurezza affidabili per impedire l'accesso non autorizzato o le query dannose. È possibile implementare una modalità di sola lettura per impedire agli utenti di modificare i dati.

    • Privacy dei dati: alcuni dati potrebbero essere sensibili e non dovrebbero essere facilmente accessibili, pertanto è necessario garantire misure di sicurezza e autorizzazioni utente appropriate.

    • Accuratezza: anche se l'elaborazione del linguaggio naturale è migliorata in modo significativo, non è perfetta. L'interpretazione errata delle query utente può causare risultati imprecisi o comportamenti imprevisti. Sarà necessario pianificare la modalità di gestione dei risultati imprevisti.

    • Efficienza: non ci sono garanzie che sql restituito da una query in linguaggio naturale sarà efficiente. In alcuni casi, potrebbero essere necessarie chiamate aggiuntive ad Azure OpenAI se le regole di post-elaborazione rilevano problemi con le query SQL.

    • Training e adattamento utente: è necessario eseguire il training degli utenti per formulare correttamente le query. Anche se è più semplice che imparare SQL, può comunque essere coinvolta una curva di apprendimento.

20. Alcuni punti finali da considerare prima di passare all'esercizio successivo:

    • Tenere presente che "Solo perché non si può dire che si dovrebbe" si applica qui. Prestare particolare attenzione e attenzione prima di integrare il linguaggio naturale in SQL in un'applicazione. È importante comprendere i potenziali rischi e pianificarli.
    • Prima di usare questo tipo di tecnologia, discutere i potenziali scenari con il team, gli amministratori di database, il team di sicurezza, gli stakeholder e qualsiasi altra parte pertinente per assicurarsi che sia appropriato per l'organizzazione. È importante discutere se il linguaggio naturale con SQL soddisfa la sicurezza, la privacy e qualsiasi altro requisito che l'organizzazione potrebbe avere.
    • La sicurezza deve essere un problema principale e integrato nel processo di pianificazione, sviluppo e distribuzione.
    • Anche se il linguaggio naturale per SQL può essere molto potente, è necessario eseguire un'attenta pianificazione per assicurarsi che le richieste abbiano regole necessarie e che sia inclusa la funzionalità di post-elaborazione. Pianificare tempo aggiuntivo per implementare e testare questo tipo di funzionalità e tenere conto degli scenari in cui vengono restituiti risultati imprevisti.
    • Con OpenAI di Azure i clienti accedono alle funzionalità di sicurezza di Microsoft Azure eseguendo gli stessi modelli di OpenAI. Azure OpenAI offre funzionalità di rete privata, disponibilità a livello di area e filtro dei contenuti di intelligenza artificiale responsabile. Altre informazioni su Dati, privacy e sicurezza per il servizio OpenAI di Azure.

21. È stato illustrato come usare Azure OpenAI per convertire il linguaggio naturale in SQL ed è stato illustrato i vantaggi e i svantaggi dell'implementazione di questo tipo di funzionalità. Nell'esercizio successivo si apprenderà come generare messaggi di posta elettronica e SMS usando Azure OpenAI.

Intelligenza artificiale: generazione di completamenti

• 112 minuti rimanenti

Oltre alla funzionalità linguaggio naturale per SQL, è anche possibile usare il servizio Azure OpenAI per generare messaggi di posta elettronica e SMS per migliorare la produttività degli utenti e semplificare i flussi di lavoro di comunicazione. Usando le funzionalità di generazione del linguaggio di Azure OpenAI, gli utenti possono definire regole specifiche, ad esempio "Order is delayed 5 days" e il sistema genererà automaticamente messaggi di posta elettronica e SMS appropriati contestualmente in base a tali regole.

Questa funzionalità funge da jump start per gli utenti, fornendo loro un modello di messaggio appositamente creato che possono facilmente personalizzare prima dell'invio. Il risultato è una riduzione significativa del tempo e dello sforzo necessario per comporre messaggi, consentendo agli utenti di concentrarsi su altre attività importanti. Inoltre, la tecnologia di generazione del linguaggio di Azure OpenAI può essere integrata nei flussi di lavoro di automazione, consentendo al sistema di generare e inviare messaggi in modo autonomo in risposta a trigger predefiniti. Questo livello di automazione non solo accelera i processi di comunicazione, ma garantisce anche messaggi coerenti e accurati in vari scenari.

In questo esercizio si eseguiranno le seguenti operazioni:

• Sperimentare con richieste diverse.
• Usare le istruzioni per generare completamenti per i messaggi di posta elettronica e SMS.
• Esplorare il codice che abilita i completamenti di intelligenza artificiale.
• Informazioni sull'importanza della progettazione dei prompt e sull'inclusione delle regole nelle richieste.

Iniziamo sperimentando regole diverse che possono essere usate per generare messaggi di posta elettronica e SMS.

Uso della funzionalità Completamento intelligenza artificiale

1. In un esercizio precedente è stato avviato il database, le API e l'applicazione. È stato aggiornato anche il .env file. Se questi passaggi non sono stati completati, seguire le istruzioni alla fine dell'esercizio prima di continuare.

2. Tornare al browser (http://localhost:4200) e selezionare Contatta cliente in qualsiasi riga della griglia dati seguita da Email/SMS Customer (Cliente di posta elettronica/SMS) per accedere alla schermata Generatore messaggi .

3. Viene usato Azure OpenAI per convertire le regole dei messaggi definite in messaggi di posta elettronica/SMS. Eseguire le attività seguenti:

   • Immettere una regola, ad esempio Order, ritardata di 5 giorni nell'input e selezionare il pulsante Genera messaggi di posta elettronica/SMS.

     

   • Verrà visualizzato un oggetto e un corpo generati per il messaggio di posta elettronica e un breve messaggio generato per l'SMS.

   Nota

   Poiché Servizi di comunicazione di Azure non è ancora abilitato, non sarà possibile inviare messaggi di posta elettronica o SMS.

4. Chiudere la finestra di dialogo email/SMS nel browser. Dopo aver visto questa funzionalità in azione, esaminiamo come viene implementata.

Esplorazione del codice di completamento dell'intelligenza artificiale

1. Aprire il file server/apiRoutes.ts e individuare la completeEmailSmsMessages route. Questa API viene chiamata dalla parte front-end dell'app quando è selezionato il pulsante Genera messaggi di posta elettronica/SMS. Recupera i valori di prompt dell'utente, società e nome contatto dal corpo e li passa alla completeEmailSMSMessages() funzione nel file server/openAI.ts . I risultati vengono quindi restituiti al client.

   router.post('/completeEmailSmsMessages', async (req, res) => {
       const { prompt, company, contactName } = req.body;
   
       if (!prompt || !company || !contactName) {
           return res.status(400).json({ 
               status: false, 
               error: 'The prompt, company, and contactName parameters must be provided.' 
           });
       }
   
       let result;
       try {
           // Call OpenAI to get the email and SMS message completions
       result = await completeEmailSMSMessages(prompt, company, contactName);
       }
       catch (e: unknown) {
           console.error('Error parsing JSON:', e);
       }
   
       res.json(result);
   });
   

2. Aprire il file server/openAI.ts e individuare la completeEmailSMSMessages() funzione.

   async function completeEmailSMSMessages(prompt: string, company: string, contactName: string) {
       console.log('Inputs:', prompt, company, contactName);
   
       const systemPrompt = `
       Assistant is a bot designed to help users create email and SMS messages from data and 
       return a JSON object with the email and SMS message information in it.
   
       Rules:
       - Generate a subject line for the email message.
       - Use the User Rules to generate the messages. 
       - All messages should have a friendly tone and never use inappropriate language.
       - SMS messages should be in plain text format and NO MORE than 160 characters. 
       - Start the message with "Hi <Contact Name>,\n\n". Contact Name can be found in the user prompt.
       - Add carriage returns to the email message to make it easier to read. 
       - End with a signature line that says "Sincerely,\nCustomer Service".
       - Return a valid JSON object with the emailSubject, emailBody, and SMS message values in it:
   
       { "emailSubject": "", "emailBody": "", "sms": "" }
   
       - The sms property value should be in plain text format and NO MORE than 160 characters.
       `;
   
       const userPrompt = `
       User Rules: 
       ${prompt}
   
       Contact Name: 
       ${contactName}
       `;
   
       let content: EmailSmsResponse = { status: true, email: '', sms: '', error: '' };
       let results = '';
       try {
           results = await callOpenAI(systemPrompt, userPrompt, 0.5);
           if (results) {
               const parsedResults = JSON.parse(results);
               content = { ...content, ...parsedResults, status: true };
           }
       }
       catch (e) {
           console.log(e);
           content.status = false;
           content.error = results;
       }
   
       return content;
   }
   

   Questa funzione presenta le funzionalità seguenti:

   • systemPrompt viene usato per definire che è necessario un assistente di intelligenza artificiale in grado di generare messaggi di posta elettronica e SMS. Include systemPrompt anche:
     • Regole per l'assistente da seguire per controllare il tono dei messaggi, il formato iniziale e finale, la lunghezza massima dei messaggi SMS e altro ancora.
     • Informazioni sui dati che devono essere inclusi nella risposta: in questo caso un oggetto JSON.
   • userPrompt viene usato per definire le regole e il nome di contatto che l'utente finale desidera includere come messaggi di posta elettronica e SMS vengono generati. La regola Order è ritardata di 5 giorni immessa in precedenza è inclusa in userPrompt.
   • La funzione chiama la callOpenAI() funzione esaminata in precedenza per generare il messaggio di posta elettronica e i completamenti SMS.

3. Tornare al browser, aggiornare la pagina e selezionare Contatta cliente in qualsiasi riga seguita da Messaggio di posta elettronica/SMS Cliente per tornare alla schermata Generatore messaggi .

4. Immettere le regole seguenti nell'input del generatore di messaggi :

   • L'ordine è in anticipo.
   • Di' al cliente di non ordinare mai più da noi, non vogliamo la loro attività.

5. Selezionare Genera messaggi di posta elettronica/SMS e prendere nota del messaggio. La All messages should have a friendly tone and never use inappropriate language. regola nel prompt di sistema sostituisce la regola negativa nella richiesta dell'utente.

6. Tornare al server/openAI.ts* nell'editor e rimuovere la All messages should have a friendly tone and never use inappropriate language. regola dal prompt nella completeEmailSMSMessages() funzione. Salvare il file.

7. Tornare al generatore di messaggi di posta elettronica/SMS nel browser ed eseguire di nuovo le stesse regole:

   • L'ordine è in anticipo.
   • Di' al cliente di non ordinare mai più da noi, non vogliamo la loro attività.

8. Selezionare Generate Email/SMS Messages (Genera messaggi di posta elettronica/SMS) e notare il messaggio restituito.

9. Che cosa accade in questi scenari? Quando si usa Azure OpenAI, è possibile applicare il filtro del contenuto per assicurarsi che venga sempre usato il linguaggio appropriato. Se si usa OpenAI, la regola definita nel prompt di sistema viene usata per assicurarsi che il messaggio restituito sia appropriato.

   Nota

   Ciò illustra l'importanza della progettazione delle richieste con le informazioni e le regole corrette per garantire che vengano restituiti risultati appropriati. Altre informazioni su questo processo sono disponibili nella documentazione introduttiva alla richiesta di progettazione .

10. Annullare le modifiche apportate a systemPrompt in completeEmailSMSMessages(), salvare il file ed eseguirlo di nuovo, ma usare solo la Order is ahead of schedule. regola (non includere la regola negativa). Questa volta dovrebbero essere visualizzati i messaggi di posta elettronica e SMS restituiti come previsto.

11. Alcuni punti finali da considerare prima di passare all'esercizio successivo:

    • È importante avere un essere umano nel ciclo per esaminare i messaggi generati. In questo esempio i completamenti Di Azure OpenAI restituiscono messaggi di posta elettronica e SMS suggeriti, ma l'utente può eseguire l'override di quelli prima dell'invio. Se si prevede di automatizzare i messaggi di posta elettronica, avere un certo tipo di processo di revisione umana per garantire che i messaggi approvati vengano inviati è importante. Visualizzare l'intelligenza artificiale come copilota, non autopilot.
    • I completamenti saranno validi solo come le regole aggiunte al prompt. Dedicare tempo per testare le richieste e i completamenti restituiti. Prendere in considerazione l'uso di Prompt flow per creare una soluzione completa che semplifica la creazione di prototipi, l'esperimento, l'iterazione e la distribuzione di applicazioni di intelligenza artificiale. Invitare altri stakeholder del progetto a esaminare anche i completamenti.
    • Potrebbe essere necessario includere il codice di post-elaborazione per garantire che i risultati imprevisti vengano gestiti correttamente.
    • Usare le istruzioni di sistema per definire le regole e le informazioni che l'assistente di intelligenza artificiale deve seguire. Usare le richieste dell'utente per definire le regole e le informazioni che l'utente finale desidera includere nei completamenti.

Intelligenza artificiale: Azure OpenAI sui dati

• 102 minuti rimanenti

L'integrazione delle funzionalità di elaborazione del linguaggio naturale (NLP) di Azure OpenAI offre un potenziale significativo per migliorare la produttività degli utenti. Sfruttando le richieste e le regole appropriate, un assistente di intelligenza artificiale può generare in modo efficiente varie forme di comunicazione, ad esempio messaggi di posta elettronica, messaggi SMS e altro ancora. Questa funzionalità comporta una maggiore efficienza degli utenti e flussi di lavoro semplificati.

Anche se questa funzionalità è molto potente da sola, possono verificarsi casi in cui gli utenti devono generare completamenti in base ai dati personalizzati dell'azienda. Ad esempio, potrebbe essere disponibile una raccolta di manuali di prodotto che potrebbero risultare difficili da esplorare quando aiutano i clienti a risolvere i problemi di installazione. In alternativa, è possibile mantenere un set completo di domande frequenti correlate ai vantaggi sanitari che possono rivelarsi difficili da leggere e ottenere le risposte necessarie. In questi casi e molti altri, il servizio Azure OpenAI consente di sfruttare i propri dati per generare completamenti, garantendo una risposta più personalizzata e contestualmente accurata alle domande dell'utente.

Ecco una rapida panoramica del funzionamento della funzionalità "Bring Your Own Data" dalla documentazione di Azure OpenAI.

In questo esercizio si eseguiranno le seguenti operazioni:

• Creare un'origine dati personalizzata usando Azure AI Studio.
• Distribuire un modello di incorporamento con Azure AI Studio.
• Caricare documenti personalizzati.
• Avviare una sessione di chat nel playground chat per sperimentare la generazione di completamenti in base ai propri dati.
• Esplorare il codice che usa Ricerca di intelligenza artificiale di Azure e Azure OpenAI per generare completamenti in base ai propri dati.

Per iniziare, distribuire un modello di incorporamento e aggiungere un'origine dati personalizzata in Azure AI Studio.

Aggiunta di un'origine dati personalizzata ad Azure AI Studio

1. Passare ad Azure OpenAI Studio e accedere con le credenziali che hanno accesso alla risorsa OpenAI di Azure.

2. Selezionare Distribuzioni dal menu di spostamento.

3. Selezionare Distribuisci modello -->Distribuisci modello di base sulla barra degli strumenti.

4. Selezionare il modello text-embedding-ada-002 dall'elenco dei modelli e selezionare Conferma.

5. Seleziona le seguenti opzioni:

   • Nome distribuzione: text-embedding-ada-002
   • Versione del modello: predefinita
   • Tipo di distribuzione: Standard
   • Impostare il valore Token al minuto limite di frequenza (migliaia) su 120.000
   • Filtro contenuto: DefaultV2
   • Abilita virgolette dinamiche: abilitato

6. Selezionare il pulsante Distribuisci .

7. Dopo aver creato il modello, selezionare Home dal menu di spostamento per passare alla schermata iniziale.

8. Individuare il riquadro Bring your own data (Bring your own data ) nella schermata iniziale e selezionare Try it now (Prova adesso).

   

9. Selezionare Aggiungi i dati e quindi Aggiungi un'origine dati.

10. Nell'elenco a discesa Seleziona origine dati selezionare Carica file.

11. Nell'elenco a discesa Selezionare la risorsa di archiviazione BLOB di Azure selezionare Crea una nuova risorsa di archiviazione BLOB di Azure.

12. Selezionare la sottoscrizione di Azure nell'elenco a discesa Sottoscrizione .

13. Nell'elenco a discesa Selezionare la risorsa di archiviazione BLOB di Azure selezionare Crea una nuova risorsa di archiviazione BLOB di Azure.

14. Verrà visualizzata la portale di Azure in cui è possibile eseguire le attività seguenti:

    • Immettere un nome univoco per l'account di archiviazione, ad esempio byodstorage[Cognome].
    • Selezionare un'area vicina alla località.
    • Selezionare Rivedi e crea.

15. Dopo aver creato la risorsa di archiviazione BLOB, tornare alla finestra di dialogo Azure AI Studio e selezionare la risorsa di archiviazione BLOB appena creata dall'elenco a discesa Selezionare la risorsa di archiviazione BLOB di Azure. Se non viene visualizzato nell'elenco, selezionare l'icona di aggiornamento accanto all'elenco a discesa.

16. Per poter accedere all'account di archiviazione, è necessario attivare la condivisione di risorse tra le origini (CORS). Selezionare Attiva CORS nella finestra di dialogo Azure AI Studio.

    

17. Nell'elenco a discesa Selezionare la risorsa di Ricerca intelligenza artificiale di Azure selezionare Crea una nuova risorsa di Ricerca intelligenza artificiale di Azure.

18. Verrà visualizzata la portale di Azure in cui è possibile eseguire le attività seguenti:

    • Immettere un nome univoco per la risorsa di ricerca di intelligenza artificiale, ad esempio byodsearch-[Cognome].
    • Selezionare un'area vicina alla località.
    • Nella sezione Piano tariffario selezionare Cambia piano tariffario e selezionare Basic seguito da Seleziona. Il livello gratuito non è supportato, quindi si pulisce la risorsa di ricerca di intelligenza artificiale alla fine di questa esercitazione.
    • Selezionare Rivedi e crea.

19. Dopo aver creato la risorsa di ricerca di intelligenza artificiale, passare alla pagina Panoramica della risorsa e copiare il valore url in un file locale.

    

20. Selezionare Impostazioni -->Chiavi nel menu di spostamento.

21. Nella pagina Controllo di accesso API selezionare Entrambi per abilitare l'accesso al servizio usando l'identità gestita o usando una chiave. Selezionare Sì quando richiesto.

    Nota

    Anche se in questo esercizio si userà una chiave API perché l'aggiunta di assegnazioni di ruolo può richiedere fino a 10 minuti, con un piccolo sforzo aggiuntivo è possibile abilitare un'identità gestita assegnata dal sistema per accedere al servizio in modo più sicuro.

22. Selezionare Chiavi nel menu di spostamento a sinistra e copiare il valore della chiave di amministrazione primaria in un file locale. I valori di URL e chiave saranno necessari più avanti nell'esercizio.

23. Selezionare Impostazioni -->Semantic ranker nel menu di spostamento e assicurarsi che sia selezionato Gratuito.

    Nota

    Per verificare se il classificatore semantico è disponibile in un'area specifica, controllare la pagina Prodotti disponibili per area nel sito Web di Azure per verificare se l'area è elencata.

24. Tornare alla finestra di dialogo Aggiungi dati di Azure AI Studio e selezionare la risorsa di ricerca appena creata dall'elenco a discesa Selezionare la risorsa di Ricerca intelligenza artificiale di Azure. Se non viene visualizzato nell'elenco, selezionare l'icona di aggiornamento accanto all'elenco a discesa.

25. Immettere il valore byod-search-index per immettere il valore del nome dell'indice.

26. Selezionare la casella di controllo Aggiungi ricerca vettoriale a questa risorsa di ricerca.

27. Nell'elenco a discesa Selezionare un modello di incorporamento selezionare il modello text-embedding-ada-002 creato in precedenza.

28. Nella finestra di dialogo Carica file selezionare Sfoglia per un file.

29. Passare alla cartella documenti del cliente del progetto (che si trova nella radice del progetto) e selezionare i file seguenti:

    • Clock A102 Installation Instructions.docx
    • FAQs.docx aziendale

    Nota

    Questa funzionalità supporta attualmente i formati di file seguenti per la creazione dell'indice locale: .txt, md, .html, .pdf, .docx e .pptx.

30. Selezionare Upload files (Carica file). I file verranno caricati in un contenitore fileupload-byod-search-index nella risorsa di archiviazione BLOB creata in precedenza.

31. Selezionare Avanti per passare alla finestra di dialogo Gestione dati.

32. Nell'elenco a discesa Tipo di ricerca selezionare Ibrido e semantico.

    Nota

    Questa opzione fornisce il supporto per la ricerca di parole chiave e vettore. Una volta restituiti i risultati, viene applicato un processo di classificazione secondario al set di risultati usando modelli di Deep Learning che migliora la pertinenza della ricerca per l'utente. Per altre informazioni sulla ricerca semantica, vedere la documentazione ricerca semantica nella documentazione di Ricerca di intelligenza artificiale di Azure.

33. Assicurarsi che il valore Selezionare una dimensione sia impostato su 1024.

34. Selezionare Avanti.

35. Per il tipo di autenticazione delle risorse di Azure selezionare Chiave API. Altre informazioni sulla selezione del tipo di autenticazione corretto sono disponibili nella documentazione sull'autenticazione di Ricerca di intelligenza artificiale di Azure.

36. Selezionare Avanti.

37. Esaminare i dettagli e selezionare Salva e chiudi.

38. Ora che i dati personalizzati sono stati caricati, i dati verranno indicizzati e disponibili per l'uso nel playground di Chat. Questo processe può richiedere alcuni minuti. Al termine, continuare con la sezione successiva.

Uso dell'origine dati personalizzata in Chat Playground

1. Individuare la sezione Sessione di chat della pagina in Azure OpenAI Studio e immettere la query Utente seguente:

   What safety rules are required to install a clock?
   

2. Dopo aver inviato la query utente, verrà visualizzato un risultato simile al seguente:

   

3. Espandere la sezione 1 riferimenti nella risposta della chat e notare che il file Clock A102 Installation Instructions.docx file (Installazione orologio A102) è elencato e che è possibile selezionarlo per visualizzare il documento.

4. Immettere il messaggio Utente seguente:

   What should I do to mount the clock on the wall?
   

5. Verrà visualizzato un risultato simile al seguente:

   

6. Si esaminerà ora il documento Domande frequenti sull'azienda. Immettere il testo seguente nel campo Query utente:

   What is the company's policy on vacation time?
   

7. Si noterà che non sono state trovate informazioni per tale richiesta.

8. Immettere il testo seguente nel campo Query utente:

   How should I handle refund requests?
   

9. Verrà visualizzato un risultato simile al seguente:

   

10. Espandere la sezione 1 riferimenti nella risposta di chat e notare che il file company FAQs.docx è elencato e che è possibile selezionarlo per visualizzare il documento.

11. Selezionare Visualizza codice nella barra degli strumenti del playground chat.

    

12. Si noti che è possibile passare da una lingua all'altra, visualizzare l'endpoint e accedere alla chiave dell'endpoint. Chiudere la finestra di dialogo Codice di esempio.

    

13. Attivare l'interruttore Mostra JSON non elaborato sopra i messaggi di chat. Si noti che la sessione di chat inizia con un messaggio simile al seguente:

    {
        "role": "system",
        "content": "You are an AI assistant that helps people find information."
    }
    

14. Ora che è stata creata un'origine dati personalizzata ed è stata sperimentata nel playground di Chat, si vedrà come usarla nell'applicazione del progetto.

Uso della funzionalità Bring Your Own Data nell'applicazione

1. Tornare al progetto in VS Code e aprire il file con estensione env . Aggiornare i valori seguenti con l'endpoint, la chiave e il nome dell'indice di AI Services. L'endpoint e la chiave sono stati copiati in un file locale in precedenza in questo esercizio.

   AZURE_AI_SEARCH_ENDPOINT=<AI_SERVICES_ENDPOINT_VALUE>
   AZURE_AI_SEARCH_KEY=<AI_SERVICES_KEY_VALUE>
   AZURE_AI_SEARCH_INDEX=byod-search-index
   

2. In un esercizio precedente è stato avviato il database, le API e l'applicazione. È stato aggiornato anche il .env file. Se questi passaggi non sono stati completati, seguire le istruzioni alla fine dell'esercizio precedente prima di continuare.

3. Dopo che l'applicazione è stata caricata nel browser, selezionare l'icona della Guida di Chat in alto a destra dell'applicazione.

   

4. Nella finestra di dialogo della chat verrà visualizzato il testo seguente:

   How should I handle a company refund request?
   

5. Selezionare il pulsante Ottieni guida . Verranno visualizzati i risultati restituiti dal documento Company FAQs.docx caricato in precedenza in Azure OpenAI Studio. Se si vuole leggere il documento, è possibile trovarlo nella cartella documenti del cliente nella radice del progetto.

6. Modificare il testo come segue e selezionare il pulsante Ottieni assistenza :

   What safety rules are required to install a clock?
   

7. Verranno visualizzati i risultati restituiti dal documento Clock A102 Installation Instructions.docx caricato in precedenza in Azure OpenAI Studio. Questo documento è disponibile anche nella cartella documenti del cliente nella radice del progetto.

Esplorazione del codice

1. Tornare al codice sorgente del progetto in Visual Studio Code.

2. Aprire il file server/apiRoutes.ts e individuare la completeBYOD route. Questa API viene chiamata quando viene selezionato il pulsante Ottieni guida nella finestra di dialogo Guida chat. Recupera il prompt dell'utente dal corpo della richiesta e lo passa alla completeBYOD() funzione nel file server/openAI.ts . I risultati vengono quindi restituiti al client.

   router.post('/completeBYOD', async (req, res) => {
       const { prompt } = req.body;
   
       if (!prompt) {
           return res.status(400).json({ 
               status: false, 
               error: 'The prompt parameter must be provided.' 
           });
       }
   
       let result;
       try {
           // Call OpenAI to get custom "bring your own data" completion
       result = await completeBYOD(prompt);
       }
       catch (e: unknown) {
           console.error('Error parsing JSON:', e);
       }
   
       res.json(result);
   });
   

3. Aprire il file server/openAI.ts e individuare la completeBYOD() funzione.

   async function completeBYOD(userPrompt: string): Promise<string> {
       const systemPrompt = 'You are an AI assistant that helps people find information in documents.';
       return await callOpenAI(systemPrompt, userPrompt, 0, true);
   }
   

   Questa funzione presenta le funzionalità seguenti:

   • Il userPrompt parametro contiene le informazioni digitate dall'utente nella finestra di dialogo della Guida della chat.
   • la systemPrompt variabile definisce che verrà usato un assistente di intelligenza artificiale progettato per aiutare gli utenti a trovare informazioni.
   • callOpenAI() viene usato per chiamare l'API OpenAI di Azure e restituire i risultati. Passa i systemPrompt valori e userPrompt e i parametri seguenti:
     • temperature - La quantità di creatività da includere nella risposta. L'utente ha bisogno di risposte coerenti (meno creative) in questo caso in modo che il valore sia impostato su 0.
     • useBYOD - Valore booleano che indica se usare o meno La ricerca di intelligenza artificiale insieme ad Azure OpenAI. In questo caso, è impostato su true in modo che venga usata la funzionalità di ricerca di intelligenza artificiale.

4. La callOpenAI() funzione accetta un useBYOD parametro usato per determinare quale funzione OpenAI chiamare. In questo caso, imposta useBYOD su true in modo che venga chiamata la getAzureOpenAIBYODCompletion() funzione .

   function callOpenAI(systemPrompt: string, userPrompt: string, temperature = 0, useBYOD = false) {
       const isAzureOpenAI = OPENAI_API_KEY && OPENAI_ENDPOINT && OPENAI_MODEL;
   
       if (isAzureOpenAI) {
           if (useBYOD) {
               return getAzureOpenAIBYODCompletion(systemPrompt, userPrompt, temperature);
           }
           return getAzureOpenAICompletion(systemPrompt, userPrompt, temperature);
       }
   
       return getOpenAICompletion(systemPrompt, userPrompt, temperature);
   }
   

5. Individuare la getAzureOpenAIBYODCompletion() funzione in server/openAI.ts. È molto simile alla getAzureOpenAICompletion() funzione esaminata in precedenza, ma viene visualizzata come funzione separata per evidenziare alcune differenze chiave specifiche dello scenario "Azure OpenAI sui dati" disponibile in Azure OpenAI.

   async function getAzureOpenAIBYODCompletion(systemPrompt: string, userPrompt: string, temperature: number): Promise<string> {
       const dataSources = [
           {
               type: 'azure_search',
               parameters: {
                   authentication: {
                       type: 'api_key',
                       key: AZURE_AI_SEARCH_KEY
                   },
                   endpoint: AZURE_AI_SEARCH_ENDPOINT,
                   index_name: AZURE_AI_SEARCH_INDEX
               }
           }
       ];
   
       const completion = await createAzureOpenAICompletion(systemPrompt, userPrompt, temperature, dataSources) as AzureOpenAIYourDataResponse;
       console.log('Azure OpenAI Add Your Own Data Output: \n', completion.choices[0]?.message);
       for (let citation of completion.choices[0]?.message?.context?.citations ?? []) {
           console.log('Citation Path:', citation.filepath);
       }
       return completion.choices[0]?.message?.content?.trim() ?? '';
   }
   

   Si noti la funzionalità seguente nella getAzureOpenAIBYODCompletion() funzione :

   • Viene creata una dataSources proprietà che contiene i valori , endpointe index_name della keyrisorsa di ricerca di intelligenza artificiale aggiunti al .env file in precedenza in questo esercizio
   • La createAzureOpenAICompletion() funzione viene chiamata con i systemPromptvalori , temperatureuserPrompt, e dataSources . Questa funzione viene usata per chiamare l'API OpenAI di Azure e restituire i risultati.
   • Una volta restituita la risposta, le citazioni del documento vengono registrate nella console. Il contenuto del messaggio di completamento viene quindi restituito al chiamante.

6. Alcuni punti finali da considerare prima di passare all'esercizio successivo:

   • L'applicazione di esempio usa un singolo indice in Ricerca di intelligenza artificiale di Azure. È possibile usare più indici e origini dati con Azure OpenAI. La dataSources proprietà nella getAzureOpenAIBYODCompletion() funzione può essere aggiornata per includere più origini dati in base alle esigenze.
   • La sicurezza deve essere valutata attentamente con questo tipo di scenario. Gli utenti non devono essere in grado di porre domande e ottenere risultati dai documenti a cui non sono in grado di accedere.

7. Dopo aver appreso informazioni su Azure OpenAI, richieste, completamenti e su come usare i propri dati, passare all'esercizio successivo per apprendere come usare le funzionalità di comunicazione per migliorare l'applicazione. Per altre informazioni su Azure OpenAI, vedere il contenuto di formazione introduzione al servizio Azure OpenAI. Altre informazioni sull'uso dei propri dati con Azure OpenAI sono disponibili nella documentazione di Azure OpenAI sui dati .

Comunicazione: creazione di una risorsa Servizi di comunicazione di Azure

• 87 minuti rimanenti

Una comunicazione efficace è essenziale per applicazioni aziendali personalizzate di successo. Usando Servizi di comunicazione di Azure (ACS), è possibile aggiungere funzionalità come telefonate, chat in tempo reale, audio/videochiamate e messaggi di posta elettronica e SMS alle applicazioni. In precedenza si è appreso come Azure OpenAI può generare completamenti per i messaggi di posta elettronica e SMS. A questo punto, si apprenderà come inviare i messaggi. Insieme, ACS e OpenAI possono migliorare le applicazioni semplificando la comunicazione, migliorando le interazioni e aumentando la produttività aziendale.

In questo esercizio si eseguiranno le seguenti operazioni:

• Creare una risorsa Servizi di comunicazione di Azure (ACS).
• Aggiungere un numero di telefono verde con funzionalità di chiamata e SMS.
• Connettere un dominio di posta elettronica.
• Aggiornare il file con estensione env del progetto con i valori della risorsa ACS.

Creare una risorsa Servizi di comunicazione di Azure

1. Visitare il portale di Azure nel browser e accedere se non è già stato fatto.

2. Digitare servizi di comunicazione nella barra di ricerca nella parte superiore della pagina e selezionare Servizi di comunicazione dalle opzioni visualizzate.

   

3. Selezionare Crea sulla barra degli strumenti.

4. Eseguire le attività seguenti:

   • Seleziona la tua sottoscrizione di Azure.
   • Selezionare il gruppo di risorse da usare (crearne uno nuovo se non esiste).
   • Immettere un nome di risorsa ACS. Deve essere un valore univoco.
   • Selezionare un percorso dati.

5. Selezionare Rivedi e crea seguito da Crea.

6. È stata creata una nuova risorsa Servizi di comunicazione di Azure. Successivamente, si abiliteranno le funzionalità di chiamata telefonica e SMS. Si connetterà anche un dominio di posta elettronica alla risorsa.

Abilitare le funzionalità chiamate telefoniche e SMS

1. Aggiungere un numero di telefono e assicurarsi che il numero di telefono abbia funzionalità di chiamata abilitate. Questo numero di telefono verrà usato per chiamare un telefono dall'app.

   • Selezionare Telefonia e SMS -->Numeri di telefono dal menu Risorsa.

   • Selezionare + Ottieni sulla barra degli strumenti (o selezionare il pulsante Ottieni un numero ) e immettere le informazioni seguenti:

     • Paese o area geografica: United States
     • Tipo di numero: Toll-free

     Nota

     Per creare il numero verde, è necessaria una carta di credito nella sottoscrizione di Azure. Se non si dispone di una scheda su file, è possibile ignorare l'aggiunta di un numero di telefono e passare alla sezione successiva dell'esercizio che connette un dominio di posta elettronica. Puoi comunque usare l'app, ma non potrai chiamare un numero di telefono.

     • Numero: selezionare Aggiungi al carrello per uno dei numeri di telefono elencati.

2. Selezionare Avanti, esaminare i dettagli del numero di telefono e selezionare Acquista ora.

   Nota

   La verifica tramite SMS per i numeri verdi è ora obbligatoria nei Stati Uniti e canada. Per abilitare la messaggistica SMS, è necessario inviare la verifica dopo l'acquisto del numero di telefono. Anche se questa esercitazione non eseguirà questo processo, è possibile selezionare Telefonia e SMS -->Documenti normativi dal menu delle risorse e aggiungere la documentazione di convalida necessaria.

3. Dopo aver creato il numero di telefono, selezionarlo per accedere al pannello Funzionalità . Assicurarsi che i valori seguenti siano impostati (devono essere impostati per impostazione predefinita):

   • Nella sezione Chiamata selezionare Make calls.
   • Nella sezione SMS selezionare Send and receive SMS.
   • Seleziona Salva.

4. Copiare il valore del numero di telefono in un file per usarlo in un secondo momento. Il numero di telefono deve seguire questo modello generale: +12345678900.

Connettere un dominio di posta elettronica

1. Eseguire le attività seguenti per creare un dominio di posta elettronica connesso per la risorsa ACS in modo da poter inviare un messaggio di posta elettronica. Verrà usato per inviare messaggi di posta elettronica dall'app.

   • Selezionare Posta elettronica -->Domini dal menu Risorsa.
   • Selezionare Connetti dominio sulla barra degli strumenti.
   • Selezionare la sottoscrizione e il gruppo di risorse.
   • Nell'elenco a discesa Servizio di posta elettronica selezionare Add an email service.
   • Assegnare al servizio di posta elettronica un nome, acs-demo-email-servicead esempio .
   • Selezionare Rivedi e crea seguito da Crea.
   • Al termine della distribuzione, selezionare e selezionare Go to resource1-click add per aggiungere un sottodominio di Azure gratuito.
   • Dopo aver aggiunto il sottodominio (la distribuzione richiederà alcuni istanti), selezionarla.
   • Una volta visualizzata la schermata AzureManagedDomain , selezionare Servizi di posta elettronica -->MailDa indirizzi dal menu Risorsa.
   • Copiare il valore MailFrom in un file. Verrà usato in un secondo momento durante l'aggiornamento del file con estensione env .
   • Tornare alla risorsa Servizi di comunicazione di Azure e selezionare Posta elettronica -->Domini dal menu delle risorse.
   • Selezionare Add domain e immettere il MailFrom valore del passaggio precedente (assicurarsi di selezionare la sottoscrizione, il gruppo di risorse e il servizio di posta elettronica corretti). Seleziona il pulsante Connect.

Aggiornare il .env file

1. Ora che il numero di telefono ACS (con chiamate e SMS abilitati) e il dominio di posta elettronica sono pronti, aggiornare le chiavi/valori seguenti nel file con estensione env nel progetto:

   ACS_CONNECTION_STRING=<ACS_CONNECTION_STRING>
   ACS_PHONE_NUMBER=<ACS_PHONE_NUMBER>
   ACS_EMAIL_ADDRESS=<ACS_EMAIL_ADDRESS>
   CUSTOMER_EMAIL_ADDRESS=<EMAIL_ADDRESS_TO_SEND_EMAIL_TO>
   CUSTOMER_PHONE_NUMBER=<UNITED_STATES_BASED_NUMBER_TO_SEND_SMS_TO>
   

   • ACS_CONNECTION_STRINGconnection string: valore della sezione Chiavi della risorsa ACS.

   • ACS_PHONE_NUMBER: assegnare il numero verde al ACS_PHONE_NUMBER valore .

   • ACS_EMAIL_ADDRESS: assegnare il valore dell'indirizzo di posta elettronica "MailTo".

   • CUSTOMER_EMAIL_ADDRESS: assegnare un indirizzo di posta elettronica a cui inviare un messaggio di posta elettronica dall'app (poiché i dati dei clienti nel database dell'app sono solo dati di esempio). È possibile usare un indirizzo di posta elettronica personale.

   • CUSTOMER_PHONE_NUMBER: è necessario specificare un numero di telefono basato su Stati Uniti (a partire da oggi) a causa di una verifica aggiuntiva necessaria in altri paesi per l'invio di messaggi SMS. Se non si dispone di un numero basato sugli Stati Uniti, è possibile lasciarlo vuoto.

Avviare/riavviare le applicazioni e i server API

Eseguire uno dei passaggi seguenti in base agli esercizi completati fino a questo punto:

• Se il database, il server API e il server Web sono stati avviati in un esercizio precedente, è necessario arrestare il server API e il server Web e riavviarli per selezionare le modifiche apportate al file con estensione env . È possibile lasciare in esecuzione il database.

  Individuare le finestre del terminale che eseguono il server API e il server Web e premere CTRL+C per arrestarli. Avviarli di nuovo digitando npm start in ogni finestra del terminale e premendo INVIO. Continuare con l'esercizio successivo.

• Se il database, il server API e il server Web non sono ancora stati avviati, completare i passaggi seguenti:

  1. Nei passaggi seguenti verranno create tre finestre del terminale in Visual Studio Code.

     

  2. Fare clic con il pulsante destro del mouse sul file con estensione env nell'elenco dei file di Visual Studio Code e scegliere Apri nel terminale integrato. Assicurarsi che il terminale si trova nella radice del progetto, openai-acs-msgraph , prima di continuare.

  3. Scegliere una delle opzioni seguenti per avviare il database PostgreSQL:

     • Se Docker Desktop è installato e in esecuzione, eseguire docker-compose up nella finestra del terminale e premere INVIO.

     • Se si dispone di Podman con podman-compose installato e in esecuzione, eseguire podman-compose up nella finestra del terminale e premere INVIO.

     • Per eseguire il contenitore PostgreSQL direttamente usando Docker Desktop, Podman, nerdctl o un altro runtime del contenitore installato, eseguire il comando seguente nella finestra del terminale:

       • Mac, Linux o sottosistema Windows per Linux (WSL):

         [docker | podman | nerdctl] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v $(pwd)/data:/var/lib/postgresql/data -p 5432:5432 postgres
         

       • Windows con PowerShell:

         [docker | podman] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v ${PWD}/data:/var/lib/postgresql/data -p 5432:5432 postgres
         

  4. Dopo l'avvio del contenitore di database, premere l'icona + nella barra degli strumenti del terminale di Visual Studio Code per creare una seconda finestra del terminale.

     

  5. cdnella cartella server/typescript ed eseguire i comandi seguenti per installare le dipendenze e avviare il server API.

     • npm install
     • npm start

  6. Premere di nuovo l'icona + nella barra degli strumenti del terminale di Visual Studio Code per creare una terza finestra del terminale.

  7. cdnella cartella client ed eseguire i comandi seguenti per installare le dipendenze e avviare il server Web.

     • npm install
     • npm start

  8. Verrà avviato un browser e si passerà a http://localhost:4200.

     

Comunicazione: effettuare una telefonata

• 79 minuti rimanenti

L'integrazione delle funzionalità di chiamata telefonica di Servizi di comunicazione di Azure in un'applicazione line-of-business (LOB) personalizzata offre diversi vantaggi principali per le aziende e i relativi utenti:

• Consente una comunicazione facile e in tempo reale tra dipendenti, clienti e partner, direttamente dall'interno dell'applicazione LINEB, eliminando la necessità di passare da più piattaforme o dispositivi.
• Migliora l'esperienza utente e migliora l'efficienza operativa complessiva.
• Facilita la risoluzione rapida dei problemi, in quanto gli utenti possono connettersi rapidamente con team di supporto pertinenti o esperti in materia in modo rapido e semplice.

In questo esercizio si eseguiranno le seguenti operazioni:

• Esplorare la funzionalità di chiamata telefonica nell'applicazione.
• Esaminare il codice per informazioni su come viene compilata la funzionalità di chiamata telefonica.

Uso della funzionalità chiamate telefonico

1. Nell'esercizio precedente è stata creata una risorsa Servizi di comunicazione di Azure (ACS) ed è stato avviato il database, il server Web e il server API. Sono stati aggiornati anche i valori seguenti nel file con estensione env .

   ACS_CONNECTION_STRING=<ACS_CONNECTION_STRING>
   ACS_PHONE_NUMBER=<ACS_PHONE_NUMBER>
   ACS_EMAIL_ADDRESS=<ACS_EMAIL_ADDRESS>
   CUSTOMER_EMAIL_ADDRESS=<EMAIL_ADDRESS_TO_SEND_EMAIL_TO>
   CUSTOMER_PHONE_NUMBER=<UNITED_STATES_BASED_NUMBER_TO_SEND_SMS_TO>
   

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

2. Tornare al browser (http://localhost:4200), individuare la griglia di dati e selezionare Contatta cliente seguito da Chiama cliente nella prima riga.

   

3. Nell'intestazione verrà aggiunto un componente di chiamata telefonica. Immettere il numero di telefono che si vuole chiamare (assicurarsi che inizi con + e includa il codice paese) e selezionare Chiama. Verrà richiesto di consentire l'accesso al microfono.

   

4. Selezionare Hang Up (Blocca ) per terminare la chiamata. Selezionare Chiudi per chiudere il componente di chiamata telefonica.

Esplorazione del codice chiamante telefonico

1. Aprire il file customers-list.component.ts . Il percorso completo del file è client/src/app/customers-list/customers-list.component.ts.

2. Si noti che openCallDialog() invia un CustomerCall messaggio e il numero di telefono del cliente usando un bus di eventi.

   openCallDialog(data: Phone) {
       this.eventBus.emit({ name: Events.CustomerCall, value: data });
   }
   

   Nota

   Il codice del bus di eventi è disponibile nel file eventbus.service.ts se si è interessati a esplorarlo di più. Il percorso completo del file è client/src/app/core/eventbus.service.ts.

3. La funzione del componente di ngOnInit() intestazione sottoscrive l'evento CustomerCall inviato dal bus di eventi e visualizza il componente di chiamata telefonica. Questo codice è disponibile in header.component.ts.

   ngOnInit() {
       this.subscription.add(
           this.eventBus.on(Events.CustomerCall, (data: Phone) => {
               this.callVisible = true; // Show phone call component
               this.callData = data; // Set phone number to call
           })
       );
   }
   

4. Aprire phone-call.component.ts. Dedicare qualche minuto a esporre il codice. Il percorso completo del file è client/src/app/phone-call/phone-call.component.ts. Si notino le funzionalità principali seguenti:

   • Recupera un token di accesso Servizi di comunicazione di Azure chiamando la acsService.getAcsToken() funzione in ngOnInit();
   • Aggiunge un "dialer telefono" alla pagina. È possibile visualizzare il dialer facendo clic sull'input del numero di telefono nell'intestazione.
   • Avvia e termina una chiamata usando rispettivamente le startCall() funzioni e endCall() .

5. Prima di esaminare il codice che effettua la chiamata telefonica, esaminiamo come viene recuperato il token di accesso ACS e come vengono creati gli oggetti chiamate telefoniche. Individuare la ngOnInit() funzione in phone-call.component.ts.

   async ngOnInit() {
       if (ACS_CONNECTION_STRING) {
           this.subscription.add(
               this.acsService.getAcsToken().subscribe(async (user: AcsUser) => {
                   const callClient = new CallClient();
                   const tokenCredential = new AzureCommunicationTokenCredential(user.token);
                   this.callAgent = await callClient.createCallAgent(tokenCredential);
               })
           );
       }
   }
   

   Questa funzione esegue le azioni seguenti:

   • Recupera un id utente ACS e un token di accesso chiamando la acsService.getAcsToken() funzione .
   • Dopo aver recuperato il token di accesso, il codice esegue le azioni seguenti:
     • Crea una nuova istanza di e AzureCommunicationTokenCredential usando il token di CallClient accesso.
     • Crea una nuova istanza di CallAgent utilizzando gli CallClient oggetti e AzureCommunicationTokenCredential . Più avanti si noterà che CallAgent viene usato per avviare e terminare una chiamata.

6. Aprire acs.services.ts e individuare la getAcsToken() funzione. Il percorso completo del file è client/src/app/core/acs.service.ts. La funzione effettua una richiesta HTTP GET alla /acstoken route esposta dal server API.

   getAcsToken(): Observable<AcsUser> {
       return this.http.get<AcsUser>(this.apiUrl + 'acstoken')
       .pipe(
           catchError(this.handleError)
       );
   }
   

7. Una funzione del server API denominata createACSToken() recupera l'id utente e il token di accesso e lo restituisce al client. È disponibile nel file server/typescript/acs.ts .

   import { CommunicationIdentityClient } from '@azure/communication-identity';
   
   const connectionString = process.env.ACS_CONNECTION_STRING as string;
   
   async function createACSToken() {
   if (!connectionString) return { userId: '', token: '' };
   
   const tokenClient = new CommunicationIdentityClient(connectionString);
   const { user, token } = await tokenClient.createUserAndToken(["voip"]);
   return { userId: user.communicationUserId, token };
   }
   

   Questa funzione esegue le azioni seguenti:

   • Controlla se è disponibile un valore ACS connectionString . In caso contrario, restituisce un oggetto con un oggetto vuoto userId e token.
   • Crea una nuova istanza di CommunicationIdentityClient e passa il connectionString valore a esso.
   • Crea un nuovo utente e un nuovo token usando tokenClient.createUserAndToken() con l'ambito "voip".
   • Restituisce un oggetto contenente i userId valori e token .

8. Dopo aver visto come vengono recuperati l'id utente e il token, tornare a phone-call.component.ts e individuare la startCall() funzione.

9. Questa funzione viene chiamata quando viene selezionata l'opzione Call nel componente di chiamata telefonica. Usa l'oggetto CallAgent menzionato in precedenza per avviare una chiamata. La callAgent.startCall() funzione accetta un oggetto che rappresenta il numero da chiamare e il numero di telefono ACS utilizzato per effettuare la chiamata.

   startCall() {
       this.call = this.callAgent?.startCall(
           [{ phoneNumber: this.customerPhoneNumber }], {
           alternateCallerId: { phoneNumber: this.fromNumber }
       });
       console.log('Calling: ', this.customerPhoneNumber);
       console.log('Call id: ', this.call?.id);
       this.inCall = true;
   
       // Adding event handlers to monitor call state
       this.call?.on('stateChanged', () => {
           console.log('Call state changed: ', this.call?.state);
           if (this.call?.state === 'Disconnected') {
               console.log('Call ended. Reason: ', this.call.callEndReason);
               this.inCall = false;
           }
       });
   }
   

10. La endCall() funzione viene chiamata quando si seleziona Hang Up nel componente di chiamata telefonica.

    endCall() {
        if (this.call) {
            this.call.hangUp({ forEveryone: true });
            this.call = undefined;
            this.inCall = false;
        }
        else {
            this.hangup.emit();
        }
    }
    

    Se è in corso una chiamata, la call.hangUp() funzione viene chiamata per terminare la chiamata. Se non è in corso alcuna chiamata, l'evento hangup viene generato al componente padre dell'intestazione per nascondere il componente di chiamata telefonica.

11. Prima di passare all'esercizio successivo, esaminare i concetti chiave trattati in questo esercizio:

    • Un id utente ACS e un token di accesso vengono recuperati dal server API usando la acsService.createUserAndToken() funzione .
    • Il token viene usato per creare un CallClient oggetto e CallAgent .
    • L'oggetto CallAgent viene utilizzato per avviare e terminare una chiamata chiamando rispettivamente le callAgent.startCall() funzioni e callAgent.hangUp() .

12. Ora che si è appreso come è possibile integrare le telefonate in un'applicazione, è possibile passare all'uso di Servizi di comunicazione di Azure per inviare messaggi di posta elettronica e SMS.

Comunicazione: invio di messaggi di posta elettronica e SMS

• 69 minuti rimanenti

Oltre alle telefonate, Servizi di comunicazione di Azure può anche inviare messaggi di posta elettronica e SMS. Ciò può essere utile quando si vuole inviare un messaggio a un cliente o a un altro utente direttamente dall'applicazione.

In questo esercizio si eseguiranno le seguenti operazioni:

• Informazioni su come inviare messaggi di posta elettronica e SMS dall'applicazione.
• Esaminare il codice per informazioni su come viene implementata la funzionalità di posta elettronica e SMS.

Uso delle funzionalità di posta elettronica e SMS

1. In un esercizio precedente è stata creata una risorsa Servizi di comunicazione di Azure (ACS) ed è stato avviato il database, il server Web e il server API. Sono stati aggiornati anche i valori seguenti nel file con estensione env .

   ACS_CONNECTION_STRING=<ACS_CONNECTION_STRING>
   ACS_PHONE_NUMBER=<ACS_PHONE_NUMBER>
   ACS_EMAIL_ADDRESS=<ACS_EMAIL_ADDRESS>
   CUSTOMER_EMAIL_ADDRESS=<EMAIL_ADDRESS_TO_SEND_EMAIL_TO>
   CUSTOMER_PHONE_NUMBER=<UNITED_STATES_BASED_NUMBER_TO_SEND_SMS_TO>
   

   Assicurarsi di aver completato l'esercizio prima di continuare.

2. Tornare al browser (http://localhost:4200) e selezionare Contatta cliente seguito da Posta elettronica/SMS Cliente nella prima riga.

   

3. Selezionare la scheda Email/SMS (Posta elettronica/SMS ) ed eseguire le attività seguenti:

   • Immettere un oggetto e un corpo del messaggio di posta elettronica e selezionare il pulsante Invia messaggio di posta elettronica.
   • Immettere un messaggio SMS e selezionare il pulsante Invia SMS .

   

   Nota

   La verifica tramite SMS per i numeri verdi è ora obbligatoria nei Stati Uniti e canada. Per abilitare la messaggistica SMS, è necessario inviare la verifica dopo l'acquisto del numero di telefono. Anche se questa esercitazione non eseguirà questo processo, è possibile selezionare Telefonia e SMS -->Documenti normativi dalla risorsa Servizi di comunicazione di Azure nella portale di Azure e aggiungere la documentazione di convalida necessaria.

4. Verificare di aver ricevuto i messaggi di posta elettronica e SMS. La funzionalità SMS funzionerà solo se sono stati inviati i documenti normativi indicati nella nota precedente. Come promemoria, il messaggio di posta elettronica verrà inviato al valore definito per CUSTOMER_EMAIL_ADDRESS e il messaggio SMS verrà inviato al valore definito per CUSTOMER_PHONE_NUMBER nel file con estensione env . Se non è stato possibile specificare un numero di telefono basato su Stati Uniti da usare per i messaggi SMS, è possibile ignorare questo passaggio.

   Nota

   Se non viene visualizzato il messaggio di posta elettronica nella cartella posta in arrivo per l'indirizzo definito per CUSTOMER_EMAIL_ADDRESS nel file con estensione env , controllare la cartella della posta indesiderata.

Esplorazione del codice di posta elettronica

1. Aprire il file customers-list.component.ts . Il percorso completo del file è client/src/app/customers-list/customers-list.component.ts.

2. Quando è stata selezionata l'opzione Contatta cliente seguito da Posta elettronica/SMS Cliente nella griglia dati, il customer-list componente visualizza una finestra di dialogo. Questa operazione viene gestita dalla openEmailSmsDialog() funzione nel file customer-list.component.ts .

   openEmailSmsDialog(data: any) {
       if (data.phone && data.email) {
           // Create the data for the dialog
           let dialogData: EmailSmsDialogData = {
               prompt: '',
               title: `Contact ${data.company}`,
               company: data.company,
               customerName: data.first_name + ' ' + data.last_name,
               customerEmailAddress: data.email,
               customerPhoneNumber: data.phone
           }
   
           // Open the dialog
           const dialogRef = this.dialog.open(EmailSmsDialogComponent, {
               data: dialogData
           });
   
           // Subscribe to the dialog afterClosed observable to get the dialog result
           this.subscription.add(
               dialogRef.afterClosed().subscribe((response: EmailSmsDialogData) => {
                   console.log('SMS dialog result:', response);
                   if (response) {
                       dialogData = response;
                   }
               })
           );
       }
       else {
           alert('No phone number available.');
       }
   }
   

   La openEmailSmsDialog() funzione esegue le attività seguenti:

   • Verifica se l'oggetto data (che rappresenta la riga dalla griglia di dati) contiene una phone proprietà e email . In caso affermativo, crea un dialogData oggetto contenente le informazioni da passare alla finestra di dialogo.
   • Apre la EmailSmsDialogComponent finestra di dialogo e passa l'oggetto dialogData .
   • Sottoscrive l'evento afterClosed() della finestra di dialogo. Questo evento viene generato quando la finestra di dialogo viene chiusa. L'oggetto response contiene le informazioni immesse nella finestra di dialogo.

3. Aprire il file email-sms-dialog.component.ts . Il percorso completo del file è client/src/app/email-sms-dialog/email-sms-dialog.component.ts.

4. Individuare la sendEmail() funzione :

   sendEmail() {
       if (this.featureFlags.acsEmailEnabled) {
           // Using CUSTOMER_EMAIL_ADDRESS instead of this.data.email for testing purposes
           this.subscription.add(
               this.acsService.sendEmail(this.emailSubject, this.emailBody, 
                   this.getFirstName(this.data.customerName), CUSTOMER_EMAIL_ADDRESS /* this.data.email */)
               .subscribe(res => {
                   console.log('Email sent:', res);
                   if (res.status) {
                       this.emailSent = true;
                   }
               })
           );
       }
       else {
           this.emailSent = true; // Used when ACS email isn't enabled
       }
   }
   

   La sendEmail() funzione esegue le attività seguenti:

   • Verifica se il acsEmailEnabled flag di funzionalità è impostato su true. Questo flag verifica se la ACS_EMAIL_ADDRESS variabile di ambiente ha un valore assegnato.
   • Se acsEmailEnabled è true, la acsService.sendEmail() funzione viene chiamata e vengono passati l'oggetto, il corpo, il nome del cliente e l'indirizzo di posta elettronica del cliente. Poiché il database contiene dati di esempio, viene usata la CUSTOMER_EMAIL_ADDRESS variabile di this.data.emailambiente anziché . In un'applicazione reale il this.data.email valore verrà usato.
   • Sottoscrive la sendEmail() funzione nel acsService servizio. Questa funzione restituisce un RxJS osservabile che contiene la risposta dal servizio lato client.
   • Se il messaggio di posta elettronica è stato inviato correttamente, la emailSent proprietà viene impostata su true.

5. Per offrire un migliore incapsulamento e riutilizzo del codice, vengono usati servizi lato client come acs.service.ts in tutta l'applicazione. In questo modo tutte le funzionalità ACS possono essere consolidate in un'unica posizione.

6. Aprire acs.service.ts e individuare la sendEmail() funzione. Il percorso completo del file è client/src/app/core/acs.service.ts.

   sendEmail(subject: string, message: string, customerName: string, customerEmailAddress: string) : Observable<EmailSmsResponse> {
       return this.http.post<EmailSmsResponse>(this.apiUrl + 'sendEmail', { subject, message, customerName, customerEmailAddress })
       .pipe(
           catchError(this.handleError)
       );
   }
   

   La sendEmail() funzione in AcsService esegue le attività seguenti:

   • Chiama la http.post() funzione e passa l'oggetto, il messaggio, il nome del cliente e l'indirizzo di posta elettronica del cliente. La http.post() funzione restituisce un RxJS osservabile che contiene la risposta dalla chiamata API.
   • Gestisce eventuali errori restituiti dalla http.post() funzione usando l'operatore RxJS catchError .

7. Si esaminerà ora come l'applicazione interagisce con la funzionalità di posta elettronica ACS. Aprire il file acs.ts e individuare la sendEmail() funzione. Il percorso completo del file è server/typescript/acs.ts.

8. La sendEmail() funzione esegue le attività seguenti:

   • Crea un nuovo EmailClient oggetto e passa il stringa di connessione ACS a esso (questo valore viene recuperato dalla ACS_CONNECTION_STRING variabile di ambiente).

     const emailClient = new EmailClient(connectionString);
     

   • Crea un nuovo EmailMessage oggetto e passa le informazioni del mittente, dell'oggetto, del messaggio e del destinatario.

     const msgObject: EmailMessage = {
         senderAddress: process.env.ACS_EMAIL_ADDRESS as string,
         content: {
             subject: subject,
             plainText: message,
         },
         recipients: {
             to: [
                 {
                     address: customerEmailAddress,
                     displayName: customerName,
                 },
             ],
         },
     };
     

   • Invia il messaggio di posta elettronica usando la emailClient.beginSend() funzione e restituisce la risposta. Anche se la funzione invia solo a un destinatario in questo esempio, la beginSend() funzione può essere usata anche per inviare a più destinatari.

     const poller = await emailClient.beginSend(msgObject);
     

   • Attende che l'oggetto poller segnali che è stato eseguito e invia la risposta al chiamante.

Esplorazione del codice SMS

1. Tornare al file email-sms-dialog.component.ts aperto in precedenza. Il percorso completo del file è client/src/app/email-sms-dialog/email-sms-dialog.component.ts.

2. Individuare la sendSms() funzione :

   sendSms() {
       if (this.featureFlags.acsPhoneEnabled) {
           // Using CUSTOMER_PHONE_NUMBER instead of this.data.customerPhoneNumber for testing purposes
           this.subscription.add(
               this.acsService.sendSms(this.smsMessage, CUSTOMER_PHONE_NUMBER /* this.data.customerPhoneNumber */)
                 .subscribe(res => {
                   if (res.status) {
                       this.smsSent = true;
                   }
               })
           );
       }
       else {
           this.smsSent = true;
       }
   }
   

   La sendSMS() funzione esegue le attività seguenti:

   • Verifica se il acsPhoneEnabled flag di funzionalità è impostato su true. Questo flag verifica se la ACS_PHONE_NUMBER variabile di ambiente ha un valore assegnato.
   • Se acsPhoneEnabled è true, viene chiamata la acsService.SendSms() funzione e vengono passati il messaggio SMS e il numero di telefono del cliente. Poiché il database contiene dati di esempio, viene usata la CUSTOMER_PHONE_NUMBER variabile di this.data.customerPhoneNumberambiente anziché . In un'applicazione reale il this.data.customerPhoneNumber valore verrà usato.
   • Sottoscrive la sendSms() funzione nel acsService servizio. Questa funzione restituisce un RxJS osservabile che contiene la risposta dal servizio lato client.
   • Se il messaggio SMS è stato inviato correttamente, imposta la smsSent proprietà su true.

3. Aprire acs.service.ts e individuare la sendSms() funzione. Il percorso completo del file è client/src/app/core/acs.service.ts.

   sendSms(message: string, customerPhoneNumber: string) : Observable<EmailSmsResponse> {
       return this.http.post<EmailSmsResponse>(this.apiUrl + 'sendSms', { message, customerPhoneNumber })
       .pipe(
           catchError(this.handleError)
       );
   }  
   

   La sendSms() funzione esegue le attività seguenti:

   • Chiama la http.post() funzione e passa il messaggio e il numero di telefono del cliente. La http.post() funzione restituisce un RxJS osservabile che contiene la risposta dalla chiamata API.
   • Gestisce eventuali errori restituiti dalla http.post() funzione usando l'operatore RxJS catchError .

4. Infine, esaminiamo come l'applicazione interagisce con la funzionalità SMS ACS. Aprire il file acs.ts . Il percorso completo del file è server/typescript/acs.ts e individuare la sendSms() funzione.

5. La sendSms() funzione esegue le attività seguenti:

   • Crea un nuovo SmsClient oggetto e passa il stringa di connessione ACS a esso (questo valore viene recuperato dalla ACS_CONNECTION_STRING variabile di ambiente).

     const smsClient = new SmsClient(connectionString);
     

   • Chiama la smsClient.send() funzione e passa il numero di telefono ACS (from), il numero di telefono del cliente (to) e il messaggio SMS:

     const sendResults = await smsClient.send({
         from: process.env.ACS_PHONE_NUMBER as string,
         to: [customerPhoneNumber],
         message: message
     });
     return sendResults;
     

   • Restituisce la risposta al chiamante.

6. Per altre informazioni sulla funzionalità di posta elettronica e SMS ACS, vedere gli articoli seguenti:

   • Posta elettronica in Servizi di comunicazione di Azure
   • SMS in Servizi di comunicazione di Azure

7. Prima di passare all'esercizio successivo, esaminare i concetti chiave trattati in questo esercizio:

   • Il file acs.service.ts incapsula la funzionalità sms e posta elettronica ACS usata dall'applicazione lato client. Gestisce le chiamate API al server e restituisce la risposta al chiamante.
   • L'API lato server usa il servizio di EmailClient controllo di accesso e SmsClient gli oggetti per inviare messaggi di posta elettronica e SMS.

8. Ora che si è appreso come inviare messaggi di posta elettronica e SMS, è possibile passare all'integrazione dei dati dell'organizzazione nell'applicazione.

Dati dell'organizzazione: creazione di una registrazione dell'app Microsoft Entra ID

• 59 minuti rimanenti

Migliorare la produttività degli utenti integrando i dati dell'organizzazione (messaggi di posta elettronica, file, chat ed eventi del calendario) direttamente nelle applicazioni personalizzate. Usando le API Microsoft Graph e l'ID Microsoft Entra, è possibile recuperare e visualizzare facilmente i dati pertinenti all'interno delle app, riducendo la necessità per gli utenti di cambiare contesto. Che faccia riferimento a un messaggio di posta elettronica inviato a un cliente, riveda un messaggio di Teams o acceda a un file, gli utenti possono trovare rapidamente le informazioni necessarie senza uscire dall'app, semplificando il processo decisionale.

In questo esercizio si eseguiranno le seguenti operazioni:

• Creare una registrazione dell'app Microsoft Entra ID in modo che Microsoft Graph possa accedere ai dati dell'organizzazione e inserirla nell'app.
• Individuare team gli ID e channel da Microsoft Teams necessari per inviare messaggi di chat a un canale specifico.
• Aggiornare il file con estensione env del progetto con i valori della registrazione dell'app Microsoft Entra ID.

Creare una registrazione dell'app Microsoft Entra ID

1. Passare a portale di Azure e selezionare Microsoft Entra ID.Go to portale di Azure and select Microsoft Entra ID.

2. Selezionare Gestisci -->Registrazioni app seguito da + Nuova registrazione.

3. Compilare i dettagli del modulo di registrazione dell'app come illustrato di seguito e selezionare Registra:

   • Nome: microsoft-graph-app
   • Tipi di account supportati: account in qualsiasi directory organizzativa (qualsiasi tenant di Microsoft Entra ID - Multi-tenant)
   • URI di reindirizzamento:
     • Selezionare Applicazione a pagina singola (SPA) e immettere http://localhost:4200 nel campo URI di reindirizzamento.
   • Selezionare Registra per creare la registrazione dell'app.

   

1. Selezionare Panoramica nel menu delle risorse e copiare il Application (client) ID valore negli Appunti.

   

Aggiornare il file con estensione env del progetto

1. Aprire il file con estensione env nell'editor e assegnare il Application (client) ID valore a ENTRAID_CLIENT_ID.

   ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
   

2. Se si vuole abilitare la possibilità di inviare un messaggio dall'app a un canale di Teams, accedere a Microsoft Teams usando l'account del tenant di sviluppo di Microsoft 365 (questo è indicato nelle domande preliminari per l'esercitazione).

3. Dopo aver eseguito l'accesso, espandere un team e trovare un canale a cui inviare messaggi dall'app. Ad esempio, è possibile selezionare il team aziendale e il canale Generale (o qualsiasi team/canale che si vuole usare).

   

4. Nell'intestazione del team fare clic sui tre puntini (...) e selezionare Ottieni collegamento al team.

5. Nel collegamento visualizzato nella finestra popup, l'ID del team è la stringa di lettere e numeri dopo team/. Ad esempio, nel collegamento "https://teams.microsoft.com/l/team/19%3ae9b9.../", l'ID del team è 19%3ae9b9... fino al carattere seguente / .

6. Copiare l'ID team e assegnarlo a TEAM_ID nel file con estensione env .

7. Nell'intestazione del canale fare clic sui tre puntini (...) e selezionare Recupera collegamento al canale.

8. Nel collegamento visualizzato nella finestra popup, l'ID canale è la stringa di lettere e numeri dopo channel/. Ad esempio, nel collegamento "https://teams.microsoft.com/l/channel/19%3aQK02.../", l'ID canale è 19%3aQK02... fino al carattere seguente / .

9. Copiare l'ID canale e assegnarlo a CHANNEL_ID nel file con estensione env .

10. Salvare il file env prima di continuare.

Avviare/riavviare le applicazioni e i server API

Eseguire uno dei passaggi seguenti in base agli esercizi completati fino a questo punto:

• Se il database, il server API e il server Web sono stati avviati in un esercizio precedente, è necessario arrestare il server API e il server Web e riavviarli per selezionare le modifiche apportate al file con estensione env . È possibile lasciare in esecuzione il database.

  Individuare le finestre del terminale che eseguono il server API e il server Web e premere CTRL+C per arrestarli. Avviarli di nuovo digitando npm start in ogni finestra del terminale e premendo INVIO. Continuare con l'esercizio successivo.

• Se il database, il server API e il server Web non sono ancora stati avviati, completare i passaggi seguenti:

  1. Nei passaggi seguenti verranno create tre finestre del terminale in Visual Studio Code.

     

  2. Fare clic con il pulsante destro del mouse sul file con estensione env nell'elenco dei file di Visual Studio Code e scegliere Apri nel terminale integrato. Assicurarsi che il terminale si trova nella radice del progetto, openai-acs-msgraph , prima di continuare.

  3. Scegliere una delle opzioni seguenti per avviare il database PostgreSQL:

     • Se Docker Desktop è installato e in esecuzione, eseguire docker-compose up nella finestra del terminale e premere INVIO.

     • Se si dispone di Podman con podman-compose installato e in esecuzione, eseguire podman-compose up nella finestra del terminale e premere INVIO.

     • Per eseguire il contenitore PostgreSQL direttamente usando Docker Desktop, Podman, nerdctl o un altro runtime del contenitore installato, eseguire il comando seguente nella finestra del terminale:

       • Mac, Linux o sottosistema Windows per Linux (WSL):

         [docker | podman | nerdctl] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v $(pwd)/data:/var/lib/postgresql/data -p 5432:5432 postgres
         

       • Windows con PowerShell:

         [docker | podman] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v ${PWD}/data:/var/lib/postgresql/data -p 5432:5432 postgres
         

  4. Dopo l'avvio del contenitore di database, premere l'icona + nella barra degli strumenti del terminale di Visual Studio Code per creare una seconda finestra del terminale.

     

  5. cdnella cartella server/typescript ed eseguire i comandi seguenti per installare le dipendenze e avviare il server API.

     • npm install
     • npm start

  6. Premere di nuovo l'icona + nella barra degli strumenti del terminale di Visual Studio Code per creare una terza finestra del terminale.

  7. cdnella cartella client ed eseguire i comandi seguenti per installare le dipendenze e avviare il server Web.

     • npm install
     • npm start

  8. Verrà avviato un browser e si passerà a http://localhost:4200.

     

Dati dell'organizzazione: accesso a un utente e recupero di un token di accesso

• 51 minuti rimanenti

Gli utenti devono eseguire l'autenticazione con Microsoft Entra ID per consentire a Microsoft Graph di accedere ai dati aziendali. In questo esercizio si vedrà come usare il componente di mgt-login Microsoft Graph Toolkit per autenticare gli utenti e recuperare un token di accesso. Il token di accesso può quindi essere usato per effettuare chiamate a Microsoft Graph.

In questo esercizio si eseguiranno le seguenti operazioni:

• Informazioni su come associare un'app Microsoft Entra ID a Microsoft Graph Toolkit per autenticare gli utenti e recuperare i dati dell'organizzazione.
• Informazioni sull'importanza degli ambiti.
• Informazioni su come usare il componente mgt-login di Microsoft Graph Toolkit per autenticare gli utenti e recuperare un token di accesso.

Uso della funzionalità di accesso

1. Nell'esercizio precedente è stata creata una registrazione dell'app in Microsoft Entra ID e si è avviato il server applicazioni e il server API. Sono stati aggiornati anche i valori seguenti nel .env file (TEAM_ID e CHANNEL_ID sono facoltativi):

   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), selezionare Accedi nell'intestazione e accedere usando un account utente amministratore dal tenant di Microsoft 365 Developer.

   Suggerimento

   Accedere con l'account amministratore del tenant per sviluppatori di Microsoft 365. È possibile visualizzare altri utenti nel tenant dello sviluppatore passando al interfaccia di amministrazione di Microsoft 365.

3. Se si accede all'applicazione per la prima volta, verrà richiesto di fornire il consenso alle autorizzazioni richieste dall'applicazione. Verranno fornite altre informazioni su queste autorizzazioni (denominate anche "ambiti") nella sezione successiva durante l'esplorazione del codice. Selezionare Accetta per continuare.

4. Dopo aver eseguito l'accesso, verrà visualizzato il nome dell'utente visualizzato nell'intestazione.

   

Esplorazione del codice di accesso

Dopo aver eseguito l'accesso, esaminare il codice usato per accedere all'utente e recuperare un token di accesso e un profilo utente. Verranno fornite informazioni sul componente Web mgt-login che fa parte di Microsoft Graph Toolkit.

1. Aprire client/package.json e notare che i @microsoft/mgt pacchetti e @microsoft/mgt-components sono inclusi nelle dipendenze. Il @microsoft/mgt pacchetto contiene funzionalità del provider MSAL (Microsoft Authentication Library) e componenti Web, ad esempio mgt-login e altri che possono essere usati per accedere agli utenti e recuperare e visualizzare i dati dell'organizzazione.

2. Aprire client/src/main.ts e notare le importazioni seguenti dal @microsoft/mgt-components pacchetto. I simboli importati vengono usati per registrare i componenti di Microsoft Graph Toolkit usati nell'applicazione.

   import { registerMgtLoginComponent, registerMgtSearchResultsComponent, registerMgtPersonComponent,  } from '@microsoft/mgt-components';
   

3. Scorrere fino alla fine del file e prendere nota del codice seguente:

   registerMgtLoginComponent();
   registerMgtSearchResultsComponent();
   registerMgtPersonComponent();
   

   Questo codice registra i mgt-logincomponenti Web , mgt-search-resultse mgt-person e li abilita per l'uso nell'applicazione.

4. Per usare il componente mgt-login per accedere agli utenti, è necessario fare riferimento e usare l'ID client dell'app Microsoft Entra ID (archiviato nel file con estensione env come ENTRAID_CLIENT_ID).

5. Aprire graph.service.ts e individuare la init() funzione. Il percorso completo del file è client/src/app/core/graph.service.ts. Verranno visualizzati l'importazione e il codice seguenti:

   import { Msal2Provider, Providers, ProviderState } from '@microsoft/mgt';
   
   init() {
       if (!this.featureFlags.microsoft365Enabled) return;
   
       if (!Providers.globalProvider) {
           console.log('Initializing Microsoft Graph global provider...');
           Providers.globalProvider = new Msal2Provider({
               clientId: ENTRAID_CLIENT_ID,
               scopes: ['User.Read', 'Presence.Read', 'Chat.ReadWrite', 'Calendars.Read', 
                       'ChannelMessage.Read.All', 'ChannelMessage.Send', 'Files.Read.All', 'Mail.Read']
           });
       }
       else {
           console.log('Global provider already initialized');
       }
   }
   

   Questo codice crea un nuovo Msal2Provider oggetto, passando l'ID client Microsoft Entra ID dalla registrazione dell'app e l'oggetto scopes per cui l'app richiederà l'accesso. Vengono scopes usati per richiedere l'accesso alle risorse di Microsoft Graph a cui l'app accederà. Dopo aver creato l'oggetto Msal2Provider , viene assegnato all'oggetto Providers.globalProvider , che viene usato dai componenti di Microsoft Graph Toolkit per recuperare i dati da Microsoft Graph.

6. Aprire header.component.html nell'editor e individuare il componente mgt-login . Il percorso completo del file è client/src/app/header/header.component.html.

   @if (this.featureFlags.microsoft365Enabled) {
       <mgt-login class="mgt-dark" (loginCompleted)="loginCompleted()"></mgt-login>
   }
   

   Il componente mgt-login abilita l'accesso dell'utente e fornisce l'accesso a un token usato con Microsoft Graph. Al termine dell'accesso, viene attivato l'evento loginCompleted , che chiama la loginCompleted() funzione . Anche se mgt-login viene usato all'interno di un componente Angular in questo esempio, è compatibile con qualsiasi applicazione Web.

   La visualizzazione del componente mgt-login dipende dal valore impostato su featureFlags.microsoft365Enabled true. Questo flag personalizzato verifica la presenza della variabile di ENTRAID_CLIENT_ID ambiente per verificare che l'applicazione sia configurata correttamente e in grado di eseguire l'autenticazione con Microsoft Entra ID. Il flag viene aggiunto per soddisfare i casi in cui gli utenti scelgono di completare solo gli esercizi di intelligenza artificiale o comunicazione all'interno dell'esercitazione, anziché seguire l'intera sequenza di esercizi.

7. Aprire header.component.ts e individuare la loginCompleted funzione. Questa funzione viene chiamata quando l'evento loginCompleted viene generato e gestisce il recupero del profilo dell'utente connesso tramite Providers.globalProvider.

   async loginCompleted() {
       const me = await Providers.globalProvider.graph.client.api('me').get();
       this.userLoggedIn.emit(me);
   }
   

   In questo esempio viene effettuata una chiamata all'API Microsoft Graph me per recuperare il profilo dell'utente (me rappresenta l'utente connesso corrente). L'istruzione this.userLoggedIn.emit(me) di codice genera un evento dal componente per passare i dati del profilo al componente padre. Il componente padre è app.component.ts file in questo caso, ovvero il componente radice per l'applicazione.

   Per altre informazioni sul componente mgt-login , visitare la documentazione di Microsoft Graph Toolkit .

8. Dopo aver eseguito l'accesso all'applicazione, si esaminerà il modo in cui è possibile recuperare i dati dell'organizzazione.

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

• 41 minuti rimanenti

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.

   Nota

   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 Registra.

       È 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.

     • Selezionare 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

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.

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

• 21 minuti rimanenti

Nell'esercizio precedente si è appreso come recuperare i file da OneDrive for Business e le chat da Microsoft Teams usando Microsoft Graph e il componente mgt-search-results di Microsoft Graph Toolkit. Si è anche appreso come inviare messaggi ai canali di Microsoft Teams. In questo esercizio si apprenderà come recuperare i messaggi di posta elettronica e gli eventi del calendario da Microsoft Graph e integrarli nell'applicazione.

In questo esercizio si eseguiranno le seguenti operazioni:

• Informazioni su come usare il componente Web mgt-search-results in Microsoft Graph Toolkit per cercare messaggi di posta elettronica ed eventi del calendario.
• Informazioni su come personalizzare il componente mgt-search-results per eseguire il rendering dei risultati della ricerca in modo personalizzato.
• Informazioni su come chiamare Direttamente Microsoft Graph per recuperare messaggi di posta elettronica ed eventi del calendario.

Esplorazione del codice di ricerca dei messaggi di posta elettronica

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. Aprire emails.component.html e esaminare il codice. Il percorso completo del file è client/src/app/emails/emails.component.html.

3. Individuare il componente mgt-search-results :

   <mgt-search-results 
     class="search-results" 
     entity-types="message" 
     [queryString]="searchText"
     (dataChange)="dataChange($any($event))">
     <template data-type="result-message"></template>
   </mgt-search-results>
   

   Questo esempio del componente mgt-search-results è configurato allo stesso modo di quello esaminato in precedenza. L'unica differenza è che l'attributo entity-types è impostato su message cui viene usato per cercare messaggi di posta elettronica e viene fornito un modello vuoto.

   • 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 è message.
   • L'attributo queryString viene usato per specificare il termine di ricerca.
   • L'evento dataChange viene generato quando i risultati della ricerca cambiano. Viene chiamata la funzione del dataChange() componente di posta elettronica, i risultati vengono passati e una proprietà denominata data viene aggiornata nel componente.
   • Per il componente viene definito un modello vuoto. Questo tipo di modello viene in genere usato per definire come verrà eseguito il rendering dei risultati della ricerca. In questo scenario, tuttavia, viene indicato al componente di non eseguire il rendering dei dati dei messaggi. Si eseguirà invece il rendering dei dati usando il data binding standard (Angular viene usato in questo caso, ma è possibile usare qualsiasi libreria/framework desiderato).

4. Esaminare sotto il componente mgt-search-results in emails.component.html per trovare i data binding usati per il rendering dei messaggi di posta elettronica. Questo esempio scorre la data proprietà e scrive l'oggetto del messaggio di posta elettronica, l'anteprima del corpo e un collegamento per visualizzare il messaggio di posta elettronica completo.

   @if (this.data.length) {
       <div>
           @for (email of this.data;track $index) {
               <mat-card>
                   <mat-card-header>
                   <mat-card-title>{{email.resource.subject}}</mat-card-title>
                   <mat-card-subtitle [innerHTML]="email.resource.bodyPreview"></mat-card-subtitle>
                   </mat-card-header>
                   <mat-card-actions>
                   <a mat-stroked-button color="basic" [href]="email.resource.webLink" target="_blank">View Email Message</a>
                   </mat-card-actions>
               </mat-card>
           }
       </div>
   }
   

   

5. Oltre a usare il componente mgt-search-results per recuperare i messaggi, Microsoft Graph offre diverse API che possono essere usate anche per cercare i messaggi di posta elettronica. L'API /search/query illustrata in precedenza potrebbe certamente essere usata, ma un'opzione più semplice è l'API messages .

6. Per informazioni su come chiamare questa API, tornare a graph.service.ts e individuare la searchEmailMessages() funzione. Crea un URL che può essere usato per chiamare l'endpoint messages di Microsoft Graph e assegna il query valore al $search parametro . Il codice effettua quindi una richiesta GET e restituisce i risultati al chiamante. L'operatore $search cerca automaticamente il query valore nei campi oggetto, corpo e mittente.

   async searchEmailMessages(query:string) {
       if (!query) return [];
       // The $search operator will search the subject, body, and sender fields automatically
       const url = `https://graph.microsoft.com/v1.0/me/messages?$search="${query}"&$select=subject,bodyPreview,from,toRecipients,receivedDateTime,webLink`;
       const response = await Providers.globalProvider.graph.client.api(url).get();
       return response.value;
   }
   

7. Il componente di posta elettronica che si trova in emails.component.ts chiama searchEmailMessages() e visualizza i risultati nell'interfaccia utente.

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

Esplorazione del codice di ricerca degli eventi del calendario

1. La ricerca di eventi del calendario può essere eseguita anche usando il componente mgt-search-results . Può gestire il rendering dei risultati, ma è anche possibile definire un modello personalizzato che verrà visualizzato più avanti in questo esercizio.

2. Aprire calendar-events.component.html e esaminare il codice. Il percorso completo del file è client/src/app/calendar-events/calendar-events.component.html. Si noterà che è molto simile ai file e ai componenti di posta elettronica esaminati in precedenza.

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

   Questo esempio del componente mgt-search-results è configurato allo stesso modo di quelli esaminati in precedenza. L'unica differenza è che l'attributo entity-types è impostato su event cui viene usato per cercare gli eventi del calendario e viene fornito un modello vuoto.

   • 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 è event.
   • L'attributo queryString viene usato per specificare il termine di ricerca.
   • L'evento dataChange viene generato quando i risultati della ricerca cambiano. Viene chiamata la funzione del componente dell'evento del calendario, i risultati vengono passati e una proprietà denominata data viene aggiornata nel dataChange() componente.
   • Per il componente viene definito un modello vuoto. In questo scenario viene indicato al componente di non eseguire il rendering di dati. Si eseguirà invece il rendering dei dati usando il data binding standard.

3. Immediatamente sotto il mgt-search-results componente in calendar-events.component.html troverai i data binding usati per eseguire il rendering degli eventi del calendario. Questo esempio scorre la data proprietà e scrive la data, l'ora e l'oggetto dell'evento. Le funzioni personalizzate incluse nel componente, dayFromDateTime() ad esempio e timeRangeFromEvent() , vengono chiamate per formattare correttamente i dati. Le associazioni HTML includono anche un collegamento per visualizzare l'evento del calendario in Outlook e il percorso dell'evento, se specificato.

   @if (this.data.length) {
       <div>
           @for (event of this.data;track $index) {
               <div class="root">
                   <div class="time-container">
                       <div class="date">{{ dayFromDateTime(event.resource.start.dateTime)}}</div>
                       <div class="time">{{ timeRangeFromEvent(event.resource) }}</div>
                   </div>
   
                   <div class="separator">
                       <div class="vertical-line top"></div>
                       <div class="circle">
                           @if (!this.event.resource.bodyPreview?.includes('Join Microsoft Teams Meeting')) {
                               <div class="inner-circle"></div>
                           }
                       </div>
                       <div class="vertical-line bottom"></div>
                   </div>
   
                   <div class="details">
                       <div class="subject">{{ event.resource.subject }}</div>
                       @if (this.event.resource.location?.displayName) {
                           <div class="location">
                               at
                               <a href="https://bing.com/maps/default.aspx?where1={{event.resource.location.displayName}}"
                                   target="_blank" rel="noopener"><b>{{ event.resource.location.displayName }}</b></a>
                           </div>
                       }
                       @if (this.event.resource.attendees?.length) {
                           <div class="attendees">
                               @for (attendee of this.event.resource.attendees;track attendee.emailAddress.name) {
                                   <span class="attendee">
                                       <mgt-person person-query="{{attendee.emailAddress.name}}"></mgt-person>
                                   </span>
                               }
                           </div>
                       }
                       @if (this.event.resource.bodyPreview?.includes('Join Microsoft Teams Meeting')) {
                           <div class="online-meeting">
                               <img class="online-meeting-icon"
                                   src="https://img.icons8.com/color/48/000000/microsoft-teams.png" title="Online Meeting" />
                               <a class="online-meeting-link" href="{{ event.resource.onlineMeetingUrl }}">
                                   Join Teams Meeting
                               </a>
                           </div>
                       }
                   </div>
               </div>
           }
       </div>
   }
   

   

4. Oltre a cercare eventi di calendario usando l'API search/query , Microsoft Graph fornisce anche un'API events che può essere usata anche per cercare eventi del calendario. Individuare la searchCalendarEvents() funzione in graph.service.ts.

5. La searchCalendarEvents() funzione crea valori di data/ora di inizio e di fine usati per definire il periodo di tempo in cui eseguire la ricerca. Viene quindi creato un URL che può essere usato per chiamare l'endpoint events di Microsoft Graph e include il parametro e le query variabili di data/ora di inizio e fine. Viene quindi effettuata una richiesta GET e i risultati vengono restituiti al chiamante.

   async searchCalendarEvents(query:string) {
       if (!query) return [];
       const startDateTime = new Date();
       const endDateTime = new Date(startDateTime.getTime() + (7 * 24 * 60 * 60 * 1000));
       const url = `/me/events?startdatetime=${startDateTime.toISOString()}&enddatetime=${endDateTime.toISOString()}&$filter=contains(subject,'${query}')&orderby=start/dateTime`;
   
       const response = await Providers.globalProvider.graph.client.api(url).get();
       return response.value;
   }
   

   • Ecco una suddivisione dell'URL creato:

     • La /me/events parte dell'URL viene usata per specificare che gli eventi dell'utente connesso devono essere recuperati.
     • I startdatetime parametri e enddatetime vengono usati per definire il periodo di tempo in cui eseguire la ricerca. In questo caso, la ricerca restituirà eventi che iniziano entro i 7 giorni successivi.
     • Il $filter parametro di query viene usato per filtrare i risultati in base al query valore , ovvero il nome della società selezionato dal datagrid in questo caso. La contains() funzione viene utilizzata per cercare il query valore nella subject proprietà dell'evento del calendario.
     • Il $orderby parametro della query viene usato per ordinare i risultati in base alla start/dateTime proprietà .

   url Dopo la creazione di , viene effettuata una richiesta GET all'API Microsoft Graph usando il valore e url i risultati vengono restituiti al chiamante.

6. Come per i componenti precedenti, il componente calendar-events (calendar-events.component.ts file) chiama search() e visualizza i risultati.

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

   Nota

   È possibile effettuare chiamate a Microsoft Graph anche da un'API personalizzata o da un'applicazione lato server. Visualizzare l'esercitazione seguente per visualizzare un esempio di chiamata di un'API Microsoft Graph da una funzione di Azure.

7. È stato ora illustrato l'uso di Microsoft Graph per recuperare file, chat, messaggi di posta elettronica ed eventi del calendario. Gli stessi concetti possono essere applicati anche ad altre API Microsoft Graph. Ad esempio, è possibile usare l'API utenti di Microsoft Graph per cercare gli utenti dell'organizzazione. È anche possibile usare l'API gruppi di Microsoft Graph per cercare i gruppi nell'organizzazione. È possibile visualizzare l'elenco completo delle API Microsoft Graph nella documentazione.

Complimenti.

• Completata al 100%!

Questa esercitazione è stata completata

Complimenti. In questa esercitazione si è appreso come:

• Azure OpenAI può essere usato per migliorare la produttività degli utenti.
• Servizi di comunicazione di Azure può essere usato per integrare le funzionalità di comunicazione.
• Le API e i componenti di Microsoft Graph possono essere usati per recuperare e visualizzare i dati dell'organizzazione.

Usando queste tecnologie, è possibile creare soluzioni efficaci che aumentano la produttività degli utenti riducendo al minimo i cambiamenti di contesto e fornendo informazioni necessarie per il processo decisionale.

Pulire le risorse di Azure

Pulire le risorse di Azure per evitare altri addebiti per l'account. Passare al portale di Azure ed eliminare le risorse seguenti:

• Risorsa di Ricerca intelligenza artificiale di Azure
• risorsa Archiviazione di Azure
• Risorsa OpenAI di Azure (assicurarsi di eliminare prima i modelli e quindi la risorsa OpenAI di Azure)
• Risorsa di Servizi di comunicazione di Azure

Passaggi successivi

Documentazione

• Documentazione di Azure OpenAI
• Azure OpenAI sui dati
• Documentazione di Servizi di comunicazione di Azure
• Documentazione di Microsoft Graph
• Documentazione di Microsoft Graph Toolkit
• Documentazione per sviluppatori di Microsoft Teams

Contenuto di training

• Applicare la progettazione dei prompt con il Servizio OpenAI di Azure
• Introduzione al Servizio OpenAI di Azure
• Introduzione alle Servizi di comunicazione di Azure
• Nozioni fondamentali su Microsoft Graph
• Corso video: Nozioni fondamentali su Microsoft Graph per principianti
• Esplorare gli scenari di Microsoft Graph per lo sviluppo JavaScript
• Esplorare gli scenari di Microsoft Graph per lo sviluppo di ASP.NET Core
• Introduzione a Microsoft Graph Toolkit
• Compilare e distribuire app per Microsoft Teams usando Teams Toolkit per Visual Studio Code