Integrieren von OpenAI-, Kommunikations- und Organisationsdatenfeatures in eine Branchen-App

Niveau: Fortgeschritten

In diesem Lernprogramm wird veranschaulicht, wie Azure OpenAI, Azure Communication Services und Microsoft Graph/Microsoft Graph Toolkit in eine Branchenanwendung integriert werden können, um die Benutzerproduktivität zu verbessern, die Benutzererfahrung zu erhöhen und BRANCHEN-Apps auf die nächste Ebene zu bringen. Zu den wichtigsten Features in der Anwendung gehören:

• KI: Ermöglichen Sie Benutzern, Fragen in natürlicher Sprache zu stellen und ihre Antworten in SQL zu konvertieren, die zum Abfragen einer Datenbank verwendet werden können, benutzern das Definieren von Regeln zu ermöglichen, die zum automatischen Generieren von E-Mails und SMS-Nachrichten verwendet werden können, und erfahren Sie, wie natürliche Sprache zum Abrufen von Daten aus Ihren eigenen benutzerdefinierten Datenquellen verwendet werden kann. Azure OpenAI wird für diese Features verwendet.
• Kommunikation: Aktivieren Von In-App-Telefonanrufen an Kunden und E-Mail-/SMS-Funktionen mithilfe von Azure Communication Services.
• Organisationsdaten: Ziehen Sie verwandte Organisationsdaten, die Benutzer möglicherweise benötigen (Dokumente, Chats, E-Mails, Kalenderereignisse), während sie mit Kunden zusammenarbeiten, um einen Kontextwechsel zu vermeiden. Durch die Bereitstellung des Zugriffs auf diese Art von Organisationsdaten wird die Notwendigkeit reduziert, dass der Benutzer zu Outlook, Teams, OneDrive, anderen benutzerdefinierten Apps, dem Smartphone usw. wechselt, da die benötigten Daten und Funktionen direkt in der App bereitgestellt werden. Microsoft Graph- und Microsoft Graph-Toolkit werden für dieses Feature verwendet.

Die Anwendung ist eine einfache Kundenverwaltungs-App, mit der Benutzer ihre Kunden und zugehörigen Daten verwalten können. Sie besteht aus einem Front-End, das mit TypeScript erstellt wurde, das Back-End-APIs aufruft, um Daten abzurufen, mit KI-Funktionen zu interagieren, E-Mail-/SMS-Nachrichten zu senden und Organisationsdaten abzurufen. Hier ist eine Übersicht über die Anwendungslösung, die Sie in diesem Lernprogramm durchgehen:

Das Lernprogramm führt Sie durch den Prozess der Einrichtung der erforderlichen Azure- und Microsoft 365-Ressourcen. Außerdem werden Sie durch den Code geführt, der zum Implementieren der KI-, Kommunikations- und Organisationsdatenfeatures verwendet wird. Während Sie keinen Code kopieren und einfügen müssen, haben Sie einige der Übungen Code geändert, um verschiedene Szenarien auszuprobieren.

Was Sie in diesem Lernprogramm erstellen werden

Eigenes Abenteuer auswählen

Sie können das gesamte Lernprogramm von Anfang bis Ende abschließen oder bestimmte Themen von Interesse abschließen. Das Lernprogramm ist in die folgenden Themen unterteilt:

• Klonen Sie die Project-Übung (erforderliche Übung).
• KI-Übungen: Erstellen Sie eine Azure OpenAI-Ressource , und verwenden Sie sie, um natürliche Sprache in SQL zu konvertieren, E-Mail-/SMS-Nachrichten zu generieren und mit Ihren eigenen Daten und Dokumenten zu arbeiten.
• Kommunikationsübungen: Erstellen Sie eine Azure Communication Services-Ressource , und verwenden Sie sie, um Telefonanrufe aus der App zu tätigen und E-Mail-/SMS-Nachrichten zu senden.
• Organisationsdatenübungen: Erstellen Sie eine Microsoft Entra ID-App-Registrierung , damit Microsoft Graph und Das Microsoft Graph-Toolkit zum Authentifizieren und Abrufen von Organisationsdaten in die Anwendung verwendet werden können.

Voraussetzungen

• Node - Node 20+ und npm 10+ werden für dieses Projekt verwendet.
• git
• Visual Studio Code (obwohl Visual Studio Code empfohlen wird, kann jeder Editor verwendet werden)
• Azure-Abonnement
• Microsoft 365-Entwicklermandant
• Docker Desktop oder eine andere OCI (Open Container Initiative) kompatible Containerlaufzeit wie Podman oder nerdctl , die einen Container ausführen kann.

Microsoft Cloud Technologies, die in diesem Lernprogramm verwendet werden

• Azure Communication Services
• Azure OpenAI Service
• Microsoft Entra ID
• Microsoft Graph
• Microsoft Graph Toolkit

Klonen des Projekts

• 132 Minuten verbleibend

Das in diesem Lernprogramm verwendete Codeprojekt ist unter https://github.com/microsoft/MicrosoftCloud. Das Projekt-Repository enthält sowohl clientseitigen als auch serverseitigen Code, der zum Ausführen des Projekts erforderlich ist, sodass Sie die integrierten Features im Zusammenhang mit künstlicher Intelligenz (AI), Kommunikation und Organisationsdaten untersuchen können. Darüber hinaus dient das Projekt als Ressource, um Sie bei der Integration ähnlicher Features in Ihre eigenen Anwendungen zu unterstützen.

In dieser Übung:

• Klonen Sie das GitHub-Repository.
• Fügen Sie dem Projekt eine env-Datei hinzu, und aktualisieren Sie sie.

Bevor Sie fortfahren, stellen Sie sicher, dass alle erforderlichen Komponenten installiert und konfiguriert sind, wie im Abschnitt "Voraussetzungen" dieses Lernprogramms beschrieben.

Klonen des GitHub-Repositorys und Erstellen einer .env Datei

1. Führen Sie den folgenden Befehl aus, um das Microsoft Cloud GitHub-Repository auf Ihren Computer zu klonen.

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

2. Öffnen Sie den Ordner "MicrosoftCloud/samples/openai-acs-msgraph " in Visual Studio Code.

   Hinweis

   Obwohl visual Studio Code in diesem Lernprogramm verwendet wird, kann jeder Code-Editor verwendet werden, um mit dem Beispielprojekt zu arbeiten.

3. Beachten Sie die folgenden Ordner und Dateien:

   • Client: Clientseitiger Anwendungscode.
   • server: Serverseitiger API-Code.
   • docker-compose.yml: Wird verwendet, um eine lokale PostgreSQL-Datenbank auszuführen.

4. Benennen Sie das Beispiel ".env." im Stammverzeichnis des Projekts in ".env" um.

5. Öffnen Sie die env-Datei , und nehmen Sie sich einen Moment Zeit, um die enthaltenen Schlüssel zu durchsuchen:

   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. Aktualisieren Sie die folgenden Werte in .env. Diese Werte werden vom API-Server verwendet, um eine Verbindung mit der lokalen PostgreSQL-Datenbank herzustellen.

   POSTGRES_USER=web
   POSTGRES_PASSWORD=web-password
   

7. Nachdem Sie nun das Projekt eingerichtet haben, probieren wir einige der Anwendungsfeatures aus, und erfahren Sie, wie sie erstellt werden. Wählen Sie unten die Schaltfläche "Weiter " aus, um mit dem Inhaltsverzeichnis zu einer bestimmten Übung fortzufahren oder zu springen.

KI: Erstellen einer Azure OpenAI-Ressource und Bereitstellen eines Modells

• 127 Minuten verbleibend

Um mit der Verwendung von Azure OpenAI in Ihren Anwendungen zu beginnen, müssen Sie einen Azure OpenAI-Dienst erstellen und ein Modell bereitstellen, das zum Ausführen von Aufgaben verwendet werden kann, z. B. das Konvertieren natürlicher Sprache in SQL, das Generieren von E-Mail-/SMS-Nachrichteninhalten und vieles mehr.

In dieser Übung:

• Erstellen Sie eine Azure OpenAI-Dienstressource.
• Bereitstellen eines Modells
• Aktualisieren Sie die env-Datei mit Werten aus Ihrer Azure OpenAI-Dienstressource.

Erstellen einer Azure OpenAI-Dienstressource

1. Besuchen Sie die Azure-Portal in Ihrem Browser, und melden Sie sich an.

2. Geben Sie openai in der Suchleiste oben auf der Portalseite ein, und wählen Sie Azure OpenAI aus den angezeigten Optionen aus.

   

3. Wählen Sie auf der Symbolleiste "Erstellen" aus.

   Hinweis

   Dieses Lernprogramm konzentriert sich zwar auf Azure OpenAI, wenn Sie über einen OpenAI-API-Schlüssel verfügen und ihn verwenden möchten, können Sie diesen Abschnitt überspringen und direkt zum Abschnitt "Project-env-Datei aktualisieren" wechseln. Weisen Sie Ihren OpenAI-API-Schlüssel in der env-Datei zu OPENAI_API_KEY (Sie können alle anderen .env Anweisungen im Zusammenhang mit OpenAI ignorieren).

4. Azure OpenAI-Modelle sind in bestimmten Regionen verfügbar. Besuchen Sie das Azure OpenAI-Modellverfügbarkeitsdokument , um zu erfahren, welche Regionen das in diesem Lernprogramm verwendete gpt-4o-Modell unterstützen.

5. Führen Sie die folgenden Aufgaben aus:

   • Wählen Sie Ihr Azure-Abonnement.
   • Wählen Sie die zu verwendende Ressourcengruppe aus (erstellen Sie bei Bedarf eine neue Gruppe).
   • Wählen Sie einen Bereich aus, in dem das gpt-4o-Modell basierend auf dem Dokument unterstützt wird, das Sie zuvor angesehen haben.
   • Geben Sie den Ressourcennamen ein. Der Name muss ein eindeutiger Wert sein.
   • Wählen Sie das Standard-S0-Preisniveau aus.

6. Wählen Sie "Weiter" aus, bis Sie zum Bildschirm "Überprüfen + Absenden " gelangen. Klicken Sie auf Erstellen.

7. Nachdem Ihre Azure OpenAI-Ressource erstellt wurde, navigieren Sie zu ihr, und wählen Sie "Ressourcenverwaltung – Schlüssel> und Endpunkt" aus.

8. Suchen Sie die KEY 1 - und Endpunktwerte . Sie verwenden beide Werte im nächsten Abschnitt, damit sie in eine lokale Datei kopiert werden.

   

9. Wählen Sie Ressourcenverwaltung –->Modellbereitstellungen aus.

10. Wählen Sie die Schaltfläche "Bereitstellungen verwalten" aus, um zu Azure OpenAI Studio zu wechseln.

11. Wählen Sie "Modell bereitstellen –> Basismodell bereitstellen" in der Symbolleiste aus.

    

12. Wählen Sie "gpt-4o " aus der Liste der Modelle und dann " Bestätigen" aus.

    Hinweis

    Azure OpenAI unterstützt verschiedene Typen von Modellen. Jedes Modell kann verwendet werden, um verschiedene Szenarien zu behandeln.

13. Das folgende Dialogfeld wird angezeigt. Nehmen Sie sich einen Moment Zeit, um die bereitgestellten Standardwerte zu untersuchen.

    

14. Ändern Sie den Token pro Minutenratengrenzwert (Tausender) auf 100 KB. Auf diese Weise können Sie mehr Anforderungen an das Modell stellen und vermeiden, dass sie beim Ausführen der folgenden Schritte das Ratelimit erreichen.

15. Klicken Sie auf Bereitstellen.

16. Nachdem das Modell bereitgestellt wurde, wählen Sie Playgrounds -->Chat aus.

17. Das Dropdownmenü "Bereitstellung" sollte das gpt-4o-Modell anzeigen.

    

18. Nehmen Sie sich einen Moment Zeit, um den bereitgestellten Systemnachrichtentext zu lesen. Dadurch wird dem Modell mitgeteilt, wie der Benutzer damit interagiert.

19. Suchen Sie das Textfeld im Chatbereich, und geben Sie " Zusammenfassen" ein, was generative KI ist und wie es verwendet werden kann. Wählen Sie die EINGABETASTE aus, um die Nachricht an das Modell zu senden und eine Antwort zu generieren.

20. Experimentieren Sie mit anderen Eingabeaufforderungen und Antworten. Geben Sie beispielsweise eine kurze Geschichte über die Hauptstadt Frankreichs ein, und beachten Sie die generierte Antwort.

Aktualisieren der Projektdatei .env

1. Wechseln Sie zurück zu Visual Studio Code, und öffnen Sie die .env Datei im Stammverzeichnis des Projekts.

2. Kopieren Sie den KEY 1-Wert aus Ihrer Azure OpenAI-Ressource, und weisen Sie ihn in der env-Datei im Stammverzeichnis des Ordners openai-acs-msgraph zuOPENAI_API_KEY:

   OPENAI_API_KEY=<KEY_1_VALUE>
   

3. Kopieren Sie den *Endpunktwert, und weisen Sie ihn in der env-Datei zuOPENAI_ENDPOINT. Entfernen Sie das / Zeichen vom Ende des Werts, wenn es vorhanden ist.

   OPENAI_ENDPOINT=<ENDPOINT_VALUE>
   

   Hinweis

   Sie sehen, dass die Werte bereits OPENAI_MODEL in der env-Datei festgelegt sind.OPENAI_API_VERSION Der Modellwert ist auf "gpt-4o " festgelegt, das dem Modellbereitstellungsnamen entspricht, den Sie zuvor in dieser Übung erstellt haben. Die API-Version wird auf einen unterstützten Wert festgelegt, der in der Azure OpenAI-Referenzdokumentation definiert ist.

4. Speichern Sie die Datei mit der Erweiterung .env.

Starten der Anwendungsdienste

Es ist an der Zeit, Ihre Anwendungsdienste einschließlich Datenbank, API-Server und Webserver zu starten.

1. In den folgenden Schritten erstellen Sie drei Terminalfenster in Visual Studio Code.

   

2. Klicken Sie in der Visual Studio Code-Dateiliste mit der rechten Maustaste auf die env-Datei, und wählen Sie "Im integrierten Terminal öffnen" aus. Stellen Sie sicher, dass sich Ihr Terminal am Stamm des Projekts befindet - openai-acs-msgraph -, bevor Sie fortfahren.

3. Wählen Sie eine der folgenden Optionen aus, um die PostgreSQL-Datenbank zu starten:

   • Wenn Docker Desktop installiert und ausgeführt wird, führen Sie sie im Terminalfenster ausdocker-compose up, und drücken Sie die EINGABETASTE.

   • Wenn Podman mit installierter und ausgeführter Podman-Erstellung ausgeführt wird, führen podman-compose up Sie sie im Terminalfenster aus, und drücken Sie die EINGABETASTE.

   • Um den PostgreSQL-Container direkt mit Docker Desktop, Podman, nerdctl oder einer anderen installierten Containerlaufzeit auszuführen, führen Sie den folgenden Befehl im Terminalfenster aus:

     • Mac, Linux oder Windows-Subsystem für 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 mit 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. Nachdem der Datenbankcontainer gestartet wurde, drücken Sie das + Symbol in der Symbolleiste des Visual Studio Code Terminal, um ein zweites Terminalfenster zu erstellen.

   

5. cd in den Server-/Typescript-Ordner ein, und führen Sie die folgenden Befehle aus, um die Abhängigkeiten zu installieren und den API-Server zu starten.

   • npm install
   • npm start

6. Drücken Sie erneut das + Symbol in der Visual Studio Code Terminal-Symbolleiste , um ein drittes Terminalfenster zu erstellen.

7. cd in den Clientordner ein, und führen Sie die folgenden Befehle aus, um die Abhängigkeiten zu installieren und den Webserver zu starten.

   • npm install
   • npm start

8. Ein Browser wird gestartet, und Sie werden zu http://localhost:4200.

   

KI: Natürliche Sprache in SQL

• 122 Minuten verbleibend

Das Zitat "Nur weil Sie nicht bedeuten können, dass Sie nicht bedeuten sollten" ist ein nützlicher Leitfaden, wenn Sie über KI-Funktionen nachdenken. Die natürliche Sprache von Azure OpenAI in SQL ermöglicht Benutzern beispielsweise das Erstellen von Datenbankabfragen in einfachem Englisch, was ein leistungsfähiges Tool sein kann, um ihre Produktivität zu verbessern. Leistungsstärke bedeutet jedoch nicht immer angemessen oder sicher. In dieser Übung wird gezeigt, wie Sie dieses KI-Feature verwenden, während sie wichtige Überlegungen berücksichtigen müssen, bevor Sie sich für die Implementierung entscheiden.

Nachfolgend finden Sie ein Beispiel für eine Abfrage mit natürlicher Sprache, die zum Abrufen von Daten aus einer Datenbank verwendet werden kann:

Get the the total revenue for all companies in London.

Mit den richtigen Eingabeaufforderungen konvertiert Azure OpenAI diese Abfrage in SQL, die verwendet werden kann, um Ergebnisse aus der Datenbank zurückzugeben. Daher können nicht technische Benutzer, einschließlich Business Analysts, Marketers und Führungskräften, wertvolle Informationen aus Datenbanken einfacher abrufen, ohne sich mit einer komplexen SQL-Syntax zu befassen oder auf eingeschränkte Datengrids und Filter zu vertrauen. Dieser optimierte Ansatz kann die Produktivität steigern, indem die Benutzer keine Unterstützung von technischen Experten benötigen.

Diese Übung bietet einen Ausgangspunkt, der Ihnen hilft, zu verstehen, wie natürliche Sprache für SQL funktioniert, Sie zu einigen wichtigen Überlegungen führen, Sie über Vor- und Nachteile nachdenken und Ihnen den Code zeigen, um zu beginnen.

In dieser Übung führen Sie die folgenden Schritte aus:

• Verwenden Sie GPT-Eingabeaufforderungen, um natürliche Sprache in SQL zu konvertieren.
• Experimentieren Sie mit verschiedenen GPT-Eingabeaufforderungen.
• Verwenden Sie die generierte SQL-Datei, um die Zuvor gestartete PostgreSQL-Datenbank abzufragen.
• Gibt Abfrageergebnisse aus PostgreSQL zurück und zeigt sie im Browser an.

Beginnen wir mit dem Experimentieren mit verschiedenen GPT-Eingabeaufforderungen, die zum Konvertieren natürlicher Sprache in SQL verwendet werden können.

Verwenden der natürlichen Sprache zum SQL-Feature

1. In der vorherigen Übung haben Sie die Datenbank, APIs und Anwendung gestartet. Sie haben die .env Datei auch aktualisiert. Wenn Sie diese Schritte nicht abgeschlossen haben, führen Sie die Anweisungen am Ende der Übung aus, bevor Sie fortfahren.

2. Wechseln Sie zurück zum Browser (http://localhost:4200), und suchen Sie den Abschnitt "Benutzerdefinierte Abfrage " der Seite unterhalb des Datagrids. Beachten Sie, dass bereits ein Beispielabfragewert enthalten ist: Abrufen des Gesamtumsatzes für alle Bestellungen. Gruppieren Sie nach Unternehmen, und schließen Sie die Stadt ein.

   

3. Wählen Sie die Schaltfläche Abfrage ausführen aus. Dadurch wird die Natürliche Sprachabfrage des Benutzers an Azure OpenAI übergeben, die sie in SQL konvertiert. Die SQL-Abfrage wird dann verwendet, um die Datenbank abzufragen und mögliche Ergebnisse zurückzugeben.

4. Führen Sie die folgende benutzerdefinierte Abfrage aus:

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

5. Zeigen Sie das Terminalfenster an, in dem der API-Server in Visual Studio Code ausgeführt wird, und beachten Sie, dass die von Azure OpenAI zurückgegebene SQL-Abfrage angezeigt wird. Die JSON-Daten werden von den serverseitigen APIs verwendet, um die PostgreSQL-Datenbank abzufragen. Alle in der Abfrage enthaltenen Zeichenfolgenwerte werden als Parameterwerte hinzugefügt, um SQL-Einfügungsangriffe zu verhindern:

   { 
       "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. Wechseln Sie zurück zum Browser, und wählen Sie "Daten zurücksetzen" aus, um alle Kunden erneut im Datagrid anzuzeigen.

Erkunden der natürlichen Sprache in SQL-Code

1. Nachdem Sie die natürliche Sprache für das SQL-Feature in Aktion gesehen haben, untersuchen wir, wie sie implementiert wird.

2. Öffnen Sie die Datei server/apiRoutes.ts , und suchen Sie die generateSql Route. Diese API-Route wird von der clientseitigen Anwendung aufgerufen, die im Browser ausgeführt wird und zum Generieren von SQL aus einer Abfrage mit natürlicher Sprache verwendet wird. Nachdem die SQL-Abfrage abgerufen wurde, wird sie verwendet, um die Datenbank abzufragen und Ergebnisse zurückzugeben.

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

   Beachten Sie die folgenden Funktionen in der generateSql Route:

   • Er ruft den Benutzerabfragewert ab req.body.prompt und weist ihn einer Variablen mit dem Namen userPromptzu. Dieser Wert wird in der GPT-Eingabeaufforderung verwendet.
   • Sie ruft eine getSQLFromNLP() Funktion auf, um natürliche Sprache in SQL zu konvertieren.
   • Sie übergibt die generierte SQL an eine Funktion mit dem Namen queryDb , die die SQL-Abfrage ausführt, und gibt Ergebnisse aus der Datenbank zurück.

3. Öffnen Sie die Datei server/openAI.ts im Editor, und suchen Sie die getSQLFromNLP() Funktion. Diese Funktion wird von der generatesql Route aufgerufen und wird verwendet, um natürliche Sprache in SQL zu konvertieren.

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

   • Ein userPrompt Parameter wird an die Funktion übergeben. Der userPrompt Wert ist die vom Benutzer im Browser eingegebene Abfrage der natürlichen Sprache.
   • A systemPrompt definiert den Typ des zu verwendenden KI-Assistenten und Regeln, die befolgt werden sollen. Dies hilft Azure OpenAI dabei, die Datenbankstruktur zu verstehen, welche Regeln angewendet werden sollen, und wie die generierte SQL-Abfrage und -Parameter zurückgegeben werden.
   • Eine benannte callOpenAI() Funktion wird aufgerufen, und die systemPrompt Werte userPrompt werden an sie übergeben.
   • Die Ergebnisse werden überprüft, um sicherzustellen, dass in der generierten SQL-Abfrage keine unzulässigen Werte enthalten sind. Wenn unzulässige Werte gefunden werden, wird die SQL-Abfrage auf eine leere Zeichenfolge festgelegt.

4. Sehen wir uns die Systemaufforderung ausführlicher an:

   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"] 
     }
   `;
   

   • Der Typ des zu verwendenden KI-Assistenten wird definiert. In diesem Fall eine "natürliche Sprache für SQL-Bot".

   • Tabellennamen und Spalten in der Datenbank werden definiert. Das allgemeine Schema, das in der Eingabeaufforderung enthalten ist, finden Sie in der Datei "server/db.schema" und sieht wie folgt aus.

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

     Tipp

     Sie können das Erstellen schreibgeschützter Ansichten in Betracht ziehen, die nur die Datenbenutzer enthalten, die abfragen dürfen, indem Sie eine natürliche Sprache in SQL verwenden.

   • Eine Regel wird definiert, um Zeichenfolgenwerte in einen parametrisierten Abfragewert zu konvertieren, um SQL-Einfügungsangriffe zu vermeiden.

   • Eine Regel wird definiert, um immer ein JSON-Objekt mit der SQL-Abfrage und den Darin enthaltenen Parameterwerten zurückzugeben.

   • Beispielbenutzeraufforderungen und die erwarteten SQL-Abfrage- und Parameterwerte werden bereitgestellt. Dies wird als "wenigen" Lernen bezeichnet. Obwohl LLMs auf große Datenmengen geschult werden, können sie mit nur wenigen Beispielen an neue Aufgaben angepasst werden. Ein alternativer Ansatz ist das "Zero-Shot"-Lernen, bei dem kein Beispiel bereitgestellt wird, und das Modell wird erwartet, dass die richtigen SQL-Abfrage- und Parameterwerte generiert werden.

5. Die getSQLFromNLP() Funktion sendet das System und die Benutzeraufforderungen an eine Funktion mit dem Namen callOpenAI() , die sich auch in der Datei server/openAI.ts befindet. Die callOpenAI() Funktion bestimmt, ob der Azure OpenAI-Dienst oder openAI-Dienst durch Überprüfen von Umgebungsvariablen aufgerufen werden soll. Wenn ein Schlüssel, Endpunkt und Modell in den Umgebungsvariablen verfügbar sind, wird Azure OpenAI aufgerufen, andernfalls wird OpenAI aufgerufen.

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

   Hinweis

   Obwohl wir uns in diesem Lernprogramm auf Azure OpenAI konzentrieren, wenn Sie nur einen OPENAI_API_KEY Wert in der env-Datei angeben, verwendet die Anwendung stattdessen OpenAI. Wenn Sie openAI anstelle von Azure OpenAI verwenden, werden in einigen Fällen möglicherweise unterschiedliche Ergebnisse angezeigt.

6. Suchen Sie die getAzureOpenAICompletion() Funktion.

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

   Diese Funktion führt folgende Aktionen aus:

   • Parameter:

     • systemPrompt, userPromptund temperature sind die hauptparameter.
       • systemPrompt: Informiert das Azure OpenAI-Modell über seine Rolle und die zu befolgenden Regeln.
       • userPrompt: Enthält die vom Benutzer bereitgestellten Informationen, z. B. Eingaben natürlicher Sprache oder Regeln zum Generieren der Ausgabe.
       • temperature: Bestimmt die Kreativitätsebene der Reaktion des Modells. Ein höherer Wert führt zu kreativeren Ausgaben.

   • Vervollständigung:

     • Die Funktionsaufrufe createAzureOpenAICompletion() mit systemPrompt, userPromptund temperature zum Generieren eines Abschlusses.
     • Er extrahiert den Inhalt aus der ersten Auswahl im Abschluss, wobei alle zusätzlichen Leerzeichen gekürzt werden.
     • Wenn der Inhalt JSON-ähnliche Strukturen enthält (durch vorhandensein { und }angegeben), extrahiert er den JSON-Inhalt.

   • Protokollierungs- und Rückgabewert:

     • Die Funktion protokolliert die Azure OpenAI-Ausgabe in der Konsole.
     • Er gibt den verarbeiteten Inhalt als Zeichenfolge zurück.

7. Suchen Sie die createAzureOpenAICompletion() Funktion.

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

   Diese Funktion führt folgende Aktionen aus:

   • Parameter:

     • systemPrompt, userPromptund temperature sind die wichtigsten Parameter, die weiter oben erläutert werden.
     • Ein optionaler dataSources Parameter unterstützt das Feature "Azure Bring Your Own Data", das weiter unten in diesem Lernprogramm behandelt wird.

   • Umgebungsvariablen überprüfen:

     • Die Funktion überprüft das Vorhandensein wesentlicher Umgebungsvariablen und löst einen Fehler aus, falls vorhanden.

   • Configuration-Objekt:

     • Ein config Objekt wird mithilfe von Werten aus der .env Datei (OPENAI_API_KEY, OPENAI_ENDPOINT, , OPENAI_MODELOPENAI_API_VERSION) erstellt. Diese Werte werden verwendet, um die URL für den Aufruf von Azure OpenAI zu erstellen.

   • AzureOpenAI-Instanz:

     • Eine Instanz von AzureOpenAI wird erstellt (unter Verwendung des Objekts config). Das AzureOpenAI Symbol ist Teil des openai Pakets, das am Anfang der Datei importiert werden soll.

   • Generieren eines Abschlusses:

     • Die chat.completions.create() Funktion wird mit den folgenden Eigenschaften aufgerufen:
       • model: Gibt das GPT-Modell (z. B. gpt-4o, gpt-3.5-turbo) wie in Ihrer .env Datei definiert an.
       • max_tokens: Definiert die maximale Anzahl von Token für den Abschluss.
       • temperature: Legt die Probenahmetemperatur fest. Höhere Werte (z. B. 0,9) liefern kreativere Antworten, während niedrigere Werte (z. B. 0) mehr deterministische Antworten erzeugen.
       • response_format: Definiert das Antwortformat. Hier wird festgelegt, dass ein JSON-Objekt zurückgegeben wird. Weitere Details zum JSON-Modus finden Sie in der Azure OpenAI-Referenzdokumentation.
       • messages: Enthält die Nachrichten zum Generieren von Chatabschlussen. Dieses Beispiel enthält zwei Meldungen: eine aus dem System (definieren von Verhalten und Regeln) und eine vom Benutzer (die den Eingabeaufforderungstext enthält).

   • Rückgabewert:

     • Die Funktion gibt das von Azure OpenAI generierte Abschlussobjekt zurück.

8. Kommentieren Sie die folgenden Zeilen in der getSQLFromNLP() Funktion aus:

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

9. Speichern Sie openAI.ts. Der API-Server erstellt den TypeScript-Code automatisch neu und startet den Server neu.

10. Wechseln Sie zurück zum Browser, und geben Sie "Alle Tabellennamen aus der Datenbank auswählen" in die Eingabe " Benutzerdefinierte Abfrage " ein. Wählen Sie Run Query (Abfrage ausführen) aus. Werden Tabellennamen angezeigt?

11. Wechseln Sie zurück zur getSQLFromNLP() Funktion in Server/openAI.ts , und fügen Sie die folgende Regel in den Rules: Abschnitt der Systemaufforderung ein, und speichern Sie die Datei.

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

12. Wechseln Sie zurück zum Browser, und führen Sie die folgenden Aufgaben aus:

    • Geben Sie "Alle Tabellennamen aus der Datenbank auswählen" in die Eingabe " Benutzerdefinierte Abfrage " ein. Wählen Sie Run Query (Abfrage ausführen) aus. Werden Tabellennamen angezeigt?
    • Geben Sie "Alle Funktionsnamen aus der Datenbank auswählen" ein. Geben Sie in die Eingabe "Benutzerdefinierte Abfrage" ein, und wählen Sie erneut "Abfrage ausführen" aus. Werden Funktionsnamen angezeigt?

13. FRAGE: Folgt ein Modell immer den Regeln, die Sie in der Eingabeaufforderung definieren?

    ANTWORT: Nein! Es ist wichtig zu beachten, dass OpenAI-Modelle gelegentlich unerwartete Ergebnisse zurückgeben können, die möglicherweise nicht den von Ihnen definierten Regeln entsprechen. Es ist wichtig, dies in Ihrem Code zu planen.

14. Wechseln Sie zurück zu Server/openAI.ts , und suchen Sie die isProhibitedQuery() Funktion. Dies ist ein Beispiel für nach der Verarbeitung von Code, der ausgeführt werden kann, nachdem Azure OpenAI Ergebnisse zurückgegeben hat. Beachten Sie, dass die sql Eigenschaft auf eine leere Zeichenfolge festgelegt wird, wenn unzulässige Schlüsselwörter in der generierten SQL-Abfrage zurückgegeben werden. Dadurch wird sichergestellt, dass, wenn unerwartete Ergebnisse aus Azure OpenAI zurückgegeben werden, die SQL-Abfrage nicht für die Datenbank ausgeführt wird.

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

    Hinweis

    Es ist wichtig zu beachten, dass dies nur Democode ist. Möglicherweise sind andere unzulässige Schlüsselwörter erforderlich, um Ihre spezifischen Anwendungsfälle abzudecken, wenn Sie eine natürliche Sprache in SQL konvertieren möchten. Dies ist ein Feature, das Sie mit Bedacht planen und verwenden müssen, um sicherzustellen, dass nur gültige SQL-Abfragen zurückgegeben und für die Datenbank ausgeführt werden. Zusätzlich zu verbotenen Schlüsselwörtern müssen Sie auch die Sicherheit berücksichtigen.

15. Wechseln Sie zurück zu Server/openAI.ts , und entfernen Sie die Kommentare des folgenden Codes in der getSQLFromNLP() Funktion. Speichern Sie die Datei .

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

16. Entfernen Sie die folgende Regel aus systemPrompt der Datei, und speichern Sie sie.

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

17. Wechseln Sie zurück zum Browser, geben Sie alle Tabellennamen aus der Datenbank erneut in die Benutzerdefinierte Abfrageeingabe ein, und wählen Sie die Schaltfläche "Abfrage ausführen" aus.

18. Werden Tabellenergebnisse angezeigt? Auch ohne die Regel verbietet der Code nach der isProhibitedQuery() Verarbeitung, dass dieser Abfragetyp für die Datenbank ausgeführt wird.

19. Wie bereits erwähnt, kann die Integration natürlicher Sprache in SQL in Branchenanwendungen für Benutzer von Vorteil sein, aber sie enthält eigene Überlegungen.

    Vorteile:

    • Benutzerfreundlichkeit: Dieses Feature kann Benutzern ohne technische Kenntnisse die Datenbankinteraktion leichter zugänglich machen, wodurch die Notwendigkeit von SQL-Kenntnissen verringert und die Vorgänge möglicherweise beschleunigt werden.

    • Höhere Produktivität: Geschäftsanalysten, Marketer, Führungskräfte und andere nicht technische Benutzer können wertvolle Informationen aus Datenbanken abrufen, ohne sich auf technische Experten verlassen zu müssen, wodurch die Effizienz erhöht wird.

    • Breite Anwendung: Mithilfe erweiterter Sprachmodelle können Anwendungen so konzipiert werden, dass sie auf eine breite Palette von Benutzern und Anwendungsfällen ausgerichtet sind.

    Überlegungen:

    • Sicherheit: Einer der größten Bedenken ist Sicherheit. Wenn Benutzer mit Datenbanken mit natürlicher Sprache interagieren können, müssen robuste Sicherheitsmaßnahmen vorhanden sein, um unbefugten Zugriff oder böswillige Abfragen zu verhindern. Sie können erwägen, einen schreibgeschützten Modus zu implementieren, um zu verhindern, dass Benutzer Daten ändern.

    • Datenschutz: Bestimmte Daten sind möglicherweise vertraulich und sollten nicht leicht zugänglich sein, daher müssen Sie sicherstellen, dass angemessene Garantien und Benutzerberechtigungen vorhanden sind.

    • Genauigkeit: Während die Verarbeitung natürlicher Sprachen erheblich verbessert wurde, ist sie nicht perfekt. Falschinterpretation von Benutzerabfragen kann zu ungenauen Ergebnissen oder unerwartetem Verhalten führen. Sie müssen planen, wie unerwartete Ergebnisse behandelt werden.

    • Effizienz: Es gibt keine Garantien, dass die von einer Abfrage mit natürlicher Sprache zurückgegebene SQL effizient ist. In einigen Fällen sind möglicherweise zusätzliche Aufrufe an Azure OpenAI erforderlich, wenn nach der Verarbeitung Regeln Probleme mit SQL-Abfragen erkennen.

    • Schulung und Benutzeranpassung: Benutzer müssen geschult werden, um ihre Abfragen richtig zu formulieren. Obwohl es einfacher ist, SQL zu erlernen, kann es immer noch eine Lernkurve geben.

20. Einige abschließende Punkte, die Sie berücksichtigen sollten, bevor Sie mit der nächsten Übung fortfahren:

    • Denken Sie daran, dass "Nur weil Sie nicht meinen sollten" hier gilt. Verwenden Sie extreme Vorsicht und sorgfältige Planung, bevor Sie natürliche Sprache in SQL in eine Anwendung integrieren. Es ist wichtig, die potenziellen Risiken zu verstehen und sie zu planen.
    • Bevor Sie diese Art von Technologie verwenden, besprechen Sie potenzielle Szenarien mit Ihrem Team, Datenbankadministratoren, Sicherheitsteam, Projektbeteiligten und anderen relevanten Parteien, um sicherzustellen, dass sie für Ihre Organisation geeignet ist. Es ist wichtig zu besprechen, ob die natürliche Sprache sql Sicherheit, Datenschutz und andere Anforderungen erfüllt, die Ihre Organisation möglicherweise eingerichtet hat.
    • Sicherheit sollte ein Hauptanliegen sein und in den Planungsprozess, die Entwicklung und den Bereitstellungsprozess integriert werden.
    • Während die natürliche Sprache in SQL sehr leistungsfähig sein kann, müssen sie sorgfältig geplant werden, um sicherzustellen, dass Eingabeaufforderungen über erforderliche Regeln verfügen und dass die Funktionalität nach der Verarbeitung enthalten ist. Planen Sie zusätzliche Zeit, um diese Art von Funktionalität zu implementieren und zu testen, und berücksichtigen Sie Szenarien, in denen unerwartete Ergebnisse zurückgegeben werden.
    • Mit Azure OpenAI erhalten Kunden die Sicherheitsfunktionen von Microsoft Azure, wobei sie die gleichen Modelle wie OpenAI ausführen. Azure OpenAI bietet private Netzwerke, regionale Verfügbarkeit und verantwortungsvolle KI-Inhaltsfilterung. Erfahren Sie mehr über Daten, Datenschutz und Sicherheit für Azure OpenAI Service.

21. Sie haben jetzt erfahren, wie Sie Azure OpenAI verwenden, um natürliche Sprache in SQL zu konvertieren, und erfahren Sie mehr über die Vor- und Nachteile der Implementierung dieser Art von Funktionalität. In der nächsten Übung erfahren Sie, wie E-Mail- und SMS-Nachrichten mithilfe von Azure OpenAI generiert werden können.

KI: Generieren von Fertigstellungen

• 112 Minuten verbleibend

Zusätzlich zur natürlichen Sprache zum SQL-Feature können Sie auch den Azure OpenAI-Dienst verwenden, um E-Mail- und SMS-Nachrichten zu generieren, um die Produktivität der Benutzer zu verbessern und Kommunikationsworkflows zu optimieren. Durch die Verwendung der Sprachgenerierungsfunktionen von Azure OpenAI können Benutzer bestimmte Regeln wie "Bestellung wird 5 Tage verzögert" definieren, und das System generiert automatisch kontextbezogene E-Mails und SMS-Nachrichten basierend auf diesen Regeln.

Diese Funktion dient als Sprungstart für Benutzer und stellt ihnen eine sorgfältig gestaltete Nachrichtenvorlage bereit, die sie vor dem Senden problemlos anpassen können. Das Ergebnis ist eine erhebliche Reduzierung der Zeit und des Aufwands zum Verfassen von Nachrichten, sodass Benutzer sich auf andere wichtige Aufgaben konzentrieren können. Darüber hinaus kann die Technologie der Sprachgenerierung von Azure OpenAI in Automatisierungsworkflows integriert werden, sodass das System Nachrichten als Reaktion auf vordefinierte Trigger autonom generieren und senden kann. Diese Automatisierungsstufe beschleunigt nicht nur Kommunikationsprozesse, sondern sorgt auch für konsistentes und genaues Messaging in verschiedenen Szenarien.

In dieser Übung führen Sie die folgenden Schritte aus:

• Experimentieren Sie mit verschiedenen Eingabeaufforderungen.
• Verwenden Sie Aufforderungen, um Fertigstellungen für E-Mail- und SMS-Nachrichten zu generieren.
• Erkunden Sie Code, der KI-Fertigstellungen ermöglicht.
• Erfahren Sie mehr über die Bedeutung von Prompt Engineering und einschließlich Regeln in Ihren Eingabeaufforderungen.

Beginnen wir mit dem Experimentieren mit verschiedenen Regeln, die zum Generieren von E-Mails und SMS-Nachrichten verwendet werden können.

Verwenden des KI-Vervollständigungsfeatures

1. In einer vorherigen Übung haben Sie die Datenbank, APIs und Anwendung gestartet. Sie haben die .env Datei auch aktualisiert. Wenn Sie diese Schritte nicht abgeschlossen haben, führen Sie die Anweisungen am Ende der Übung aus, bevor Sie fortfahren.

2. Wechseln Sie zurück zum Browser (http://localhost:4200), und wählen Sie "Kunden kontaktieren" in einer beliebigen Zeile im Datagrid gefolgt von "E-Mail/SMS-Kunde " aus, um zum Bildschirm " Nachrichtengenerator " zu gelangen.

3. Dies verwendet Azure OpenAI zum Konvertieren von Nachrichtenregeln, die Sie in E-Mail-/SMS-Nachrichten definieren. Führen Sie die folgenden Aufgaben aus:

   • Geben Sie eine Regel wie "Bestellung" 5 Tage in die Eingabe ein, und wählen Sie die Schaltfläche "E-Mail-/SMS-Nachrichten generieren" aus.

     

   • Es wird ein Betreff und Textkörper angezeigt, der für die E-Mail und eine kurze Nachricht generiert wurde, die für die SMS generiert wurde.

   Hinweis

   Da Azure Communication Services noch nicht aktiviert ist, können Sie die E-Mail- oder SMS-Nachrichten nicht senden.

4. Schließen Sie das Dialogfeld "E-Mail/SMS" im Browser. Nachdem Sie dieses Feature nun in Aktion gesehen haben, untersuchen wir, wie es implementiert wird.

Erkunden des KI-Abschlusscodes

1. Öffnen Sie die Datei server/apiRoutes.ts , und suchen Sie die completeEmailSmsMessages Route. Diese API wird vom Front-End-Teil der App aufgerufen, wenn die Schaltfläche "E-Mail-/SMS-Nachrichten generieren" ausgewählt ist. Er ruft die Werte der Benutzeraufforderung, des Unternehmens und des Kontaktnamens aus dem Textkörper ab und übergibt sie an die completeEmailSMSMessages() Funktion in der Server-/openAI.ts datei. Die Ergebnisse werden dann an den Client zurückgegeben.

   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. Öffnen Sie die Datei server/openAI.ts , und suchen Sie die completeEmailSMSMessages() Funktion.

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

   Diese Funktion weist die folgenden Features auf:

   • systemPrompt wird verwendet, um zu definieren, dass ein KI-Assistent zum Generieren von E-Mails und SMS-Nachrichten erforderlich ist. Dies systemPrompt umfasst auch:
     • Regeln für den Assistenten, um den Ton der Nachrichten, das Start- und Endformat, die maximale Länge von SMS-Nachrichten und vieles mehr zu steuern.
     • Informationen zu Daten, die in der Antwort enthalten sein sollen – ein JSON-Objekt in diesem Fall.
   • userPrompt wird verwendet, um die Regeln und den Kontaktnamen zu definieren, die der Endbenutzer als E-Mail- und SMS-Nachrichten einfügen möchte. Die Bestellung wird 5 Tage regel verzögert, die Sie zuvor eingegeben haben, ist in userPromptenthalten.
   • Die Funktion ruft die callOpenAI() zuvor untersuchte Funktion auf, um die E-Mail- und SMS-Fertigstellungen zu generieren.

3. Wechseln Sie zurück zum Browser, aktualisieren Sie die Seite, und wählen Sie "Kunde kontaktieren" in einer beliebigen Zeile gefolgt von "E-Mail-/SMS-Kunde " aus, um erneut zum Bildschirm " Nachrichtengenerator " zu gelangen.

4. Geben Sie die folgenden Regeln in die Nachrichtengeneratoreingabe ein:

   • Die Bestellung liegt vor dem Zeitplan.
   • Teilen Sie dem Kunden mit, dass er nie wieder von uns bestellt werden soll, wir wollen nicht, dass es sein Geschäft ist.

5. Wählen Sie "E-Mail-/SMS-Nachrichten generieren" aus, und notieren Sie die Nachricht. Die All messages should have a friendly tone and never use inappropriate language. Regel in der Systemaufforderung überschreibt die negative Regel in der Benutzeraufforderung.

6. Wechseln Sie zurück zu Server/openAI.ts* im Editor, und entfernen Sie die All messages should have a friendly tone and never use inappropriate language. Regel aus der Eingabeaufforderung in der completeEmailSMSMessages() Funktion. Speichern Sie die Datei .

7. Wechseln Sie zurück zum E-Mail-/SMS-Nachrichtengenerator im Browser, und führen Sie die gleichen Regeln erneut aus:

   • Die Bestellung liegt vor dem Zeitplan.
   • Teilen Sie dem Kunden mit, dass er nie wieder von uns bestellt werden soll, wir wollen nicht, dass es sein Geschäft ist.

8. Wählen Sie "E-Mail-/SMS-Nachrichten generieren" aus, und beachten Sie die zurückgegebene Nachricht.

9. Was geschieht in diesen Szenarien? Bei Verwendung von Azure OpenAI können Inhaltsfilter angewendet werden, um sicherzustellen, dass die entsprechende Sprache immer verwendet wird. Wenn Sie OpenAI verwenden, wird die in der Systemaufforderung definierte Regel verwendet, um sicherzustellen, dass die zurückgegebene Nachricht angemessen ist.

   Hinweis

   Dies veranschaulicht die Wichtigkeit der Konstruktion Ihrer Eingabeaufforderungen mit den richtigen Informationen und Regeln, um sicherzustellen, dass die richtigen Ergebnisse zurückgegeben werden. Weitere Informationen zu diesem Prozess finden Sie in der Einführung in die Technische Dokumentation.

10. Rückgängig machen Sie die änderungen, an denen Sie vorgenommen haben systemPrompt completeEmailSMSMessages(), speichern Sie die Datei, und führen Sie sie erneut aus, verwenden Sie jedoch nur die Order is ahead of schedule. Regel (schließen Sie die negative Regel nicht ein). Diesmal sollten die E-Mail- und SMS-Nachrichten wie erwartet zurückgegeben werden.

11. Einige abschließende Punkte, die Sie berücksichtigen sollten, bevor Sie mit der nächsten Übung fortfahren:

    • Es ist wichtig, einen Menschen in der Schleife zu haben, um generierte Nachrichten zu überprüfen. In diesem Beispiel geben Azure OpenAI-Fertigstellungen vorgeschlagene E-Mails und SMS-Nachrichten zurück, aber der Benutzer kann diese außer Kraft setzen, bevor er gesendet wird. Wenn Sie beabsichtigen, E-Mails zu automatisieren, ist es wichtig, dass genehmigte Nachrichten gesendet werden. Zeigen Sie KI als Copilot an, nicht als Autopilot.
    • Die Fertigstellungen sind nur so gut wie die Regeln, die Sie zur Eingabeaufforderung hinzufügen. Nehmen Sie sich Zeit, um Ihre Eingabeaufforderungen und die zurückgegebenen Fertigstellungen zu testen. Erwägen Sie die Verwendung des Eingabeaufforderungsflusses , um eine umfassende Lösung zu erstellen, die die Prototyperstellung, das Experimentieren, Durchlaufen und Bereitstellen von KI-Anwendungen vereinfacht. Laden Sie andere Projektbeteiligte ein, auch die Fertigstellungen zu überprüfen.
    • Möglicherweise müssen Sie nach der Verarbeitung Code einschließen, um sicherzustellen, dass unerwartete Ergebnisse ordnungsgemäß verarbeitet werden.
    • Verwenden Sie Systemaufforderungen, um die Regeln und Informationen zu definieren, die der KI-Assistent befolgen soll. Verwenden Sie Benutzeraufforderungen, um die Regeln und Informationen zu definieren, die der Endbenutzer in die Fertigstellungen aufnehmen möchte.

KI: Azure OpenAI auf Ihren Daten

• 102 Minuten verbleibend

Die Integration von Azure OpenAI Natural Language Processing (NLP) und Abschlussfunktionen bietet ein erhebliches Potenzial zur Verbesserung der Benutzerproduktivität. Durch die Nutzung geeigneter Aufforderungen und Regeln kann ein KI-Assistent effizient verschiedene Kommunikationsformen generieren, z. B. E-Mail-Nachrichten, SMS-Nachrichten und vieles mehr. Diese Funktionalität führt zu einer erhöhten Benutzereffizienz und optimierten Workflows.

Dieses Feature ist zwar eigenständig sehr leistungsfähig, es kann jedoch Vorkommen geben, in denen Benutzer Fertigstellungen basierend auf den benutzerdefinierten Daten Ihres Unternehmens generieren müssen. Sie können z. B. eine Sammlung von Produkthandbüchern haben, die für Benutzer schwierig sein können, zu navigieren, wenn sie Kunden bei Installationsproblemen unterstützen. Alternativ können Sie einen umfassenden Satz von häufig gestellten Fragen (FAQs) im Zusammenhang mit den Vorteilen des Gesundheitswesens beibehalten, die sich für Benutzer als schwierig erweisen können, sich durchzulesen und die benötigten Antworten zu erhalten. In diesen Fällen und vielen anderen ermöglicht Ihnen der Azure OpenAI-Dienst, Ihre eigenen Daten zu nutzen, um Fertigstellungen zu generieren, um eine maßgeschneidertere und kontextbezogenere Antwort auf Benutzerfragen sicherzustellen.

Hier ist eine kurze Übersicht darüber, wie das Feature "Eigene Daten mitbringen" aus der Azure OpenAI-Dokumentation funktioniert.

In dieser Übung führen Sie die folgenden Schritte aus:

• Erstellen Sie eine benutzerdefinierte Datenquelle mit Azure AI Studio.
• Stellen Sie ein Einbettungsmodell mit Azure AI Studio bereit.
• Laden Sie benutzerdefinierte Dokumente hoch.
• Starten Sie eine Chatsitzung im Chat-Playground, um mit dem Generieren von Fertigstellungen basierend auf Ihren eigenen Daten zu experimentieren.
• Erkunden Sie Code, der Azure AI Search und Azure OpenAI verwendet, um Abschlusse basierend auf Ihren eigenen Daten zu generieren.

Beginnen wir mit der Bereitstellung eines Einbettungsmodells und dem Hinzufügen einer benutzerdefinierten Datenquelle in Azure AI Studio.

Hinzufügen einer benutzerdefinierten Datenquelle zu Azure AI Studio

1. Navigieren Sie zu Azure OpenAI Studio , und melden Sie sich mit Anmeldeinformationen an, die Zugriff auf Ihre Azure OpenAI-Ressource haben.

2. Wählen Sie "Bereitstellungen" im Navigationsmenü aus.

3. Wählen Sie auf der Symbolleiste die Option "Modell bereitstellen> – Basismodell bereitstellen" aus.

4. Wählen Sie das Modell "text-embedding-ada-002 " aus der Liste der Modelle aus, und wählen Sie " Bestätigen" aus.

5. Wählen Sie die folgenden Optionen:

   • Bereitstellungsname: text-embedding-ada-002
   • Modellversion: Standard
   • Bereitstellungstyp: Standard
   • Festlegen des Tokens pro Minute Rate Limit (Tausend) Wert auf 120K
   • Inhaltsfilter: DefaultV2
   • Dynamisches Anführungszeichen aktivieren: Aktiviert

6. Wählen Sie die Schaltfläche Bereitstellen aus.

7. Nachdem das Modell erstellt wurde, wählen Sie im Navigationsmenü "Start " aus, um zur Willkommensseite zu wechseln.

8. Suchen Sie die Kachel "Eigene Daten aufbringen" auf der Willkommensseite, und wählen Sie "Jetzt testen" aus.

   

9. Wählen Sie "Daten hinzufügen" gefolgt von "Datenquelle hinzufügen" aus.

10. Wählen Sie in der Dropdownliste "Datenquelle auswählen" die Option "Dateien hochladen" aus.

11. Wählen Sie unter der Dropdownliste "Azure Blob Storage-Ressource auswählen" die Option "Neue Azure Blob Storage-Ressource erstellen" aus.

12. Wählen Sie Ihr Azure-Abonnement in der Dropdownliste "Abonnement " aus.

13. Wählen Sie unter der Dropdownliste "Azure Blob Storage-Ressource auswählen" die Option "Neue Azure Blob Storage-Ressource erstellen" aus.

14. Dadurch gelangen Sie zu der Azure-Portal, in der Sie die folgenden Aufgaben ausführen können:

    • Geben Sie einen eindeutigen Namen für das Speicherkonto ein, z . B. byodstorage[Ihr Nachname].
    • Wählen Sie eine Region aus, die sich in der Nähe Ihres Standorts befindet.
    • Wählen Sie "Überprüfen" gefolgt von "Erstellen" aus.

15. Nachdem die Blob-Speicherressource erstellt wurde, wechseln Sie zurück zum Azure AI Studio-Dialogfeld, und wählen Sie ihre neu erstellte Blob-Speicherressource aus der Dropdownliste "Azure Blob Storage-Ressource auswählen" aus. Wenn die Liste nicht angezeigt wird, wählen Sie das Aktualisierungssymbol neben der Dropdownliste aus.

16. Die ursprungsübergreifende Ressourcenfreigabe (CROSS-Origin Resource Sharing, CORS) muss aktiviert sein, damit auf Ihr Speicherkonto zugegriffen werden kann. Wählen Sie "CORS aktivieren" im Azure AI Studio-Dialogfeld aus.

    

17. Wählen Sie unter dem Dropdown "Azure AI Search-Ressource auswählen" die Option "Neue Azure AI Search-Ressource erstellen" aus.

18. Dadurch gelangen Sie zurück zum Azure-Portal, in dem Sie die folgenden Aufgaben ausführen können:

    • Geben Sie einen eindeutigen Namen für die AI-Suchressource ein, z . B. byodsearch-[Ihr Nachname].
    • Wählen Sie eine Region aus, die sich in der Nähe Ihres Standorts befindet.
    • Wählen Sie im Abschnitt "Preisebene " die Option "Preisstufe ändern" aus, und wählen Sie "Einfach " gefolgt von "Auswählen" aus. Die kostenlose Stufe wird nicht unterstützt, sodass Sie die KI-Suchressource am Ende dieses Lernprogramms bereinigen.
    • Wählen Sie "Überprüfen" gefolgt von "Erstellen" aus.

19. Nachdem die KI-Suchressource erstellt wurde, wechseln Sie zur Seite "Ressourcenübersicht", und kopieren Sie den URL-Wert in eine lokale Datei.

    

20. Wählen Sie "Einstellungen –> Tasten " im Navigationsmenü aus.

21. Wählen Sie auf der Seite "API-Zugriffssteuerung " die Option "Beide " aus, um den Zugriff auf den Dienst mithilfe der verwalteten Identität oder mithilfe eines Schlüssels zu ermöglichen. Wählen bei entsprechender Aufforderung Ja aus.

    Hinweis

    Obwohl in dieser Übung ein API-Schlüssel verwendet wird, da das Hinzufügen von Rollenzuweisungen bis zu 10 Minuten dauern kann, können Sie mit etwas zusätzlichem Aufwand ein system zugewiesene verwaltete Identität aktivieren, um sicherer auf den Dienst zuzugreifen.

22. Wählen Sie "Schlüssel" im linken Navigationsmenü aus, und kopieren Sie den Wert des primären Administratorschlüssels in eine lokale Datei. Sie benötigen die URL und die Schlüsselwerte später in der Übung.

23. Wählen Sie "Einstellungen –> Semantischer Rangfolger" im Navigationsmenü aus, und stellen Sie sicher, dass "Frei" ausgewählt ist.

    Hinweis

    Um zu überprüfen, ob der semantische Rang in einer bestimmten Region verfügbar ist, überprüfen Sie die Seite "Produkte verfügbar nach Region " auf der Azure-Website, um festzustellen, ob Ihre Region aufgeführt ist.

24. Wechseln Sie zurück zum Azure AI Studio-Dialogfeld "Daten hinzufügen", und wählen Sie Ihre neu erstellte Suchressource aus der Dropdownliste "Azure AI Search-Ressource auswählen" aus. Wenn die Liste nicht angezeigt wird, wählen Sie das Aktualisierungssymbol neben der Dropdownliste aus.

25. Geben Sie einen Wert für den Byod-Suchindex für den Indexnamenwert ein.

26. Aktivieren Sie das Kontrollkästchen "Vektorsuche hinzufügen" zu dieser Suchressource .

27. Wählen Sie im Dropdownmenü "Einbettungsmodell auswählen" das zuvor erstellte Text-einbetten-ada-002-Modell aus.

28. Wählen Sie im Dialogfeld "Dateien hochladen" die Option " Nach einer Datei suchen" aus.

29. Navigieren Sie zum Kundendokumentordner des Projekts (im Stammverzeichnis des Projekts), und wählen Sie die folgenden Dateien aus:

    • Clock A102 Installation Instructions.docx
    • Unternehmens-FAQs.docx

    Hinweis

    Dieses Feature unterstützt derzeit die folgenden Dateiformate für die lokale Indexerstellung: .txt, MD, .html, .pdf, .docx und .pptx.

30. Wählen Sie Upload files (Dateien hochladen) aus. Die Dateien werden in einen Dateiupload-byod-search-index-Container in der zuvor erstellten BLOB-Speicherressource hochgeladen.

31. Wählen Sie "Weiter" aus, um zum Dialogfeld "Datenverwaltung " zu wechseln.

32. Wählen Sie im Dropdownmenü "Suchtyp " die Option "Hybrid+ Semantik" aus.

    Hinweis

    Diese Option bietet Unterstützung für die Schlüsselwort- und Vektorsuche. Sobald Ergebnisse zurückgegeben werden, wird ein sekundärer Rangfolgeprozess mithilfe von Deep Learning-Modellen auf das Resultset angewendet, wodurch die Suchrelevanz für den Benutzer verbessert wird. Weitere Informationen zur semantischen Suche finden Sie in der Azure AI Search-Dokumentation zur Semantiksuche.

33. Stellen Sie sicher, dass der Wert "Größe auswählen" auf 1024 festgelegt ist.

34. Wählen Sie Weiter aus.

35. Wählen Sie für den Azure-Ressourcenauthentifizierungstyp DEN API-Schlüssel aus. Weitere Informationen zum Auswählen des richtigen Authentifizierungstyps finden Sie in der Azure AI Search-Authentifizierungsdokumentation.

36. Wählen Sie Weiter aus.

37. Überprüfen Sie die Details, und wählen Sie " Speichern und schließen" aus.

38. Nachdem Ihre benutzerdefinierten Daten hochgeladen wurden, werden die Daten indiziert und stehen zur Verwendung im Chat-Playground zur Verfügung. Dieser Prozess kann einige Minuten in Anspruch nehmen. Fahren Sie nach Abschluss des Vorgangs mit dem nächsten Abschnitt fort.

Verwenden der benutzerdefinierten Datenquelle im Chat-Playground

1. Suchen Sie den Abschnitt "Chatsitzung " der Seite in Azure OpenAI Studio, und geben Sie die folgende Benutzerabfrage ein:

   What safety rules are required to install a clock?
   

2. Nach der Übermittlung der Benutzerabfrage sollte ein Ergebnis wie folgt angezeigt werden:

   

3. Erweitern Sie den Abschnitt "1 Verweise " in der Chatantwort, und beachten Sie, dass die Clock A102-Installation Instructions.docx Datei aufgeführt ist und sie auswählen können, um das Dokument anzuzeigen.

4. Geben Sie die folgende Benutzernachricht ein:

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

5. Es sollte ein Ergebnis wie folgt angezeigt werden:

   

6. Lassen Sie uns nun mit dem FaQs-Dokument des Unternehmens experimentieren. Geben Sie den folgenden Text in das Feld "Benutzerabfrage " ein:

   What is the company's policy on vacation time?
   

7. Sie sollten sehen, dass für diese Anforderung keine Informationen gefunden wurden.

8. Geben Sie den folgenden Text in das Feld "Benutzerabfrage " ein:

   How should I handle refund requests?
   

9. Es sollte ein Ergebnis wie folgt angezeigt werden:

   

10. Erweitern Sie den Abschnitt "1 Verweise " in der Chatantwort, und beachten Sie, dass die Datei "Unternehmen FAQs.docx " aufgeführt ist und dass Sie ihn auswählen können, um das Dokument anzuzeigen.

11. Wählen Sie "Code anzeigen" in der Symbolleiste des Chat-Playgrounds aus.

    

12. Beachten Sie, dass Sie zwischen verschiedenen Sprachen wechseln, den Endpunkt anzeigen und auf den Schlüssel des Endpunkts zugreifen können. Schließen Sie das Dialogfeld "Beispielcode ".

    

13. Aktivieren Sie den Unformatierten JSON-Umschalter über den Chatnachrichten. Beachten Sie, dass die Chatsitzung mit einer ähnlichen Nachricht beginnt:

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

14. Nachdem Sie nun eine benutzerdefinierte Datenquelle erstellt und im Chat-Playground damit experimentiert haben, sehen wir uns an, wie Sie sie in der Anwendung des Projekts verwenden können.

Verwenden des Features "Eigene Daten übertragen" in der Anwendung

1. Wechseln Sie zurück zum Projekt in VS Code, und öffnen Sie die env-Datei . Aktualisieren Sie die folgenden Werte mit Ihrem AI Services-Endpunkt, Schlüssel und Indexnamen. Sie haben den Endpunkt und den Schlüssel weiter oben in dieser Übung in eine lokale Datei kopiert.

   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 einer vorherigen Übung haben Sie die Datenbank, APIs und Anwendung gestartet. Sie haben die .env Datei auch aktualisiert. Wenn Sie diese Schritte nicht abgeschlossen haben, führen Sie die Anweisungen am Ende der vorherigen Übung aus, bevor Sie fortfahren.

3. Nachdem die Anwendung im Browser geladen wurde, wählen Sie oben rechts in der Anwendung das Symbol "Chathilfe " aus.

   

4. Der folgende Text sollte im Chatdialogfeld angezeigt werden:

   How should I handle a company refund request?
   

5. Wählen Sie die Schaltfläche "Hilfe abrufen" aus. Sie sollten Ergebnisse sehen, die aus dem Unternehmen FAQs.docx Dokument zurückgegeben wurden, das Sie zuvor in Azure OpenAI Studio hochgeladen haben. Wenn Sie das Dokument lesen möchten, finden Sie es im Ordner "Kundendokumente " im Stammverzeichnis des Projekts.

6. Ändern Sie den Text wie folgt, und wählen Sie die Schaltfläche "Hilfe abrufen" aus:

   What safety rules are required to install a clock?
   

7. Sie sollten Ergebnisse sehen, die von der Clock A102-Installation Instructions.docx Dokument zurückgegeben wurden, das Sie zuvor in Azure OpenAI Studio hochgeladen haben. Dieses Dokument ist auch im Ordner "Kundendokumente " im Stammverzeichnis des Projekts verfügbar.

Erkunden des Codes

1. Wechseln Sie zurück zum Projektquellcode in Visual Studio Code.

2. Öffnen Sie die Datei server/apiRoutes.ts , und suchen Sie die completeBYOD Route. Diese API wird aufgerufen, wenn die Schaltfläche "Hilfe abrufen" im Dialogfeld "Chathilfe" ausgewählt ist. Er ruft die Benutzeraufforderung aus dem Anforderungstext ab und übergibt sie an die completeBYOD() Funktion in der Datei server/openAI.ts . Die Ergebnisse werden dann an den Client zurückgegeben.

   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. Öffnen Sie die Datei server/openAI.ts , und suchen Sie die completeBYOD() Funktion.

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

   Diese Funktion weist die folgenden Features auf:

   • Der userPrompt Parameter enthält die Informationen, die der Benutzer im Dialogfeld "Chathilfe" eingegeben hat.
   • Die systemPrompt Variable definiert, dass ein KI-Assistent verwendet wird, der personen beim Auffinden von Informationen helfen soll.
   • callOpenAI() wird verwendet, um die Azure OpenAI-API aufzurufen und die Ergebnisse zurückzugeben. Sie übergibt die systemPrompt Werte sowie userPrompt die folgenden Parameter:
     • temperature - Die Menge der Kreativität, die in die Antwort aufgenommen werden soll. Der Benutzer benötigt in diesem Fall konsistente (weniger kreative) Antworten, sodass der Wert auf 0 festgelegt ist.
     • useBYOD – Ein boolescher Wert, der angibt, ob AI Search zusammen mit Azure OpenAI verwendet werden soll. In diesem Fall ist sie so true festgelegt, dass die KI-Suchfunktion verwendet wird.

4. Die callOpenAI() Funktion akzeptiert einen useBYOD Parameter, der verwendet wird, um zu bestimmen, welche OpenAI-Funktion aufgerufen werden soll. In diesem Fall wird sie so true festgelegtuseBYOD, dass die getAzureOpenAIBYODCompletion() Funktion aufgerufen wird.

   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. Suchen Sie die getAzureOpenAIBYODCompletion() Funktion in Server/openAI.ts. Es ist ziemlich ähnlich wie die funktion, die getAzureOpenAICompletion() Sie zuvor untersucht haben, aber es wird als separate Funktion gezeigt, um einige wichtige Unterschiede hervorzuheben, die für das Szenario "Azure OpenAI auf Ihren Daten" eindeutig sind, das in Azure OpenAI verfügbar ist.

   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() ?? '';
   }
   

   Beachten Sie die folgenden Funktionen in der getAzureOpenAIBYODCompletion() Funktion:

   • Es wird eine dataSources Eigenschaft erstellt, die die KI-Suchressource endpointkeyund index_name werte enthält, die .env der Datei weiter oben in dieser Übung hinzugefügt wurden.
   • Die createAzureOpenAICompletion() Funktion wird mit den systemPromptWerten , userPrompt, , temperatureund dataSources den Werten aufgerufen. Diese Funktion wird verwendet, um die Azure OpenAI-API aufzurufen und die Ergebnisse zurückzugeben.
   • Sobald die Antwort zurückgegeben wird, werden die Dokumentzitate in der Konsole protokolliert. Der Inhalt der Abschlussnachricht wird dann an den Aufrufer zurückgegeben.

6. Einige abschließende Punkte, die Sie berücksichtigen sollten, bevor Sie mit der nächsten Übung fortfahren:

   • Die Beispielanwendung verwendet einen einzelnen Index in Azure AI Search. Sie können mehrere Indizes und Datenquellen mit Azure OpenAI verwenden. Die dataSources Eigenschaft in der getAzureOpenAIBYODCompletion() Funktion kann aktualisiert werden, um bei Bedarf mehrere Datenquellen einzuschließen.
   • Die Sicherheit muss mit dieser Art von Szenario sorgfältig bewertet werden. Benutzer sollten nicht in der Lage sein, Fragen zu stellen und Ergebnisse aus Dokumenten zu erhalten, auf die sie nicht zugreifen können.

7. Nachdem Sie nun azure OpenAI kennengelernt haben, Eingabeaufforderungen, Abschlusse und wie Sie Ihre eigenen Daten verwenden können, gehen wir zur nächsten Übung, um zu erfahren, wie Kommunikationsfeatures verwendet werden können, um die Anwendung zu verbessern. Wenn Sie mehr über Azure OpenAI erfahren möchten, lesen Sie die Schulungsinhalte " Erste Schritte mit Azure OpenAI Service ". Weitere Informationen zur Verwendung Ihrer eigenen Daten mit Azure OpenAI finden Sie in der Azure OpenAI in Ihrer Datendokumentation .

Kommunikation: Erstellen einer Azure Communication Services-Ressource

• 87 Minuten verbleibend

Eine effektive Kommunikation ist für erfolgreiche benutzerdefinierte Geschäftsanwendungen unerlässlich. Mithilfe von Azure Communication Services (ACS) können Sie Ihren Anwendungen Features wie Telefonanrufe, Live-Chat, Audio-/Videoanrufe und E-Mail- und SMS-Nachrichten hinzufügen. Früher haben Sie erfahren, wie Azure OpenAI Abschlusse für E-Mail- und SMS-Nachrichten generieren kann. Jetzt erfahren Sie, wie Sie die Nachrichten senden. Gemeinsam können ACS und OpenAI Ihre Anwendungen verbessern, indem sie die Kommunikation vereinfachen, Interaktionen verbessern und die Geschäftliche Produktivität steigern.

In dieser Übung führen Sie die folgenden Schritte aus:

• Erstellen Sie eine Azure Communication Services (ACS)-Ressource.
• Fügen Sie eine gebührenfreie Telefonnummer mit Anruf- und SMS-Funktionen hinzu.
• Verbinden einer E-Mail-Domäne
• Aktualisieren Sie die env-Datei des Projekts mit Werten aus Ihrer ACS-Ressource.

Erstellen einer Azure Communication Services-Ressource

1. Besuchen Sie die Azure-Portal in Ihrem Browser, und melden Sie sich an, wenn Sie dies noch nicht getan haben.

2. Geben Sie Kommunikationsdienste in die Suchleiste oben auf der Seite ein, und wählen Sie "Kommunikationsdienste " aus den angezeigten Optionen aus.

   

3. Wählen Sie auf der Symbolleiste "Erstellen" aus.

4. Führen Sie die folgenden Aufgaben aus:

   • Wählen Sie Ihr Azure-Abonnement.
   • Wählen Sie die zu verwendende Ressourcengruppe aus (erstellen Sie eine neue Gruppe, wenn sie nicht vorhanden ist).
   • Geben Sie einen ACS-Ressourcennamen ein. Der Name muss ein eindeutiger Wert sein.
   • Wählen Sie einen Datenspeicherort aus.

5. Wählen Sie "Überprüfen" und "Erstellen" gefolgt von "Erstellen" aus.

6. Sie haben erfolgreich eine neue Azure Communication Services-Ressource erstellt! Als Nächstes aktivieren Sie die Telefonanruf- und SMS-Funktionen. Außerdem verbinden Sie eine E-Mail-Domäne mit der Ressource.

Aktivieren von Telefonanruf- und SMS-Funktionen

1. Fügen Sie eine Telefonnummer hinzu, und stellen Sie sicher, dass die Telefonnummer Anruffunktionen aktiviert hat. Sie verwenden diese Telefonnummer, um von der App aus ein Telefon aufzurufen.

   • Wählen Sie "Telefonie" und "SMS-Telefonnummern>" im Menü "Ressource" aus.

   • Wählen Sie +Abrufen in der Symbolleiste aus (oder wählen Sie die Schaltfläche "Zahl abrufen") aus, und geben Sie die folgenden Informationen ein:

     • Land oder Region: United States
     • Zahlentyp: Toll-free

     Hinweis

     Eine Kreditkarte ist für Ihr Azure-Abonnement erforderlich, um die gebührenfreie Nummer zu erstellen. Wenn Sie keine Karte in der Datei haben, können Sie das Hinzufügen einer Telefonnummer überspringen und zum nächsten Abschnitt der Übung springen, der eine E-Mail-Domäne verbindet. Sie können die App weiterhin verwenden, können aber keine Telefonnummer anrufen.

     • Nummer: Wählen Sie "Zum Warenkorb hinzufügen" für eine der aufgeführten Telefonnummern aus.

2. Wählen Sie "Weiter" aus, überprüfen Sie die Details der Telefonnummer, und wählen Sie "Jetzt kaufen" aus.

   Hinweis

   Sms-Überprüfung für gebührenfreie Nummern ist jetzt in den USA und Kanada obligatorisch. Um SMS-Nachrichten zu aktivieren, müssen Sie die Überprüfung nach dem Kauf der Telefonnummer übermitteln. Während dieses Lernprogramms diesen Vorgang nicht durchläuft, können Sie telefonie- und SMS -->Regulatorische Dokumente aus dem Ressourcenmenü auswählen und die erforderliche Validierungsdokumentation hinzufügen.

3. Nachdem die Telefonnummer erstellt wurde, wählen Sie sie aus, um zum Bereich "Features " zu gelangen. Stellen Sie sicher, dass die folgenden Werte festgelegt sind (sie sollten standardmäßig festgelegt werden):

   • Wählen Sie im Abschnitt "Anrufe " die Option Make callsaus.
   • Wählen Sie im Abschnitt SMS die Option Send and receive SMSaus.
   • Wählen Sie Speichern.

4. Kopieren Sie den Telefonnummernwert zur späteren Verwendung in eine Datei. Die Telefonnummer sollte diesem allgemeinen Muster entsprechen: +12345678900.

Verbinden einer E-Mail-Domäne

1. Führen Sie die folgenden Aufgaben aus, um eine verbundene E-Mail-Domäne für Ihre ACS-Ressource zu erstellen, damit Sie E-Mails senden können. Dies wird verwendet, um E-Mails von der App zu senden.

   • Wählen Sie "E-Mail-Domänen>" im Menü "Ressource" aus.
   • Wählen Sie in der Symbolleiste "Domäne verbinden" aus.
   • Wählen Sie Ihre Abonnement - und Ressourcengruppe aus.
   • Wählen Sie unter der Dropdownliste "E-Mail-Dienst " die Option Add an email serviceaus.
   • Geben Sie dem E-Mail-Dienst einen Namen, z acs-demo-email-service. B. .
   • Wählen Sie "Überprüfen" und "Erstellen" gefolgt von "Erstellen" aus.
   • Wählen Sie Go to resourcenach Abschluss der Bereitstellung eine kostenlose Azure-Unterdomäne aus, und wählen Sie sie aus 1-click add , um eine kostenlose Azure-Unterdomäne hinzuzufügen.
   • Nachdem die Unterdomäne hinzugefügt wurde (es dauert ein paar Minuten, um bereitgestellt zu werden), wählen Sie sie aus.
   • Sobald Sie sich auf dem Bildschirm "AzureManagedDomain " befinden, wählen Sie "E-Mail-Dienste –-MailFrom"->Adressen aus dem Menü "Ressource" aus.
   • Kopieren Sie den MailFrom-Wert in eine Datei. Sie verwenden sie später, wenn Sie die env-Datei aktualisieren.
   • Wechseln Sie zurück zu Ihrer Azure Communication Services-Ressource, und wählen Sie "E-Mail-Domänen>" aus dem Ressourcenmenü aus.
   • Wählen Sie den MailFrom Wert aus dem vorherigen Schritt ausAdd domain, und geben Sie ihn ein (stellen Sie sicher, dass Sie das richtige Abonnement, die Ressourcengruppe und den E-Mail-Dienst auswählen). Wählen Sie die Schaltfläche Connect aus.

Aktualisieren der .env Datei

1. Nachdem Ihre ACS-Telefonnummer (mit Aktivierter Anrufe und SMS) und E-Mail-Domäne bereit ist, aktualisieren Sie die folgenden Schlüssel/Werte in der env-Datei in Ihrem Projekt:

   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_STRING: Der connection string Wert aus dem Abschnitt "Schlüssel " Ihrer ACS-Ressource.

   • ACS_PHONE_NUMBER: Weisen Sie dem Wert Ihre gebührenfreie Nummer zu ACS_PHONE_NUMBER .

   • ACS_EMAIL_ADDRESS: Weisen Sie Ihren E-Mail-Adresswert "MailTo" zu.

   • CUSTOMER_EMAIL_ADDRESS: Weisen Sie eine E-Mail-Adresse zu, an die E-Mails von der App gesendet werden sollen (da die Kundendaten in der App-Datenbank nur Beispieldaten sind). Sie können eine persönliche E-Mail-Adresse verwenden.

   • CUSTOMER_PHONE_NUMBER: Sie müssen aufgrund einer zusätzlichen Überprüfung, die in anderen Ländern zum Senden von SMS-Nachrichten erforderlich ist, eine USA basierte Telefonnummer (ab heute) angeben. Wenn Sie keine US-basierte Nummer haben, können Sie sie leer lassen.

Starten/Neustarten der Anwendungs- und API-Server

Führen Sie einen der folgenden Schritte basierend auf den Übungen aus, die Sie bis zu diesem Punkt abgeschlossen haben:

• Wenn Sie die Datenbank, den API-Server und den Webserver in einer früheren Übung gestartet haben, müssen Sie den API-Server und den Webserver beenden und neu starten, um die env-Dateiänderungen zu übernehmen. Sie können die Datenbank ausführen lassen.

  Suchen Sie die Terminalfenster, unter denen der API-Server und der Webserver ausgeführt werden, und drücken Sie STRG+C , um sie zu beenden. Starten Sie sie erneut, indem Sie in jedes Terminalfenster eingeben npm start und die EINGABETASTE drücken. Fahren Sie mit der nächsten Übung fort.

• Wenn Sie die Datenbank, den API-Server und den Webserver noch nicht gestartet haben, führen Sie die folgenden Schritte aus:

  1. In den folgenden Schritten erstellen Sie drei Terminalfenster in Visual Studio Code.

     

  2. Klicken Sie in der Visual Studio Code-Dateiliste mit der rechten Maustaste auf die env-Datei, und wählen Sie "Im integrierten Terminal öffnen" aus. Stellen Sie sicher, dass sich Ihr Terminal am Stamm des Projekts befindet - openai-acs-msgraph -, bevor Sie fortfahren.

  3. Wählen Sie eine der folgenden Optionen aus, um die PostgreSQL-Datenbank zu starten:

     • Wenn Docker Desktop installiert und ausgeführt wird, führen Sie sie im Terminalfenster ausdocker-compose up, und drücken Sie die EINGABETASTE.

     • Wenn Podman mit installierter und ausgeführter Podman-Erstellung ausgeführt wird, führen podman-compose up Sie sie im Terminalfenster aus, und drücken Sie die EINGABETASTE.

     • Um den PostgreSQL-Container direkt mit Docker Desktop, Podman, nerdctl oder einer anderen installierten Containerlaufzeit auszuführen, führen Sie den folgenden Befehl im Terminalfenster aus:

       • Mac, Linux oder Windows-Subsystem für 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 mit 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. Nachdem der Datenbankcontainer gestartet wurde, drücken Sie das + Symbol in der Symbolleiste des Visual Studio Code Terminal, um ein zweites Terminalfenster zu erstellen.

     

  5. cd in den Server-/Typescript-Ordner ein, und führen Sie die folgenden Befehle aus, um die Abhängigkeiten zu installieren und den API-Server zu starten.

     • npm install
     • npm start

  6. Drücken Sie erneut das + Symbol in der Visual Studio Code Terminal-Symbolleiste , um ein drittes Terminalfenster zu erstellen.

  7. cd in den Clientordner ein, und führen Sie die folgenden Befehle aus, um die Abhängigkeiten zu installieren und den Webserver zu starten.

     • npm install
     • npm start

  8. Ein Browser wird gestartet, und Sie werden zu http://localhost:4200.

     

Kommunikation: Tätigen eines Telefonanrufs

• 79 Minuten verbleibend

Die Integration der Telefonanruffunktionen von Azure Communication Services in eine benutzerdefinierte Branchenanwendung bietet unternehmen und ihren Benutzern mehrere wichtige Vorteile:

• Ermöglicht eine nahtlose und echtzeitbasierte Kommunikation zwischen Mitarbeitern, Kunden und Partnern direkt aus der Branchenanwendung, ohne dass zwischen mehreren Plattformen oder Geräten gewechselt werden muss.
• Verbessert die Benutzererfahrung und verbessert die gesamtbetriebstechnische Effizienz.
• Erleichtert die schnelle Problemlösung, da Benutzer schnell und einfach mit relevanten Supportteams oder Fachexperten in Verbindung treten können.

In dieser Übung führen Sie die folgenden Schritte aus:

• Erkunden Sie die Telefonanruffunktion in der Anwendung.
• Führen Sie den Code durch, um zu erfahren, wie das Telefonanruffeature erstellt wird.

Verwenden der Telefonanruffunktion

1. In der vorherigen Übung haben Sie eine Azure Communication Services (ACS)-Ressource erstellt und die Datenbank, den Webserver und den API-Server gestartet. Sie haben auch die folgenden Werte in der env-Datei aktualisiert.

   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>
   

   Stellen Sie sicher, dass Sie die vorherige Übung abgeschlossen haben, bevor Sie fortfahren.

2. Wechseln Sie zurück zum Browser (http://localhost:4200), suchen Sie das Datagrid, und wählen Sie "Kunden kontaktieren" gefolgt von "Kunden anrufen" in der ersten Zeile aus.

   

3. Der Kopfzeile wird eine Telefonanrufkomponente hinzugefügt. Geben Sie Ihre Telefonnummer ein, die Sie anrufen möchten (stellen Sie sicher, dass sie mit + beginnt und die Ländervorwahl enthält), und wählen Sie "Anrufen" aus. Sie werden aufgefordert, den Zugriff auf Ihr Mikrofon zuzulassen.

   

4. Wählen Sie "Auflegen" aus, um den Anruf zu beenden. Wählen Sie "Schließen" aus, um die Telefonanrufkomponente zu schließen.

Erkunden des Telefonanrufcodes

1. Öffnen Sie die datei customers-list.component.ts . Der vollständige Pfad zur Datei ist client/src/app/customers-list/customers-list.component.ts.

2. Beachten Sie, dass openCallDialog() eine CustomerCall Nachricht und die Kundentelefonnummer mit einem Ereignisbus gesendet werden.

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

   Hinweis

   Der Ereignisbuscode finden Sie in der datei eventbus.service.ts , wenn Sie mehr erfahren möchten. Der vollständige Pfad zur Datei ist client/src/app/core/eventbus.service.ts.

3. Die Funktion der Kopfzeilenkomponente ngOnInit() abonniert das CustomerCall vom Ereignisbus gesendete Ereignis und zeigt die Telefonanrufkomponente an. Sie finden diesen Code 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. Öffnen Sie phone-call.component.ts. Nehmen Sie sich einen Moment Zeit, um den Code verfügbar zu machen. Der vollständige Pfad zur Datei ist client/src/app/phone-call/phone-call.component.ts. Beachten Sie die folgenden wichtigsten Features:

   • Ruft ein Azure Communication Services-Zugriffstoken durch Aufrufen der acsService.getAcsToken() Funktion in ngOnInit();
   • Fügt der Seite einen "Telefonwähler" hinzu. Sie können die Wählhilfe anzeigen, indem Sie in der Kopfzeile auf die Eingabe der Telefonnummer klicken.
   • Startet und beendet einen Aufruf mit den startCall() jeweiligen endCall() Funktionen.

5. Bevor wir uns den Code ansehen, der den Telefonanruf vornimmt, untersuchen wir, wie das ACS-Zugriffstoken abgerufen wird und wie Telefonanrufobjekte erstellt werden. Suchen Sie die ngOnInit() Funktion 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);
               })
           );
       }
   }
   

   Diese Funktion führt die folgenden Aktionen aus:

   • Ruft eine ACS userId und ein Zugriffstoken durch Aufrufen der acsService.getAcsToken() Funktion ab.
   • Nachdem das Zugriffstoken abgerufen wurde, führt der Code die folgenden Aktionen aus:
     • Erstellt eine neue Instanz von CallClient und AzureCommunicationTokenCredential verwendet das Zugriffstoken.
     • Erstellt eine neue Instanz der Verwendung der CallAgent CallClient Objekte.AzureCommunicationTokenCredential Später sehen Sie, dass CallAgent zum Starten und Beenden eines Anrufs verwendet wird.

6. Öffnen Sie acs.services.ts , und suchen Sie die getAcsToken() Funktion. Der vollständige Pfad zur Datei ist client/src/app/core/acs.service.ts. Die Funktion sendet eine HTTP GET-Anforderung an die Route, die /acstoken vom API-Server verfügbar gemacht wird.

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

7. Eine API-Serverfunktion mit dem Namen createACSToken() ruft die UserId und das Zugriffstoken ab und gibt sie an den Client zurück. Sie befindet sich in der Datei "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 };
   }
   

   Diese Funktion führt die folgenden Aktionen aus:

   • Überprüft, ob ein ACS-Wert connectionString verfügbar ist. Wenn dies nicht der Fehler ist, wird ein Objekt mit einem leeren userId und tokeneinem .
   • Erstellt eine neue Instanz von CommunicationIdentityClient und übergibt den connectionString Wert an ihn.
   • Erstellt einen neuen Benutzer und ein neues Token mit tokenClient.createUserAndToken() dem Bereich "voip".
   • Gibt ein Objekt zurück, das die userId Werte enthält token .

8. Nachdem Sie nun gesehen haben, wie die UserId und das Token abgerufen werden, wechseln Sie zurück, phone-call.component.ts und suchen Sie die startCall() Funktion.

9. Diese Funktion wird aufgerufen, wenn "Anruf " in der Telefonanrufkomponente ausgewählt ist. Es verwendet das CallAgent zuvor erwähnte Objekt, um einen Aufruf zu starten. Die callAgent.startCall() Funktion akzeptiert ein Objekt, das die Rufnummer und die ACS-Telefonnummer darstellt, die zum Tätigen des Anrufs verwendet wird.

   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. Die endCall() Funktion wird aufgerufen, wenn Hang Up in der Telefonanrufkomponente ausgewählt ist.

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

    Wenn ein Aufruf ausgeführt wird, wird die call.hangUp() Funktion aufgerufen, um den Aufruf zu beenden. Wenn kein Anruf ausgeführt wird, wird das hangup Ereignis an die übergeordnete Kopfzeilenkomponente ausgegeben, um die Telefonanrufkomponente auszublenden.

11. Bevor wir mit der nächsten Übung fortfahren, sehen wir uns die wichtigsten Konzepte an, die in dieser Übung behandelt werden:

    • Eine ACS-Benutzer-ID und ein Zugriffstoken werden mithilfe der acsService.createUserAndToken() Funktion vom API-Server abgerufen.
    • Das Token wird verwendet, um ein Objekt und CallAgent ein CallClient Objekt zu erstellen.
    • Das CallAgent Objekt wird verwendet, um einen Aufruf zu starten und zu beenden, indem die callAgent.startCall() entsprechenden Funktionen aufgerufen werden callAgent.hangUp() .

12. Nachdem Sie nun gelernt haben, wie Telefonanrufe in eine Anwendung integriert werden können, setzen wir unseren Fokus auf die Verwendung von Azure Communication Services zum Senden von E-Mails und SMS-Nachrichten.

Kommunikation: Senden von E-Mails und SMS-Nachrichten

• 69 Minuten verbleibend

Zusätzlich zu Telefonanrufen können Azure Communication Services auch E-Mail- und SMS-Nachrichten senden. Dies kann hilfreich sein, wenn Sie eine Nachricht direkt aus der Anwendung an einen Kunden oder einen anderen Benutzer senden möchten.

In dieser Übung führen Sie die folgenden Schritte aus:

• Erfahren Sie, wie E-Mail- und SMS-Nachrichten von der Anwendung gesendet werden können.
• Führen Sie den Code durch, um zu erfahren, wie die E-Mail- und SMS-Funktionalität implementiert wird.

Verwenden der E-Mail- und SMS-Funktionen

1. In einer vorherigen Übung haben Sie eine Azure Communication Services (ACS)-Ressource erstellt und die Datenbank, den Webserver und den API-Server gestartet. Sie haben auch die folgenden Werte in der env-Datei aktualisiert.

   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>
   

   Stellen Sie sicher, dass Sie die Übung abgeschlossen haben, bevor Sie fortfahren.

2. Wechseln Sie zurück zum Browser (http://localhost:4200), und wählen Sie "Kunden kontaktieren" gefolgt von "E-Mail/SMS-Kunde " in der ersten Zeile aus.

   

3. Wählen Sie die Registerkarte "E-Mail/SMS " aus, und führen Sie die folgenden Aufgaben aus:

   • Geben Sie einen E-Mail-Betreff und text ein, und wählen Sie die Schaltfläche "E-Mail senden" aus.
   • Geben Sie eine SMS-Nachricht ein, und wählen Sie die Schaltfläche "SMS senden" aus.

   

   Hinweis

   Sms-Überprüfung für gebührenfreie Nummern ist jetzt in den USA und Kanada obligatorisch. Um SMS-Nachrichten zu aktivieren, müssen Sie die Überprüfung nach dem Kauf der Telefonnummer übermitteln. Während dieses Lernprogramms diesen Vorgang nicht durchlaufen wird, können Sie telefonie- und SMS --Regulatorische Dokumente aus Ihrer Azure Communication Services-Ressource> in der Azure-Portal auswählen und die erforderliche Validierungsdokumentation hinzufügen.

4. Überprüfen Sie, ob Sie die E-Mail- und SMS-Nachrichten erhalten haben. SMS-Funktionen funktionieren nur, wenn Sie die in der vorherigen Notiz erwähnten regulatorischen Dokumente übermittelt haben. Als Erinnerung wird die E-Mail-Nachricht an den für sie definierten CUSTOMER_EMAIL_ADDRESS Wert gesendet, und die SMS-Nachricht wird an den in der env-Datei definierten CUSTOMER_PHONE_NUMBER Wert gesendet. Wenn Sie keine USA basierende Telefonnummer angeben konnten, die für SMS-Nachrichten verwendet werden soll, können Sie diesen Schritt überspringen.

   Hinweis

   Wenn die E-Mail-Nachricht in Ihrem Posteingang für die Adresse, die Sie in der env-Datei definiert CUSTOMER_EMAIL_ADDRESS haben, nicht angezeigt wird, überprüfen Sie Ihren Spamordner.

Erkunden des E-Mail-Codes

1. Öffnen Sie die datei customers-list.component.ts . Der vollständige Pfad zur Datei ist client/src/app/customers-list/customers-list.component.ts.

2. Wenn Sie "Kunden kontaktieren" gefolgt von "E-Mail/SMS-Kunde" im Datagrid ausgewählt haben, zeigt die customer-list Komponente ein Dialogfeld an. Dies wird von der Funktion in der openEmailSmsDialog() datei customer-list.component.ts behandelt.

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

   Die openEmailSmsDialog() Funktion führt die folgenden Aufgaben aus:

   • Überprüft, ob das data Objekt (das die Zeile aus dem Datagrid darstellt) eine phone und email eine Eigenschaft enthält. Wenn dies der Fall ist, wird ein dialogData Objekt erstellt, das die Informationen enthält, die an das Dialogfeld übergeben werden sollen.
   • Öffnet das EmailSmsDialogComponent Dialogfeld und übergibt das dialogData Objekt an das Objekt.
   • Abonniert das afterClosed() Ereignis des Dialogfelds. Dieses Ereignis wird ausgelöst, wenn das Dialogfeld geschlossen wird. Das response Objekt enthält die Informationen, die in das Dialogfeld eingegeben wurden.

3. Öffnen Sie die datei email-sms-dialog.component.ts . Der vollständige Pfad zur Datei ist client/src/app/email-sms-dialog/email-sms-dialog.component.ts.

4. Suchen Sie die sendEmail() Funktion:

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

   Die sendEmail() Funktion führt die folgenden Aufgaben aus:

   • Überprüft, ob das acsEmailEnabled Feature-Flag auf .true Mit diesem Kennzeichen wird überprüft, ob die ACS_EMAIL_ADDRESS Umgebungsvariable über einen zugewiesenen Wert verfügt.
   • Wenn acsEmailEnabled wahr, wird die acsService.sendEmail() Funktion aufgerufen, und der E-Mail-Betreff, der Textkörper, der Kundenname und die E-Mail-Adresse des Kunden werden übergeben. Da die Datenbank Beispieldaten enthält, wird die CUSTOMER_EMAIL_ADDRESS Umgebungsvariable anstelle von this.data.email. In einer realen Anwendung würde der this.data.email Wert verwendet werden.
   • Abonniert die sendEmail() Funktion im acsService Dienst. Diese Funktion gibt eine RxJS-Observable zurück, die die Antwort des clientseitigen Diensts enthält.
   • Wenn die E-Mail erfolgreich gesendet wurde, wird die emailSent Eigenschaft auf true.

5. Um eine bessere Codekapselung bereitzustellen und wiederzuverwenden, werden clientseitige Dienste wie acs.service.ts in der gesamten Anwendung verwendet. Dadurch können alle ACS-Funktionen an einem zentralen Ort konsolidiert werden.

6. Öffnen Sie acs.service.ts , und suchen Sie die sendEmail() Funktion. Der vollständige Pfad zur Datei ist 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)
       );
   }
   

   Die sendEmail() Funktion führt die folgenden Aufgaben aus AcsService :

   • Ruft die http.post() Funktion auf und übergibt den E-Mail-Betreff, die Nachricht, den Kundennamen und die E-Mail-Adresse des Kunden. Die http.post() Funktion gibt eine RxJS observable zurück, die die Antwort des API-Aufrufs enthält.
   • Behandelt alle fehler, die von der http.post() Funktion mithilfe des RxJS-Operators catchError zurückgegeben werden.

7. Sehen wir uns nun an, wie die Anwendung mit dem ACS-E-Mail-Feature interagiert. Öffnen Sie die datei acs.ts , und suchen Sie die sendEmail() Funktion. Der vollständige Pfad zur Datei ist server/typescript/acs.ts.

8. Die sendEmail() Funktion führt die folgenden Aufgaben aus:

   • Erstellt ein neues EmailClient Objekt und übergibt die ACS-Verbindungszeichenfolge an das Objekt (dieser Wert wird aus der ACS_CONNECTION_STRING Umgebungsvariable abgerufen).

     const emailClient = new EmailClient(connectionString);
     

   • Erstellt ein neues EmailMessage Objekt und übergibt die Absender-, Betreff-, Nachrichten- und Empfängerinformationen.

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

   • Sendet die E-Mail mithilfe der emailClient.beginSend() Funktion und gibt die Antwort zurück. Obwohl die Funktion nur an einen Empfänger in diesem Beispiel gesendet wird, kann die beginSend() Funktion auch zum Senden an mehrere Empfänger verwendet werden.

     const poller = await emailClient.beginSend(msgObject);
     

   • Wartet, bis das poller Objekt signalisiert, dass es abgeschlossen ist, und sendet die Antwort an den Aufrufer.

Erkunden des SMS-Codes

1. Wechseln Sie zurück zur email-sms-dialog.component.ts Datei, die Sie zuvor geöffnet haben. Der vollständige Pfad zur Datei ist client/src/app/email-sms-dialog/email-sms-dialog.component.ts.

2. Suchen Sie die sendSms() Funktion:

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

   Die sendSMS() Funktion führt die folgenden Aufgaben aus:

   • Überprüft, ob das acsPhoneEnabled Feature-Flag auf .true Mit diesem Kennzeichen wird überprüft, ob die ACS_PHONE_NUMBER Umgebungsvariable über einen zugewiesenen Wert verfügt.
   • Wenn acsPhoneEnabled wahr, wird die acsService.SendSms() Funktion aufgerufen, und die SMS-Nachricht und die Kundentelefonnummer werden übergeben. Da die Datenbank Beispieldaten enthält, wird die CUSTOMER_PHONE_NUMBER Umgebungsvariable anstelle von this.data.customerPhoneNumber. In einer realen Anwendung würde der this.data.customerPhoneNumber Wert verwendet werden.
   • Abonniert die sendSms() Funktion im acsService Dienst. Diese Funktion gibt eine RxJS-Observable zurück, die die Antwort des clientseitigen Diensts enthält.
   • Wenn die SMS-Nachricht erfolgreich gesendet wurde, legt sie die smsSent Eigenschaft auf true.

3. Öffnen Sie acs.service.ts , und suchen Sie die sendSms() Funktion. Der vollständige Pfad zur Datei ist 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)
       );
   }  
   

   Die sendSms() Funktion führt die folgenden Aufgaben aus:

   • Ruft die http.post() Funktion auf und übergibt die Nachricht und die Kundentelefonnummer an sie. Die http.post() Funktion gibt eine RxJS observable zurück, die die Antwort des API-Aufrufs enthält.
   • Behandelt alle fehler, die von der http.post() Funktion mithilfe des RxJS-Operators catchError zurückgegeben werden.

4. Abschließend untersuchen wir, wie die Anwendung mit dem ACS SMS-Feature interagiert. Öffnen Sie die datei acs.ts . Der vollständige Pfad zur Datei ist server/typescript/acs.ts und sucht die sendSms() Funktion.

5. Die sendSms() Funktion führt die folgenden Aufgaben aus:

   • Erstellt ein neues SmsClient Objekt und übergibt die ACS-Verbindungszeichenfolge an das Objekt (dieser Wert wird aus der ACS_CONNECTION_STRING Umgebungsvariable abgerufen).

     const smsClient = new SmsClient(connectionString);
     

   • Ruft die smsClient.send() Funktion auf und übergibt die ACS-Telefonnummer (from), die Kundentelefonnummer (to) und die SMS-Nachricht:

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

   • Gibt die Antwort auf den Aufrufer zurück.

6. Weitere Informationen zu ACS-E-Mail- und SMS-Funktionen finden Sie in den folgenden Artikeln:

   • E-Mail in Azure Communication Services
   • SMS in Azure Communication Services

7. Bevor wir mit der nächsten Übung fortfahren, sehen wir uns die wichtigsten Konzepte an, die in dieser Übung behandelt werden:

   • Die acs.service.ts Datei kapselt die ACS-E-Mail- und SMS-Funktionalität, die von der clientseitigen Anwendung verwendet wird. Er verarbeitet die API-Aufrufe an den Server und gibt die Antwort an den Aufrufer zurück.
   • Die serverseitige API verwendet acS EmailClient und SmsClient Objekte zum Senden von E-Mails und SMS-Nachrichten.

8. Nachdem Sie nun gelernt haben, wie E-Mail- und SMS-Nachrichten gesendet werden können, setzen wir unseren Fokus auf die Integration von Organisationsdaten in die Anwendung.

Organisationsdaten: Erstellen einer Microsoft Entra ID-App-Registrierung

• 59 Minuten verbleibend

Verbessern Sie die Benutzerproduktivität, indem Sie Organisationsdaten (E-Mails, Dateien, Chats und Kalenderereignisse) direkt in Ihre benutzerdefinierten Anwendungen integrieren. Mithilfe von Microsoft Graph-APIs und Microsoft Entra-ID können Sie relevante Daten in Ihren Apps nahtlos abrufen und anzeigen, wodurch die Notwendigkeit reduziert wird, dass Benutzer den Kontext wechseln müssen. Ganz gleich, ob sie auf eine E-Mail verweist, die an einen Kunden gesendet wird, eine Teams-Nachricht überprüfen oder auf eine Datei zugreifen, benutzer können schnell die benötigten Informationen finden, ohne Ihre App zu verlassen und ihren Entscheidungsprozess zu optimieren.

In dieser Übung führen Sie die folgenden Schritte aus:

• Erstellen Sie eine Microsoft Entra ID-App-Registrierung, damit Microsoft Graph auf Organisationsdaten zugreifen und sie in die App übertragen kann.
• Suchen team und channel IDs aus Microsoft Teams, die zum Senden von Chatnachrichten an einen bestimmten Kanal erforderlich sind.
• Aktualisieren Sie die env-Datei des Projekts mit Werten aus Ihrer Microsoft Entra ID-App-Registrierung.

Erstellen einer Microsoft Entra ID-App-Registrierung

1. Wechseln Sie zu Azure-Portal, und wählen Sie "Microsoft Entra-ID" aus.

2. Wählen Sie "Verwalten-> App-Registrierungen gefolgt von + Neue Registrierung" aus.

3. Füllen Sie die Details des neuen App-Registrierungsformulars aus, wie unten dargestellt, und wählen Sie "Registrieren" aus:

   • Name: microsoft-graph-app
   • Unterstützte Kontotypen: Konten in einem beliebigen Organisationsverzeichnis (Beliebiger Microsoft Entra ID-Mandant - Multitenant)
   • Umleitungs-URI:
     • Wählen Sie eine Einzelseitenanwendung (Single Page Application, SPA) aus, und geben Sie http://localhost:4200 das Feld "Umleitungs-URI" ein.
   • Wählen Sie Registrieren aus, um die App-Registrierung zu erstellen.

   

1. Wählen Sie im Ressourcenmenü die Option "Übersicht" aus, und kopieren Sie den Application (client) ID Wert in die Zwischenablage.

   

Aktualisieren der env-Datei des Projekts

1. Öffnen Sie die env-Datei in Ihrem Editor, und weisen Sie den Application (client) ID Wert zu ENTRAID_CLIENT_ID.

   ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
   

2. Wenn Sie die Möglichkeit zum Senden einer Nachricht aus der App in einen Teams-Kanal aktivieren möchten, melden Sie sich mit Ihrem Microsoft 365-Entwicklermandantenkonto bei Microsoft Teams an (dies wird in den Vorabfragen für das Lernprogramm erwähnt).

3. Nachdem Sie angemeldet sind, erweitern Sie ein Team, und suchen Sie einen Kanal, an den Sie Nachrichten von der App senden möchten. Sie können z. B. das Firmenteam und den Kanal "Allgemein " auswählen (oder das team/den Kanal, den Sie verwenden möchten).

   

4. Klicken Sie in der Teamkopfzeile auf die drei Punkte (...) und wählen Sie "Link zum Team abrufen" aus.

5. In dem Link, der im Popupfenster angezeigt wird, ist die Team-ID die Zeichenfolge von Buchstaben und Zahlen nach team/. Im Link "https://teams.microsoft.com/l/team/19%3ae9b9.../"ist die Team-ID beispielsweise 19%3ae9b9... bis zum folgenden / Zeichen.

6. Kopieren Sie die Team-ID, und weisen Sie sie in der env-Datei zuTEAM_ID.

7. Klicken Sie in der Kanalkopfzeile auf die drei Punkte (...) und wählen Sie "Link zum Kanal abrufen" aus.

8. In dem Link, der im Popupfenster angezeigt wird, ist die Kanal-ID die Zeichenfolge von Buchstaben und Zahlen nach channel/. Im Link "https://teams.microsoft.com/l/channel/19%3aQK02.../"ist die Kanal-ID beispielsweise 19%3aQK02... bis zum folgenden / Zeichen.

9. Kopieren Sie die Kanal-ID, und weisen Sie sie in der env-Datei zuCHANNEL_ID.

10. Speichern Sie die env-Datei , bevor Sie fortfahren.

Starten/Neustarten der Anwendungs- und API-Server

Führen Sie einen der folgenden Schritte basierend auf den Übungen aus, die Sie bis zu diesem Punkt abgeschlossen haben:

• Wenn Sie die Datenbank, den API-Server und den Webserver in einer früheren Übung gestartet haben, müssen Sie den API-Server und den Webserver beenden und neu starten, um die env-Dateiänderungen zu übernehmen. Sie können die Datenbank ausführen lassen.

  Suchen Sie die Terminalfenster, unter denen der API-Server und der Webserver ausgeführt werden, und drücken Sie STRG+C , um sie zu beenden. Starten Sie sie erneut, indem Sie in jedes Terminalfenster eingeben npm start und die EINGABETASTE drücken. Fahren Sie mit der nächsten Übung fort.

• Wenn Sie die Datenbank, den API-Server und den Webserver noch nicht gestartet haben, führen Sie die folgenden Schritte aus:

  1. In den folgenden Schritten erstellen Sie drei Terminalfenster in Visual Studio Code.

     

  2. Klicken Sie in der Visual Studio Code-Dateiliste mit der rechten Maustaste auf die env-Datei, und wählen Sie "Im integrierten Terminal öffnen" aus. Stellen Sie sicher, dass sich Ihr Terminal am Stamm des Projekts befindet - openai-acs-msgraph -, bevor Sie fortfahren.

  3. Wählen Sie eine der folgenden Optionen aus, um die PostgreSQL-Datenbank zu starten:

     • Wenn Docker Desktop installiert und ausgeführt wird, führen Sie sie im Terminalfenster ausdocker-compose up, und drücken Sie die EINGABETASTE.

     • Wenn Podman mit installierter und ausgeführter Podman-Erstellung ausgeführt wird, führen podman-compose up Sie sie im Terminalfenster aus, und drücken Sie die EINGABETASTE.

     • Um den PostgreSQL-Container direkt mit Docker Desktop, Podman, nerdctl oder einer anderen installierten Containerlaufzeit auszuführen, führen Sie den folgenden Befehl im Terminalfenster aus:

       • Mac, Linux oder Windows-Subsystem für 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 mit 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. Nachdem der Datenbankcontainer gestartet wurde, drücken Sie das + Symbol in der Symbolleiste des Visual Studio Code Terminal, um ein zweites Terminalfenster zu erstellen.

     

  5. cd in den Server-/Typescript-Ordner ein, und führen Sie die folgenden Befehle aus, um die Abhängigkeiten zu installieren und den API-Server zu starten.

     • npm install
     • npm start

  6. Drücken Sie erneut das + Symbol in der Visual Studio Code Terminal-Symbolleiste , um ein drittes Terminalfenster zu erstellen.

  7. cd in den Clientordner ein, und führen Sie die folgenden Befehle aus, um die Abhängigkeiten zu installieren und den Webserver zu starten.

     • npm install
     • npm start

  8. Ein Browser wird gestartet, und Sie werden zu http://localhost:4200.

     

Organisationsdaten: Anmelden eines Benutzers und Abrufen eines Zugriffstokens

• 51 Minuten verbleibend

Benutzer müssen sich mit der Microsoft Entra-ID authentifizieren, damit Microsoft Graph auf Organisationsdaten zugreifen kann. In dieser Übung erfahren Sie, wie die Komponente des Microsoft Graph-Toolkits mgt-login verwendet werden kann, um Benutzer zu authentifizieren und ein Zugriffstoken abzurufen. Das Zugriffstoken kann dann verwendet werden, um Aufrufe an Microsoft Graph zu tätigen.

In dieser Übung führen Sie die folgenden Schritte aus:

• Erfahren Sie, wie Sie eine Microsoft Entra-ID-App dem Microsoft Graph-Toolkit zuordnen, um Benutzer zu authentifizieren und Organisationsdaten abzurufen.
• Erfahren Sie mehr über die Bedeutung von Bereichen.
• Erfahren Sie, wie die mgt-login-Komponente des Microsoft Graph-Toolkits verwendet werden kann, um Benutzer zu authentifizieren und ein Zugriffstoken abzurufen.

Verwenden der Anmeldefunktion

1. In der vorherigen Übung haben Sie eine App-Registrierung in Microsoft Entra ID erstellt und den Anwendungsserver und den API-Server gestartet. Sie haben auch die folgenden Werte in der .env Datei aktualisiert (TEAM_ID und CHANNEL_ID sind optional):

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

   Stellen Sie sicher, dass Sie die vorherige Übung abgeschlossen haben, bevor Sie fortfahren.

2. Wechseln Sie zurück zum Browser (http://localhost:4200), wählen Sie "Anmelden in der Kopfzeile" aus, und melden Sie sich mit einem Administratorbenutzerkonto von Ihrem Microsoft 365-Entwicklermandanten an.

   Tipp

   Melden Sie sich mit Ihrem Microsoft 365-Entwicklermandantenadministratorkonto an. Sie können andere Benutzer in Ihrem Entwicklermandanten anzeigen, indem Sie zum Microsoft 365 Admin Center wechseln.

3. Wenn Sie sich zum ersten Mal bei der Anwendung anmelden, werden Sie aufgefordert, den von der Anwendung angeforderten Berechtigungen zuzustimmen. Sie erfahren mehr über diese Berechtigungen (auch als "Bereiche" bezeichnet) im nächsten Abschnitt, während Sie den Code erkunden. Wählen Sie Zustimmen aus, um fortzufahren.

4. Nachdem Sie angemeldet sind, sollte der Name des Benutzers angezeigt werden, der in der Kopfzeile angezeigt wird.

   

Erkunden des Anmeldecodes

Nachdem Sie sich angemeldet haben, sehen wir uns den Code an, mit dem sich der Benutzer anmelden und ein Zugriffstoken und Benutzerprofil abrufen kann. Sie erfahren mehr über die mgt-login-Webkomponente , die Teil des Microsoft Graph-Toolkits ist.

1. Öffnen Sie Client/package.json , und beachten Sie, dass die @microsoft/mgt Und-Pakete @microsoft/mgt-components in den Abhängigkeiten enthalten sind. Das @microsoft/mgt Paket enthält MSAL-Anbieterfeatures (Microsoft Authentication Library) und Webkomponenten wie mgt-login und andere, die zum Anmelden von Benutzern verwendet und Organisationsdaten abgerufen und angezeigt werden können.

2. Öffnen Sie client/src/main.ts , und beachten Sie die folgenden Importe aus dem @microsoft/mgt-components Paket. Die importierten Symbole werden verwendet, um die Microsoft Graph-Toolkit-Komponenten zu registrieren, die in der Anwendung verwendet werden.

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

3. Scrollen Sie zum Ende der Datei, und notieren Sie sich den folgenden Code:

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

   Dieser Code registriert die mgt-loginKomponenten mgt-search-resultsund Webkomponenten und mgt-person ermöglicht sie für die Verwendung in der Anwendung.

4. Um die mgt-login-Komponente zum Anmelden von Benutzern zu verwenden, muss auf die Client-ID der Microsoft Entra-ID (die in der env-Datei ENTRAID_CLIENT_IDgespeichert ist) verwiesen und verwendet werden.

5. Öffnen Sie graph.service.ts , und suchen Sie die init() Funktion. Der vollständige Pfad zur Datei ist client/src/app/core/graph.service.ts. Der folgende Import und Code werden angezeigt:

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

   Mit diesem Code wird ein neues Msal2Provider Objekt erstellt, das die Microsoft Entra ID-Client-ID aus ihrer App-Registrierung übergibt und für scopes die die App Zugriff anfordert. Sie scopes werden verwendet, um den Zugriff auf Microsoft Graph-Ressourcen anzufordern, auf die die App zugreifen wird. Nachdem das Msal2Provider Objekt erstellt wurde, wird es dem Providers.globalProvider Objekt zugewiesen, das von Microsoft Graph-Toolkit-Komponenten zum Abrufen von Daten aus Microsoft Graph verwendet wird.

6. Öffnen Sie header.component.html in Ihrem Editor, und suchen Sie die mgt-login-Komponente . Der vollständige Pfad zur Datei ist client/src/app/header/header.component.html.

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

   Die mgt-Login-Komponente ermöglicht die Benutzeranmeldung und bietet Zugriff auf ein Token, das mit Microsoft Graph verwendet wird. Bei erfolgreicher Anmeldung wird das loginCompleted Ereignis ausgelöst, das die loginCompleted() Funktion aufruft. Obwohl mgt-login in einer Angular-Komponente in diesem Beispiel verwendet wird, ist sie mit jeder Beliebigen Webanwendung kompatibel.

   Die Anzeige der mgt-login-Komponente hängt von dem Wert ab, auf trueden featureFlags.microsoft365Enabled festgelegt wird. Mit diesem benutzerdefinierten Flag wird überprüft, ob die ENTRAID_CLIENT_ID Umgebungsvariable vorhanden ist, um zu bestätigen, dass die Anwendung ordnungsgemäß konfiguriert ist und sich bei Microsoft Entra-ID authentifizieren kann. Die Kennzeichnung wird hinzugefügt, um Fälle zu berücksichtigen, in denen Benutzer nur die KI- oder Kommunikationsübungen innerhalb des Lernprogramms durchführen möchten, anstatt die gesamte Abfolge der Übungen zu verfolgen.

7. Öffnen Sie header.component.ts , und suchen Sie die loginCompleted Funktion. Diese Funktion wird aufgerufen, wenn das loginCompleted Ereignis ausgegeben wird und das Abrufen des Profils des angemeldeten Benutzers mithilfe Providers.globalProvidervon .

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

   In diesem Beispiel wird ein Aufruf der Microsoft Graph-API me ausgeführt, um das Profil des Benutzers abzurufen (me stellt den aktuellen angemeldeten Benutzer dar). Die this.userLoggedIn.emit(me) Code-Anweisung gibt ein Ereignis aus der Komponente aus, um die Profildaten an die übergeordnete Komponente zu übergeben. Die übergeordnete Komponente ist in diesem Fall app.component.ts Datei, die die Stammkomponente für die Anwendung ist.

   Weitere Informationen zur mgt-login-Komponente finden Sie in der Dokumentation zum Microsoft Graph-Toolkit .

8. Nachdem Sie sich nun bei der Anwendung angemeldet haben, sehen wir uns an, wie Organisationsdaten abgerufen werden können.

Organisationsdaten: Abrufen von Dateien, Chats und Senden von Nachrichten an Teams

• 41 Minuten verbleibend

In der heutigen digitalen Umgebung arbeiten Benutzer mit einer vielzahl von Organisationsdaten, einschließlich E-Mails, Chats, Dateien, Kalenderereignissen und mehr. Dies kann zu häufigen Kontextverschiebungen führen , die zwischen Aufgaben oder Anwendungen wechseln, wodurch der Fokus unterbrochen und die Produktivität reduziert werden kann. Beispielsweise muss ein Benutzer, der an einem Projekt arbeitet, von seiner aktuellen Anwendung zu Outlook wechseln, um wichtige Details in einer E-Mail zu finden oder zu OneDrive for Business zu wechseln, um eine verwandte Datei zu finden. Diese Back-and-Forth-Aktion stört den Fokus und verschwendet Zeit, die besser für die Aufgabe aufgewendet werden könnte.

Um die Effizienz zu steigern, können Sie Organisationsdaten direkt in die Anwendungen integrieren, die benutzer täglich verwenden. Durch die Bereitstellung von Organisationsdaten in Ihre Anwendungen können Benutzer nahtloser auf Informationen zugreifen und diese verwalten, wodurch Kontextverschiebungen minimiert und die Produktivität verbessert werden. Darüber hinaus bietet diese Integration wertvolle Einblicke und Kontext, sodass Benutzer fundierte Entscheidungen treffen und effektiver arbeiten können.

In dieser Übung führen Sie die folgenden Schritte aus:

• Erfahren Sie, wie die mgt-search-results-Webkomponente im Microsoft Graph-Toolkit verwendet werden kann, um nach Dateien zu suchen.
• Erfahren Sie, wie Sie Microsoft Graph direkt aufrufen, um Dateien aus OneDrive for Business und Chatnachrichten aus Microsoft Teams abzurufen.
• Verstehen, wie Chatnachrichten mithilfe von Microsoft Graph an Microsoft Teams-Kanäle gesendet werden.

Verwenden des Features "Organisationsdaten"

1. In einer vorherigen Übung haben Sie eine App-Registrierung in Microsoft Entra ID erstellt und den Anwendungsserver und den API-Server gestartet. Außerdem haben Sie die folgenden Werte in der .env Datei aktualisiert.

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

   Stellen Sie sicher, dass Sie die vorherige Übung abgeschlossen haben, bevor Sie fortfahren.

2. Wechseln Sie zurück zum Browser (http://localhost:4200). Wenn Sie noch nicht angemeldet sind, wählen Sie "Anmelden" in der Kopfzeile aus, und melden Sie sich mit einem Benutzer aus Ihrem Microsoft 365-Entwicklermandanten an.

   Hinweis

   Zusätzlich zur Authentifizierung des Benutzers ruft die mgt-login-Webkomponente auch ein Zugriffstoken ab, das von Microsoft Graph für den Zugriff auf Dateien, Chats, E-Mails, Kalenderereignisse und andere Organisationsdaten verwendet werden kann. Das Zugriffstoken enthält die Bereiche (Berechtigungen) wie Chat.ReadWrite, Files.Read.Allund andere, die Sie zuvor gesehen haben:

   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. Wählen Sie "Verwandte Inhalte anzeigen" für die Zeile "Adatum Corporation " im Datagrid aus. Dies führt dazu, dass Organisationsdaten wie Dateien, Chats, E-Mails und Kalenderereignisse mithilfe von Microsoft Graph abgerufen werden. Sobald die Daten geladen wurden, wird sie unterhalb des Datengrids in einer Benutzeroberfläche mit Registerkarten angezeigt. Es ist wichtig zu erwähnen, dass an diesem Punkt möglicherweise keine Daten angezeigt werden, da Sie noch keine Dateien, Chats, E-Mails oder Kalenderereignisse für den Benutzer in Ihrem Microsoft 365-Entwicklermandanten hinzugefügt haben. Lassen Sie uns dies im nächsten Schritt beheben.

   

4. Ihr Microsoft 365-Mandant hat möglicherweise zu diesem Zeitpunkt keine zugehörigen Organisationsdaten für die Adatum Corporation . Führen Sie zum Hinzufügen einiger Beispieldaten mindestens eine der folgenden Aktionen aus:

   • Fügen Sie Dateien hinzu, indem Sie Ihre Microsoft 365 Developer-Mandantenanmeldeinformationen besuchen https://onedrive.com und sich anmelden.

     • Wählen Sie "Meine Dateien " im linken Navigationsbereich aus.
     • Wählen Sie +Neu hinzufügen und dann ordnerupload aus dem Menü aus.
     • Wählen Sie den Ordner "openai-acs-msgraph/customer documents " aus dem Projekt aus, das Sie geklont haben.

     

   • Fügen Sie Chatnachrichten und Kalenderereignisse hinzu, indem Sie Ihre Microsoft 365 Developer-Mandantenanmeldeinformationen besuchen https://teams.microsoft.com und sich anmelden.

     • Wählen Sie Teams in der linken Navigationsleiste aus.

     • Wählen Sie ein Team und einen Kanal aus.

     • Wählen Sie "Beitrag starten" aus.

     • Geben Sie neue Bestellung für die Adatum Corporation für den Betreff und alle zusätzlichen Texte ein, die Sie im Nachrichtentext hinzufügen möchten. Wählen Sie die Schaltfläche Buchen aus.

       Sie können zusätzliche Chatnachrichten hinzufügen, die andere in der Anwendung verwendete Unternehmen erwähnen, z . B. Adventure Works Cycles, Contoso Pharmaceuticals und Tailwind Traders.

       

     • Wählen Sie im linken Navigationsbereich "Kalender" aus.

     • Wählen Sie "Neue Besprechung" aus.

     • Geben Sie "Meet with Adatum Corporation about project schedule" für den Titel und den Textkörper ein.

     • Wählen Sie Speichern.

       

   • Fügen Sie E-Mails hinzu, indem Sie ihre Microsoft 365 Developer-Mandantenanmeldeinformationen besuchen https://outlook.com und sich anmelden.

     • Wählen Sie "Neue E-Mail" aus.

     • Geben Sie Ihre persönliche E-Mail-Adresse in das Feld "An " ein.

     • Geben Sie neue Bestellung für die Adatum Corporation für den Betreff und alles ein, was Sie für den Textkörper wünschen.

     • Wählen Sie Send (Senden) aus.

       

5. Wechseln Sie zurück zur Anwendung im Browser, und aktualisieren Sie die Seite. Wählen Sie "Verwandte Inhalte erneut anzeigen" für die Zeile "Adatum Corporation " aus. Nun sollten daten angezeigt werden, die auf den Registerkarten angezeigt werden, je nachdem, welche Aufgaben Sie im vorherigen Schritt ausgeführt haben.

6. Sehen wir uns den Code an, der das Feature für Organisationsdaten in der Anwendung ermöglicht. Um die Daten abzurufen, verwendet der clientseitige Teil der Anwendung das Zugriffstoken, das von der mgt-Login-Komponente abgerufen wurde, die Sie zuvor angesehen haben, um Aufrufe an Microsoft Graph-APIs auszuführen.

Durchsuchen des Dateisuchcodes

1. Sehen wir uns zunächst an, wie Dateidaten aus OneDrive for Business abgerufen werden. Öffnen Sie files.component.html , und nehmen Sie sich einen Moment Zeit, um den Code zu durchsuchen. Der vollständige Pfad zur Datei ist client/src/app/files/files.component.html.

2. Suchen Sie die mgt-search-results-Komponente , und notieren Sie sich die folgenden Attribute:

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

   Die Mgt-Search-Results-Komponente ist Teil des Microsoft Graph-Toolkits, und wie der Name schon sagt, wird sie verwendet, um Suchergebnisse aus Microsoft Graph anzuzeigen. Die Komponente verwendet die folgenden Features in diesem Beispiel:

   • Das class Attribut wird verwendet, um anzugeben, dass die search-results CSS-Klasse auf die Komponente angewendet werden soll.

   • Das entity-types Attribut wird verwendet, um den Datentyp anzugeben, nach dem gesucht werden soll. In diesem Fall wird driveItem der Wert verwendet, um nach Dateien in OneDrive for Business zu suchen.

   • Das queryString Attribut wird verwendet, um den Suchbegriff anzugeben. In diesem Fall ist der Wert an die searchText Eigenschaft gebunden, die an die Dateikomponente übergeben wird, wenn der Benutzer "Verwandte Inhalte anzeigen" für eine Zeile im Datagrid auswählt. Die eckigen Klammern queryString geben an, dass die Eigenschaft an den searchText Wert gebunden ist.

   • Das dataChange Ereignis wird ausgelöst, wenn sich die Suchergebnisse ändern. In diesem Fall wird eine benannte dataChange() Kundenfunktion in der Dateikomponente aufgerufen, und die Ereignisdaten werden an die Funktion übergeben. Die Klammer dataChange zeigt an, dass das Ereignis an die dataChange() Funktion gebunden ist.

   • Da keine benutzerdefinierte Vorlage bereitgestellt wird, wird die integrierte mgt-search-results Standardvorlage verwendet, um die Suchergebnisse anzuzeigen.

     

3. Eine Alternative zur Verwendung von Komponenten wie mgt-search-results besteht darin, Microsoft Graph-APIs direkt mithilfe von Code aufzurufen. Um zu sehen, wie das funktioniert, öffnen Sie die graph.service.ts Datei, und suchen Sie die searchFiles() Funktion. Der vollständige Pfad zur Datei ist client/src/app/core/graph.service.ts.

   • Sie werden feststellen, dass ein query Parameter an die Funktion übergeben wird. Dies ist der Suchbegriff, der übergeben wird, wenn der Benutzer "Verwandte Inhalte anzeigen" für eine Zeile im Datagrid auswählt. Wenn kein Suchbegriff übergeben wird, wird ein leeres Array zurückgegeben.

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

   • Anschließend wird ein Filter erstellt, der den auszuführenden Suchtyp definiert. In diesem Fall sucht der Code nach Dateien in OneDrive for Business, sodass driveItem er genauso verwendet wird wie zuvor mit der mgt-search-results Komponente. Dies ist identisch mit der Übergabe driveItem an entity-types die mgt-search-results-Komponente , die Sie zuvor gesehen haben. Der query Parameter wird dann zusammen mit ContentType:Documentdem queryString Filter hinzugefügt.

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

   • Anschließend wird mithilfe der Funktion ein Aufruf an die /search/query Providers.globalProvider.graph.client.api() Microsoft Graph-API ausgeführt. Das filter Objekt wird an die post() Funktion übergeben, die die Daten an die API sendet.

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

   • Die Suchergebnisse werden dann durchlaufen, um sie zu suchen hits. Jede hit enthält Informationen zu einem Dokument, das gefunden wurde. Eine benannte resource Eigenschaft enthält die Dokumentmetadaten und wird dem files Array hinzugefügt.

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

   • Das files Array wird dann an den Aufrufer zurückgegeben.

     return files;
     

4. Wenn Sie diesen Code durchsehen, können Sie sehen, dass die zuvor untersuchte mgt-search-results-Webkomponente viel Arbeit für Sie erledigt und die Menge an Code, den Sie schreiben müssen, erheblich reduziert! Es kann jedoch Szenarien geben, in denen Sie Microsoft Graph direkt aufrufen möchten, um mehr Kontrolle über die Daten zu haben, die an die API gesendet werden oder wie die Ergebnisse verarbeitet werden.

5. Öffnen Sie die files.component.ts Datei, und suchen Sie die search() Funktion. Der vollständige Pfad zur Datei ist client/src/app/files/files.component.ts.

   Obwohl der Textkörper dieser Funktion aufgrund der verwendeten mgt-search-results-Komponente auskommentiert wird, kann die Funktion verwendet werden, um den Aufruf von Microsoft Graph auszuführen, wenn der Benutzer "Verwandte Inhalte anzeigen" für eine Zeile im Datagrid auswählt. Die search() Funktion ruft searchFiles() in graph.service.ts auf und übergibt den query Parameter an ihn (den Namen des Unternehmens in diesem Beispiel). Die Ergebnisse der Suche werden dann der data Eigenschaft der Komponente zugewiesen.

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

   Die Dateikomponente kann dann die data Eigenschaft verwenden, um die Suchergebnisse anzuzeigen. Sie können dies mit benutzerdefinierten HTML-Bindungen oder mithilfe eines anderen Microsoft Graph-Toolkit-Steuerelements namens mgt-file-listbehandeln. Hier sehen Sie ein Beispiel für die Bindung der data Eigenschaft an eine der Eigenschaften der Komponente, die benannt files sind und das itemClick Ereignis behandeln, während der Benutzer mit einer Datei interagiert.

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

6. Unabhängig davon, ob Sie die zuvor gezeigte mgt-search-results-Komponente verwenden oder benutzerdefinierten Code schreiben, um Microsoft Graph aufzurufen, hängt von Ihrem jeweiligen Szenario ab. In diesem Beispiel wird die mgt-search-results-Komponente verwendet, um den Code zu vereinfachen und die Menge an Arbeit zu verringern, die Sie erledigen müssen.

Erkunden des Suchcodes für Teams-Chatnachrichten

1. Wechseln Sie zurück zu graph.service.ts , und suchen Sie die searchChatMessages() Funktion. Sie werden sehen, dass es der Funktion ähnelt, die searchFiles() Sie zuvor angesehen haben.

   • Es veröffentlicht Filterdaten in die MICROSOFT Graph-API /search/query und konvertiert die Ergebnisse in ein Array von Objekten, die Informationen zu dem teamId, channelIdund messageId die dem Suchbegriff entsprechen.
   • Um die Teams-Kanalnachrichten abzurufen, wird ein zweiter Aufruf an die /teams/${chat.teamId}/channels/${chat.channelId}/messages/${chat.messageId} API und die teamId, channelIdund messageId werden übergeben. Dadurch werden die vollständigen Nachrichtendetails zurückgegeben.
   • Zusätzliche Filteraufgaben werden ausgeführt, und die resultierenden Nachrichten werden an searchChatMessages() den Aufrufer zurückgegeben.

2. Öffnen Sie die datei chats.component.ts , und suchen Sie die search() Funktion. Der vollständige Pfad zur Datei ist client/src/app/chats/chats.component.ts. Die search() Funktion ruft searchChatMessages() in graph.service.ts auf und übergibt den query Parameter an ihn.

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

   Die Ergebnisse der Suche werden der data Eigenschaft der Komponente zugewiesen, und die Datenbindung wird verwendet, um das Ergebnisarray zu durchlaufen und die Daten zu rendern. In diesem Beispiel wird eine Angular Material-Kartenkomponente zum Anzeigen der Suchergebnisse verwendet.

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

   

Senden einer Nachricht an einen Microsoft Teams-Kanal

1. Zusätzlich zur Suche nach Microsoft Teams-Chatnachrichten ermöglicht die Anwendung einem Benutzer auch das Senden von Nachrichten an einen Microsoft Teams-Kanal. Dies kann durch Aufrufen des /teams/${teamId}/channels/${channelId}/messages Endpunkts von Microsoft Graph erfolgen.

   

2. Im folgenden Code sehen Sie, dass eine URL erstellt wird, die die teamId Werte enthält channelId . Umgebungsvariablenwerte werden für die Team-ID und Kanal-ID in diesem Beispiel verwendet, aber diese Werte können dynamisch mit Microsoft Graph abgerufen werden. Die body Konstante enthält die zu sendende Nachricht. Anschließend erfolgt eine POST-Anforderung, und die Ergebnisse werden an den Aufrufer zurückgegeben.

   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. Die Nutzung dieser Art von Funktionalität in Microsoft Graph bietet eine hervorragende Möglichkeit, die Benutzerproduktivität zu verbessern, indem sie es Benutzern ermöglichen, direkt über die Anwendung, die sie bereits verwenden, mit Microsoft Teams zu interagieren.

Organisationsdaten: Abrufen von E-Mails und Kalenderereignissen

• 21 Minuten verbleibend

In der vorherigen Übung haben Sie gelernt, wie Sie Dateien aus OneDrive for Business und Chats aus Microsoft Teams mithilfe von Microsoft Graph und der mgt-Search-Results-Komponente aus dem Microsoft Graph-Toolkit abrufen. Außerdem haben Sie erfahren, wie Sie Nachrichten an Microsoft Teams-Kanäle senden. In dieser Übung erfahren Sie, wie Sie E-Mail-Nachrichten und Kalenderereignisse aus Microsoft Graph abrufen und in die Anwendung integrieren.

In dieser Übung führen Sie die folgenden Schritte aus:

• Erfahren Sie, wie die mgt-search-results-Webkomponente im Microsoft Graph-Toolkit verwendet werden kann, um nach E-Mails und Kalenderereignissen zu suchen.
• Erfahren Sie, wie Sie die mgt-search-results-Komponente so anpassen, dass Suchergebnisse auf benutzerdefinierte Weise gerendert werden.
• Erfahren Sie, wie Sie Microsoft Graph direkt aufrufen, um E-Mails und Kalenderereignisse abzurufen.

Untersuchen des Suchcodes für E-Mail-Nachrichten

1. In einer vorherigen Übung haben Sie eine App-Registrierung in Microsoft Entra ID erstellt und den Anwendungsserver und den API-Server gestartet. Außerdem haben Sie die folgenden Werte in der .env Datei aktualisiert.

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

   Stellen Sie sicher, dass Sie die vorherige Übung abgeschlossen haben, bevor Sie fortfahren.

2. Öffnen Sie emails.component.html , und nehmen Sie sich einen Moment Zeit, um den Code zu durchsuchen. Der vollständige Pfad zur Datei ist client/src/app/emails/emails.component.html.

3. Suchen Sie die mgt-search-results-Komponente :

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

   Dieses Beispiel der mgt-search-results-Komponente ist auf die gleiche Weise konfiguriert wie die zuvor betrachtete Komponente. Der einzige Unterschied besteht darin, dass das entity-types Attribut festgelegt ist, auf message das zum Suchen nach E-Mail-Nachrichten und einer leeren Vorlage verwendet wird.

   • Das class Attribut wird verwendet, um anzugeben, dass die search-results CSS-Klasse auf die Komponente angewendet werden soll.
   • Das entity-types Attribut wird verwendet, um den Datentyp anzugeben, nach dem gesucht werden soll. In diesem Fall handelt es sich um den Wert message.
   • Das queryString Attribut wird verwendet, um den Suchbegriff anzugeben.
   • Das dataChange Ereignis wird ausgelöst, wenn sich die Suchergebnisse ändern. Die Funktion der dataChange() E-Mail-Komponente wird aufgerufen, die Ergebnisse werden an sie übergeben, und eine benannte Eigenschaft data wird in der Komponente aktualisiert.
   • Für die Komponente wird eine leere Vorlage definiert. Diese Art von Vorlage wird normalerweise verwendet, um zu definieren, wie die Suchergebnisse gerendert werden. In diesem Szenario wird der Komponente jedoch mitgeteilt, dass keine Nachrichtendaten gerendert werden. Stattdessen rendern wir die Daten selbst mithilfe von Standarddatenbindung (Angular wird in diesem Fall verwendet, aber Sie können jedes gewünschte Bibliotheks-/Framework verwenden).

4. Sehen Sie sich die mgt-search-results-Komponente in emails.component.html an, um die Datenbindungen zu finden, die zum Rendern der E-Mail-Nachrichten verwendet werden. In diesem Beispiel werden die data Eigenschaft durchlaufen und der E-Mail-Betreff, der Textkörpervorschau und ein Link zum Anzeigen der vollständigen E-Mail-Nachricht ausgegeben.

   @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. Zusätzlich zur Verwendung der mgt-search-results-Komponente zum Abrufen von Nachrichten stellt Microsoft Graph mehrere APIs bereit, die auch zum Durchsuchen von E-Mails verwendet werden können. Die /search/query API, die Sie zuvor gesehen haben, könnte sicherlich verwendet werden, aber eine einfachere Option ist die messages API.

6. Um zu erfahren, wie Sie diese API aufrufen, wechseln Sie zurück zu graph.service.ts und suchen Sie die searchEmailMessages() Funktion. Sie erstellt eine URL, die zum Aufrufen des messages Endpunkts von Microsoft Graph verwendet werden kann, und weist dem Parameter den query $search Wert zu. Der Code sendet dann eine GET-Anforderung und gibt die Ergebnisse an den Aufrufer zurück. Der $search Operator sucht automatisch nach dem query Wert im Betreff-, Text- und Absenderfeld.

   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. Die E-Mail-Komponente in emails.component.ts Aufrufen searchEmailMessages() und zeigt die Ergebnisse in der Benutzeroberfläche an.

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

Durchsuchen des Suchcodes für Kalenderereignisse

1. Die Suche nach Kalenderereignissen kann auch mithilfe der mgt-search-results-Komponente durchgeführt werden. Es kann das Rendern der Ergebnisse für Sie behandeln, Aber Sie können auch Ihre eigene Vorlage definieren, die Sie später in dieser Übung sehen werden.

2. Öffnen Sie calendar-events.component.html , und nehmen Sie sich einen Moment Zeit, um den Code zu durchsuchen. Der vollständige Pfad zur Datei ist client/src/app/calendar-events/calendar-events.component.html. Sie werden sehen, dass die Dateien und E-Mail-Komponenten, die Sie zuvor angesehen haben, sehr ähnlich sind.

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

   Dieses Beispiel der mgt-search-results-Komponente ist auf die gleiche Weise konfiguriert wie die, die Sie zuvor angesehen haben. Der einzige Unterschied besteht darin, dass das entity-types Attribut festgelegt ist, auf event das zum Suchen nach Kalenderereignissen und einer leeren Vorlage verwendet wird.

   • Das class Attribut wird verwendet, um anzugeben, dass die search-results CSS-Klasse auf die Komponente angewendet werden soll.
   • Das entity-types Attribut wird verwendet, um den Datentyp anzugeben, nach dem gesucht werden soll. In diesem Fall handelt es sich um den Wert event.
   • Das queryString Attribut wird verwendet, um den Suchbegriff anzugeben.
   • Das dataChange Ereignis wird ausgelöst, wenn sich die Suchergebnisse ändern. Die Funktion der dataChange() Kalenderereigniskomponente wird aufgerufen, die Ergebnisse werden an sie übergeben, und eine benannte data Eigenschaft wird in der Komponente aktualisiert.
   • Für die Komponente wird eine leere Vorlage definiert. In diesem Szenario wird der Komponente mitgeteilt, dass keine Daten gerendert werden. Stattdessen rendern wir die Daten selbst mithilfe einer Standarddatenbindung.

3. Unmittelbar unterhalb der mgt-search-results Komponente in calendar-events.component.html finden Sie die Datenbindungen, die zum Rendern der Kalenderereignisse verwendet werden. In diesem Beispiel werden die data Eigenschaft durchlaufen und das Startdatum, die Uhrzeit und der Betreff des Ereignisses herausgeschrieben. Benutzerdefinierte Funktionen, die in der Komponente enthalten sind, z dayFromDateTime() . B. und timeRangeFromEvent() werden aufgerufen, um Daten ordnungsgemäß zu formatieren. Die HTML-Bindungen enthalten auch einen Link zum Anzeigen des Kalenderereignisses in Outlook und den Ort des Ereignisses, wenn eine angegeben ist.

   @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. Zusätzlich zur Suche nach Kalenderereignissen mithilfe der search/query API stellt Microsoft Graph auch eine events API bereit, die auch zum Durchsuchen von Kalenderereignissen verwendet werden kann. Suchen Sie die searchCalendarEvents() Funktion in graph.service.ts.

5. Die searchCalendarEvents() Funktion erstellt Start- und Enddatums-/Uhrzeitwerte, die zum Definieren des zu durchsuchenden Zeitraums verwendet werden. Anschließend wird eine URL erstellt, die zum Aufrufen des events Endpunkts von Microsoft Graph verwendet werden kann und die query Parameter sowie Start- und Enddatums-/Enddatumsvariablen enthält. Anschließend erfolgt eine GET-Anforderung, und die Ergebnisse werden an den Aufrufer zurückgegeben.

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

   • Hier ist eine Aufschlüsselung der URL, die erstellt wird:

     • Der /me/events Teil der URL wird verwendet, um anzugeben, dass die Ereignisse des angemeldeten Benutzers abgerufen werden sollen.
     • Die startdatetime Parameter werden enddatetime verwendet, um den zu durchsuchenden Zeitraum zu definieren. In diesem Fall gibt die Suche Ereignisse zurück, die innerhalb der nächsten 7 Tage beginnen.
     • Der $filter Abfrageparameter wird verwendet, um die Ergebnisse nach dem query Wert zu filtern (der im Datagrid in diesem Fall ausgewählte Firmenname). Die contains() Funktion wird verwendet, um nach dem query Wert in der subject Eigenschaft des Kalenderereignisses zu suchen.
     • Der $orderby Abfrageparameter wird verwendet, um die Ergebnisse nach der start/dateTime Eigenschaft zu sortieren.

   Nachdem die url Anforderung erstellt wurde, wird eine GET-Anforderung an die Microsoft Graph-API mit dem Wert url gesendet, und die Ergebnisse werden an den Aufrufer zurückgegeben.

6. Wie bei den vorherigen Komponenten ruft search() die Kalenderereignissekomponente (calendar-events.component.ts Datei) die Ergebnisse auf und zeigt sie an.

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

   Hinweis

   Sie können Auch Microsoft Graph-Aufrufe aus einer benutzerdefinierten API oder serverseitigen Anwendung ausführen. Sehen Sie sich das folgende Lernprogramm an, um ein Beispiel für den Aufruf einer Microsoft Graph-API aus einer Azure-Funktion anzuzeigen.

7. Sie haben nun ein Beispiel für die Verwendung von Microsoft Graph zum Abrufen von Dateien, Chats, E-Mail-Nachrichten und Kalenderereignissen gesehen. Dieselben Konzepte können auch auf andere Microsoft Graph-APIs angewendet werden. Sie können beispielsweise die Microsoft Graph-Benutzer-API verwenden, um nach Benutzern in Ihrer Organisation zu suchen. Sie können auch die Microsoft Graph-Gruppen-API verwenden, um nach Gruppen in Ihrer Organisation zu suchen. Sie können die vollständige Liste der Microsoft Graph-APIs in der Dokumentation anzeigen.

Herzlichen Glückwunsch!

• 100 % abgeschlossen!

Sie haben dieses Lernprogramm abgeschlossen.

Herzlichen Glückwunsch! In diesem Lernprogramm haben Sie folgendes gelernt:

• Azure OpenAI kann verwendet werden, um die Produktivität der Benutzer zu verbessern.
• Azure Communication Services kann verwendet werden, um Kommunikationsfunktionen zu integrieren.
• Microsoft Graph-APIs und -Komponenten können zum Abrufen und Anzeigen von Organisationsdaten verwendet werden.

Mithilfe dieser Technologien können Sie effektive Lösungen erstellen, die die Benutzerproduktivität steigern, indem Sie Kontextverschiebungen minimieren und notwendige Entscheidungsfindungsinformationen bereitstellen.

Bereinigen von Azure-Ressourcen

Bereinigen Sie Ihre Azure-Ressourcen, um mehr Gebühren für Ihr Konto zu vermeiden. Wechseln Sie zum Azure-Portal, und löschen Sie die folgenden Ressourcen:

• Azure KI Search-Ressource
• Azure Storage-Ressource
• Azure OpenAI-Ressource (stellen Sie sicher, dass Sie Ihre Modelle zuerst und dann die Azure OpenAI-Ressource löschen)
• Azure Communication Services-Ressource

Nächste Schritte

Dokumentation

• Azure OpenAI-Dokumentation
• Azure OpenAI Service on your data
• Dokumentation zu Azure Communication Services
• Microsoft Graph-Dokumentation
• Dokumentation zum Microsoft Graph-Toolkit
• Microsoft Teams-Entwicklerdokumentation

Schulungsinhalte

• Anwenden von Prompt Engineering mit Azure OpenAI Service
• Erste Schritte mit Azure OpenAI Service
• Einführung in Azure Communication Services
• Grundlagen zu Microsoft Graph
• Videokurs: Grundlagen zu Microsoft Graph für Anfänger
• Erkunden von Microsoft Graph-Szenarien für die JavaScript-Entwicklung
• Erkunden von Microsoft Graph-Szenarien für ASP.NET Core-Entwicklung
• Erste Schritte mit dem Microsoft Graph-Toolkit
• Erstellen und Bereitstellen von Apps für Microsoft Teams mithilfe des Teams-Toolkits für Visual Studio Code