Integrowanie funkcji openAI, komunikacji i danych organizacyjnych z aplikacją biznesową

Artykuł
Developer (Średni)
Czas do ukończenia: 136 min

Poziom: Pośredni

W tym samouczku pokazano, jak można zintegrować aplikacje Azure OpenAI, Azure Communication Services i Microsoft Graph/Microsoft Graph Toolkit z aplikacją biznesową (LOB), aby zwiększyć produktywność użytkowników, podnieść poziom środowiska użytkownika i przejść do następnego poziomu aplikacji biznesowych. Najważniejsze funkcje w aplikacji obejmują:

Sztuczna inteligencja: umożliwia użytkownikom zadawanie pytań w języku naturalnym i konwertowanie odpowiedzi na język SQL, które mogą służyć do wykonywania zapytań w bazie danych, umożliwiają użytkownikom definiowanie reguł, które mogą służyć do automatycznego generowania wiadomości e-mail i wiadomości SMS, oraz dowiedz się, jak można używać języka naturalnego do pobierania danych z własnych niestandardowych źródeł danych. Usługa Azure OpenAI jest używana dla tych funkcji.
Komunikacja: włączanie połączeń telefonicznych w aplikacji dla klientów i funkcji poczty e-mail/wiadomości SMS przy użyciu usług Azure Communication Services.
Dane organizacyjne: ściągaj powiązane dane organizacyjne, których użytkownicy mogą potrzebować (dokumentów, czatów, wiadomości e-mail, wydarzeń kalendarza) podczas pracy z klientami, aby uniknąć przełączania kontekstu. Zapewnienie dostępu do tego typu danych organizacji zmniejsza potrzebę przełączenia się użytkownika do aplikacji Outlook, Teams, OneDrive, innych aplikacji niestandardowych, telefonu itp., ponieważ określone potrzebne dane i funkcje są udostępniane bezpośrednio w aplikacji. W przypadku tej funkcji są używane programy Microsoft Graph i Microsoft Graph Toolkit.

Aplikacja to prosta aplikacja do zarządzania klientami, która umożliwia użytkownikom zarządzanie klientami i powiązanymi danymi. Składa się z frontonu utworzonego przy użyciu języka TypeScript, który wywołuje interfejsy API zaplecza w celu pobierania danych, interakcji z funkcją sztucznej inteligencji, wysyłania wiadomości e-mail/wiadomości SMS i ściągania danych organizacyjnych. Poniżej przedstawiono omówienie rozwiązania aplikacji, które omówisz w tym samouczku:

Omówienie scenariusza chmury firmy Microsoft

Ten samouczek przeprowadzi Cię przez proces konfigurowania wymaganych zasobów platformy Azure i platformy Microsoft 365. Omówi on również kod używany do implementowania funkcji sztucznej inteligencji, komunikacji i danych organizacji. Chociaż nie będzie konieczne kopiowanie i wklejanie kodu, niektóre ćwiczenia będą miały modyfikację kodu w celu wypróbowania różnych scenariuszy.

Co utworzysz w tym samouczku

Wybierz własną przygodę

Cały samouczek można ukończyć od początku do końca lub ukończyć określone tematy. Samouczek jest podzielony na następujące tematy:

Sklonuj ćwiczenie projektu (wymagane ćwiczenie).
Ćwiczenia dotyczące sztucznej inteligencji: utwórz zasób usługi Azure OpenAI i użyj go do konwertowania języka naturalnego na język SQL, generowania wiadomości e-mail/wiadomości SMS oraz pracy z własnymi danymi i dokumentami.
Ćwiczenia komunikacyjne: utwórz zasób usług Azure Communication Services i użyj go do nawiązywania połączeń telefonicznych z aplikacji i wysyłania wiadomości e-mail/SMS.
Ćwiczenia dotyczące danych organizacyjnych: utwórz rejestrację aplikacji Microsoft Entra ID, dzięki czemu program Microsoft Graph i zestaw narzędzi Microsoft Graph mogą służyć do uwierzytelniania i ściągania danych organizacji do aplikacji.

Wybierz własną przygodę. Ukończ cały samouczek lub wybierz określone obszary tematu.

Wymagania wstępne

Węzeł — węzły 20+ i npm 10+ będą używane dla tego projektu
git
Visual Studio Code (chociaż program Visual Studio Code jest zalecany, można użyć dowolnego edytora)
Subskrypcja platformy Azure
Dzierżawa deweloperów platformy Microsoft 365
Docker Desktop lub inny zgodny ze środowiskiem uruchomieniowym kontenera OCI (Open Container Initiative), takim jak Podman lub nerdctl , może uruchomić kontener.

Technologie w chmurze firmy Microsoft używane w tym samouczku

Azure Communication Services
Azure OpenAI Service
Microsoft Entra ID
Microsoft Graph
Zestaw narzędzi programu Microsoft Graph

Klonowanie projektu

Pozostały czas: 132 min

Projekt kodu używany w tym samouczku jest dostępny pod adresem https://github.com/microsoft/MicrosoftCloud. Repozytorium projektu zawiera zarówno kod po stronie klienta, jak i po stronie serwera wymagany do uruchomienia projektu, umożliwiając eksplorowanie zintegrowanych funkcji związanych ze sztuczną inteligencją (AI), komunikacją i danymi organizacyjnymi. Ponadto projekt służy jako zasób ułatwiający dołączanie podobnych funkcji do własnych aplikacji.

W tym ćwiczeniu wykonasz następujące czynności:

Sklonuj repozytorium GitHub.
Dodaj plik env do projektu i zaktualizuj go.

Przed kontynuowaniem upewnij się, że wszystkie wymagania wstępne zostały zainstalowane i skonfigurowane zgodnie z opisem w sekcji Wymagania wstępne tego samouczka.

Klonowanie repozytorium GitHub i tworzenie `.env` pliku

Uruchom następujące polecenie, aby sklonować repozytorium Microsoft Cloud GitHub na maszynę.
```
git clone https://github.com/microsoft/MicrosoftCloud
```
Otwórz folder MicrosoftCloud/samples/openai-acs-msgraph w programie Visual Studio Code.

Uwaga

Mimo że w tym samouczku użyjemy programu Visual Studio Code, dowolny edytor kodu może służyć do pracy z przykładowym projektem.
Zwróć uwagę na następujące foldery i pliki:
- klient: kod aplikacji po stronie klienta.
- serwer: kod interfejsu API po stronie serwera.
- docker-compose.yml: służy do uruchamiania lokalnej bazy danych PostgreSQL.
Zmień nazwę pliku env.example w katalogu głównym projektu na .env.

Otwórz plik env i poświęć chwilę na przejrzenie uwzględnionych kluczy:

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=

Zaktualizuj następujące wartości w pliku env. Te wartości będą używane przez serwer interfejsu API do nawiązywania połączenia z lokalną bazą danych PostgreSQL.
```
POSTGRES_USER=web
POSTGRES_PASSWORD=web-password
```
Teraz, gdy masz już projekt, wypróbujmy niektóre funkcje aplikacji i dowiedzmy się, jak zostały one skompilowane. Wybierz poniższy przycisk Dalej, aby kontynuować lub przejść do określonego ćwiczenia przy użyciu spisu treści.

Sztuczna inteligencja: tworzenie zasobu usługi Azure OpenAI i wdrażanie modelu

Pozostały czas: 127 min

Aby rozpocząć korzystanie z usługi Azure OpenAI w aplikacjach, musisz utworzyć usługę Azure OpenAI Service i wdrożyć model, który może służyć do wykonywania zadań, takich jak konwertowanie języka naturalnego na język SQL, generowanie zawartości wiadomości e-mail/SMS i nie tylko.

W tym ćwiczeniu wykonasz następujące czynności:

Utwórz zasób usługi Azure OpenAI Service.
Wdrażanie modelu.
Zaktualizuj plik env przy użyciu wartości z zasobu usługi Azure OpenAI.

Omówienie scenariusza chmury firmy Microsoft

Tworzenie zasobu usługi Azure OpenAI Service

Odwiedź witrynę Azure Portal w przeglądarce i zaloguj się.
Wprowadź ciąg openai na pasku wyszukiwania w górnej części strony portalu i wybierz pozycję Azure OpenAI z wyświetlonych opcji.
Wybierz pozycję Utwórz na pasku narzędzi.

Uwaga

Chociaż ten samouczek koncentruje się na usłudze Azure OpenAI, jeśli masz klucz interfejsu API OpenAI i chcesz go użyć, możesz pominąć tę sekcję i przejść bezpośrednio do sekcji Aktualizowanie pliku env projektu poniżej. Przypisz klucz interfejsu API OpenAI do OPENAI_API_KEY w pliku env (możesz zignorować wszelkie inne .env instrukcje związane z interfejsem OpenAI).
Modele usługi Azure OpenAI są dostępne w określonych regionach. Zapoznaj się z dokumentem dotyczącym dostępności modelu usługi Azure OpenAI, aby dowiedzieć się, które regiony obsługują model gpt-4o używany w tym samouczku.
Wykonaj następujące zadania:
- Wybierz subskrypcję platformy Azure.
- Wybierz grupę zasobów do użycia (w razie potrzeby utwórz nową).
- Wybierz region, w którym model gpt-4o jest obsługiwany na podstawie wcześniej omówionego dokumentu.
- Wprowadź nazwę zasobu. Ta wartość musi być unikatowa.
- Wybierz warstwę cenową Standardowa S0 .
Wybierz przycisk Dalej , dopóki nie zostanie wyświetlony ekran Przeglądanie i przesyłanie . Wybierz pozycję Utwórz.
Po utworzeniu zasobu usługi Azure OpenAI przejdź do niego i wybierz pozycję Zarządzanie zasobami —->Klucze i punkt końcowy .
Znajdź wartości KLUCZ 1 i Punkt końcowy. Obie wartości będą używane w następnej sekcji, więc skopiujesz je do pliku lokalnego.
Wybierz pozycję Zarządzanie zasobami —> wdrożenia modelu.
Wybierz przycisk Zarządzaj wdrożeniami, aby przejść do usługi Azure OpenAI Studio.
Wybierz pozycję Wdróż model -->Wdróż model podstawowy na pasku narzędzi.
Wybierz pozycję gpt-4o z listy modeli i wybierz pozycję Potwierdź.

Uwaga

Usługa Azure OpenAI obsługuje kilka różnych typów modeli. Każdy model może służyć do obsługi różnych scenariuszy.
Zostanie wyświetlone następujące okno dialogowe. Pośmiń chwilę na sprawdzenie podanych wartości domyślnych.
Zmień wartość Tokens per Minute Rate Limit (tysiące) na 100K. Pozwoli to na wykonywanie większej liczby żądań do modelu i unikanie osiągnięcia limitu szybkości podczas wykonywania poniższych kroków.
Wybierz Wdróż.
Po wdrożeniu modelu wybierz pozycję Place zabaw -->Chat.
Na liście rozwijanej Wdrożenie powinien zostać wyświetlony model gpt-4o.
Pośmiń chwilę na przeczytanie dostarczonego tekstu komunikatu systemowego. Informuje to model, jak działać, gdy użytkownik wchodzi z nim w interakcję.
Znajdź pole tekstowe w obszarze czatu i wprowadź ciąg Summarize what Generative AI is and how it can be used (Podsumuj, czym jest generowanie sztucznej inteligencji i jak można go używać). Wybierz Enter, aby wysłać komunikat do modelu i wygenerować odpowiedź.
Poeksperymentuj z innymi monitami i odpowiedziami. Na przykład wprowadź ciąg Podaj krótką historię stolicy Francji i zwróć uwagę na wygenerowaną odpowiedź.

Aktualizowanie pliku projektu `.env`

Wróć do programu Visual Studio Code i otwórz .env plik w katalogu głównym projektu.
Skopiuj wartość KEY 1 z zasobu usługi Azure OpenAI i przypisz ją do OPENAI_API_KEY pliku env znajdującego się w katalogu głównym folderu openai-acs-msgraph:
```
OPENAI_API_KEY=<KEY_1_VALUE>
```
Skopiuj wartość *Punkt końcowy i przypisz ją do OPENAI_ENDPOINT pliku env . / Usuń znak z końca wartości, jeśli jest obecny.
```
OPENAI_ENDPOINT=<ENDPOINT_VALUE>
```
Uwaga

Zobaczysz, że wartości dla OPENAI_MODEL i OPENAI_API_VERSION są już ustawione w pliku env . Wartość modelu jest ustawiona na wartość gpt-4o zgodną z nazwą wdrożenia modelu utworzoną wcześniej w tym ćwiczeniu. Wersja interfejsu API jest ustawiona na obsługiwaną wartość zdefiniowaną w dokumentacji referencyjnej usługi Azure OpenAI.
Zapisz plik ENV.

Uruchamianie usług aplikacji

Nadszedł czas, aby uruchomić usługi aplikacji, w tym bazę danych, serwer interfejsu API i serwer internetowy.

W poniższych krokach utworzysz trzy okna terminalowe w programie Visual Studio Code.
Kliknij prawym przyciskiem myszy plik env na liście plików programu Visual Studio Code i wybierz polecenie Otwórz w zintegrowanym terminalu. Przed kontynuowaniem upewnij się, że terminal znajduje się w katalogu głównym projektu — openai-acs-msgraph .
Wybierz jedną z następujących opcji, aby uruchomić bazę danych PostgreSQL:
- Jeśli masz zainstalowany i uruchomiony program Docker Desktop , uruchom polecenie docker-compose up w oknie terminalu i naciśnij Enter.
- Jeśli masz zainstalowaną i uruchomioną aplikację Podman-compose , uruchom polecenie podman-compose up w oknie terminalu i naciśnij Enter.
- Aby uruchomić kontener PostgreSQL bezpośrednio przy użyciu programu Docker Desktop, Podman, nerdctl lub innego zainstalowanego środowiska uruchomieniowego kontenera, uruchom następujące polecenie w oknie terminalu:
  - Komputery Mac, Linux lub Podsystem Windows dla systemu 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 z programem 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
```
Po uruchomieniu kontenera bazy danych naciśnij ikonę + na pasku narzędzi terminalu programu Visual Studio Code, aby utworzyć drugie okno terminalu.
cd w folderze server/typescript uruchom następujące polecenia, aby zainstalować zależności i uruchomić serwer interfejsu API.
- npm install
- npm start
Naciśnij ponownie ikonę + na pasku narzędzi terminalu programu Visual Studio Code, aby utworzyć trzecie okno terminalu.
cd w folderze klienta i uruchom następujące polecenia, aby zainstalować zależności i uruchomić serwer internetowy.
- npm install
- npm start
Zostanie uruchomiona przeglądarka i nastąpi przekierowanie do http://localhost:4200.

Sztuczna inteligencja: język naturalny do języka SQL

Pozostały czas: 122 min

Cytat "Tylko dlatego, że nie możesz oznaczać, że powinieneś" jest przydatnym przewodnikiem podczas myślenia o możliwościach sztucznej inteligencji. Na przykład funkcja języka naturalnego usługi Azure OpenAI do języka SQL umożliwia użytkownikom wykonywanie zapytań bazy danych w języku angielskim, co może być zaawansowanym narzędziem zwiększającym produktywność. Jednak potężny nie zawsze oznacza odpowiednie ani bezpieczne. W tym ćwiczeniu pokazano, jak używać tej funkcji sztucznej inteligencji, omawiając również ważne zagadnienia, które należy wziąć pod uwagę przed podjęciem decyzji o jej zaimplementowaniu.

Oto przykład zapytania języka naturalnego, które może służyć do pobierania danych z bazy danych:

Get the the total revenue for all companies in London.

Po wyświetleniu odpowiednich monitów usługa Azure OpenAI przekonwertuje to zapytanie na język SQL, który może służyć do zwracania wyników z bazy danych. W związku z tym użytkownicy nietechniczni, w tym analitycy biznesowi, marketerzy i kierownicy, mogą łatwiej pobierać cenne informacje z baz danych bez zmagania się ze skomplikowanymi składniami SQL lub polegać na ograniczonych datagrids i filtrach. Takie usprawnione podejście może zwiększyć produktywność, eliminując potrzebę poszukiwania pomocy przez ekspertów technicznych.

To ćwiczenie zawiera punkt wyjścia, który pomoże zrozumieć, jak działa język naturalny w języku naturalnym SQL, przedstawić kilka ważnych zagadnień, zastanowić się nad zaletami i wadami oraz pokazać kod, aby rozpocząć pracę.

W tym ćwiczeniu wykonasz następujące czynności:

Użyj monitów GPT, aby przekonwertować język naturalny na język SQL.
Poeksperymentuj z różnymi monitami GPT.
Użyj wygenerowanej bazy danych SQL, aby wysłać zapytanie do bazy danych PostgreSQL uruchomionej wcześniej.
Zwracanie wyników zapytania z bazy danych PostgreSQL i wyświetlanie ich w przeglądarce.

Zacznijmy od eksperymentowania z różnymi monitami GPT, których można użyć do konwersji języka naturalnego na język SQL.

Używanie języka naturalnego do funkcji SQL

W poprzednim ćwiczeniu uruchomiono bazę danych, interfejsy API i aplikację. Zaktualizowano .env również plik. Jeśli nie wykonasz tych kroków, przed kontynuowaniem wykonaj instrukcje na końcu ćwiczenia.
Wróć do przeglądarki (http://localhost:4200) i znajdź sekcję Zapytanie niestandardowe na stronie poniżej usługi datagrid. Zwróć uwagę, że przykładowa wartość zapytania jest już uwzględniona: Uzyskaj całkowity przychód dla wszystkich zamówień. Grupuj według firmy i uwzględnij miasto.
Wybierz przycisk Uruchom zapytanie. Spowoduje to przekazanie zapytania języka naturalnego użytkownika do usługi Azure OpenAI, która zostanie przekonwertowana na język SQL. Zapytanie SQL będzie następnie używane do wykonywania zapytań względem bazy danych i zwracania potencjalnych wyników.

Uruchom następujące zapytanie niestandardowe:

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

Wyświetl okno terminalu z uruchomionym serwerem interfejsu API w programie Visual Studio Code i zwróć uwagę, że zostanie wyświetlone zapytanie SQL zwrócone z usługi Azure OpenAI. Dane JSON są używane przez interfejsy API po stronie serwera do wykonywania zapytań względem bazy danych PostgreSQL. Wszystkie wartości ciągów zawarte w zapytaniu są dodawane jako wartości parametrów, aby zapobiec atakom polegającym na wstrzyknięciu kodu SQL:
```
{ 
    "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"] 
}
```
Wróć do przeglądarki i wybierz pozycję Resetuj dane , aby ponownie wyświetlić wszystkich klientów w usłudze datagrid.

Eksplorowanie języka naturalnego do kodu SQL

Napiwek

Jeśli używasz programu Visual Studio Code, możesz otwierać pliki bezpośrednio, wybierając pozycję:

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

Następnie wpisz nazwę pliku, który chcesz otworzyć.

Uwaga

Celem tego ćwiczenia jest pokazanie, co jest możliwe dzięki funkcjom języka naturalnego SQL i pokazać, jak rozpocząć korzystanie z niego. Jak wspomniano wcześniej, ważne jest, aby omówić, czy ten typ sztucznej inteligencji jest odpowiedni dla organizacji przed kontynuowaniem jakiejkolwiek implementacji. Konieczne jest również zaplanowanie odpowiednich reguł monitów i środków zabezpieczeń bazy danych w celu zapobiegania nieautoryzowanemu dostępowi i ochronie poufnych danych.

Teraz, gdy już wiesz, jak działa funkcja języka naturalnego sql, sprawdźmy, jak jest ona zaimplementowana.

Otwórz plik serwera/apiRoutes.ts i znajdź generateSql trasę. Ta trasa interfejsu API jest wywoływana przez aplikację po stronie klienta uruchomioną w przeglądarce i używaną do generowania kodu SQL na podstawie zapytania języka naturalnego. Po pobraniu zapytania SQL jest ono używane do wykonywania zapytań względem bazy danych i zwracania wyników.

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

Zwróć uwagę na następujące funkcje trasy generateSql :

Pobiera wartość zapytania użytkownika z req.body.prompt i przypisuje ją do zmiennej o nazwie userPrompt. Ta wartość będzie używana w wierszu polecenia GPT.
Wywołuje funkcję w celu przekonwertowania języka naturalnego getSQLFromNLP() na język SQL.
Przekazuje wygenerowany język SQL do funkcji o nazwie queryDb , która wykonuje zapytanie SQL i zwraca wyniki z bazy danych.

Otwórz plik serwera/openAI.ts w edytorze i znajdź getSQLFromNLP() funkcję. Ta funkcja jest wywoływana generatesql przez trasę i służy do konwertowania języka naturalnego na język SQL.

async function getSQLFromNLP(userPrompt: string): Promise<QueryData> {
    // Get the high-level database schema summary to be used in the prompt.
    // The db.schema file could be generated by a background process or the 
    // schema could be dynamically retrieved.
    const dbSchema = await fs.promises.readFile('db.schema', 'utf8');

    const systemPrompt = `
    Assistant is a natural language to SQL bot that returns a JSON object with the SQL query and 
    the parameter values in it. The SQL will query a PostgreSQL database.

    PostgreSQL tables with their columns:    

    ${dbSchema}

    Rules:
    - Convert any strings to a PostgreSQL parameterized query value to avoid SQL injection attacks.
    - Return a JSON object with the following structure: { "sql": "", "paramValues": [] }

    Examples:

    User: "Display all company reviews. Group by company."      
    Assistant: { "sql": "SELECT * FROM reviews", "paramValues": [] }

    User: "Display all reviews for companies located in cities that start with 'L'."
    Assistant: { "sql": "SELECT r.* FROM reviews r INNER JOIN customers c ON r.customer_id = c.id WHERE c.city LIKE 'L%'", "paramValues": [] }

    User: "Display revenue for companies located in London. Include the company name and city."
    Assistant: { 
        "sql": "SELECT c.company, c.city, SUM(o.total) AS revenue FROM customers c INNER JOIN orders o ON c.id = o.customer_id WHERE c.city = $1 GROUP BY c.company, c.city", 
        "paramValues": ["London"] 
    }

    User: "Get the total revenue for Adventure Works Cycles. Include the contact information as well."
    Assistant: { 
        "sql": "SELECT c.company, c.city, c.email, SUM(o.total) AS revenue FROM customers c INNER JOIN orders o ON c.id = o.customer_id WHERE c.company = $1 GROUP BY c.company, c.city, c.email", 
        "paramValues": ["Adventure Works Cycles"] 
    }
    `;

    let queryData: QueryData = { sql: '', paramValues: [], error: '' };
    let results = '';

    try {
        results = await callOpenAI(systemPrompt, userPrompt);
        if (results) {
            console.log('results', results);
            const parsedResults = JSON.parse(results);
            queryData = { ...queryData, ...parsedResults };
            if (isProhibitedQuery(queryData.sql)) {
                queryData.sql = '';
                queryData.error = 'Prohibited query.';
            }
        }
    } catch (error) {
        console.log(error);
        if (isProhibitedQuery(results)) {
            queryData.sql = '';
            queryData.error = 'Prohibited query.';
        } else {
            queryData.error = results;
        }
    }

    return queryData;
}

Parametr userPrompt jest przekazywany do funkcji. Wartość userPrompt to zapytanie języka naturalnego wprowadzone przez użytkownika w przeglądarce.
A systemPrompt definiuje typ asystenta sztucznej inteligencji do użycia i reguły, które powinny być przestrzegane. Pomaga to usłudze Azure OpenAI zrozumieć strukturę bazy danych, jakie reguły mają być stosowane oraz jak zwrócić wygenerowane zapytanie SQL i parametry.
Wywoływana jest funkcja o nazwie callOpenAI() , a systemPrompt wartości i userPrompt są do niej przekazywane.
Wyniki są sprawdzane, aby upewnić się, że w wygenerowanych zapytaniach SQL nie są uwzględniane żadne niedozwolone wartości. Jeśli zostaną znalezione niedozwolone wartości, zapytanie SQL zostanie ustawione na pusty ciąg.

Bardziej szczegółowo omówimy monit systemowy:

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

Typ asystenta sztucznej inteligencji do użycia jest zdefiniowany. W tym przypadku "język naturalny do bota SQL".
Nazwy tabel i kolumny w bazie danych są definiowane. Schemat wysokiego poziomu zawarty w wierszu polecenia można znaleźć w pliku server/db.schema i wygląda następująco.
```
- 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)
```
Napiwek

Możesz rozważyć utworzenie widoków tylko do odczytu, które zawierają tylko użytkowników danych, mogą wykonywać zapytania przy użyciu języka naturalnego do języka SQL.
Reguła jest definiowana w celu przekonwertowania dowolnych wartości ciągu na sparametryzowaną wartość zapytania w celu uniknięcia ataków polegających na wstrzyknięciu kodu SQL.
Reguła jest definiowana tak, aby zawsze zwracała obiekt JSON z zapytaniem SQL i wartościami parametrów w nim.
Podano przykładowe monity użytkownika oraz oczekiwane wartości zapytań SQL i parametrów. Jest to nazywane uczeniem "kilka strzałów". Mimo że maszyny LLM są trenowane na dużych ilościach danych, można je dostosować do nowych zadań z zaledwie kilkoma przykładami. Alternatywną metodą jest uczenie "zero-shot", w którym nie podano żadnego przykładu, a model powinien wygenerować poprawne wartości zapytania SQL i parametrów.

Funkcja getSQLFromNLP() wysyła systemowi i użytkownikowi monity do funkcji o nazwie callOpenAI() , która znajduje się również w pliku serwera/openAI.ts . Funkcja callOpenAI() określa, czy usługa Azure OpenAI lub OpenAI powinna być wywoływana przez sprawdzenie zmiennych środowiskowych. Jeśli klucz, punkt końcowy i model są dostępne w zmiennych środowiskowych, wywoływana jest usługa Azure OpenAI. W przeciwnym razie wywoływana jest funkcja OpenAI.
```
function callOpenAI(systemPrompt: string, userPrompt: string, temperature = 0, useBYOD = false) {
    const isAzureOpenAI = OPENAI_API_KEY && OPENAI_ENDPOINT && OPENAI_MODEL;

    if (isAzureOpenAI) {
        if (useBYOD) {
            return getAzureOpenAIBYODCompletion(systemPrompt, userPrompt, temperature);
        }
        return getAzureOpenAICompletion(systemPrompt, userPrompt, temperature);
    }

    return getOpenAICompletion(systemPrompt, userPrompt, temperature);
}
```
Uwaga

Mimo że w tym samouczku skoncentrujemy się na usłudze Azure OpenAI, jeśli podasz OPENAI_API_KEY tylko wartość w pliku env, zamiast tego aplikacja będzie używać interfejsu OpenAI. Jeśli zdecydujesz się używać interfejsu OpenAI zamiast usługi Azure OpenAI, w niektórych przypadkach mogą pojawić się różne wyniki.
getAzureOpenAICompletion() Znajdź funkcję.
```
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;
}
```
Ta funkcja wykonuje następujące czynności:
- Parametry:
  - systemPrompt, userPrompti temperature są głównymi parametrami.
    - systemPrompt: informuje model usługi Azure OpenAI o swojej roli i regułach, które należy przestrzegać.
    - userPrompt: Zawiera informacje podane przez użytkownika, takie jak dane wejściowe języka naturalnego lub reguły generowania danych wyjściowych.
    - temperature: określa poziom kreatywności odpowiedzi modelu. Wyższa wartość powoduje zwiększenie kreatywnych danych wyjściowych.
- Generowanie ukończenia:
  - Funkcja wywołuje metodę createAzureOpenAICompletion() systemPrompt, userPrompti temperature w celu wygenerowania ukończenia.
  - Wyodrębnia zawartość z pierwszego wyboru w zakończeniu, przycinając wszelkie dodatkowe odstępy.
  - Jeśli zawartość zawiera struktury podobne do JSON (wskazywane przez obecność { i }), wyodrębnia zawartość JSON.
- Rejestrowanie i zwracana wartość:
  - Funkcja rejestruje dane wyjściowe usługi Azure OpenAI w konsoli.
  - Zwraca przetworzoną zawartość jako ciąg.
createAzureOpenAICompletion() Znajdź funkcję.
```
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.`);
        }
    }
}
```
Ta funkcja wykonuje następujące czynności:
- Parametry:
  - systemPrompt, userPrompti temperature są głównymi parametrami omówionymi wcześniej.
  - Opcjonalny dataSources parametr obsługuje funkcję "Azure Bring Your Own Data", która zostanie omówiona w dalszej części tego samouczka.
- Sprawdzanie zmiennych środowiskowych:
  - Funkcja sprawdza obecność podstawowych zmiennych środowiskowych, zgłaszając błąd, jeśli brakuje.
- Obiekt konfiguracji:
  - Obiekt config jest tworzony przy użyciu wartości z .env pliku (OPENAI_API_KEY, OPENAI_ENDPOINT, OPENAI_API_VERSION, OPENAI_MODEL). Te wartości służą do konstruowania adresu URL do wywoływania usługi Azure OpenAI.
- Wystąpienie usługi AzureOpenAI:
  - AzureOpenAI Wystąpienie obiektu jest tworzone przy użyciu config obiektu . Symbol AzureOpenAI jest częścią openai pakietu, który powinien zostać zaimportowany w górnej części pliku.
- Generowanie ukończenia:
  - Funkcja jest wywoływana chat.completions.create() z następującymi właściwościami:
    - model: Określa model GPT (np. gpt-4o, gpt-3.5-turbo) zgodnie z definicją w .env pliku.
    - max_tokens: definiuje maksymalną liczbę tokenów na potrzeby ukończenia.
    - temperature: Ustawia temperaturę próbkowania. Wyższe wartości (np. 0,9) dają więcej odpowiedzi kreatywnych, podczas gdy niższe wartości (np. 0) generują bardziej deterministyczne odpowiedzi.
    - response_format: definiuje format odpowiedzi. W tym miejscu jest ustawiona wartość zwracania obiektu JSON. Więcej informacji na temat trybu JSON można znaleźć w dokumentacji referencyjnej usługi Azure OpenAI.
    - messages: zawiera komunikaty służące do generowania uzupełniania czatu. Ten przykład obejmuje dwa komunikaty: jeden z systemu (definiowanie zachowania i reguł) i jeden od użytkownika (zawierający tekst monitu).
- Wartość zwracana:
  - Funkcja zwraca obiekt uzupełniania wygenerowany przez usługę Azure OpenAI.

Oznacz jako komentarz następujące wiersze w getSQLFromNLP() funkcji:

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

Zapisz openAI.ts. Serwer interfejsu API automatycznie ponownie skompiluje kod TypeScript i uruchomi ponownie serwer.
Wróć do przeglądarki i wprowadź pozycję Wybierz wszystkie nazwy tabel z bazy danych do danych wejściowych zapytania niestandardowego. Wybierz pozycję Uruchom zapytanie. Czy są wyświetlane nazwy tabel?
Wróć do getSQLFromNLP() funkcji na serwerze/openAI.ts i dodaj następującą regułę do Rules: sekcji monitu systemowego, a następnie zapisz plik.
```
- Do not allow the SELECT query to return table names, function names, or procedure names.
```
Wróć do przeglądarki i wykonaj następujące zadania:
- Wprowadź pozycję Wybierz wszystkie nazwy tabel z bazy danych do danych wejściowych zapytania niestandardowego. Wybierz pozycję Uruchom zapytanie. Czy są wyświetlane nazwy tabel?
- Wprowadź pozycję Wybierz wszystkie nazwy funkcji z bazy danych. w danych wejściowych zapytania niestandardowego i ponownie wybierz pozycję Uruchom zapytanie. Czy są wyświetlane nazwy funkcji?
PYTANIE: Czy model zawsze będzie przestrzegać reguł zdefiniowanych w wierszu polecenia?

ODPOWIEDŹ: Nie! Należy pamiętać, że modele OpenAI mogą zwracać nieoczekiwane wyniki przy okazji, które mogą nie być zgodne z zdefiniowanymi regułami. Ważne jest, aby zaplanować to w kodzie.
Wróć do serwera/openAI.ts i znajdź isProhibitedQuery() funkcję. Jest to przykład kodu przetwarzania końcowego, który można uruchomić po zwracaniu wyników przez usługę Azure OpenAI. Zwróć uwagę, że właściwość jest ustawiana sql na pusty ciąg, jeśli niedozwolone słowa kluczowe są zwracane w wygenerowanym zapytaniu SQL. Gwarantuje to, że jeśli z usługi Azure OpenAI zostaną zwrócone nieoczekiwane wyniki, zapytanie SQL nie zostanie uruchomione względem bazy danych.
```
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));
}
```
Uwaga

Należy pamiętać, że jest to tylko kod demonstracyjny. W przypadku wybrania konwersji języka naturalnego na język SQL mogą istnieć inne zabronione słowa kluczowe wymagane do pokrycia określonych przypadków użycia. Jest to funkcja, którą należy zaplanować i używać z ostrożnością, aby upewnić się, że zwracane są tylko prawidłowe zapytania SQL i są uruchamiane względem bazy danych. Oprócz zabronionych słów kluczowych należy również uwzględnić bezpieczeństwo.
Wróć do serwera/openAI.ts i usuń komentarz z poniższego getSQLFromNLP() kodu w funkcji. Zapisz plik.
```
if (isProhibitedQuery(queryData.sql)) { 
    queryData.sql = '';
}
```

Usuń następującą regułę z systemPrompt pliku i zapisz go.

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

Wróć do przeglądarki, wprowadź ponownie pozycję Wybierz wszystkie nazwy tabel z bazy danych do danych wejściowych zapytania niestandardowego , a następnie wybierz przycisk Uruchom zapytanie .
Czy są wyświetlane jakieś wyniki tabeli? Nawet bez reguły isProhibitedQuery() kod przetwarzania końcowego uniemożliwia uruchamianie tego typu zapytania względem bazy danych.
Jak wspomniano wcześniej, integracja języka naturalnego z bazą danych SQL w aplikacjach biznesowych może być bardzo korzystna dla użytkowników, ale zawiera własny zestaw zagadnień.

Zalety:
- Przyjazność użytkownika: ta funkcja może sprawić, że interakcja z bazą danych będzie bardziej dostępna dla użytkowników bez wiedzy technicznej, co zmniejsza zapotrzebowanie na wiedzę SQL i potencjalnie przyspiesza operacje.
- Zwiększona produktywność: analitycy biznesowi, marketerzy, kierownictwo i inni użytkownicy nietechniczni mogą pobierać cenne informacje z baz danych bez konieczności polegania na ekspertach technicznych, zwiększając tym samym wydajność.
- Szeroka aplikacja: przy użyciu zaawansowanych modeli językowych aplikacje można projektować tak, aby obsługiwały szeroką gamę użytkowników i przypadków użycia.
Ważne kwestie:
- Bezpieczeństwo: Jednym z największych problemów jest bezpieczeństwo. Jeśli użytkownicy mogą wchodzić w interakcje z bazami danych przy użyciu języka naturalnego, należy stosować niezawodne środki zabezpieczeń, aby zapobiec nieautoryzowanemu dostępowi lub złośliwym zapytaniom. Możesz rozważyć zaimplementowanie trybu tylko do odczytu, aby uniemożliwić użytkownikom modyfikowanie danych.
- Prywatność danych: niektóre dane mogą być poufne i nie powinny być łatwo dostępne, dlatego należy zapewnić odpowiednie zabezpieczenia i uprawnienia użytkownika.
- Dokładność: Chociaż przetwarzanie języka naturalnego znacznie się poprawiło, nie jest idealne. Błędna interpretacja zapytań użytkowników może prowadzić do niedokładnych wyników lub nieoczekiwanego zachowania. Należy zaplanować obsługę nieoczekiwanych wyników.
- Wydajność: Nie ma gwarancji, że baza danych SQL zwrócona z zapytania w języku naturalnym będzie wydajna. W niektórych przypadkach mogą być wymagane dodatkowe wywołania usługi Azure OpenAI, jeśli reguły przetwarzania końcowego wykrywają problemy z zapytaniami SQL.
- Szkolenie i adaptacja użytkowników: użytkownicy muszą być przeszkoleni, aby prawidłowo sformułować swoje zapytania. Chociaż jest to łatwiejsze niż uczenie się języka SQL, nadal może istnieć krzywa nauki.
Kilka ostatnich kwestii, które należy wziąć pod uwagę przed przejściem do następnego ćwiczenia:
- Pamiętaj, że "Tylko dlatego, że nie możesz oznaczać, że powinieneś" ma zastosowanie tutaj. Przed zintegrowaniem języka naturalnego z bazą danych SQL w aplikacji należy zachować szczególną ostrożność i staranne planowanie. Ważne jest, aby zrozumieć potencjalne zagrożenia i zaplanować je.
- Przed użyciem tej technologii należy omówić potencjalne scenariusze z zespołem, administratorami baz danych, zespołem ds. zabezpieczeń, uczestnikami projektu i wszystkimi innymi odpowiednimi stronami, aby upewnić się, że jest ona odpowiednia dla Twojej organizacji. Ważne jest, aby omówić, czy język naturalny sql spełnia wymagania dotyczące zabezpieczeń, prywatności i innych wymagań organizacji.
- Bezpieczeństwo powinno być głównym problemem i wbudowane w proces planowania, programowania i wdrażania.
- Chociaż język naturalny do języka SQL może być bardzo zaawansowany, staranne planowanie musi przejść do niego, aby upewnić się, że monity mają wymagane reguły i że funkcja przetwarzania końcowego jest uwzględniona. Zaplanuj dodatkowy czas, aby zaimplementować i przetestować ten typ funkcji oraz uwzględnić scenariusze, w których zwracane są nieoczekiwane wyniki.
- Dzięki usłudze Azure OpenAI klienci uzyskują możliwości zabezpieczeń platformy Microsoft Azure podczas uruchamiania tych samych modeli co openAI. Usługa Azure OpenAI oferuje prywatną sieć, dostępność regionalną i odpowiedzialne filtrowanie zawartości sztucznej inteligencji. Dowiedz się więcej na temat danych, prywatności i zabezpieczeń usługi Azure OpenAI Service.
Wiesz już, jak używać usługi Azure OpenAI do konwertowania języka naturalnego na język SQL i poznaliśmy zalety i wady implementacji tego typu funkcji. W następnym ćwiczeniu dowiesz się, jak można wygenerować wiadomości e-mail i SMS przy użyciu usługi Azure OpenAI.

Sztuczna inteligencja: generowanie uzupełniania

Pozostały czas: 112 min

Oprócz języka naturalnego do funkcji SQL można również użyć usługi Azure OpenAI Service do generowania wiadomości e-mail i wiadomości SMS w celu zwiększenia produktywności użytkowników i usprawnić przepływy pracy komunikacji. Korzystając z funkcji generowania języka usługi Azure OpenAI, użytkownicy mogą definiować określone reguły, takie jak "Kolejność jest opóźniona 5 dni", a system automatycznie wygeneruje kontekstowo odpowiednie wiadomości e-mail i SMS na podstawie tych reguł.

Ta funkcja służy jako początek dla użytkowników, zapewniając im przemyślany szablon wiadomości, który można łatwo dostosować przed wysłaniem. Rezultatem jest znaczne skrócenie czasu i nakładu pracy wymaganego do tworzenia komunikatów, co pozwala użytkownikom skupić się na innych ważnych zadaniach. Ponadto technologia generowania języka usługi Azure OpenAI może być zintegrowana z przepływami pracy automatyzacji, umożliwiając systemowi autonomiczne generowanie i wysyłanie komunikatów w odpowiedzi na wstępnie zdefiniowane wyzwalacze. Ten poziom automatyzacji nie tylko przyspiesza procesy komunikacji, ale także zapewnia spójne i dokładne komunikaty w różnych scenariuszach.

W tym ćwiczeniu wykonasz następujące czynności:

Poeksperymentuj z różnymi monitami.
Użyj monitów, aby wygenerować uzupełnianie wiadomości e-mail i wiadomości SMS.
Zapoznaj się z kodem, który umożliwia uzupełnianie sztucznej inteligencji.
Dowiedz się więcej o znaczeniu inżynierii monitów i uwzględnianiu reguł w monitach.

Zacznijmy od eksperymentowania z różnymi regułami, których można użyć do generowania wiadomości e-mail i wiadomości SMS.

Korzystanie z funkcji uzupełniania sztucznej inteligencji

W poprzednim ćwiczeniu uruchomiono bazę danych, interfejsy API i aplikację. Zaktualizowano .env również plik. Jeśli nie wykonasz tych kroków, przed kontynuowaniem wykonaj instrukcje na końcu ćwiczenia.
Wróć do przeglądarki (http://localhost:4200) i wybierz pozycję Skontaktuj się z klientem w dowolnym wierszu w usłudze datagrid, a następnie pozycję E-mail/SMS Customer , aby przejść do ekranu Generator wiadomości.
Używa to usługi Azure OpenAI do konwertowania reguł wiadomości zdefiniowanych na wiadomości e-mail/SMS. Wykonaj następujące zadania:
- Wprowadź regułę, taką jak Zamówienie jest opóźniona o 5 dni w danych wejściowych, a następnie wybierz przycisk Generuj wiadomości e-mail/SMS.
- Zostanie wyświetlony temat i treść wygenerowana dla wiadomości e-mail oraz krótka wiadomość wygenerowana dla wiadomości SMS.
Uwaga

Ponieważ usługi Azure Communication Services nie są jeszcze włączone, nie będzie można wysyłać wiadomości e-mail ani wiadomości SMS.
Zamknij okno dialogowe wiadomości e-mail/sms w przeglądarce. Teraz, po zapoznaniu się z tą funkcją w działaniu, sprawdźmy, jak została zaimplementowana.

Eksplorowanie kodu uzupełniania sztucznej inteligencji

Napiwek

Jeśli używasz programu Visual Studio Code, możesz otwierać pliki bezpośrednio, wybierając pozycję:

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

Następnie wpisz nazwę pliku, który chcesz otworzyć.

Otwórz plik serwera/apiRoutes.ts i znajdź completeEmailSmsMessages trasę. Ten interfejs API jest wywoływany przez część frontonu aplikacji po wybraniu przycisku Generuj wiadomości e-mail/SMS. Pobiera on wartości monitu użytkownika, firmy i nazwy kontaktu z treści i przekazuje je do completeEmailSMSMessages() funkcji w pliku serwera/openAI.ts . Wyniki są następnie zwracane do klienta.

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

Otwórz plik serwera/openAI.ts i znajdź completeEmailSMSMessages() funkcję.

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

Ta funkcja ma następujące funkcje:

systemPrompt Służy do definiowania, że wymagany jest asystent sztucznej inteligencji umożliwiający generowanie wiadomości e-mail i wiadomości SMS. Obejmuje systemPrompt również:
- Reguły dotyczące asystenta do kontrolowania tonu wiadomości, formatu początkowego i końcowego, maksymalnej długości wiadomości SMS i nie tylko.
- Informacje o danych, które powinny zostać uwzględnione w odpowiedzi — w tym przypadku obiekt JSON.
userPrompt Służy do definiowania reguł i nazwy kontaktu, które użytkownik końcowy chce dołączyć jako wiadomości e-mail i SMS są generowane. Wprowadzona wcześniej reguła Order jest opóźniona o 5 dni.userPrompt
Funkcja wywołuje callOpenAI() eksplorowaną wcześniej funkcję w celu wygenerowania uzupełniania wiadomości e-mail i wiadomości SMS.

Wróć do przeglądarki, odśwież stronę i wybierz pozycję Skontaktuj się z klientem w dowolnym wierszu, a następnie pozycję E-mail/SMS Customer, aby ponownie przejść do ekranu Generator wiadomości.
Wprowadź następujące reguły w danych wejściowych generatora komunikatów:
- Kolejność jest przed harmonogramem.
- Poinformuj klienta, aby nigdy nie zamówił od nas ponownie, nie chcemy, aby ich działalność.
Wybierz pozycję Generuj wiadomości e-mail/SMS i zanotuj wiadomość. Reguła All messages should have a friendly tone and never use inappropriate language. w wierszu polecenia systemu zastępuje regułę ujemną w wierszu polecenia użytkownika.
Wróć do serwera/openAI.ts* w edytorze i usuń regułę All messages should have a friendly tone and never use inappropriate language. z wiersza polecenia w completeEmailSMSMessages() funkcji. Zapisz plik.
Wróć do generatora wiadomości e-mail/SMS w przeglądarce i ponownie uruchom te same reguły:
- Kolejność jest przed harmonogramem.
- Poinformuj klienta, aby nigdy nie zamówił od nas ponownie, nie chcemy, aby ich działalność.
Wybierz pozycję Generuj wiadomości e-mail/SMS i zwróć uwagę na zwróconą wiadomość.
Co się dzieje w tych scenariuszach? W przypadku korzystania z usługi Azure OpenAI filtrowanie zawartości można zastosować w celu zapewnienia, że odpowiedni język jest zawsze używany. Jeśli używasz interfejsu OpenAI, reguła zdefiniowana w wierszu polecenia systemu jest używana w celu upewnienia się, że zwrócony komunikat jest odpowiedni.

Uwaga

Ilustruje to znaczenie inżynierii monitów z odpowiednimi informacjami i regułami w celu zapewnienia, że zostaną zwrócone odpowiednie wyniki. Przeczytaj więcej na temat tego procesu w dokumentacji wprowadzenie do monitowania o inżynierię .
Cofnij zmiany wprowadzone systemPrompt w completeEmailSMSMessages()pliku , zapisz plik i uruchom go ponownie, ale użyj Order is ahead of schedule. tylko reguły (nie uwzględniaj reguły ujemnej). Tym razem powinna zostać wyświetlona wiadomość e-mail i wiadomości SMS zwrócone zgodnie z oczekiwaniami.
Kilka ostatnich kwestii, które należy wziąć pod uwagę przed przejściem do następnego ćwiczenia:
- Ważne jest, aby człowiek w pętli przeglądał wygenerowane komunikaty. W tym przykładzie uzupełnienia usługi Azure OpenAI zwracają sugerowane wiadomości e-mail i SMS, ale użytkownik może je zastąpić przed wysłaniem. Jeśli planujesz zautomatyzować wiadomości e-mail, posiadanie pewnego typu procesu przeglądu przez człowieka w celu zapewnienia, że zatwierdzone wiadomości są wysyłane, jest ważne. Wyświetlanie sztucznej inteligencji jako copilot, a nie autopilot.
- Ukończenia będą tak dobre, jak reguły dodawane do monitu. Pośmiń czas na przetestowanie monitów i zwróconych uzupełniania. Rozważ użycie przepływu Monituj, aby utworzyć kompleksowe rozwiązanie, które upraszcza tworzenie prototypów, eksperymentowanie, iterowanie i wdrażanie aplikacji sztucznej inteligencji. Zaproś inne osoby biorące udział w projekcie, aby przejrzeć również ukończenie.
- Może być konieczne dołączenie kodu przetwarzania końcowego w celu zapewnienia prawidłowego obsługi nieoczekiwanych wyników.
- Użyj monitów systemowych, aby zdefiniować reguły i informacje, które powinien przestrzegać asystent sztucznej inteligencji. Użyj monitów użytkownika, aby zdefiniować reguły i informacje, które użytkownik końcowy chce uwzględnić w ukończeniach.

Sztuczna inteligencja: Azure OpenAI na danych

Pozostały czas: 102 min

Integracja usługi Azure OpenAI Natural Language Processing (NLP) i możliwości uzupełniania zapewnia znaczący potencjał zwiększania produktywności użytkowników. Dzięki wykorzystaniu odpowiednich monitów i reguł asystent sztucznej inteligencji może efektywnie generować różne formy komunikacji, takie jak wiadomości e-mail, wiadomości SMS i inne. Ta funkcja prowadzi do zwiększenia wydajności użytkownika i usprawnionych przepływów pracy.

Chociaż ta funkcja jest bardzo zaawansowana, mogą wystąpić przypadki, w których użytkownicy muszą generować uzupełnienia na podstawie niestandardowych danych firmy. Na przykład może istnieć kolekcja podręczników produktów, które mogą być trudne dla użytkowników, aby poruszać się, gdy pomagają klientom w rozwiązywaniu problemów z instalacją. Alternatywnie możesz zachować kompleksowy zestaw często zadawanych pytań związanych z świadczeniami opieki zdrowotnej, które mogą okazać się trudne dla użytkowników do przeczytania i uzyskania potrzebnych odpowiedzi. W takich przypadkach i wielu innych usługa Azure OpenAI Service umożliwia wykorzystanie własnych danych do generowania uzupełniania, zapewniając bardziej dopasowaną i kontekstową dokładniejszą odpowiedź na pytania użytkowników.

Poniżej przedstawiono krótkie omówienie działania funkcji "bring your own data" z dokumentacji usługi Azure OpenAI.

Uwaga

Jedną z kluczowych funkcji usługi Azure OpenAI na danych jest możliwość pobierania i wykorzystywania danych w sposób zwiększający dane wyjściowe modelu. Usługa Azure OpenAI na danych wraz z usługą Azure AI Search określa, jakie dane mają być pobierane z wyznaczonego źródła danych na podstawie danych wejściowych użytkownika i podanej historii konwersacji. Te dane są następnie rozszerzane i ponownie przesyłane jako monit o model OpenAI z pobranymi informacjami dołączanymi do oryginalnego monitu. Mimo że pobrane dane są dołączane do monitu, wynikowe dane wejściowe są nadal przetwarzane przez model jak każdy inny monit. Po pobraniu danych i przesłaniu monitu do modelu model model używa tych informacji w celu zapewnienia ukończenia.

W tym ćwiczeniu wykonasz następujące czynności:

Utwórz niestandardowe źródło danych przy użyciu programu Azure AI Studio.
Wdrażanie modelu osadzania przy użyciu programu Azure AI Studio.
Przekazywanie dokumentów niestandardowych.
Rozpocznij sesję czatu na placu zabaw czatu, aby poeksperymentować z generowaniem uzupełnień na podstawie własnych danych.
Zapoznaj się z kodem, który używa usług Azure AI Search i Azure OpenAI do generowania uzupełniania na podstawie własnych danych.

Zacznijmy od wdrożenia modelu osadzania i dodania niestandardowego źródła danych w usłudze Azure AI Studio.

Dodawanie niestandardowego źródła danych do programu Azure AI Studio

Przejdź do usługi Azure OpenAI Studio i zaloguj się przy użyciu poświadczeń, które mają dostęp do zasobu usługi Azure OpenAI.
Wybierz pozycję Wdrożenia z menu nawigacji.
Wybierz pozycję Wybierz pozycję Wdróż model -->Wdróż model podstawowy na pasku narzędzi.
Wybierz model text-embedding-ada-002 z listy modeli i wybierz pozycję Potwierdź.
Wybierz jedną z następujących opcji:
- Nazwa wdrożenia: text-embedding-ada-002
- Wersja modelu: domyślna
- Typ wdrożenia: Standardowa
- Ustaw wartość limitu szybkości tokenów na minutę (tysiące) na 120 0000
- Filtr zawartości: DefaultV2
- Włącz cudzysłów dynamicznych: włączone
Wybierz przycisk Wdróż.
Po utworzeniu modelu wybierz pozycję Strona główna z menu nawigacji, aby przejść do ekranu powitalnego.
Znajdź kafelek Bring your own data (Przynieś własne dane) na ekranie powitalnym i wybierz pozycję Wypróbuj teraz.
Wybierz pozycję Dodaj dane , a następnie pozycję Dodaj źródło danych.
Z listy rozwijanej Wybierz źródło danych wybierz pozycję Przekaż pliki.
Na liście rozwijanej Wybierz zasób usługi Azure Blob Storage wybierz pozycję Utwórz nowy zasób usługi Azure Blob Storage.
Wybierz swoją subskrypcję platformy Azure na liście rozwijanej Subskrypcja .
Na liście rozwijanej Wybierz zasób usługi Azure Blob Storage wybierz pozycję Utwórz nowy zasób usługi Azure Blob Storage.
Spowoduje to przejście do witryny Azure Portal, w której można wykonać następujące zadania:
- Wprowadź unikatową nazwę konta magazynu, na przykład byodstorage[Twoje nazwisko].
- Wybierz region, który znajduje się blisko lokalizacji.
- Wybierz pozycję Przejrzyj , a następnie pozycję Utwórz.
Po utworzeniu zasobu usługi Blob Storage wróć do okna dialogowego Azure AI Studio i wybierz nowo utworzony zasób magazynu obiektów blob z listy rozwijanej Wybierz zasób usługi Azure Blob Storage. Jeśli nie widzisz jej na liście, wybierz ikonę odświeżania obok listy rozwijanej.
Aby można było uzyskać dostęp do konta magazynu, należy włączyć współużytkowanie zasobów między źródłami (CORS). Wybierz pozycję Włącz mechanizm CORS w oknie dialogowym Azure AI Studio.
Na liście rozwijanej Wybierz zasób usługi Azure AI Search wybierz pozycję Utwórz nowy zasób usługi Azure AI Search.
Spowoduje to powrót do witryny Azure Portal, w której można wykonać następujące zadania:
- Wprowadź unikatową nazwę zasobu wyszukiwania sztucznej inteligencji, taką jak byodsearch-[Twoje nazwisko].
- Wybierz region, który znajduje się blisko lokalizacji.
- W sekcji Warstwa cenowa wybierz pozycję Zmień warstwę cenową i wybierz pozycję Podstawowa, a następnie pozycję Wybierz. Warstwa Bezpłatna nie jest obsługiwana, dlatego na końcu tego samouczka wyczyścisz zasób wyszukiwania sztucznej inteligencji.
- Wybierz pozycję Przejrzyj , a następnie pozycję Utwórz.
Po utworzeniu zasobu wyszukiwania sztucznej inteligencji przejdź do strony Przegląd zasobu i skopiuj wartość Adresu URL do pliku lokalnego.
Wybierz pozycję Ustawienia -> Klucze w menu nawigacji.
Na stronie Kontrola dostępu do interfejsu API wybierz pozycję Oba, aby umożliwić dostęp do usługi przy użyciu tożsamości zarządzanej lub klucza. Po wyświetleniu monitu wybierz pozycję Tak .

Uwaga

Mimo że w tym ćwiczeniu użyjemy klucza interfejsu API, ponieważ dodanie przypisań ról może potrwać do 10 minut, przy niewielkim dodatkowym wysiłku można włączyć tożsamość zarządzaną przypisaną przez system, aby bezpieczniej uzyskać dostęp do usługi.
Wybierz pozycję Klucze w menu nawigacji po lewej stronie i skopiuj wartość podstawowego klucza administratora do pliku lokalnego. W dalszej części ćwiczenia będziesz potrzebować wartości adresu URL i klucza.
Wybierz pozycję Ustawienia -->Semantic ranker w menu nawigacji i upewnij się, że wybrano pozycję Bezpłatna.

Uwaga

Aby sprawdzić, czy klasyfikator semantyczny jest dostępny w określonym regionie, sprawdź stronę Dostępność produktów według regionów w witrynie internetowej platformy Azure, aby sprawdzić, czy region znajduje się na liście.
Wróć do okna dialogowego Dodawanie danych programu Azure AI Studio i wybierz nowo utworzony zasób wyszukiwania z listy rozwijanej Wybierz zasób usługi Azure AI Search. Jeśli nie widzisz jej na liście, wybierz ikonę odświeżania obok listy rozwijanej.
Wprowadź wartość byod-search-index dla wartości Wprowadź nazwę indeksu.
Zaznacz pole wyboru Dodaj wyszukiwanie wektorów do tego zasobu wyszukiwania.
Na liście rozwijanej Wybierz model osadzania wybierz utworzony wcześniej model text-embedding-ada-002 .
W oknie dialogowym Przekazywanie plików wybierz pozycję Przeglądaj dla pliku.
Przejdź do folderu dokumentów klienta projektu (znajdującego się w katalogu głównym projektu) i wybierz następujące pliki:
- Instructions.docx instalacji zegara A102
- FAQs.docx firmy
Uwaga

Ta funkcja obsługuje obecnie następujące formaty plików do tworzenia indeksu lokalnego: .txt, md, .html, .pdf, .docx i .pptx.
Wybierz pozycję Przekaż pliki. Pliki zostaną przekazane do kontenera fileupload-byod-search-index w utworzonym wcześniej zasobie magazynu obiektów blob.
Wybierz przycisk Dalej , aby przejść do okna dialogowego Zarządzanie danymi.
Na liście rozwijanej Typ wyszukiwania wybierz pozycję Hybryda i semantyka.

Uwaga

Ta opcja zapewnia obsługę wyszukiwania słów kluczowych i wektorów. Po zwróceniu wyników pomocniczy proces klasyfikowania jest stosowany do zestawu wyników przy użyciu modeli uczenia głębokiego, co poprawia istotność wyszukiwania dla użytkownika. Aby dowiedzieć się więcej na temat wyszukiwania semantycznego, zapoznaj się z dokumentacją wyszukiwania semantycznego w usłudze Azure AI Search .
Upewnij się, że ustawiono wartość Wybierz rozmiar na 1024.
Wybierz Dalej.
W polu Typ uwierzytelniania zasobów platformy Azure wybierz pozycję Klucz interfejsu API. Dowiedz się więcej na temat wybierania odpowiedniego typu uwierzytelniania w dokumentacji uwierzytelniania usługi Azure AI Search.
Wybierz Dalej.
Przejrzyj szczegóły i wybierz pozycję Zapisz i zamknij.
Teraz, po przekazaniu danych niestandardowych, dane zostaną zindeksowane i będą dostępne do użycia na placu zabaw czatu. Ten proces może potrwać kilka minut. Po zakończeniu przejdź do następnej sekcji.

Używanie niestandardowego źródła danych na placu zabaw czatu

Znajdź sekcję Sesja czatu na stronie w programie Azure OpenAI Studio i wprowadź następujące zapytanie użytkownika:
```
What safety rules are required to install a clock?
```
Po przesłaniu zapytania użytkownika powinien zostać wyświetlony wynik podobny do następującego:
Rozwiń sekcję 1 odwołań w odpowiedzi na czat i zwróć uwagę, że na liście znajduje się plik Instructions.docx instalacji zegara A102, który można wybrać, aby wyświetlić dokument.

Wprowadź następujący komunikat użytkownika:

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

Powinien zostać wyświetlony wynik podobny do następującego:
Teraz poeksperymentujmy z dokumentem Często zadawane pytania dotyczące firmy. Wprowadź następujący tekst w polu Zapytanie użytkownika:
```
What is the company's policy on vacation time?
```
Powinien zostać wyświetlony komunikat, że dla tego żądania nie znaleziono żadnych informacji.
Wprowadź następujący tekst w polu Zapytanie użytkownika:
```
How should I handle refund requests?
```
Powinien zostać wyświetlony wynik podobny do następującego:
Rozwiń sekcję 1 odwołań w odpowiedzi na czat i zwróć uwagę, że plik FAQs.docx firmy znajduje się na liście i możesz wybrać go, aby wyświetlić dokument.
Wybierz pozycję Wyświetl kod na pasku narzędzi placu zabaw czatu.
Należy pamiętać, że możesz przełączać się między różnymi językami, wyświetlać punkt końcowy i uzyskiwać dostęp do klucza punktu końcowego. Zamknij okno dialogowe Przykładowy kod.
Włącz przełącznik Pokaż nieprzetworzone dane JSON powyżej wiadomości czatu. Zwróć uwagę, że sesja czatu rozpoczyna się od komunikatu podobnego do następującego:
```
{
    "role": "system",
    "content": "You are an AI assistant that helps people find information."
}
```
Teraz, gdy utworzono niestandardowe źródło danych i poeksperymentowaliśmy je na placu zabaw czatu, zobaczmy, jak można go używać w aplikacji projektu.

Korzystanie z funkcji Bring Your Own Data w aplikacji

Wróć do projektu w programie VS Code i otwórz plik env . Zaktualizuj następujące wartości przy użyciu punktu końcowego, klucza i nazwy indeksu usług AI Services. Skopiowano punkt końcowy i klucz do pliku lokalnego wcześniej w tym ćwiczeniu.
```
AZURE_AI_SEARCH_ENDPOINT=<AI_SERVICES_ENDPOINT_VALUE>
AZURE_AI_SEARCH_KEY=<AI_SERVICES_KEY_VALUE>
AZURE_AI_SEARCH_INDEX=byod-search-index
```
W poprzednim ćwiczeniu uruchomiono bazę danych, interfejsy API i aplikację. Zaktualizowano .env również plik. Jeśli nie wykonasz tych kroków, przed kontynuowaniem wykonaj instrukcje na końcu wcześniejszego ćwiczenia.
Po załadowaniu aplikacji w przeglądarce wybierz ikonę Pomoc czatu w prawym górnym rogu aplikacji.
W oknie dialogowym czatu powinien zostać wyświetlony następujący tekst:
```
How should I handle a company refund request?
```
Wybierz przycisk Uzyskaj pomoc. Powinny zostać wyświetlone wyniki zwrócone z dokumentu Company FAQs.docx przekazanego wcześniej w usłudze Azure OpenAI Studio. Jeśli chcesz przeczytać dokument, możesz go znaleźć w folderze dokumentów klienta w katalogu głównym projektu.
Zmień tekst na następujący i wybierz przycisk Uzyskaj pomoc :
```
What safety rules are required to install a clock?
```
Powinny zostać wyświetlone wyniki zwrócone z dokumentu Instructions.docx instalacji zegara A102 przekazanego wcześniej w narzędziu Azure OpenAI Studio. Ten dokument jest również dostępny w folderze dokumentów klienta w katalogu głównym projektu.

Eksplorowanie kodu

Napiwek

Jeśli używasz programu Visual Studio Code, możesz otwierać pliki bezpośrednio, wybierając pozycję:

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

Następnie wpisz nazwę pliku, który chcesz otworzyć.

Wróć do kodu źródłowego projektu w programie Visual Studio Code.

Otwórz plik serwera/apiRoutes.ts i znajdź completeBYOD trasę. Ten interfejs API jest wywoływany po wybraniu przycisku Uzyskaj pomoc w oknie dialogowym Pomoc czatu. Pobiera on monit użytkownika z treści żądania i przekazuje go do completeBYOD() funkcji w pliku serwera/openAI.ts . Wyniki są następnie zwracane do klienta.

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

Otwórz plik serwera/openAI.ts i znajdź completeBYOD() funkcję.
```
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);
}
```
Ta funkcja ma następujące funkcje:
- Parametr userPrompt zawiera informacje wpisane przez użytkownika w oknie dialogowym pomocy czatu.
- zmienna systemPrompt definiuje, że asystent sztucznej inteligencji zaprojektowany w celu ułatwienia użytkownikom znajdowania informacji będzie używany.
- callOpenAI() służy do wywoływania interfejsu API usługi Azure OpenAI i zwracania wyników. systemPrompt Przekazuje wartości iuserPrompt, a także następujące parametry:
  - temperature - Ilość kreatywności, którą należy uwzględnić w odpowiedzi. Użytkownik potrzebuje spójnych (mniej kreatywnych) odpowiedzi w tym przypadku, więc wartość jest ustawiona na 0.
  - useBYOD — wartość logiczna wskazująca, czy należy używać funkcji wyszukiwania sztucznej inteligencji wraz z usługą Azure OpenAI. W takim przypadku jest ona ustawiona na true wartość , aby funkcja wyszukiwania sztucznej inteligencji była używana.

Funkcja callOpenAI() akceptuje useBYOD parametr używany do określania, która funkcja OpenAI ma być wywoływana. W tym przypadku ustawia useBYOD wartość na true , aby funkcja była wywoływana getAzureOpenAIBYODCompletion() .

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

getAzureOpenAIBYODCompletion() Znajdź funkcję na serwerze/openAI.ts. Jest ona bardzo podobna do getAzureOpenAICompletion() funkcji, którą zbadano wcześniej, ale jest wyświetlana jako osobna funkcja, aby wyróżnić kilka kluczowych różnic, które są unikatowe dla scenariusza "Azure OpenAI on your data" dostępnego w usłudze Azure OpenAI.
```
async function getAzureOpenAIBYODCompletion(systemPrompt: string, userPrompt: string, temperature: number): Promise<string> {
    const dataSources = [
        {
            type: 'azure_search',
            parameters: {
                authentication: {
                    type: 'api_key',
                    key: AZURE_AI_SEARCH_KEY
                },
                endpoint: AZURE_AI_SEARCH_ENDPOINT,
                index_name: AZURE_AI_SEARCH_INDEX
            }
        }
    ];

    const completion = await createAzureOpenAICompletion(systemPrompt, userPrompt, temperature, dataSources) as AzureOpenAIYourDataResponse;
    console.log('Azure OpenAI Add Your Own Data Output: \n', completion.choices[0]?.message);
    for (let citation of completion.choices[0]?.message?.context?.citations ?? []) {
        console.log('Citation Path:', citation.filepath);
    }
    return completion.choices[0]?.message?.content?.trim() ?? '';
}
```
Zwróć uwagę na następujące funkcje w getAzureOpenAIBYODCompletion() funkcji:
- Utworzono dataSources właściwość zawierającą wartości , endpoint, i index_name zasobu keywyszukiwania sztucznej .env inteligencji, które zostały dodane do pliku wcześniej w tym ćwiczeniu
- Funkcja jest wywoływana createAzureOpenAICompletion() za systemPromptpomocą wartości , userPrompt, temperaturei dataSources . Ta funkcja służy do wywoływania interfejsu API usługi Azure OpenAI i zwracania wyników.
- Gdy odpowiedź zostanie zwrócona, cytaty dokumentu są rejestrowane w konsoli programu . Zawartość komunikatu ukończenia jest następnie zwracana do elementu wywołującego.
Kilka ostatnich kwestii, które należy wziąć pod uwagę przed przejściem do następnego ćwiczenia:
- Przykładowa aplikacja używa pojedynczego indeksu w usłudze Azure AI Search. Za pomocą usługi Azure OpenAI można używać wielu indeksów i źródeł danych. Właściwość dataSources w getAzureOpenAIBYODCompletion() funkcji można zaktualizować w celu uwzględnienia wielu źródeł danych w razie potrzeby.
- Zabezpieczenia muszą być dokładnie oceniane przy użyciu tego typu scenariusza. Użytkownicy nie powinni mieć możliwości zadawania pytań i uzyskiwania wyników z dokumentów, do których nie mają dostępu.
Teraz, gdy znasz już interfejs Azure OpenAI, monity, uzupełnienia i sposób używania własnych danych, przejdźmy do następnego ćwiczenia, aby dowiedzieć się, jak można używać funkcji komunikacji w celu ulepszenia aplikacji. Jeśli chcesz dowiedzieć się więcej o usłudze Azure OpenAI, zapoznaj się z zawartością szkoleniową Wprowadzenie do usługi Azure OpenAI Service . Dodatkowe informacje na temat używania własnych danych z usługą Azure OpenAI można znaleźć w dokumentacji usługi Azure OpenAI .

Komunikacja: tworzenie zasobu usług Azure Communication Services

Pozostały czas: 87 min

Efektywna komunikacja jest niezbędna w przypadku udanych niestandardowych aplikacji biznesowych. Za pomocą usług Azure Communication Services (ACS) można dodawać do aplikacji funkcje, takie jak połączenia telefoniczne, czat na żywo, połączenia audio/wideo oraz wiadomości e-mail i SMS. Wcześniej wiesz już, jak usługa Azure OpenAI może generować uzupełnienia wiadomości e-mail i WIADOMOŚCI SMS. Teraz dowiesz się, jak wysyłać komunikaty. Razem usługi ACS i OpenAI mogą ulepszać aplikacje, upraszczając komunikację, poprawiając interakcje i zwiększając produktywność biznesową.

W tym ćwiczeniu wykonasz następujące czynności:

Utwórz zasób usług Azure Communication Services (ACS).
Dodaj bezpłatny numer telefonu z funkcjami połączeń telefonicznych i wiadomości SMS.
Połącz domenę poczty e-mail.
Zaktualizuj plik env projektu przy użyciu wartości z zasobu ACS.

Omówienie scenariusza chmury firmy Microsoft

Tworzenie zasobu usług Azure Communication Services

Odwiedź witrynę Azure Portal w przeglądarce i zaloguj się, jeśli jeszcze tego nie zrobiono.
Wpisz usługi komunikacyjne na pasku wyszukiwania w górnej części strony i wybierz pozycję Usługi komunikacyjne z wyświetlonych opcji.
Wybierz pozycję Utwórz na pasku narzędzi.
Wykonaj następujące zadania:
- Wybierz subskrypcję platformy Azure.
- Wybierz grupę zasobów do użycia (utwórz nową, jeśli nie istnieje).
- Wprowadź nazwę zasobu USŁUGI ACS. Ta wartość musi być unikatowa.
- Wybierz lokalizację danych.
Wybierz pozycję Przejrzyj i utwórz , a następnie pozycję Utwórz.
Pomyślnie utworzono nowy zasób usług Azure Communication Services! Następnie włączysz możliwości połączeń telefonicznych i wiadomości SMS. Połączysz również domenę poczty e-mail z zasobem.

Włączanie możliwości połączeń telefonicznych i wiadomości SMS

Dodaj numer telefonu i upewnij się, że numer telefonu ma włączone możliwości połączeń telefonicznych. Użyjesz tego numeru telefonu, aby zadzwonić na telefon z aplikacji.
- Wybierz pozycję Telefonia i SMS -->Numery telefonów z menu Zasób.
- Wybierz pozycję + Pobierz na pasku narzędzi (lub wybierz przycisk Pobierz liczbę ) i wprowadź następujące informacje:
  - Kraj lub region: United States
  - Typ numeru: Toll-free
  Uwaga
  
  Karta kredytowa jest wymagana w ramach subskrypcji platformy Azure, aby utworzyć bezpłatny numer. Jeśli nie masz karty na pliku, możesz pominąć dodawanie numeru telefonu i przejść do następnej sekcji ćwiczenia, które łączy domenę poczty e-mail. Nadal możesz używać aplikacji, ale nie będzie można wywołać numeru telefonu.
  - Numer: wybierz pozycję Dodaj do koszyka dla jednego z wymienionych numerów telefonów.
Wybierz pozycję Dalej, przejrzyj szczegóły numeru telefonu i wybierz pozycję Kup teraz.

Uwaga

Weryfikacja wiadomości SMS dla bezpłatnych numerów jest teraz obowiązkowa w Stany Zjednoczone i Kanadzie. Aby włączyć obsługę wiadomości SMS, musisz przesłać weryfikację po zakupie numeru telefonu. Chociaż ten samouczek nie przejdzie przez ten proces, możesz wybrać pozycję Telefonia i SMS -->Dokumenty regulacyjne z menu zasobów i dodać wymaganą dokumentację weryfikacji.
Po utworzeniu numeru telefonu wybierz go, aby przejść do panelu Funkcje . Upewnij się, że ustawiono następujące wartości (należy je ustawić domyślnie):
- W sekcji Wywoływanie wybierz pozycję Make calls.
- W sekcji SMS wybierz pozycję Send and receive SMS.
- Wybierz pozycję Zapisz.
Skopiuj wartość numeru telefonu do pliku do późniejszego użycia. Numer telefonu powinien być zgodny z tym ogólnym wzorcem: +12345678900.

Łączenie domeny poczty e-mail

Wykonaj następujące zadania, aby utworzyć połączoną domenę poczty e-mail dla zasobu usługi ACS, aby można było wysłać wiadomość e-mail. Będzie to używane do wysyłania wiadomości e-mail z aplikacji.
- Wybierz pozycję Poczta e-mail -> Domeny z menu Zasób.
- Wybierz pozycję Połącz domenę z paska narzędzi.
- Wybierz swoją subskrypcję i grupę zasobów.
- Na liście rozwijanej Usługa poczty e-mail wybierz pozycję Add an email service.
- Nadaj usłudze poczty e-mail nazwę, taką jak acs-demo-email-service.
- Wybierz pozycję Przejrzyj i utwórz , a następnie pozycję Utwórz.
- Po zakończeniu wdrażania wybierz pozycję Go to resource, a następnie wybierz pozycję 1-click add , aby dodać bezpłatną domenę podrzędną platformy Azure.
- Po dodaniu poddomeny (jej wdrożenie zajmie kilka chwil), wybierz ją.
- Po przejściu na ekranie AzureManagedDomain wybierz pozycję Usługi poczty e-mail -->MailFrom adresów z menu Zasób.
- Skopiuj wartość MailFrom do pliku. Użyjesz go później podczas aktualizowania pliku env .
- Wróć do zasobu usług Azure Communication Services i wybierz pozycję Poczta e-mail -->Domeny z menu zasobów.
- Wybierz Add domain i wprowadź MailFrom wartość z poprzedniego kroku (upewnij się, że wybrano poprawną subskrypcję, grupę zasobów i usługę poczty e-mail). Wybierz przycisk Connect.

`.env` Aktualizowanie pliku

Teraz, gdy twój numer telefonu ACS (z włączoną obsługą połączeń i wiadomości SMS) i domena poczty e-mail są gotowe, zaktualizuj następujące klucze/wartości w pliku env w projekcie:
```
ACS_CONNECTION_STRING=<ACS_CONNECTION_STRING>
ACS_PHONE_NUMBER=<ACS_PHONE_NUMBER>
ACS_EMAIL_ADDRESS=<ACS_EMAIL_ADDRESS>
CUSTOMER_EMAIL_ADDRESS=<EMAIL_ADDRESS_TO_SEND_EMAIL_TO>
CUSTOMER_PHONE_NUMBER=<UNITED_STATES_BASED_NUMBER_TO_SEND_SMS_TO>
```
- ACS_CONNECTION_STRINGconnection string: wartość z sekcji Klucze zasobu ACS.
- ACS_PHONE_NUMBER: Przypisz numer bezpłatny do ACS_PHONE_NUMBER wartości.
- ACS_EMAIL_ADDRESS: Przypisz wartość adresu e-mail "MailTo".
- CUSTOMER_EMAIL_ADDRESS: Przypisz adres e-mail, do którego chcesz wysłać wiadomość e-mail z aplikacji (ponieważ dane klienta w bazie danych aplikacji są tylko przykładowymi danymi). Możesz użyć osobistego adresu e-mail.
- CUSTOMER_PHONE_NUMBER: Musisz podać Stany Zjednoczone oparty na numerze telefonu (od dzisiaj) ze względu na dodatkową weryfikację wymaganą w innych krajach do wysyłania wiadomości SMS. Jeśli nie masz numeru opartego na Stanach Zjednoczonych, możesz pozostawić go pusty.

Uruchamianie/ponowne uruchamianie serwerów aplikacji i interfejsów API

Wykonaj jedną z następujących czynności na podstawie wykonanych ćwiczeń do tego momentu:

Jeśli uruchomiono bazę danych, serwer interfejsu API i serwer internetowy we wcześniejszym ćwiczeniu, musisz zatrzymać serwer interfejsu API i serwer internetowy i ponownie uruchomić je, aby pobrać zmiany w pliku env . Możesz pozostawić uruchomioną bazę danych.

Znajdź okna terminalu z uruchomionym serwerem interfejsu API i serwerem internetowym, a następnie naciśnij CTRL + C , aby je zatrzymać. Uruchom je ponownie, wpisując npm start w każdym oknie terminalu i naciskając Enter. Przejdź do następnego ćwiczenia.
Jeśli baza danych, serwer interfejsu API i serwer internetowy nie zostały jeszcze uruchomione, wykonaj następujące kroki:
1. W poniższych krokach utworzysz trzy okna terminalowe w programie Visual Studio Code.
2. Kliknij prawym przyciskiem myszy plik env na liście plików programu Visual Studio Code i wybierz polecenie Otwórz w zintegrowanym terminalu. Przed kontynuowaniem upewnij się, że terminal znajduje się w katalogu głównym projektu — openai-acs-msgraph .
3. Wybierz jedną z następujących opcji, aby uruchomić bazę danych PostgreSQL:
  - Jeśli masz zainstalowany i uruchomiony program Docker Desktop , uruchom polecenie docker-compose up w oknie terminalu i naciśnij Enter.
  - Jeśli masz zainstalowaną i uruchomioną aplikację Podman-compose , uruchom polecenie podman-compose up w oknie terminalu i naciśnij Enter.
  - Aby uruchomić kontener PostgreSQL bezpośrednio przy użyciu programu Docker Desktop, Podman, nerdctl lub innego zainstalowanego środowiska uruchomieniowego kontenera, uruchom następujące polecenie w oknie terminalu:
    - Komputery Mac, Linux lub Podsystem Windows dla systemu 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 z programem 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. Po uruchomieniu kontenera bazy danych naciśnij ikonę + na pasku narzędzi terminalu programu Visual Studio Code, aby utworzyć drugie okno terminalu.
5. cd w folderze server/typescript uruchom następujące polecenia, aby zainstalować zależności i uruchomić serwer interfejsu API.
  - npm install
  - npm start
6. Naciśnij ponownie ikonę + na pasku narzędzi terminalu programu Visual Studio Code, aby utworzyć trzecie okno terminalu.
7. cd w folderze klienta i uruchom następujące polecenia, aby zainstalować zależności i uruchomić serwer internetowy.
  - npm install
  - npm start
8. Zostanie uruchomiona przeglądarka i nastąpi przekierowanie do http://localhost:4200.

Komunikacja: nawiązywanie połączenia telefonicznego

Pozostały czas: 79 min

Integrowanie funkcji połączeń telefonicznych usług Azure Communication Services z niestandardową aplikacją loB (Line of Business) oferuje kilka kluczowych korzyści dla firm i ich użytkowników:

Umożliwia bezproblemową i w czasie rzeczywistym komunikację między pracownikami, klientami i partnerami bezpośrednio z poziomu aplikacji LOB, eliminując konieczność przełączania się między wieloma platformami lub urządzeniami.
Zwiększa środowisko użytkownika i zwiększa ogólną wydajność operacyjną.
Ułatwia szybkie rozwiązywanie problemów, ponieważ użytkownicy mogą szybko łączyć się z odpowiednimi zespołami pomocy technicznej lub ekspertami w danej dziedzinie szybko i łatwo.

W tym ćwiczeniu wykonasz następujące czynności:

Zapoznaj się z funkcją połączeń telefonicznych w aplikacji.
Zapoznaj się z kodem, aby dowiedzieć się, jak jest utworzona funkcja połączeń telefonicznych.

Korzystanie z funkcji połączenia telefonicznego

W poprzednim ćwiczeniu utworzono zasób usług Azure Communication Services (ACS) i uruchomiono bazę danych, serwer internetowy i serwer interfejsu API. Zaktualizowano również następujące wartości w pliku env .
```
ACS_CONNECTION_STRING=<ACS_CONNECTION_STRING>
ACS_PHONE_NUMBER=<ACS_PHONE_NUMBER>
ACS_EMAIL_ADDRESS=<ACS_EMAIL_ADDRESS>
CUSTOMER_EMAIL_ADDRESS=<EMAIL_ADDRESS_TO_SEND_EMAIL_TO>
CUSTOMER_PHONE_NUMBER=<UNITED_STATES_BASED_NUMBER_TO_SEND_SMS_TO>
```
Przed kontynuowaniem upewnij się, że wykonano poprzednie ćwiczenie .
Wróć do przeglądarki (http://localhost:4200), znajdź usługę datagrid i wybierz pozycję Skontaktuj się z klientem , a następnie w pierwszym wierszu skontaktuj się z klientem .
Składnik połączenia telefonicznego zostanie dodany do nagłówka. Wprowadź numer telefonu, który chcesz zadzwonić (upewnij się, że rozpoczyna się od + i zawiera kod kraju), a następnie wybierz pozycję Zadzwoń. Zostanie wyświetlony monit o zezwolenie na dostęp do mikrofonu.
Wybierz pozycję Zawieszaj się , aby zakończyć połączenie. Wybierz pozycję Zamknij , aby zamknąć składnik połączenia telefonicznego.

Eksplorowanie kodu rozmów telefonicznych

Napiwek

Jeśli używasz programu Visual Studio Code, możesz otwierać pliki bezpośrednio, wybierając pozycję:

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

Następnie wpisz nazwę pliku, który chcesz otworzyć.

Otwórz plik customers-list.component.ts. Pełna ścieżka do pliku to client/src/app/customers-list/customers-list.component.ts.
Należy pamiętać, że openCallDialog() wysyła CustomerCall wiadomość i numer telefonu klienta przy użyciu magistrali zdarzeń.
```
openCallDialog(data: Phone) {
    this.eventBus.emit({ name: Events.CustomerCall, value: data });
}
```
Uwaga

Kod magistrali zdarzeń można znaleźć w pliku eventbus.service.ts , jeśli chcesz go dokładniej eksplorować. Pełna ścieżka do pliku to client/src/app/core/eventbus.service.ts.

Funkcja składnika nagłówka ngOnInit() subskrybuje CustomerCall zdarzenie wysyłane przez magistralę zdarzeń i wyświetla składnik połączenia telefonicznego. Ten kod można znaleźć w 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
        })
    );
}

Otwórz phone-call.component.ts. Pośmiń chwilę, aby wyeksponować kod. Pełna ścieżka do pliku to client/src/app/phone-call/phone-call.component.ts. Zwróć uwagę na następujące kluczowe funkcje:
- Pobiera token dostępu usług Azure Communication Services przez wywołanie acsService.getAcsToken() funkcji w pliku ngOnInit();
- Dodaje do strony "numer telefonu". Możesz wyświetlić numer telefonu, klikając numer telefonu w nagłówku.
- Uruchamia i kończy wywołanie, używając startCall() odpowiednio funkcji i endCall() .
Przed przyjrzeniem się kodowi, który wykonuje połączenie telefoniczne, sprawdźmy, jak jest pobierany token dostępu ACS i jak są tworzone obiekty połączeń telefonicznych. ngOnInit() Znajdź funkcję w 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);
            })
        );
    }
}
```
Ta funkcja wykonuje następujące akcje:
- Pobiera identyfikator użytkownika usługi ACS i token dostępu przez wywołanie acsService.getAcsToken() funkcji.
- Po pobraniu tokenu dostępu kod wykonuje następujące akcje:
  - Tworzy nowe wystąpienie elementu CallClient i AzureCommunicationTokenCredential przy użyciu tokenu dostępu.
  - Tworzy nowe wystąpienie CallAgent obiektu CallClient i AzureCommunicationTokenCredential . Później zobaczysz, że CallAgent służy do uruchamiania i kończenia wywołania.
Otwórz acs.services.ts i znajdź getAcsToken() funkcję . Pełna ścieżka do pliku to client/src/app/core/acs.service.ts. Funkcja wysyła żądanie HTTP GET do /acstoken trasy uwidocznionej przez serwer interfejsu API.
```
getAcsToken(): Observable<AcsUser> {
    return this.http.get<AcsUser>(this.apiUrl + 'acstoken')
    .pipe(
        catchError(this.handleError)
    );
}
```
Funkcja serwera interfejsu API o nazwie createACSToken() pobiera identyfikator userId i token dostępu i zwraca ją do klienta. Można go znaleźć w pliku 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 };
}
```
Ta funkcja wykonuje następujące akcje:
- Sprawdza, czy wartość usługi ACS connectionString jest dostępna. Jeśli nie, zwraca obiekt z pustym userId elementem i token.
- Tworzy nowe wystąpienie CommunicationIdentityClient klasy i przekazuje connectionString do niej wartość.
- Tworzy nowego użytkownika i tokenu przy użyciu tokenClient.createUserAndToken() zakresu "voip".
- Zwraca obiekt zawierający userId wartości i token .
Teraz, gdy już wiesz, jak pobrano identyfikator userId i token, wróć do phone-call.component.ts funkcji i znajdź tę startCall() funkcję.

Ta funkcja jest wywoływana po wybraniu połączenia w składniku połączenia telefonicznego. Używa obiektu wymienionego CallAgent wcześniej do uruchomienia wywołania. Funkcja callAgent.startCall() akceptuje obiekt reprezentujący numer do wywołania i numer telefonu ACS użyty do nawiązania połączenia.

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

Funkcja jest wywoływana endCall() po wybraniu funkcji Hang Up w składniku połączenia telefonicznego.
```
endCall() {
    if (this.call) {
        this.call.hangUp({ forEveryone: true });
        this.call = undefined;
        this.inCall = false;
    }
    else {
        this.hangup.emit();
    }
}
```
Jeśli wywołanie jest w toku, funkcja jest wywoływana w call.hangUp() celu zakończenia wywołania. Jeśli żadne wywołanie nie jest w toku, hangup zdarzenie jest emitowane do składnika nadrzędnego nagłówka w celu ukrycia składnika połączenia telefonicznego.
Przed przejściem do następnego ćwiczenia przejrzyjmy kluczowe pojęcia omówione w tym ćwiczeniu:
- Identyfikator użytkownika usługi ACS i token dostępu są pobierane z serwera interfejsu acsService.createUserAndToken() API przy użyciu funkcji .
- Token jest używany do tworzenia CallClient obiektu i CallAgent .
- Obiekt jest używany do uruchamiania CallAgent i kończenia wywołania przez wywołanie callAgent.startCall() odpowiednio funkcji i callAgent.hangUp() .
Teraz, gdy wiesz już, jak można zintegrować połączenia telefoniczne z aplikacją, przełączmy naszą koncentrację na używanie usług Azure Communication Services w celu wysyłania wiadomości e-mail i wiadomości SMS.

Komunikacja: wysyłanie wiadomości e-mail i wiadomości SMS

Pozostały czas: 69 min

Oprócz połączeń telefonicznych usługi Azure Communication Services mogą również wysyłać wiadomości e-mail i SMS. Może to być przydatne, gdy chcesz wysłać wiadomość do klienta lub innego użytkownika bezpośrednio z aplikacji.

W tym ćwiczeniu wykonasz następujące czynności:

Dowiedz się, jak można wysyłać wiadomości e-mail i SMS z aplikacji.
Zapoznaj się z kodem, aby dowiedzieć się, jak zaimplementowano funkcję poczty e-mail i wiadomości SMS.

Korzystanie z funkcji poczty e-mail i wiadomości SMS

W poprzednim ćwiczeniu utworzono zasób usług Azure Communication Services (ACS) i uruchomiono bazę danych, serwer internetowy i serwer interfejsu API. Zaktualizowano również następujące wartości w pliku env .
```
ACS_CONNECTION_STRING=<ACS_CONNECTION_STRING>
ACS_PHONE_NUMBER=<ACS_PHONE_NUMBER>
ACS_EMAIL_ADDRESS=<ACS_EMAIL_ADDRESS>
CUSTOMER_EMAIL_ADDRESS=<EMAIL_ADDRESS_TO_SEND_EMAIL_TO>
CUSTOMER_PHONE_NUMBER=<UNITED_STATES_BASED_NUMBER_TO_SEND_SMS_TO>
```
Przed kontynuowaniem upewnij się, że wykonano ćwiczenie .
Wróć do przeglądarki (http://localhost:4200) i wybierz pozycję Skontaktuj się z klientem, a następnie pozycję E-mail/SMS Customer w pierwszym wierszu.
Wybierz kartę Poczta e-mail/sms i wykonaj następujące zadania:
- Wprowadź temat wiadomości e-mail i treść, a następnie wybierz przycisk Wyślij wiadomość e-mail.
- Wprowadź wiadomość SMS i wybierz przycisk Wyślij wiadomość SMS .
Uwaga

Weryfikacja wiadomości SMS dla bezpłatnych numerów jest teraz obowiązkowa w Stany Zjednoczone i Kanadzie. Aby włączyć obsługę wiadomości SMS, musisz przesłać weryfikację po zakupie numeru telefonu. Chociaż ten samouczek nie przejdzie przez ten proces, możesz wybrać pozycję Telefonia i sms -->Regulatory Documents z zasobu usług Azure Communication Services w witrynie Azure Portal i dodać wymaganą dokumentację weryfikacji.
Sprawdź, czy odebrano wiadomości e-mail i SMS. Funkcjonalność wiadomości SMS będzie działać tylko wtedy, gdy przesłano dokumenty regulacyjne wymienione w poprzedniej notatce. Przypominamy, że wiadomość e-mail zostanie wysłana do wartości zdefiniowanej dla , a wiadomość SMS zostanie wysłana do wartości zdefiniowanej CUSTOMER_EMAIL_ADDRESS CUSTOMER_PHONE_NUMBER w pliku env. Jeśli nie możesz podać Stany Zjednoczone numeru telefonu do użycia dla wiadomości SMS, możesz pominąć ten krok.

Uwaga

Jeśli w skrzynce odbiorczej nie widzisz wiadomości e-mail dla adresu zdefiniowanego CUSTOMER_EMAIL_ADDRESS w pliku env , sprawdź folder spamu.

Eksplorowanie kodu wiadomości e-mail

Napiwek

Jeśli używasz programu Visual Studio Code, możesz otwierać pliki bezpośrednio, wybierając pozycję:

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

Następnie wpisz nazwę pliku, który chcesz otworzyć.

Otwórz plik customers-list.component.ts. Pełna ścieżka do pliku to client/src/app/customers-list/customers-list.component.ts.

Po wybraniu pozycji Kontakt z klientem , a następnie e-mail /SMS Customer w usłudze datagrid, customer-list składnik wyświetli okno dialogowe. Jest to obsługiwane przez openEmailSmsDialog() funkcję w pliku customer-list.component.ts .

openEmailSmsDialog(data: any) {
    if (data.phone && data.email) {
        // Create the data for the dialog
        let dialogData: EmailSmsDialogData = {
            prompt: '',
            title: `Contact ${data.company}`,
            company: data.company,
            customerName: data.first_name + ' ' + data.last_name,
            customerEmailAddress: data.email,
            customerPhoneNumber: data.phone
        }

        // Open the dialog
        const dialogRef = this.dialog.open(EmailSmsDialogComponent, {
            data: dialogData
        });

        // Subscribe to the dialog afterClosed observable to get the dialog result
        this.subscription.add(
            dialogRef.afterClosed().subscribe((response: EmailSmsDialogData) => {
                console.log('SMS dialog result:', response);
                if (response) {
                    dialogData = response;
                }
            })
        );
    }
    else {
        alert('No phone number available.');
    }
}

Funkcja openEmailSmsDialog() wykonuje następujące zadania:

Sprawdza, czy data obiekt (który reprezentuje wiersz z usługi datagrid) zawiera phone właściwość i email . Jeśli tak, tworzy dialogData obiekt zawierający informacje przekazywane do okna dialogowego.
EmailSmsDialogComponent Otwiera okno dialogowe i przekazuje dialogData do niego obiekt.
Subskrybuje afterClosed() zdarzenie okna dialogowego. To zdarzenie jest wyzwalane po zamknięciu okna dialogowego. Obiekt response zawiera informacje wprowadzone w oknie dialogowym.

Otwórz plik email-sms-dialog.component.ts. Pełna ścieżka do pliku to client/src/app/email-sms-dialog/email-sms-dialog.component.ts.
sendEmail() Znajdź funkcję:
```
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
    }
}
```
Funkcja sendEmail() wykonuje następujące zadania:
- Sprawdza, czy flaga acsEmailEnabled funkcji jest ustawiona na true. Ta flaga sprawdza, czy zmienna ACS_EMAIL_ADDRESS środowiskowa ma przypisaną wartość.
- Jeśli acsEmailEnabled ma wartość true, funkcja jest wywoływana, acsService.sendEmail() a temat wiadomości e-mail, treść, nazwa klienta i adres e-mail klienta są przekazywane. Ponieważ baza danych zawiera przykładowe dane, zmienna CUSTOMER_EMAIL_ADDRESS środowiskowa jest używana zamiast this.data.email. W rzeczywistej aplikacji this.data.email wartość będzie używana.
- Subskrybuje funkcję w usłudze sendEmail() acsService . Ta funkcja zwraca obserwowalny zestaw RxJS zawierający odpowiedź z usługi po stronie klienta.
- Jeśli wiadomość e-mail została wysłana pomyślnie, właściwość jest ustawiona emailSent na truewartość .
Aby zapewnić lepszą hermetyzację kodu i używać ich ponownie, usługi po stronie klienta, takie jak acs.service.ts , są używane w całej aplikacji. Dzięki temu wszystkie funkcje usługi ACS można skonsolidować w jednym miejscu.
Otwórz acs.service.ts i znajdź sendEmail() funkcję. Pełna ścieżka do pliku to 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)
    );
}
```
Funkcja sendEmail() w programie AcsService wykonuje następujące zadania:
- http.post() Wywołuje funkcję i przekazuje do niej temat wiadomości e-mail, wiadomość, nazwę klienta i adres e-mail klienta. Funkcja http.post() zwraca obserwowalny zestaw RxJS zawierający odpowiedź wywołania interfejsu API.
- Obsługuje wszelkie błędy zwracane przez http.post() funkcję przy użyciu operatora RxJS catchError .
Teraz sprawdźmy, jak aplikacja współdziała z funkcją poczty e-mail usługi ACS. Otwórz plik acs.ts i znajdź sendEmail() funkcję. Pełna ścieżka do pliku to server/typescript/acs.ts.
Funkcja sendEmail() wykonuje następujące zadania:
- Tworzy nowy EmailClient obiekt i przekazuje parametry połączenia ACS do niego (ta wartość jest pobierana ze zmiennej środowiskowejACS_CONNECTION_STRING).
```
const emailClient = new EmailClient(connectionString);
```
- Tworzy nowy EmailMessage obiekt i przekazuje informacje nadawcy, tematu, wiadomości i adresata.
```
const msgObject: EmailMessage = {
    senderAddress: process.env.ACS_EMAIL_ADDRESS as string,
    content: {
        subject: subject,
        plainText: message,
    },
    recipients: {
        to: [
            {
                address: customerEmailAddress,
                displayName: customerName,
            },
        ],
    },
};
```
- Wysyła wiadomość e-mail przy użyciu emailClient.beginSend() funkcji i zwraca odpowiedź. Mimo że funkcja wysyła tylko do jednego adresata w tym przykładzie, beginSend() funkcja może służyć do wysyłania do wielu adresatów.
```
const poller = await emailClient.beginSend(msgObject);
```
- Czeka, aż poller obiekt będzie sygnalizować, że jest on wykonany i wysyła odpowiedź do obiektu wywołującego.

Eksplorowanie kodu SMS

Wróć do otwartego wcześniej pliku email-sms-dialog.component.ts . Pełna ścieżka do pliku to client/src/app/email-sms-dialog/email-sms-dialog.component.ts.
sendSms() Znajdź funkcję:
```
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;
    }
}
```
Funkcja sendSMS() wykonuje następujące zadania:
- Sprawdza, czy flaga acsPhoneEnabled funkcji jest ustawiona na true. Ta flaga sprawdza, czy zmienna ACS_PHONE_NUMBER środowiskowa ma przypisaną wartość.
- Jeśli acsPhoneEnabled ma wartość true, funkcja jest wywoływana, acsService.SendSms() a wiadomość SMS i numer telefonu klienta są przekazywane. Ponieważ baza danych zawiera przykładowe dane, zmienna CUSTOMER_PHONE_NUMBER środowiskowa jest używana zamiast this.data.customerPhoneNumber. W rzeczywistej aplikacji this.data.customerPhoneNumber wartość będzie używana.
- Subskrybuje funkcję w usłudze sendSms() acsService . Ta funkcja zwraca obserwowalny zestaw RxJS zawierający odpowiedź z usługi po stronie klienta.
- Jeśli wiadomość SMS została wysłana pomyślnie, ustawia smsSent właściwość na true.
Otwórz acs.service.ts i znajdź sendSms() funkcję. Pełna ścieżka do pliku to 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)
    );
}  
```
Funkcja sendSms() wykonuje następujące zadania:
- http.post() Wywołuje funkcję i przekazuje do niej komunikat i numer telefonu klienta. Funkcja http.post() zwraca obserwowalny zestaw RxJS zawierający odpowiedź wywołania interfejsu API.
- Obsługuje wszelkie błędy zwracane przez http.post() funkcję przy użyciu operatora RxJS catchError .
Na koniec sprawdźmy, jak aplikacja współdziała z funkcją programu ACS SMS. Otwórz plik acs.ts. Pełną ścieżką do pliku jest serwer/typescript/acs.ts i znajdź sendSms() funkcję.
Funkcja sendSms() wykonuje następujące zadania:
- Tworzy nowy SmsClient obiekt i przekazuje parametry połączenia ACS do niego (ta wartość jest pobierana ze zmiennej środowiskowejACS_CONNECTION_STRING).
```
const smsClient = new SmsClient(connectionString);
```
- smsClient.send() Wywołuje funkcję i przekazuje numer telefonu ACS (from), numer telefonu klienta (to) i wiadomość SMS:
```
const sendResults = await smsClient.send({
    from: process.env.ACS_PHONE_NUMBER as string,
    to: [customerPhoneNumber],
    message: message
});
return sendResults;
```
- Zwraca odpowiedź na obiekt wywołujący.
Więcej informacji na temat funkcji wiadomości e-mail i wiadomości SMS usługi ACS można uzyskać w następujących artykułach:
- Poczta e-mail w usługach Azure Communication Services
- Sms w usługach Azure Communication Services
Przed przejściem do następnego ćwiczenia przejrzyjmy kluczowe pojęcia omówione w tym ćwiczeniu:
- Plik acs.service.ts hermetyzuje funkcje poczty e-mail i wiadomości SMS usługi ACS używane przez aplikację po stronie klienta. Obsługuje wywołania interfejsu API do serwera i zwraca odpowiedź na obiekt wywołujący.
- Interfejs API po stronie serwera używa usług ACS EmailClient i SmsClient obiektów do wysyłania wiadomości e-mail i wiadomości SMS.
Teraz, gdy wiesz już, jak można wysyłać wiadomości e-mail i SMS, przełączmy naszą koncentrację na integrowanie danych organizacji z aplikacją.

Dane organizacyjne: tworzenie rejestracji aplikacji entra ID firmy Microsoft

Pozostały czas: 59 min

Zwiększ produktywność użytkowników, integrując dane organizacyjne (wiadomości e-mail, pliki, czaty i zdarzenia kalendarza) bezpośrednio z aplikacjami niestandardowymi. Korzystając z interfejsów API programu Microsoft Graph i identyfikatora Entra firmy Microsoft, można bezproblemowo pobierać i wyświetlać odpowiednie dane w aplikacjach, co zmniejsza potrzebę przełączania kontekstu przez użytkowników. Niezależnie od tego, czy odwołuje się ona do wiadomości e-mail wysłanej do klienta, przeglądania wiadomości usługi Teams, czy uzyskiwania dostępu do pliku, użytkownicy mogą szybko znaleźć potrzebne informacje bez opuszczania aplikacji, usprawniając proces podejmowania decyzji.

W tym ćwiczeniu wykonasz następujące czynności:

Utwórz rejestrację aplikacji Microsoft Entra ID, aby program Microsoft Graph mógł uzyskiwać dostęp do danych organizacji i wprowadzać je do aplikacji.
Znajdź team i channel identyfikatory z usługi Microsoft Teams, które są potrzebne do wysyłania wiadomości czatu do określonego kanału.
Zaktualizuj plik env projektu przy użyciu wartości z rejestracji aplikacji Microsoft Entra ID.

Omówienie scenariusza chmury firmy Microsoft

Tworzenie rejestracji aplikacji Microsoft Entra ID

Przejdź do witryny Azure Portal i wybierz pozycję Microsoft Entra ID.
Wybierz pozycję Zarządzaj -->Rejestracje aplikacji, a następnie pozycję + Nowa rejestracja.
Wypełnij szczegóły nowego formularza rejestracji aplikacji, jak pokazano poniżej, a następnie wybierz pozycję Zarejestruj:
- Nazwa: microsoft-graph-app
- Obsługiwane typy kont: konta w dowolnym katalogu organizacyjnym (dowolna dzierżawa identyfikatora entra firmy Microsoft — wielodostępna)
- Adres URI przekierowania:
  - Wybierz pozycję Aplikacja jednostronicowa (SPA) i wprowadź http://localhost:4200 wartość w polu Identyfikator URI przekierowania.
- Wybierz pozycję Zarejestruj, aby utworzyć rejestrację aplikacji.

Wybierz pozycję Przegląd w menu zasobów i skopiuj Application (client) ID wartość do schowka.

Aktualizowanie pliku env projektu

Otwórz plik env w edytorze i przypisz Application (client) ID wartość do ENTRAID_CLIENT_ID.
```
ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
```
Jeśli chcesz włączyć możliwość wysyłania komunikatu z aplikacji do kanału usługi Teams, zaloguj się do usługi Microsoft Teams przy użyciu konta dzierżawy usługi Microsoft 365 (jest to wymienione w sekcji przed ponownymi pytaniami dotyczącymi tego samouczka).
Po zalogowaniu rozwiń zespół i znajdź kanał, do którego chcesz wysyłać komunikaty z aplikacji. Możesz na przykład wybrać zespół firmy i kanał Ogólny (lub dowolny zespół/kanał, którego chcesz użyć).
W nagłówku zespołu kliknij trzy kropki (...) i wybierz pozycję Pobierz link do zespołu.
W linku wyświetlanym w oknie podręcznym identyfikator zespołu to ciąg liter i cyfr po team/. Na przykład w linku "https://teams.microsoft.com/l/team/19%3ae9b9.../"identyfikator zespołu to 19%3ae9b9... maksymalnie do następującego / znaku.
Skopiuj identyfikator zespołu i przypisz go do TEAM_ID pliku env .
W nagłówku kanału kliknij trzy kropki (...) i wybierz pozycję Pobierz link do kanału.
W linku wyświetlanym w oknie podręcznym identyfikator kanału jest ciągiem liter i cyfr po channel/. Na przykład w linku "https://teams.microsoft.com/l/channel/19%3aQK02.../"identyfikator kanału to 19%3aQK02... maksymalnie do następującego / znaku.
Skopiuj identyfikator kanału i przypisz go do CHANNEL_ID pliku env .
Zapisz plik env przed kontynuowaniem.

Uruchamianie/ponowne uruchamianie serwerów aplikacji i interfejsów API

Wykonaj jedną z następujących czynności na podstawie wykonanych ćwiczeń do tego momentu:

Jeśli uruchomiono bazę danych, serwer interfejsu API i serwer internetowy we wcześniejszym ćwiczeniu, musisz zatrzymać serwer interfejsu API i serwer internetowy i ponownie uruchomić je, aby pobrać zmiany w pliku env . Możesz pozostawić uruchomioną bazę danych.

Znajdź okna terminalu z uruchomionym serwerem interfejsu API i serwerem internetowym, a następnie naciśnij CTRL + C , aby je zatrzymać. Uruchom je ponownie, wpisując npm start w każdym oknie terminalu i naciskając Enter. Przejdź do następnego ćwiczenia.
Jeśli baza danych, serwer interfejsu API i serwer internetowy nie zostały jeszcze uruchomione, wykonaj następujące kroki:
1. W poniższych krokach utworzysz trzy okna terminalowe w programie Visual Studio Code.
2. Kliknij prawym przyciskiem myszy plik env na liście plików programu Visual Studio Code i wybierz polecenie Otwórz w zintegrowanym terminalu. Przed kontynuowaniem upewnij się, że terminal znajduje się w katalogu głównym projektu — openai-acs-msgraph .
3. Wybierz jedną z następujących opcji, aby uruchomić bazę danych PostgreSQL:
  - Jeśli masz zainstalowany i uruchomiony program Docker Desktop , uruchom polecenie docker-compose up w oknie terminalu i naciśnij Enter.
  - Jeśli masz zainstalowaną i uruchomioną aplikację Podman-compose , uruchom polecenie podman-compose up w oknie terminalu i naciśnij Enter.
  - Aby uruchomić kontener PostgreSQL bezpośrednio przy użyciu programu Docker Desktop, Podman, nerdctl lub innego zainstalowanego środowiska uruchomieniowego kontenera, uruchom następujące polecenie w oknie terminalu:
    - Komputery Mac, Linux lub Podsystem Windows dla systemu 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 z programem 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. Po uruchomieniu kontenera bazy danych naciśnij ikonę + na pasku narzędzi terminalu programu Visual Studio Code, aby utworzyć drugie okno terminalu.
5. cd w folderze server/typescript uruchom następujące polecenia, aby zainstalować zależności i uruchomić serwer interfejsu API.
  - npm install
  - npm start
6. Naciśnij ponownie ikonę + na pasku narzędzi terminalu programu Visual Studio Code, aby utworzyć trzecie okno terminalu.
7. cd w folderze klienta i uruchom następujące polecenia, aby zainstalować zależności i uruchomić serwer internetowy.
  - npm install
  - npm start
8. Zostanie uruchomiona przeglądarka i nastąpi przekierowanie do http://localhost:4200.

Dane organizacyjne: logowanie użytkownika i uzyskiwanie tokenu dostępu

Pozostały czas: 51 min

Użytkownicy muszą uwierzytelniać się przy użyciu identyfikatora Entra firmy Microsoft, aby program Microsoft Graph uzyskiwał dostęp do danych organizacji. W tym ćwiczeniu zobaczysz, jak składnik zestawu narzędzi Microsoft Graph Toolkit mgt-login może służyć do uwierzytelniania użytkowników i pobierania tokenu dostępu. Token dostępu może następnie służyć do nawiązywania wywołań do programu Microsoft Graph.

Uwaga

Jeśli dopiero zaczynasz korzystać z programu Microsoft Graph, możesz dowiedzieć się więcej o nim w ścieżce szkoleniowej Podstawy programu Microsoft Graph.

W tym ćwiczeniu wykonasz następujące czynności:

Dowiedz się, jak skojarzyć aplikację Microsoft Entra ID z zestawem narzędzi Microsoft Graph Toolkit w celu uwierzytelniania użytkowników i pobierania danych organizacji.
Dowiedz się więcej o znaczeniu zakresów.
Dowiedz się, jak składnik mgt-login zestawu narzędzi microsoft Graph może służyć do uwierzytelniania użytkowników i pobierania tokenu dostępu.

W poprzednim ćwiczeniu utworzono rejestrację aplikacji w usłudze Microsoft Entra ID i uruchomiono serwer aplikacji i serwer interfejsu API. Zaktualizowano również następujące wartości w .env pliku (TEAM_ID i CHANNEL_ID są opcjonalne):
```
ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
TEAM_ID=<TEAMS_TEAM_ID>
CHANNEL_ID=<TEAMS_CHANNEL_ID>
```
Przed kontynuowaniem upewnij się, że wykonano poprzednie ćwiczenie .
Wróć do przeglądarki (http://localhost:4200), wybierz pozycję Zaloguj się w nagłówku i zaloguj się przy użyciu konta użytkownika administratora z dzierżawy deweloperów platformy Microsoft 365.

Napiwek

Zaloguj się przy użyciu konta administratora dzierżawy dewelopera platformy Microsoft 365. Możesz wyświetlić innych użytkowników w dzierżawie deweloperów, przechodząc do Centrum administracyjne platformy Microsoft 365.
Jeśli logujesz się do aplikacji po raz pierwszy, zostanie wyświetlony monit o wyrażenie zgody na uprawnienia żądane przez aplikację. Więcej informacji na temat tych uprawnień (nazywanych również "zakresami") znajdziesz w następnej sekcji podczas eksplorowania kodu. Wybierz pozycję Akceptuj , aby kontynuować.
Po zalogowaniu powinna zostać wyświetlona nazwa użytkownika wyświetlana w nagłówku.

Po zalogowaniu przyjrzyjmy się kodowi użytemu do zalogowania użytkownika i pobraniu tokenu dostępu i profilu użytkownika. Poznasz składnik internetowy mgt-login , który jest częścią zestawu narzędzi Microsoft Graph Toolkit.

Napiwek

Jeśli używasz programu Visual Studio Code, możesz otwierać pliki bezpośrednio, wybierając pozycję:

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

Następnie wpisz nazwę pliku, który chcesz otworzyć.

Otwórz klienta/package.json i zwróć uwagę, że @microsoft/mgt pakiety i @microsoft/mgt-components są uwzględnione w zależnościach. Pakiet @microsoft/mgt zawiera funkcje dostawcy biblioteki MSAL (Microsoft Authentication Library) i składniki internetowe, takie jak mgt-login i inne, które mogą służyć do logowania użytkowników i pobierania i wyświetlania danych organizacji.
Otwórz klienta/src/main.ts i zwróć uwagę na następujące importy z @microsoft/mgt-components pakietu. Zaimportowane symbole służą do rejestrowania składników zestawu narzędzi Microsoft Graph Toolkit używanych w aplikacji.
```
import { registerMgtLoginComponent, registerMgtSearchResultsComponent, registerMgtPersonComponent,  } from '@microsoft/mgt-components';
```
Przewiń do dołu pliku i zanotuj następujący kod:
```
registerMgtLoginComponent();
registerMgtSearchResultsComponent();
registerMgtPersonComponent();
```
Ten kod rejestruje mgt-loginskładniki , mgt-search-resultsi mgt-person sieci Web i umożliwia ich używanie w aplikacji.
Aby użyć składnika mgt-login do logowania użytkowników, należy odwołać się i użyć identyfikatora klienta aplikacji Microsoft Entra ID (przechowywanego w pliku env jako ENTRAID_CLIENT_ID).
Otwórz graph.service.ts i znajdź init() funkcję . Pełna ścieżka do pliku to client/src/app/core/graph.service.ts. Zobaczysz następujący import i kod:
```
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');
    }
}
```
Ten kod tworzy nowy Msal2Provider obiekt, przekazując identyfikator klienta Microsoft Entra ID z rejestracji aplikacji oraz identyfikator scopes , dla którego aplikacja będzie żądać dostępu. Są scopes one używane do żądania dostępu do zasobów programu Microsoft Graph, do których aplikacja będzie uzyskiwać dostęp. Po utworzeniu Msal2Provider obiektu zostanie on przypisany do Providers.globalProvider obiektu, który jest używany przez składniki zestawu narzędzi Microsoft Graph do pobierania danych z programu Microsoft Graph.
Otwórz header.component.html w edytorze i znajdź składnik mgt-login . Pełna ścieżka do pliku jest client/src/app/header/header.component.html.
```
@if (this.featureFlags.microsoft365Enabled) {
    <mgt-login class="mgt-dark" (loginCompleted)="loginCompleted()"></mgt-login>
}
```
Składnik mgt-login umożliwia logowanie użytkownika i zapewnia dostęp do tokenu używanego w programie Microsoft Graph. Po pomyślnym zalogowaniu loginCompleted zdarzenie jest wyzwalane, co wywołuje loginCompleted() funkcję. Mimo że mgt-login jest używany w składniku Angular w tym przykładzie, jest zgodny z dowolną aplikacją internetową.

Wyświetlanie składnika mgt-login zależy od wartości ustawionej featureFlags.microsoft365Enabled na true. Ta niestandardowa flaga sprawdza obecność zmiennej środowiskowej ENTRAID_CLIENT_ID , aby potwierdzić, że aplikacja jest prawidłowo skonfigurowana i może uwierzytelniać się względem identyfikatora Entra firmy Microsoft. Flaga jest dodawana w celu uwzględnienia przypadków, w których użytkownicy zdecydują się wykonać tylko ćwiczenia dotyczące sztucznej inteligencji lub komunikacji w ramach samouczka, zamiast wykonywać całą sekwencję ćwiczeń.
Otwórz header.component.ts i znajdź loginCompleted funkcję. Ta funkcja jest wywoływana, loginCompleted gdy zdarzenie jest emitowane i obsługuje pobieranie profilu zalogowanych użytkowników przy użyciu polecenia Providers.globalProvider.
```
async loginCompleted() {
    const me = await Providers.globalProvider.graph.client.api('me').get();
    this.userLoggedIn.emit(me);
}
```
W tym przykładzie wykonywane jest wywołanie interfejsu API programu Microsoft Graph me w celu pobrania profilu użytkownika (me reprezentuje bieżącego zalogowanego użytkownika). Instrukcja this.userLoggedIn.emit(me) kodu emituje zdarzenie ze składnika w celu przekazania danych profilu do składnika nadrzędnego. W tym przypadku składnik nadrzędny jest app.component.ts pliku, który jest składnikiem głównym aplikacji.

Aby dowiedzieć się więcej na temat składnika mgt-login , odwiedź dokumentację zestawu narzędzi Microsoft Graph Toolkit .
Po zalogowaniu się do aplikacji przyjrzyjmy się sposobowi pobierania danych organizacji.

Dane organizacyjne: pobieranie plików, czatów i wysyłanie wiadomości do usługi Teams

Pozostały czas: 41 min

W dzisiejszym środowisku cyfrowym użytkownicy pracują z szeroką gamą danych organizacyjnych, w tym wiadomości e-mail, czatów, plików, wydarzeń kalendarza i nie tylko. Może to prowadzić do częstych zmian kontekstu — przełączania między zadaniami lub aplikacjami — co może zakłócić skupienie się i zmniejszyć produktywność. Na przykład użytkownik pracujący nad projektem może wymagać przełączenia się z bieżącej aplikacji do programu Outlook w celu znalezienia kluczowych szczegółów w wiadomości e-mail lub przełączenia się na OneDrive dla Firm w celu znalezienia powiązanego pliku. To działanie z powrotem i z powrotem zakłóca skupienie się i marnuje czas, który może być lepiej spędzony na zadaniu.

Aby zwiększyć wydajność, możesz zintegrować dane organizacyjne bezpośrednio z aplikacjami, których użytkownicy używają codziennie. Dzięki wprowadzeniu danych organizacji do aplikacji użytkownicy mogą bezproblemowo uzyskiwać dostęp do informacji i zarządzać nimi, minimalizując zmiany kontekstu i zwiększając produktywność. Ponadto ta integracja zapewnia cenne szczegółowe informacje i kontekst, umożliwiając użytkownikom podejmowanie świadomych decyzji i wydajniejszą pracę.

W tym ćwiczeniu wykonasz następujące czynności:

Dowiedz się, jak składnik internetowy mgt-search-results w zestawie narzędzi Microsoft Graph Może służyć do wyszukiwania plików.
Dowiedz się, jak wywołać program Microsoft Graph bezpośrednio w celu pobrania plików z OneDrive dla Firm i wiadomości czatu z usługi Microsoft Teams.
Dowiedz się, jak wysyłać wiadomości czatu do kanałów usługi Microsoft Teams przy użyciu programu Microsoft Graph.

Korzystanie z funkcji danych organizacyjnych

W poprzednim ćwiczeniu utworzono rejestrację aplikacji w usłudze Microsoft Entra ID i uruchomiono serwer aplikacji i serwer interfejsu API. Zaktualizowano również następujące wartości w .env pliku.
```
ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
TEAM_ID=<TEAMS_TEAM_ID>
CHANNEL_ID=<TEAMS_CHANNEL_ID>
```
Przed kontynuowaniem upewnij się, że wykonano poprzednie ćwiczenie .
Wróć do przeglądarki (http://localhost:4200). Jeśli jeszcze nie zalogowałeś się, wybierz pozycję Zaloguj się w nagłówku i zaloguj się przy użyciu użytkownika z dzierżawy deweloperów platformy Microsoft 365.
Uwaga

Oprócz uwierzytelniania użytkownika składnik internetowy mgt-login pobiera również token dostępu, który może być używany przez program Microsoft Graph do uzyskiwania dostępu do plików, czatów, wiadomości e-mail, zdarzeń kalendarza i innych danych organizacji. Token dostępu zawiera zakresy (uprawnienia), takie jak Chat.ReadWrite, Files.Read.Alli inne, które pokazano wcześniej:
```
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']
});
```
Wybierz pozycję Wyświetl powiązaną zawartość dla wiersza Adatum Corporation w usłudze datagrid. Spowoduje to pobranie danych organizacji, takich jak pliki, czaty, wiadomości e-mail i zdarzenia kalendarza przy użyciu programu Microsoft Graph. Po załadowaniu danych będzie ona wyświetlana poniżej parametru datagrid w interfejsie z kartami. Ważne jest, aby wspomnieć, że w tym momencie nie widzisz żadnych danych, ponieważ nie dodano jeszcze żadnych plików, czatów, wiadomości e-mail ani wydarzeń kalendarza dla użytkownika w dzierżawie deweloperów platformy Microsoft 365. Naprawmy to w następnym kroku.
Twoja dzierżawa platformy Microsoft 365 może nie mieć żadnych powiązanych danych organizacyjnych dla firmy Adatum Corporation na tym etapie. Aby dodać przykładowe dane, wykonaj co najmniej jedną z następujących akcji:
- Dodaj pliki, odwiedzając https://onedrive.com i logując się przy użyciu poświadczeń dzierżawy dewelopera platformy Microsoft 365.
  - Wybierz pozycję Moje pliki w obszarze nawigacji po lewej stronie.
  - Wybierz pozycję + Dodaj nowy , a następnie pozycję Przekaż folder z menu.
  - Wybierz folder openai-acs-msgraph/customer documents z sklonowanego projektu.
- Dodaj wiadomości czatu i zdarzenia kalendarza, odwiedzając https://teams.microsoft.com i logując się przy użyciu poświadczeń dzierżawy dewelopera platformy Microsoft 365.
  - Wybierz pozycję Teams w obszarze nawigacji po lewej stronie.
  - Wybierz zespół i kanał.
  - Wybierz pozycję Rozpocznij wpis.
  - Wprowadź nowe zamówienie złożone dla Adatum Corporation dla tematu i dowolny dodatkowy tekst, który chcesz dodać w treści wiadomości. Wybierz przycisk Opublikuj.
    
    Możesz dodać dodatkowe wiadomości czatu, które wspominają inne firmy używane w aplikacji, takie jak Adventure Works Cycles, Contoso Pharmaceuticals i Tailwind Traders.
  - Wybierz pozycję Kalendarz w obszarze nawigacji po lewej stronie.
  - Wybierz pozycję Nowe spotkanie.
  - Wprowadź tekst "Meet with Adatum Corporation about project schedule" (Poznaj z firmą Adatum Corporation) jako tytuł i treść.
  - Wybierz pozycję Zapisz.
- Dodaj wiadomości e-mail, odwiedzając https://outlook.com i logując się przy użyciu poświadczeń dzierżawy dewelopera platformy Microsoft 365.
  - Wybierz pozycję Nowa poczta.
  - Wprowadź osobisty adres e-mail w polu Do .
  - Wprowadź nowe zamówienie złożone dla Adatum Corporation dla tematu i wszystko, co chcesz dla ciała.
  - Wybierz Wyślij.
Wróć do aplikacji w przeglądarce i odśwież stronę. Ponownie wybierz pozycję Wyświetl powiązaną zawartość dla wiersza Adatum Corporation . Dane powinny być teraz wyświetlane na kartach w zależności od zadań wykonywanych w poprzednim kroku.
Przyjrzyjmy się kodowi, który umożliwia funkcję danych organizacji w aplikacji. Aby pobrać dane, część po stronie klienta aplikacji używa tokenu dostępu pobranego przez składnik mgt-login , który został wcześniej przyjrzeny w celu wykonania wywołań do interfejsów API programu Microsoft Graph.

Eksplorowanie kodu wyszukiwania plików

Napiwek

Jeśli używasz programu Visual Studio Code, możesz otwierać pliki bezpośrednio, wybierając pozycję:

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

Następnie wpisz nazwę pliku, który chcesz otworzyć.

Zacznijmy od przyjrzenia się sposobowi pobierania danych plików z OneDrive dla Firm. Otwórz files.component.html i pośmiń chwilę na przejrzenie kodu. Pełna ścieżka do pliku jest client/src/app/files/files.component.html.
Znajdź składnik mgt-search-results i zanotuj następujące atrybuty:
```
<mgt-search-results 
    class="search-results" 
    entity-types="driveItem" 
    [queryString]="searchText"
    (dataChange)="dataChange($any($event))" 
/>
```
Składnik mgt-search-results jest częścią zestawu narzędzi Microsoft Graph Toolkit i jak wskazuje nazwa, jest używany do wyświetlania wyników wyszukiwania z programu Microsoft Graph. Składnik używa następujących funkcji w tym przykładzie:
- Atrybut służy do określania class , że search-results klasa CSS powinna być stosowana do składnika.
- Atrybut entity-types służy do określania typu danych do wyszukania. W tym przypadku wartość jest driveItem używana do wyszukiwania plików w OneDrive dla Firm.
- Atrybut queryString służy do określania terminu wyszukiwania. W takim przypadku wartość jest powiązana z searchText właściwością, która jest przekazywana do składnika plików, gdy użytkownik wybierze pozycję Wyświetl powiązaną zawartość dla wiersza w usłudze datagrid. Nawiasy kwadratowe wokół queryString wskazują, że właściwość jest powiązana z wartością searchText .
- Zdarzenie dataChange jest uruchamiane po zmianie wyników wyszukiwania. W takim przypadku funkcja klienta o nazwie dataChange() jest wywoływana w składniku plików , a dane zdarzenia są przekazywane do funkcji. Nawias wokół dataChange wskazuje, że zdarzenie jest powiązane z funkcją dataChange() .
- Ponieważ nie podano szablonu niestandardowego, domyślny szablon wbudowany mgt-search-results jest używany do wyświetlania wyników wyszukiwania.
Alternatywą dla używania składników, takich jak mgt-search-results, jest wywołanie interfejsów API programu Microsoft Graph bezpośrednio przy użyciu kodu. Aby zobaczyć, jak to działa, otwórz plik graph.service.ts i znajdź searchFiles() funkcję. Pełna ścieżka do pliku to client/src/app/core/graph.service.ts.
- Zauważysz, że query parametr jest przekazywany do funkcji. Jest to termin wyszukiwania, który jest przekazywany, gdy użytkownik wybiera pozycję Wyświetl powiązaną zawartość dla wiersza w usłudze datagrid. Jeśli termin wyszukiwania nie zostanie przekazany, zwracana jest pusta tablica.
```
async searchFiles(query: string) {
    const files: DriveItem[] = [];
    if (!query) return files;

    ...
}
```
- Następnie zostanie utworzony filtr, który definiuje typ wyszukiwania do wykonania. W takim przypadku kod wyszukuje pliki w OneDrive dla Firm, więc driveItem jest używany tak jak pokazano wcześniej w składnikumgt-search-results. Jest to takie samo, jak przekazywanie driveItem do entity-types składnika mgt-search-results , który został wyświetlony wcześniej. Parametr query jest następnie dodawany do filtru queryString wraz z parametrem ContentType:Document.
```
const filter = {
    "requests": [
        {
            "entityTypes": [
                "driveItem"
            ],
            "query": {
                "queryString": `${query} AND ContentType:Document`
            }
        }
    ]
};
```
- Następnie wykonano wywołanie interfejsu /search/query API programu Microsoft Graph przy użyciu Providers.globalProvider.graph.client.api() funkcji . Obiekt filter jest przekazywany do post() funkcji, która wysyła dane do interfejsu API.
```
const searchResults = await Providers.globalProvider.graph.client.api('/search/query').post(filter);
```
- Wyniki wyszukiwania są następnie iterowane w celu zlokalizowania hits. Każdy hit zawiera informacje o odnalezionym dokumencie. Właściwość o nazwie resource zawiera metadane dokumentu i jest dodawana do tablicy files .
```
if (searchResults.value.length !== 0) {
    for (const hitContainer of searchResults.value[0].hitsContainers) {
        if (hitContainer.hits) {
            for (const hit of hitContainer.hits) {
                files.push(hit.resource);
            }
        }
    }
}
```
- Tablica files jest następnie zwracana do obiektu wywołującego.
```
return files;
```
Patrząc przez ten kod, możesz zobaczyć, że omówiony wcześniej składnik internetowy mgt-search-results wykonuje wiele pracy dla Ciebie i znacznie zmniejsza ilość kodu, który trzeba napisać! Jednak mogą istnieć scenariusze, w których chcesz wywołać program Microsoft Graph bezpośrednio, aby mieć większą kontrolę nad danymi wysyłanymi do interfejsu API lub sposobem przetwarzania wyników.
Otwórz plik files.component.ts i znajdź search() funkcję. Pełna ścieżka do pliku to client/src/app/files/files.component.ts.

Mimo że treść tej funkcji jest oznaczona jako komentarz ze względu na używany składnik mgt-search-results, funkcja może służyć do wywołania programu Microsoft Graph, gdy użytkownik wybierze pozycję Wyświetl powiązaną zawartość dla wiersza w usłudze datagrid. Funkcja search() wywołuje searchFiles() graph.service.ts i przekazuje query do niego parametr (nazwa firmy w tym przykładzie). Wyniki wyszukiwania są następnie przypisywane do data właściwości składnika.
```
override async search(query: string) {
    this.data = await this.graphService.searchFiles(query);
}
```
Składnik plików może następnie użyć data właściwości , aby wyświetlić wyniki wyszukiwania. Można to obsłużyć przy użyciu niestandardowych powiązań HTML lub za pomocą innej kontrolki zestawu narzędzi Microsoft Graph Toolkit o nazwie mgt-file-list. Oto przykład powiązania data właściwości z jedną z właściwości składnika o nazwie files i obsługi itemClick zdarzenia podczas interakcji użytkownika z plikiem.
```
<mgt-file-list (itemClick)="itemClick($any($event))" [files]="data"></mgt-file-list>
```
Niezależnie od tego, czy zdecydujesz się użyć składnika mgt-search-results pokazanego wcześniej, czy napisać kod niestandardowy do wywołania programu Microsoft Graph, będzie zależeć od konkretnego scenariusza. W tym przykładzie składnik mgt-search-results służy do uproszczenia kodu i zmniejszenia ilości pracy, którą należy wykonać.

Eksplorowanie kodu wyszukiwania wiadomości czatu w aplikacji Teams

Wróć do graph.service.ts i znajdź searchChatMessages() funkcję. Zobaczysz, że jest ona podobna do searchFiles() funkcji, którą wcześniej przyjrzeno.
- Publikuje on filtry danych do interfejsu /search/query API programu Microsoft Graph i konwertuje wyniki na tablicę obiektów, które zawierają informacje o teamIdobiekcie , channelIdi messageId zgodne z terminem wyszukiwania.
- Aby pobrać komunikaty kanału usługi Teams, drugie wywołanie jest wykonywane do interfejsu /teams/${chat.teamId}/channels/${chat.channelId}/messages/${chat.messageId} teamIdchannelIdAPI i , i messageId są przekazywane. Spowoduje to zwrócenie pełnych szczegółów komunikatu.
- Wykonywane są dodatkowe zadania filtrowania, a wynikowe komunikaty są zwracane z searchChatMessages() do obiektu wywołującego.

Otwórz plik chats.component.ts i znajdź search() funkcję. Pełna ścieżka do pliku to client/src/app/chats/chats.component.ts. Funkcja search() wywołuje searchChatMessages() graph.service.ts i przekazuje query do niego parametr .

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

Wyniki wyszukiwania są przypisywane do data właściwości składnika, a powiązanie danych służy do iterowania przez tablicę wyników i renderowania danych. W tym przykładzie użyto składnika karty Angular Material do wyświetlenia wyników wyszukiwania.

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

Wyświetlanie czatów w aplikacji Teams

Wysyłanie wiadomości do kanału usługi Microsoft Teams

Oprócz wyszukiwania wiadomości czatów w aplikacji Microsoft Teams aplikacja umożliwia również użytkownikowi wysyłanie wiadomości do kanału usługi Microsoft Teams. Można to zrobić, wywołując /teams/${teamId}/channels/${channelId}/messages punkt końcowy programu Microsoft Graph.

W poniższym kodzie zobaczysz, że zostanie utworzony adres URL zawierający teamId wartości i channelId . Wartości zmiennych środowiskowych są używane dla identyfikatora zespołu i identyfikatora kanału w tym przykładzie, ale te wartości mogą być również pobierane dynamicznie przy użyciu programu Microsoft Graph. Stała body zawiera komunikat do wysłania. Następnie zostanie wykonane żądanie POST, a wyniki zostaną zwrócone do elementu wywołującego.

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

Korzystanie z tego typu funkcji w programie Microsoft Graph zapewnia doskonały sposób ulepszania produktu użytkownika dzięki umożliwieniu użytkownikom interakcji z usługą Microsoft Teams bezpośrednio z aplikacji, z której już korzystają.

Dane organizacyjne: pobieranie wiadomości e-mail i zdarzeń kalendarza

Pozostały czas: 21 min

W poprzednim ćwiczeniu przedstawiono sposób pobierania plików z OneDrive dla Firm i czatów z usługi Microsoft Teams przy użyciu programu Microsoft Graph oraz składnika mgt-search-results z zestawu narzędzi Microsoft Graph Toolkit. Przedstawiono również sposób wysyłania komunikatów do kanałów usługi Microsoft Teams. W tym ćwiczeniu dowiesz się, jak pobierać wiadomości e-mail i zdarzenia kalendarza z programu Microsoft Graph i integrować je z aplikacją.

W tym ćwiczeniu wykonasz następujące czynności:

Dowiedz się, jak składnik internetowy mgt-search-results w zestawie narzędzi Microsoft Graph Toolkit może służyć do wyszukiwania wiadomości e-mail i zdarzeń kalendarza.
Dowiedz się, jak dostosować składnik mgt-search-results w celu renderowania wyników wyszukiwania w niestandardowy sposób.
Dowiedz się, jak wywołać program Microsoft Graph bezpośrednio w celu pobrania wiadomości e-mail i zdarzeń kalendarza.

Eksplorowanie kodu wyszukiwania wiadomości e-mail

Napiwek

Jeśli używasz programu Visual Studio Code, możesz otwierać pliki bezpośrednio, wybierając pozycję:

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

Następnie wpisz nazwę pliku, który chcesz otworzyć.

W poprzednim ćwiczeniu utworzono rejestrację aplikacji w usłudze Microsoft Entra ID i uruchomiono serwer aplikacji i serwer interfejsu API. Zaktualizowano również następujące wartości w .env pliku.
```
ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
TEAM_ID=<TEAMS_TEAM_ID>
CHANNEL_ID=<TEAMS_CHANNEL_ID>
```
Przed kontynuowaniem upewnij się, że wykonano poprzednie ćwiczenie .
Otwórz emails.component.html i pośmiń chwilę na przejrzenie kodu. Pełna ścieżka do pliku jest client/src/app/emails/emails.component.html.
Znajdź składnik mgt-search-results:
```
<mgt-search-results 
  class="search-results" 
  entity-types="message" 
  [queryString]="searchText"
  (dataChange)="dataChange($any($event))">
  <template data-type="result-message"></template>
</mgt-search-results>
```
W tym przykładzie składnika mgt-search-results skonfigurowano taki sam sposób, jak poprzednio. Jedyną różnicą jest to, że entity-types atrybut jest ustawiony, do message którego służy wyszukiwanie wiadomości e-mail, a pusty szablon jest dostarczany.
- Atrybut służy do określania class , że search-results klasa CSS powinna być stosowana do składnika.
- Atrybut entity-types służy do określania typu danych do wyszukania. W tym przypadku wartość to message.
- Atrybut queryString służy do określania terminu wyszukiwania.
- Zdarzenie dataChange jest uruchamiane po zmianie wyników wyszukiwania. Funkcja składnika dataChange() wiadomości e-mail jest wywoływana, wyniki są do niego przekazywane, a właściwość o nazwie data jest aktualizowana w składniku.
- Pusty szablon jest zdefiniowany dla składnika. Ten typ szablonu jest zwykle używany do definiowania sposobu renderowania wyników wyszukiwania. Jednak w tym scenariuszu mówimy składnikowi, aby nie renderować żadnych danych komunikatów. Zamiast tego dane będą renderowane przy użyciu standardowego powiązania danych (w tym przypadku usługa Angular jest używana, ale możesz użyć dowolnej biblioteki/platformy).

Spójrz poniżej składnika mgt-search-results w emails.component.html , aby znaleźć powiązania danych używane do renderowania wiadomości e-mail. W tym przykładzie data wykonuje iterację po właściwości i zapisuje temat wiadomości e-mail, podgląd treści i link, aby wyświetlić pełną wiadomość e-mail.

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

Wyświetlanie wiadomości e-mail

Oprócz używania składnika mgt-search-results do pobierania komunikatów program Microsoft Graph udostępnia kilka interfejsów API, których można również używać do wyszukiwania wiadomości e-mail. Interfejs /search/query API, który został wyświetlony wcześniej, z pewnością może być używany, ale bardziej prostą opcją messages jest interfejs API.
Aby zobaczyć, jak wywołać ten interfejs API, wróć do graph.service.ts i znajdź searchEmailMessages() funkcję. Tworzy adres URL, który może służyć do wywoływania messages punktu końcowego programu Microsoft Graph i przypisuje query wartość do parametru $search . Następnie kod wysyła żądanie GET i zwraca wyniki do elementu wywołującego. Operator $search automatycznie wyszukuje query wartość w polach tematu, treści i nadawcy.
```
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;
}
```
Składnik wiadomości e-mail znajdujący się w emails.component.ts wywołaniach searchEmailMessages() i wyświetla wyniki w interfejsie użytkownika.
```
override async search(query: string) {
    this.data = await this.graphService.searchEmailMessages(query);
}
```

Eksplorowanie kodu wyszukiwania zdarzeń kalendarza

Wyszukiwanie zdarzeń kalendarza można również wykonać przy użyciu składnika mgt-search-results . Może on obsługiwać renderowanie wyników, ale możesz również zdefiniować własny szablon, który będzie widoczny w dalszej części tego ćwiczenia.
Otwórz calendar-events.component.html i pośmiń chwilę na przejrzenie kodu. Pełna ścieżka do pliku jest client/src/app/calendar-events/calendar-events.component.html. Zobaczysz, że jest ona bardzo podobna do składników plików i wiadomości e-mail, które zostały wcześniej wyświetlone.
```
<mgt-search-results 
    class="search-results" 
    entity-types="event" 
    [queryString]="searchText"
    (dataChange)="dataChange($any($event))">
    <template data-type="result-event"></template>
</mgt-search-results>
```
W tym przykładzie składnika mgt-search-results skonfigurowano taki sam sposób, jak te, które były wcześniej analizowane. Jedyną różnicą jest to, że entity-types atrybut jest ustawiony do event wyszukiwania zdarzeń kalendarza i jest dostarczany pusty szablon.
- Atrybut służy do określania class , że search-results klasa CSS powinna być stosowana do składnika.
- Atrybut entity-types służy do określania typu danych do wyszukania. W tym przypadku wartość to event.
- Atrybut queryString służy do określania terminu wyszukiwania.
- Zdarzenie dataChange jest uruchamiane po zmianie wyników wyszukiwania. Funkcja składnika dataChange() zdarzenia kalendarza jest wywoływana, wyniki są do niego przekazywane, a właściwość o nazwie data jest aktualizowana w składniku.
- Pusty szablon jest zdefiniowany dla składnika. W tym scenariuszu mówimy składnikowi, aby nie renderować żadnych danych. Zamiast tego renderujemy dane przy użyciu standardowego powiązania danych.

Bezpośrednio poniżej mgt-search-results składnika w calendar-events.component.html znajdziesz powiązania danych używane do renderowania zdarzeń kalendarza. W tym przykładzie data iteruje za pośrednictwem właściwości i zapisuje datę rozpoczęcia, godzinę i temat zdarzenia. Funkcje niestandardowe zawarte w składniku, takie jak dayFromDateTime() i timeRangeFromEvent() , są wywoływane w celu poprawnego formatowania danych. Powiązania HTML zawierają również link umożliwiający wyświetlenie zdarzenia kalendarza w programie Outlook oraz lokalizację zdarzenia, jeśli zostanie określone.

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

Oprócz wyszukiwania zdarzeń kalendarza przy użyciu interfejsu search/query API program Microsoft Graph udostępnia events również interfejs API, który może służyć do wyszukiwania zdarzeń kalendarza. searchCalendarEvents() Znajdź funkcję w graph.service.ts.
Funkcja searchCalendarEvents() tworzy wartości daty/godziny rozpoczęcia i zakończenia, które są używane do definiowania okresu do wyszukiwania. Następnie tworzy adres URL, który może służyć do wywoływania events punktu końcowego programu Microsoft Graph i zawiera query parametr oraz zmienne daty/godziny rozpoczęcia i zakończenia. Następnie zostanie wykonane żądanie GET, a wyniki zostaną zwrócone do wywołującego.
```
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;
}
```
- Oto podział utworzonego adresu URL:
  - Część /me/events adresu URL służy do określania, że należy pobrać zdarzenia zalogowanego użytkownika.
  - Parametry startdatetime i enddatetime służą do definiowania okresu do wyszukiwania. W takim przypadku wyszukiwanie zwróci zdarzenia rozpoczynające się w ciągu najbliższych 7 dni.
  - Parametr $filter zapytania służy do filtrowania wyników według query wartości (nazwa firmy wybrana z usługi datagrid w tym przypadku). Funkcja contains() służy do wyszukiwania query wartości we subject właściwości zdarzenia kalendarza.
  - $orderby Parametr zapytania służy do zamawiania wyników przez start/dateTime właściwość .
Po utworzeniu url obiektu żądanie GET jest wykonywane do interfejsu API programu Microsoft Graph przy użyciu wartości url , a wyniki są zwracane do obiektu wywołującego.
Podobnie jak w przypadku poprzednich składników, składnik zdarzeń kalendarza (calendar-events.component.ts pliku) wywołuje search() i wyświetla wyniki.
```
override async search(query: string) {
    this.data = await this.graphService.searchCalendarEvents(query);
}
```
Uwaga

Możesz również wykonywać wywołania programu Microsoft Graph z niestandardowego interfejsu API lub aplikacji po stronie serwera. Zapoznaj się z poniższym samouczkiem , aby zobaczyć przykład wywoływania interfejsu API programu Microsoft Graph z funkcji platformy Azure.
Znasz już przykład użycia programu Microsoft Graph do pobierania plików, czatów, wiadomości e-mail i wydarzeń kalendarza. Te same pojęcia można również zastosować do innych interfejsów API programu Microsoft Graph. Na przykład możesz użyć interfejsu API użytkowników programu Microsoft Graph do wyszukiwania użytkowników w organizacji. Możesz również użyć interfejsu API grup programu Microsoft Graph do wyszukiwania grup w organizacji. Pełną listę interfejsów API programu Microsoft Graph można wyświetlić w dokumentacji.

Udostępnij za pośrednictwem

Integrowanie funkcji openAI, komunikacji i danych organizacyjnych z aplikacją biznesową

Co utworzysz w tym samouczku

Wybierz własną przygodę

Wymagania wstępne

Technologie w chmurze firmy Microsoft używane w tym samouczku

Klonowanie projektu

Klonowanie repozytorium GitHub i tworzenie .env pliku

Sztuczna inteligencja: tworzenie zasobu usługi Azure OpenAI i wdrażanie modelu

Tworzenie zasobu usługi Azure OpenAI Service

Aktualizowanie pliku projektu .env

Uruchamianie usług aplikacji

Sztuczna inteligencja: język naturalny do języka SQL

Używanie języka naturalnego do funkcji SQL

Eksplorowanie języka naturalnego do kodu SQL

Sztuczna inteligencja: generowanie uzupełniania

Korzystanie z funkcji uzupełniania sztucznej inteligencji

Eksplorowanie kodu uzupełniania sztucznej inteligencji

Sztuczna inteligencja: Azure OpenAI na danych

Dodawanie niestandardowego źródła danych do programu Azure AI Studio

Używanie niestandardowego źródła danych na placu zabaw czatu

Korzystanie z funkcji Bring Your Own Data w aplikacji

Eksplorowanie kodu

Komunikacja: tworzenie zasobu usług Azure Communication Services

Tworzenie zasobu usług Azure Communication Services

Włączanie możliwości połączeń telefonicznych i wiadomości SMS

Łączenie domeny poczty e-mail

.env Aktualizowanie pliku

Uruchamianie/ponowne uruchamianie serwerów aplikacji i interfejsów API

Komunikacja: nawiązywanie połączenia telefonicznego

Korzystanie z funkcji połączenia telefonicznego

Eksplorowanie kodu rozmów telefonicznych

Komunikacja: wysyłanie wiadomości e-mail i wiadomości SMS

Korzystanie z funkcji poczty e-mail i wiadomości SMS

Eksplorowanie kodu wiadomości e-mail

Eksplorowanie kodu SMS

Dane organizacyjne: tworzenie rejestracji aplikacji entra ID firmy Microsoft

Tworzenie rejestracji aplikacji Microsoft Entra ID

Aktualizowanie pliku env projektu

Uruchamianie/ponowne uruchamianie serwerów aplikacji i interfejsów API

Dane organizacyjne: logowanie użytkownika i uzyskiwanie tokenu dostępu

Korzystanie z funkcji logowania

Eksplorowanie kodu logowania

Dane organizacyjne: pobieranie plików, czatów i wysyłanie wiadomości do usługi Teams

Korzystanie z funkcji danych organizacyjnych

Eksplorowanie kodu wyszukiwania plików

Eksplorowanie kodu wyszukiwania wiadomości czatu w aplikacji Teams

Wysyłanie wiadomości do kanału usługi Microsoft Teams

Dane organizacyjne: pobieranie wiadomości e-mail i zdarzeń kalendarza

Eksplorowanie kodu wyszukiwania wiadomości e-mail

Eksplorowanie kodu wyszukiwania zdarzeń kalendarza

Gratulacje!

Ukończono ten samouczek

Czyszczenie zasobów platformy Azure

Następne kroki

Dokumentacja

Treści szkoleniowe

Opinia

Klonowanie repozytorium GitHub i tworzenie `.env` pliku

Aktualizowanie pliku projektu `.env`

`.env` Aktualizowanie pliku