Integrace funkcí OpenAI, komunikace a organizačních dat do obchodní aplikace

Článek
Developer (Středně pokročilý)
136 min do dokončení

Úroveň: Středně pokročilá

Tento kurz ukazuje, jak je možné integrovat Azure OpenAI, Azure Communication Services a Microsoft Graph/Microsoft Graph Toolkit do obchodních aplikací za účelem zvýšení produktivity uživatelů, zvýšení uživatelského prostředí a zvýšení úrovně obchodních aplikací.

AI: Umožňuje uživatelům pokládat otázky v přirozeném jazyce a převádět jejich odpovědi na SQL, které se dají použít k dotazování databáze, umožnit uživatelům definovat pravidla, která se dají použít k automatickému generování e-mailových a SMS zpráv, a zjistit, jak se dá přirozený jazyk použít k načtení dat z vlastních zdrojů dat. Pro tyto funkce se používá Azure OpenAI.
Komunikace: Povolte telefonní hovory v aplikaci zákazníkům a Email/SMS funkce pomocí Azure Communication Services.
Organizační data: Při práci se zákazníky si můžete vyžádat související organizační data, která uživatelé můžou potřebovat (dokumenty, chaty, e-maily, události kalendáře), aby se zabránilo přepínání kontextu. Poskytnutí přístupu k tomuto typu dat organizace snižuje potřebu, aby uživatel přešel na Outlook, Teams, OneDrive, další vlastní aplikace, telefon atd., protože konkrétní data a funkce, které potřebují, jsou poskytovány přímo v aplikaci. Pro tuto funkci se používá Microsoft Graph a Microsoft Graph Toolkit.

Aplikace je jednoduchá aplikace pro správu zákazníků, která uživatelům umožňuje spravovat jejich zákazníky a související data. Skládá se z front-endu vytvořeného pomocí TypeScriptu, který volá back-endová rozhraní API pro načítání dat, interakci s funkcemi AI, odesílání e-mailů a SMS zpráv a získávání dat organizace. Tady je přehled řešení aplikací, které si projdete v tomto kurzu:

Přehled scénářů Microsoft Cloud

Tento kurz vás provede procesem nastavení požadovaných prostředků Azure a Microsoft 365. Provede vás také kódem, který se používá k implementaci funkcí AI, komunikace a organizačních dat. I když nebudete muset kopírovat a vkládat kód, v některých cvičeních budete muset upravit kód tak, abyste vyzkoušeli různé scénáře.

Co vytvoříte v tomto kurzu

Zvolte si vlastní dobrodružství

Můžete dokončit celý kurz od začátku do konce nebo dokončit konkrétní témata, která vás zajímají. Kurz je rozdělený do následujících témat:

Naklonujte cvičení projektu (povinné cvičení).
Cvičení AI: Vytvořte prostředek Azure OpenAI a použijte ho k převodu přirozeného jazyka na SQL, generování e-mailových nebo SMS zpráv a práci s vlastními daty a dokumenty.
Komunikační cvičení: Vytvořte Azure Communication Services prostředek a použijte ho k telefonním hovorům z aplikace a odesílání e-mailů nebo SMS zpráv.
Cvičení s daty organizace: Vytvořte registraci aplikace Microsoft Entra ID, aby bylo možné k ověřování a načtení dat organizace do aplikace použít Microsoft Graph a Microsoft Graph Toolkit.

Vyberte si vlastní dobrodružství. Dokončete celý kurz nebo vyberte konkrétní oblasti témat.

Požadavky

Node – Pro tento projekt se použije uzel 16 nebo novější a npm 7 nebo novější.
git
Visual Studio Code (i když se doporučuje Visual Studio Code, je možné použít libovolný editor)
Předplatné Azure
Vývojářský tenant Microsoft 365
Docker Desktop nebo jiný modul runtime kontejneru kompatibilní s OCI (Open Container Initiative), jako je Podman nebo nerdctl schopný spustit kontejner.

Cloudové technologie Microsoftu použité v tomto kurzu

Microsoft Entra ID
Azure Communication Services
Azure OpenAI Service
Microsoft Graph
Sada nástrojů pro Microsoft Graph

Klonování projektu

132 min zbývá

Projekt kódu použitý v tomto kurzu je k dispozici na adrese https://github.com/microsoft/MicrosoftCloud. Úložiště projektu obsahuje kód na straně klienta i na straně serveru potřebný ke spuštění projektu, což vám umožní prozkoumat integrované funkce související s umělou inteligencí (AI), komunikací a organizačními daty. Projekt navíc slouží jako zdroj, který vás provede začleněním podobných funkcí do vlastních aplikací.

V tomto cvičení:

Naklonujte úložiště GitHub.
Přidejte do projektu soubor .env a aktualizujte ho.

Než budete pokračovat, ujistěte se, že máte nainstalované a nakonfigurované všechny požadavky, jak je popsáno v části Požadavky tohoto kurzu.

Naklonujte úložiště GitHub a vytvořte `.env` soubor.

Spuštěním následujícího příkazu naklonujte do počítače úložiště Microsoft Cloud GitHub .
```
git clone https://github.com/microsoft/MicrosoftCloud
```
Otevřete složku MicrosoftCloud/samples/openai-acs-msgraph v editoru Visual Studio Code.

Poznámka

I když v tomto kurzu použijeme Visual Studio Code, pro práci s ukázkovým projektem je možné použít libovolný editor kódu.
Všimněte si následujících složek a souborů:
- klient: Kód aplikace na straně klienta.
- server: Kód rozhraní API na straně serveru.
- docker-compose.yml: Používá se ke spuštění místní databáze PostgreSQL.
Přejmenujte .env.example v kořenovém adresáři projektu na .env.

Otevřete soubor .env a chvíli si prohlédněte klíče, které jsou součástí:

ENTRAID_CLIENT_ID=
TEAM_ID=
CHANNEL_ID=
OPENAI_API_KEY=
OPENAI_ENDPOINT=
OPENAI_API_VERSION=2023-06-01-preview
OPENAI_MODEL=gpt-35-turbo
POSTGRES_USER=
POSTGRES_PASSWORD=
ACS_CONNECTION_STRING=
ACS_PHONE_NUMBER=
ACS_EMAIL_ADDRESS=
CUSTOMER_EMAIL_ADDRESS=
CUSTOMER_PHONE_NUMBER=
API_PORT=3000
AZURE_COGNITIVE_SEARCH_ENDPOINT=
AZURE_COGNITIVE_SEARCH_KEY=
AZURE_COGNITIVE_SEARCH_INDEX=

Aktualizujte následující hodnoty v souboru .env. Tyto hodnoty použije server rozhraní API pro připojení k místní databázi PostgreSQL.
```
POSTGRES_USER=web
POSTGRES_PASSWORD=web-password
```
Teď, když máte projekt hotový, vyzkoušíme některé z funkcí aplikace a dozvíme se, jak jsou sestavené. Výběrem tlačítka Další níže pokračujte nebo přejděte na konkrétní cvičení pomocí obsahu.

AI: Vytvoření prostředku Azure OpenAI a nasazení modelu

127 min zbývá

Pokud chcete ve svých aplikacích začít používat Azure OpenAI, musíte vytvořit službu Azure OpenAI a nasadit model, který se dá použít k provádění úloh, jako je převod přirozeného jazyka na SQL, generování obsahu e-mailů nebo zpráv SMS a další.

V tomto cvičení:

Vytvořte prostředek služby Azure OpenAI.
Nasazení modelu
Aktualizujte soubor .env hodnotami z prostředku služby Azure OpenAI.

Přehled scénářů Microsoft Cloud

Vytvoření prostředku služby Azure OpenAI

Přejděte na Azure Portal v prohlížeči a přihlaste se.
Do vyhledávacího panelu v horní části stránky portálu zadejte openai a v zobrazených možnostech vyberte Azure OpenAI.
Na panelu nástrojů vyberte Vytvořit .

Poznámka

Pokud se zobrazí zpráva o vyplnění formuláře žádosti o povolení Azure OpenAI ve vašem předplatném, vyberte odkaz Kliknutím sem požádejte o přístup ke službě Azure OpenAI a vyplňte formulář. Po vyplnění formuláře budete muset počkat, než tým Azure OpenAI vaši žádost schválí. Po obdržení oznámení o schválení se můžete vrátit k tomuto cvičení a vytvořit prostředek.

I když se tento kurz zaměřuje na Azure OpenAI, pokud máte klíč rozhraní API OpenAI a chcete ho použít při čekání na přístup k Azure OpenAI, můžete tuto část přeskočit a přejít přímo do části Aktualizace souboru .env projektu níže. V souboru .env přiřaďte klíč OPENAI_API_KEY rozhraní API OpenAI (můžete ignorovat všechny další .env pokyny související s OpenAI). Jakmile budete mít přístup k Azure OpenAI, znovu se k tomuto cvičení dostanete, vytvořte prostředek a model a aktualizujte soubor .env hodnotami z prostředku Azure OpenAI.
Proveďte následující úlohy:
- Vyberte své předplatné Azure.
- Vyberte skupinu prostředků, kterou chcete použít (v případě potřeby vytvořte novou).
- Vyberte oblast, kterou chcete použít.
- Zadejte název prostředku. Tato hodnota musí být jedinečná.
- Vyberte cenovou úroveň Standard S0 .
Vyberte Další , dokud se nedostanete na obrazovku Zkontrolovat a odeslat . Vyberte Vytvořit.
Po vytvoření prostředku Azure OpenAI na něj přejděte a v části Správa prostředků vyberte Klíče a koncový bod.
Vyhledejte hodnoty KLÍČ 1 a Koncový bod . Obě hodnoty použijete v další části, takže je zkopírujte do místního souboru.
V části Správa prostředků vyberte Nasazení modelů.
Výběrem tlačítka Spravovat nasazení přejděte na Azure OpenAI Studio.
Na panelu nástrojů vyberte Vytvořit nové nasazení .
Zadejte tyto hodnoty:
- Model: gpt-35-turbo.
- Verze modelu: Automaticky se aktualizuje na výchozí.
- Název nasazení: gpt-35-turbo.
Poznámka

Azure OpenAI podporuje několik různých typů modelů. Každý model je možné použít ke zpracování různých scénářů.
Vyberte Vytvořit.
Po nasazení modelu vyberte v části Hřištěmožnost Dokončení.
V rozevíracím seznamu Nasazení vyberte model gpt-35-turbo. V rozevíracím seznamu Příklady vyberte Vygenerovat e-mail.
Chvíli si přečtěte zadaný text výzvy. Vyberte Generovat a zobrazte text, který model vygeneruje.

Upozornění

Pokud se zobrazí chybová zpráva o tom, že model není připravený, počkejte několik minut a zkuste to znovu. Úplné nasazení a připravenost modelu k použití může několik minut trvat.

Pokud se zobrazí chyba s informací, že operace dokončení nefunguje se zadaným modelem, obvykle to znamená, že jste vybrali novější verzi modelu, a ne výchozí verzi. Vyberte Nasazení a odstraňte model, který jste vytvořili dříve. Vytvořte nové nasazení modelu gpt-35-turbo, ujistěte se, že jste pro verzi modelu vybrali automatickou aktualizaci na výchozí, pojmenujte ji gpt-35-turbo a počkejte, až se model plně nasadí. Po nasazení se vraťte do dětského hřiště a zkuste dokončení znovu.
Vyberte Znovu vygenerovat vícekrát. Všimněte si, že text se pokaždé liší.
Napravo od obrazovky uvidíte vlastnosti, jako je teplota. Změňte hodnotu Teplota na 0 a znovu vyberte Znovu vygenerovat . Přečtěte si vygenerovaný text e-mailu.
Vyberte Znovu vygenerovat znovu a všimněte si, že text e-mailu je stejný jako text, který byl vygenerován dříve.

Poznámka

Snížení teploty znamená, že model bude vytvářet více opakujících se a deterministických odpovědí. Zvýšení teploty bude mít za následek neočekávanější nebo kreativnější reakce.

Aktualizace souboru projektu `.env`

Zpět do editoru .env Visual Studio Code a otevřete soubor v kořenovém adresáři projektu.
Zkopírujte hodnotu KEY 1 z prostředku Azure OpenAI a přiřaďte ji do OPENAI_API_KEY souboru .env umístěného v kořenové složce openai-acs-msgraph :
```
OPENAI_API_KEY=<KEY_1_VALUE>
```
Zkopírujte hodnotu *Endpoint a přiřaďte ji do OPENAI_ENDPOINT souboru .env . / Odeberte znak z konce hodnoty, pokud je k dispozici.
```
OPENAI_ENDPOINT=<ENDPOINT_VALUE>
```
Poznámka

Uvidíte, že hodnoty pro OPENAI_MODEL a OPENAI_API_VERSION jsou už nastavené v souboru .env . Hodnota modelu je nastavená na gpt-35-turbo , která by měla odpovídat názvu modelu, který jste vytvořili dříve v tomto cvičení. Verze rozhraní API je nastavená na podporovanou hodnotu definovanou v referenční dokumentaci k Azure OpenAI.
Uložte soubor .env.

Spuštění aplikačních služeb

Je čas spustit aplikační služby, včetně databáze, serveru rozhraní API a webového serveru.

V následujících krocích vytvoříte v editoru Visual Studio Code tři okna terminálu.
Klikněte pravým tlačítkem na soubor .env v seznamu souborů editoru Visual Studio Code a vyberte Otevřít v integrovaném terminálu. Než budete pokračovat, ujistěte se, že je váš terminál v kořenovém adresáři projektu – openai-acs-msgraph .
Pro spuštění databáze PostgreSQL zvolte jednu z následujících možností:
- Pokud máte nainstalovaný a spuštěný Docker Desktop , spusťte docker-compose up v okně terminálu příkaz a stiskněte Enter.
- Pokud máte nainstalovaný a spuštěný Podman s podman-compose , spusťte podman-compose up v okně terminálu a stiskněte Enter.
- Pokud chcete kontejner PostgreSQL spustit přímo pomocí Docker Desktopu, Podmanu, nerdctl nebo jiného nainstalovaného modulu runtime kontejneru, spusťte v okně terminálu následující příkaz:
  - Mac, Linux nebo Subsystém Windows pro 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 s PowerShellem:
```
[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 spuštění kontejneru databáze vytvořte stisknutím + ikony na panelu nástrojů Terminálu editoru Visual Studio Code druhé okno terminálu.
cd do složky server/typescript a spuštěním následujících příkazů nainstalujte závislosti a spusťte server rozhraní API.
- npm install
- npm start
+ Dalším stisknutím ikony na panelu nástrojů Terminálu editoru Visual Studio Code vytvořte třetí okno terminálu.
cd do klientské složky a spuštěním následujících příkazů nainstalujte závislosti a spusťte webový server.
- npm install
- npm start
Spustí se prohlížeč a budete přesměrováni na http://localhost:4200adresu .

AI: Přirozený jazyk pro SQL

122 min zbývá

Citace "Jen proto, že to jde, neznamená, že byste měli" je užitečným průvodcem při úvahách o možnostech AI. Například funkce přirozeného jazyka Azure OpenAI pro SQL umožňuje uživatelům provádět databázové dotazy v prosté angličtině, což může být výkonný nástroj pro zvýšení produktivity. Výkon ale nemusí vždy znamenat vhodné nebo bezpečné. V tomto cvičení si ukážeme, jak tuto funkci AI používat, a zároveň probereme důležité aspekty, které je potřeba mít na paměti před tím, než se ji rozhodnete implementovat.

Tady je příklad dotazu v přirozeném jazyce, který lze použít k načtení dat z databáze:

Get the the total revenue for all companies in London.

Po správných výzev Azure OpenAI převede tento dotaz na SQL, který se dá použít k vrácení výsledků z databáze. V důsledku toho můžou netechničtí uživatelé, včetně obchodních analytiků, marketingových pracovníků a vedoucích pracovníků, snadněji načítat cenné informace z databází, aniž by museli řešit složitou syntaxi SQL nebo se spoléhat na omezené datové mřížky a filtry. Tento zjednodušený přístup může zvýšit produktivitu tím, že eliminuje potřebu uživatelů hledat pomoc od technických odborníků.

Toto cvičení poskytuje výchozí bod, který vám pomůže pochopit, jak funguje přirozený jazyk SQL, seznámí vás s některými důležitými aspekty, přiměte se zamyslet nad klady a zápory a ukáže vám kód, který vám pomůže začít.

Toto cvičení zahrnuje:

Pomocí výzev GPT převeďte přirozený jazyk na SQL.
Experimentujte s různými výzvami GPT.
Pomocí vygenerovaného SQL můžete dotazovat databázi PostgreSQL, která byla spuštěna dříve.
Vrátí výsledky dotazu z PostgreSQL a zobrazí je v prohlížeči.

Začněme experimentováním s různými výzvami GPT, které lze použít k převodu přirozeného jazyka na SQL.

Použití funkce SQL z přirozeného jazyka

V předchozím cvičení jste spustili databázi, rozhraní API a aplikaci. Aktualizovali .env jste také soubor. Pokud jste tyto kroky nedokončili, postupujte před pokračováním podle pokynů na konci cvičení.
Zpět do prohlížeče (http://localhost:4200) a na stránce pod datovou mřížkou vyhledejte část Vlastní dotaz. Všimněte si, že hodnota ukázkového dotazu je už zahrnutá: Získání celkových výnosů pro všechny objednávky. Seskupte podle společnosti a včetně města.
Vyberte tlačítko Spustit dotaz . Tím se předá dotaz uživatele v přirozeném jazyce do Azure OpenAI, který ho převede na SQL. Dotaz SQL se pak použije k dotazování databáze a vrácení potenciálních výsledků.

Spusťte následující vlastní dotaz:

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

Zobrazte okno terminálu, na kterém běží server rozhraní API v editoru Visual Studio Code, a všimněte si, že se zobrazí dotaz SQL vrácený z Azure OpenAI. Data JSON používají rozhraní API na straně serveru k dotazování databáze PostgreSQL. Všechny řetězcové hodnoty zahrnuté v dotazu se přidají jako hodnoty parametrů, aby se zabránilo útokům prostřednictvím injektáže 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"] 
}
```
Zpět do prohlížeče a vyberte Obnovit data, aby se všichni zákazníci znovu zobrazili v datové mřížce.

Zkoumání přirozeného jazyka pro kód SQL

Tip

Pokud používáte Visual Studio Code, můžete soubory otevřít přímo tak, že vyberete:

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

Pak zadejte název souboru, který chcete otevřít.

Poznámka

Cílem tohoto cvičení je ukázat, co je možné s funkcemi SQL v přirozeném jazyce, a ukázat, jak ho začít používat. Jak už bylo zmíněno dříve, je důležité probrat, jestli je tento typ AI vhodný pro vaši organizaci, než budete pokračovat v jakékoli implementaci. Je také nezbytné naplánovat správná pravidla výzvy a bezpečnostní opatření databáze , aby se zabránilo neoprávněnému přístupu a chránila citlivá data.

Teď, když jste viděli funkci přirozeného jazyka SQL v akci, pojďme se podívat, jak se implementuje.

Otevřete soubor serveru nebo apiRoutes.ts a vyhledejte trasu generateSql . Tuto trasu rozhraní API volá aplikace na straně klienta spuštěná v prohlížeči a používá se ke generování SQL z dotazu v přirozeném jazyce. Jakmile se dotaz SQL načte, použije se k dotazování databáze a vrácení výsledků.

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

Všimněte si následujících funkcí na generateSql trase:

Načte hodnotu uživatelského dotazu z req.body.query a přiřadí ji k proměnné s názvem userQuery. Tato hodnota se použije v příkazovém řádku GPT.
Volá funkci pro převod přirozeného getSQLFromNLP() jazyka na SQL.
Vygenerovaný sql předá funkci s názvem queryDb , která spustí dotaz SQL a vrátí výsledky z databáze.

Otevřete soubor serveru nebo openAI.ts v editoru getSQLFromNLP() a vyhledejte funkci. Tato funkce je volána trasou generatesql a slouží k převodu přirozeného jazyka na 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 only 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.
      - Always return a JSON object with the SQL query and the parameter values in it.
      - Return a JSON object. Do NOT include any text outside of the JSON object.
      - Example JSON object to return: { "sql": "", "paramValues": [] }

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

      - Convert any strings to a PostgreSQL parameterized query value to avoid SQL injection attacks.
      - Do NOT include any text outside of the JSON object. Do not provide any additional explanations or context. Just the JSON object is needed.
    `;

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

Do userPrompt funkce se předá parametr. Hodnota userPrompt je dotaz v přirozeném jazyce zadaný uživatelem v prohlížeči.
A systemPrompt definuje typ asistent AI, který se má použít, a pravidla, která se mají dodržovat. To pomáhá Službě Azure OpenAI pochopit strukturu databáze, jaká pravidla se mají použít a jak vrátit vygenerovaný dotaz a parametry SQL.
Volá se funkce s názvem callOpenAI() a systemPrompt předávají se jí hodnoty a userPrompt .
Výsledky se zkontrolují, aby se zajistilo, že ve vygenerovaném dotazu SQL nejsou zahrnuté žádné zakázané hodnoty. Pokud jsou nalezeny zakázané hodnoty, je dotaz SQL nastavený na prázdný řetězec.

Pojďme si systémovou výzvu projít podrobněji:

const systemPrompt = `
    Assistant is a natural language to SQL bot that returns only 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.
    - Always return a JSON object with the SQL query and the parameter values in it.
    - Return a JSON object. Do NOT include any text outside of the JSON object.
    - Example JSON object to return: { "sql": "", "paramValues": [] }

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

    - Convert any strings to a PostgreSQL parameterized query value to avoid SQL injection attacks.
    - Do NOT include any text outside of the JSON object. Do not provide any additional explanations or context. Just the JSON object is needed.
`;

Je definován typ asistent AI, který se má použít. V tomto případě se jedná o "přirozený jazyk robota SQL".
Názvy tabulek a sloupce v databázi jsou definované. Schéma vysoké úrovně, které je součástí výzvy, najdete v souboru server/db.schema a vypadá takto.
```
- 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)
```
Tip

Můžete zvážit vytvoření zobrazení jen pro čtení, která obsahují pouze data, na která se uživatelé můžou dotazovat pomocí přirozeného jazyka sql.
Je definováno pravidlo, které převede všechny řetězcové hodnoty na parametrizovanou hodnotu dotazu, aby se zabránilo útokům prostřednictvím injektáže SQL.
Pravidlo je definované tak, aby vždy vrátilo objekt JSON (a nic jiného) s dotazem SQL a hodnotami parametrů v něm.
Je uveden příklad pro typ objektu JSON, který se má vrátit.
Jsou k dispozici ukázkové výzvy uživatele a očekávané hodnoty dotazu SQL a parametrů. To se označuje jako "učení s několika výstřely". I když se počítače LLM trénují na velkých objemech dat, dají se přizpůsobit novým úkolům jen s několika příklady. Alternativním přístupem je učení "zero-shot", kde není k dispozici žádný příklad a očekává se, že model vygeneruje správné hodnoty dotazu a parametrů SQL.
V dolní části systémové výzvy se znovu opakují dvě důležitá pravidla, aby se zabránilo "zkreslení recency".

Tip

Další informace o předpojatosti aktuálnosti najdete v dokumentaci k Azure OpenAI.

Funkce getSQLFromNLP() odešle výzvu systému a uživatele funkci s názvem callOpenAI() , která je také umístěna v souboru serveru nebo openAI.ts . Funkce callOpenAI() určuje, jestli se má volat služba Azure OpenAI nebo OpenAI, a to kontrolou proměnných prostředí. Pokud jsou v proměnných prostředí k dispozici klíč, koncový bod a model, volá se Azure OpenAI, jinak se volá OpenAI.
```
function callOpenAI(systemPrompt: string, userPrompt: string, temperature = 0, useBYOD = false) {
    const isAzureOpenAI = OPENAI_API_KEY && OPENAI_ENDPOINT && OPENAI_MODEL;

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

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

    return getOpenAICompletion(systemPrompt, userPrompt, temperature);
}
```
Poznámka

I když se v tomto kurzu zaměříme na Azure OpenAI, pokud zadáte OPENAI_API_KEY jenom hodnotu v souboru .env , aplikace místo toho použije OpenAI. Pokud se rozhodnete místo Azure OpenAI použít OpenAI, můžou se v některých případech zobrazit jiné výsledky.
getAzureOpenAICompletion() Vyhledejte funkci.
```
async function getAzureOpenAICompletion(systemPrompt: string, userPrompt: string, temperature: number): Promise<string> {
    checkRequiredEnvVars(['OPENAI_API_KEY', 'OPENAI_ENDPOINT', 'OPENAI_MODEL']);

    const fetchUrl = `${OPENAI_ENDPOINT}/openai/deployments/${OPENAI_MODEL}/chat/completions?api-version=${OPENAI_API_VERSION}`;

    const messageData: ChatGPTData = {
        max_tokens: 1024,
        temperature,
        messages: [
            { role: 'system', content: systemPrompt },
            { role: 'user', content: userPrompt }
        ]
    };

    const headersBody: OpenAIHeadersBody = {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'api-key': OPENAI_API_KEY
        },
        body: JSON.stringify(messageData),
    };

    const completion = await fetchAndParse(fetchUrl, headersBody);
    console.log(completion);

    let content = (completion.choices[0]?.message?.content?.trim() ?? '') as string;
    console.log('Azure OpenAI Output: \n', content);

    if (content && content.includes('{') && content.includes('}')) {
        content = extractJson(content);
    }

    console.log('After parse: \n', content);

    return content;
}

function checkRequiredEnvVars(requiredEnvVars: string[]) {
    for (const envVar of requiredEnvVars) {
        if (!process.env[envVar]) {
            throw new Error(`Missing ${envVar} in environment variables.`);
        }
    }
}

async function fetchAndParse(url: string, headersBody: Record<string, any>): Promise<any> {
    try {
        const response = await fetch(url, headersBody);
        return await response.json();
    } catch (error) {
        console.error(`Error fetching data from ${url}:`, error);
        throw error;
    }
}
```
Tato funkce provede následující:
- Přijímá systemPromptparametry , userPrompta temperature .
  - systemPrompt: Umožňuje modelu Azure OpenAI zjistit, jakou roli by měl hrát a jaká pravidla má dodržovat.
  - userPrompt: Informace o uživateli zadané do aplikace, jako je přirozený jazyk nebo pravidla, která model použije k vygenerování výstupu.
  - temperature: Určuje, jak kreativní by měl být model při generování odpovědi. Vyšší hodnota znamená, že model bude riskovat více.
- Zajišťuje dostupnost platného klíče rozhraní API Azure OpenAI, koncového bodu a modelu voláním checkRequiredEnvVars().
- Vytvoří fetchUrl hodnotu, která se používá k volání rozhraní REST API služby Azure OpenAI, a vloží do adresy URL hodnoty koncového bodu, modelu a verze rozhraní API z proměnných prostředí.
- Vytvoří messageData objekt, který obsahuje max_token, temperaturea messages pro odeslání do Azure OpenAI.
  - max_tokens: Maximální počet tokenů, které se mají vygenerovat při dokončování. Počet tokenů výzvy plus max_tokens nesmí překročit délku kontextu modelu. Starší modely mají délku kontextu 2 048 tokenů, zatímco novější podporují 4 096, 8 192 nebo dokonce 32 768 tokenů v závislosti na použitém modelu.
  - temperature: Jakou teplotu vzorkování použít. Vyšší hodnoty znamenají, že model bude více riskovat. Vyzkoušejte 0,9 pro kreativnější aplikace a 0 pro ty s dobře definovanou odpovědí.
  - messages: Představuje zprávy, pro které se mají generovat dokončení chatu, ve formátu chatu. V tomto příkladu jsou předány dvě zprávy: jedna pro systém a jedna pro uživatele. Systémová zpráva definuje celkové chování a pravidla, která se budou používat, zatímco zpráva uživatele definuje text výzvy poskytnuté uživatelem.
- Volání fetchAndParse() k odeslání fetchUrl hodnot a headersBody do Azure OpenAI.
- Zpracuje odpověď načtením completion.choices[0].message.content hodnoty. Pokud odpověď obsahuje očekávané výsledky, kód z odpovědi extrahuje objekt JSON a vrátí ho.
  
  Poznámka
  
  Další informace o těchto a dalších parametrech najdete v referenční dokumentaci k Azure OpenAI.

Zakomentujte následující řádky getSQLFromNLP() ve funkci:

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

Uložit openAI.ts. Server rozhraní API automaticky znovu sestaví kód TypeScriptu a restartuje server.
Zpět do prohlížeče a do vstupu Vlastní dotaz zadejte Vybrat všechny názvy tabulek z databáze. Vyberte Spustit dotaz. Zobrazují se názvy tabulek?
Zpět na getSQLFromNLP() funkci na serveru/openAI.ts a do Rules: části systémové výzvy přidejte následující pravidlo a pak soubor uložte.
```
- Do not allow the SELECT query to return table names, function names, or procedure names.
```
Zpět do prohlížeče a proveďte následující úlohy:
- Do vstupu Vlastní dotaz zadejte Vybrat všechny názvy tabulek z databáze. Vyberte Spustit dotaz. Zobrazují se názvy tabulek?
- Zadejte Vybrat všechny názvy funkcí z databáze. Do vstupu Vlastní dotaz a znovu vyberte Spustit dotaz . Zobrazují se názvy funkcí?
OTÁZKA: Proč to stále funguje i po přidání pravidla, které říká, že názvy tabulek, názvy funkcí a názvy procedur nejsou povolené?

ODPOVĚĎ: Důvodem je pravidlo "pouze JSON". Pokud byla pravidla flexibilnější a nevyžadovala vrácení objektu JSON, může se zobrazit zpráva o tom, že Azure OpenAI nemůže provést úlohu.

Poznámka

Je důležité si uvědomit, že modely OpenAI můžou občas vrátit neočekávané výsledky, které nemusí odpovídat definovaným pravidlům. To je důležité naplánovat v kódu.

Vyberte následující pravidlo z systemPrompt a uložte soubor.

- Only return a JSON object. Do NOT include any text outside of the JSON object. Do not provide any additional explanations or context. 
  Just the JSON object is needed.

Znovu spusťte příkaz Vybrat všechny názvy tabulek z databázového dotazu.
Všimněte si zprávy, která se teď zobrazuje v prohlížeči. Azure OpenAI nemůže provést úlohu kvůli následujícímu pravidlu. Vzhledem k tomu, že jsme odebrali pravidlo "pouze JSON", může odpověď poskytnout další podrobnosti o tom, proč úlohu nejde provést.
```
- Do not allow the SELECT query to return table names, function names, or procedure names.
```
Vidíte, že AI může generovat neočekávané výsledky, i když máte určitá pravidla. Proto potřebujete pečlivě naplánovat text výzvy a pravidla, ale také do kódu přidat krok následného zpracování, který bude zpracovávat případy, kdy obdržíte neočekávané výsledky.
Zpět na server nebo openAI.ts a vyhledejte isProhibitedQuery() funkci. Toto je příklad kódu pro následné zpracování, který je možné spustit po vrácení výsledků Azure OpenAI. Všimněte si, že vlastnost nastaví sql na prázdný řetězec, pokud jsou ve vygenerovaném dotazu SQL vrácena zakázaná klíčová slova. Tím se zajistí, že pokud se z Azure OpenAI vrátí neočekávané výsledky, dotaz SQL se pro databázi nespustí.
```
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_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));
}
```
Poznámka

Je důležité si uvědomit, že se jedná pouze o ukázkový kód. Pokud se rozhodnete převést přirozený jazyk na SQL, můžou být pro konkrétní případy použití vyžadována další zakázaná klíčová slova. Jedná se o funkci, kterou musíte naplánovat a používat s opatrností, abyste zajistili, že se v databázi vrátí a spustí pouze platné dotazy SQL. Kromě zakázaných klíčových slov budete muset také zohlednit zabezpečení.
Zpět na server nebo openAI.ts a zrušte komentář následujícího kódu ve getSQLFromNLP() funkci. Soubor uložte.
```
if (isProhibitedQuery(queryData.sql)) { 
    queryData.sql = '';
}
```

Odeberte následující pravidlo z systemPrompt a soubor uložte.

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

Zpět v prohlížeči znovu zadejte Do vstupu Vlastní dotazpříkaz Select all table names from the database (Vybrat všechny názvy tabulek z databáze) a vyberte tlačítko Run Query (Spustit dotaz).
Zobrazují se výsledky v tabulce? I bez tohoto pravidla kód následného isProhibitedQuery() zpracování zakáže spuštění tohoto typu dotazu v databázi.
Jak už jsme si řekli dříve, integrace přirozeného jazyka do SQL v obchodních aplikacích může být pro uživatele docela přínosná, ale má to svůj vlastní soubor aspektů.

Výhody:
- Uživatelsky přívětivost: Tato funkce může zpřístupnit interakci s databází uživatelům bez technických odborných znalostí, což snižuje potřebu znalostí SQL a potenciálně urychluje operace.
- Vyšší produktivita: Obchodní analytici, obchodní pracovníci, vedoucí pracovníci a další netechnická uživatelé můžou z databází načítat cenné informace, aniž by se museli spoléhat na technické odborníky, což zvyšuje efektivitu.
- Široké použití: Pomocí pokročilých jazykových modelů je možné aplikace navrhnout tak, aby vyhovovaly širokému okruhu uživatelů a případů použití.
Úvahy:
- Zabezpečení: Jedním z největších problémů je zabezpečení. Pokud uživatelé můžou pracovat s databázemi pomocí přirozeného jazyka, musí být zavedená robustní bezpečnostní opatření, která zabrání neoprávněnému přístupu nebo škodlivým dotazům. Můžete zvážit implementaci režimu jen pro čtení, abyste uživatelům zabránili v úpravách dat.
- Ochrana osobních údajů v datech: Některá data můžou být citlivá a neměla by být snadno přístupná, takže budete muset zajistit náležitá bezpečnostní opatření a uživatelská oprávnění.
- Přesnost: I když se zpracování přirozeného jazyka výrazně zlepšilo, není dokonalé. Nesprávná interpretace uživatelských dotazů může vést k nepřesným výsledkům nebo neočekávanému chování. Budete muset naplánovat, jak se budou zpracovávat neočekávané výsledky.
- Efektivita: Neexistuje žádná záruka, že sql server vrácený dotazem v přirozeném jazyce bude efektivní. V některých případech se můžou vyžadovat další volání Azure OpenAI, pokud pravidla následného zpracování detekují problémy s dotazy SQL.
- Školení a přizpůsobení uživatelům: Aby uživatelé správně formulovali své dotazy, je potřeba je vytrénovat. I když je to jednodušší než učení SQL, stále může být součástí křivky učení.
Pár posledních bodů, které je potřeba zvážit, než přejdete k dalšímu cvičení:
- Nezapomeňte, že "Jen proto, že můžete, neznamená, že byste měli". Před integrací přirozeného jazyka do SQL do aplikace postupujte velmi opatrně a pečlivě. Je důležité pochopit potenciální rizika a naplánovat je.
- Před použitím tohoto typu technologie prodiskutujte potenciální scénáře se svým týmem, správci databází, bezpečnostními týmy, zúčastněnými stranami a dalšími důležitými stranami, abyste zajistili, že jsou vhodné pro vaši organizaci. Je důležité prodiskutovat, jestli přirozený jazyk SQL splňuje zabezpečení, ochranu osobních údajů a další požadavky, které vaše organizace může mít.
- Zabezpečení by mělo být primárním problémem a mělo by být součástí procesu plánování, vývoje a nasazení.
- I když přirozený jazyk SQL může být velmi výkonný, je potřeba ho pečlivě naplánovat, aby se zajistilo, že výzvy mají požadovaná pravidla a že jsou zahrnuté funkce následného zpracování. Naplánujte další čas na implementaci a otestování tohoto typu funkcí a na scénáře, ve kterých se vrátí neočekávané výsledky.
- S Azure OpenAI získají zákazníci možnosti zabezpečení Microsoft Azure a současně používají stejné modely jako OpenAI. Azure OpenAI nabízí privátní sítě, regionální dostupnost a zodpovědné filtrování obsahu AI. Přečtěte si další informace o datech, ochraně osobních údajů a zabezpečení pro službu Azure OpenAI.
Teď jste viděli, jak pomocí Azure OpenAI převést přirozený jazyk na SQL, a seznámili jste se s klady a nevýhodami implementace tohoto typu funkcí. V dalším cvičení se dozvíte, jak se dají generovat e-mailové a SMS zprávy pomocí Azure OpenAI.

AI: Generování dokončení

112 min zbývá

Kromě funkce přirozeného jazyka SQL můžete také pomocí služby Azure OpenAI generovat e-mailové a SMS zprávy a zvýšit produktivitu uživatelů a zjednodušit komunikační pracovní postupy. Díky možnostem generování jazyka v Azure OpenAI můžou uživatelé definovat konkrétní pravidla, jako je například "Objednávka je zpožděná o 5 dnů", a systém na základě těchto pravidel automaticky vygeneruje kontextově vhodné e-mailové a SMS zprávy.

Tato funkce slouží jako "rychlý start" pro uživatele a poskytuje jim promyšleně vytvořenou šablonu zpráv, kterou si mohou před odesláním snadno přizpůsobit. Výsledkem je výrazné zkrácení času a úsilí potřebného k vytváření zpráv, což uživatelům umožňuje soustředit se na další důležité úkoly. Technologie generování jazyka v Azure OpenAI se navíc dá integrovat do pracovních postupů automatizace, což systému umožňuje autonomní generování a odesílání zpráv v reakci na předdefinované triggery. Tato úroveň automatizace nejen zrychluje komunikační procesy, ale také zajišťuje konzistentní a přesné zasílání zpráv v různých scénářích.

Toto cvičení zahrnuje:

Experimentujte s různými výzvami GPT.
Pomocí výzev GPT vygenerujte dokončení e-mailových a SMS zpráv.
Prozkoumejte kód, který umožňuje dokončování GPT.
Seznamte se s důležitostí rychlé přípravy a zahrnutím pravidel do výzev.

Začněme experimentováním s různými pravidly, která se dají použít ke generování e-mailových a SMS zpráv.

Použití funkce dokončování GPT

V předchozím cvičení jste spustili databázi, rozhraní API a aplikaci. Aktualizovali .env jste také soubor. Pokud jste tyto kroky nedokončili, postupujte před pokračováním podle pokynů na konci cvičení.
Zpět v prohlížeči (http://localhost:4200) a výběrem možnosti Kontaktovat zákazníka na libovolném řádku datové mřížky následovaným zákazníkem Email/SMS přejděte na obrazovku Generátor zpráv.
To používá Azure OpenAI k převodu pravidel zpráv, která definujete, na Email/SMS zprávy. Proveďte následující úlohy:
- Zadejte pravidlo, například Objednávka se zpozdí o 5 dnů před vstupem, a vyberte tlačítko Generovat Email/SMS zprávy.
- Zobrazí se předmět a text vygenerovaný pro e-mail a krátká zpráva vygenerovaná pro SMS.
Poznámka

Vzhledem k tomu, že Azure Communication Services ještě není povolená, nebudete moct odesílat e-maily ani ZPRÁVY SMS.
Zavřete dialogové okno e-mailu nebo SMS v prohlížeči. Teď, když jste tuto funkci viděli v akci, se podíváme na její implementaci.

Zkoumání kódu dokončování GPT

Tip

Pokud používáte Visual Studio Code, můžete soubory otevřít přímo tak, že vyberete:

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

Potom zadejte název souboru, který chcete otevřít.

Otevřete soubor server/apiRoutes.ts a vyhledejte trasu completeEmailSmsMessages . Toto rozhraní API volá front-endová část aplikace, když je vybráno tlačítko Generovat Email/SMS zprávy. Načte hodnoty výzvy uživatele, společnosti a jména kontaktu z těla a předá je funkci completeEmailSMSMessages() v souboru serveru/openAI.ts . Výsledky se pak vrátí klientovi.

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

Otevřete soubor server/openAI.ts a vyhledejte completeEmailSMSMessages() funkci .

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. 
    - Only return a valid JSON object. Do NOT include any text outside of the JSON object. Do not provide any additional explanations or context. 
    Just the JSON object is needed.
    `;

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

Tato funkce má následující funkce:

systemPromptSlouží k definování, že se vyžaduje asistent umělé inteligence schopné generovat e-mailové a SMS zprávy. Obsahuje systemPrompt také:
- Pravidla pro asistent, která mají řídit tón zpráv, počáteční a koncový formát, maximální délku SMS zpráv a další.
- Informace o datech, která by měla být součástí odpovědi – v tomto případě jde o objekt JSON a pouze objekt JSON.
- V dolní části výzvy systému se znovu opakují dvě kritická pravidla, aby se zabránilo "zkreslení aktuálnosti".
userPrompt Slouží k definování pravidel a kontaktního jména, které chce koncový uživatel zahrnout při generování e-mailových a SMS zpráv. Pravidlo Objednávky se zpožděním o 5 dnů , které jste zadali dříve, je součástí userPrompt.
Funkce volá funkci, callOpenAI() kterou jste prozkoumali dříve, a vygeneruje dokončení e-mailu a ZPRÁVY SMS.

Zpět do prohlížeče aktualizujte stránku a na libovolném řádku vyberte Contact Customer (Kontaktovat zákazníka), po kterém následuje Email/SMS Customer (Zákazník Email/SMS), abyste se znovu dostali na obrazovku Generátor zpráv.
Do vstupu Generátor zpráv zadejte následující pravidla:
- Objednávka je před plánem.
- Řekněte zákazníkovi, aby si u nás už nikdy neobjednán, protože nechceme jeho podnikání.
Vyberte Generovat Email/SMS zprávy a poznamenejte si zprávu. Pravidlo All messages should have a friendly tone and never use inappropriate language. na příkazovém řádku systému přepisuje záporné pravidlo v příkazovém řádku uživatele.
Zpět v editoru na server/openAI.ts* a odeberte All messages should have a friendly tone and never use inappropriate language. pravidlo z výzvy completeEmailSMSMessages() ve funkci. Soubor uložte.
Zpět do generátoru e-mailů/SMS zpráv v prohlížeči a znovu spusťte stejná pravidla:
- Objednávka je před plánem.
- Řekněte zákazníkovi, aby si u nás už nikdy neobjednán, protože nechceme jeho podnikání.
Vyberte Generovat Email/SMS zprávy a všimněte si vrácené zprávy.
Co se v těchto scénářích děje? Při použití Azure OpenAI se použije filtrování obsahu , aby se zajistilo, že se vždy používá vhodný jazyk. Pokud používáte OpenAI, použije se pravidlo definované v systémovém příkazovém řádku, aby se zajistilo, že vrácená zpráva je vhodnou.

Poznámka

To ilustruje důležitost přípravy výzev se správnými informacemi a pravidly, které zajistí vrácení správných výsledků. Další informace o tomto procesu najdete v úvodu do dokumentace prompt engineering .
Vraťte zpět změny, které jste udělali systemPrompt v completeEmailSMSMessages(), uložte soubor a znovu ho spusťte, ale použijte Order is ahead of schedule. jenom pravidlo (nezahrnujte záporné pravidlo). Tentokrát by se měly e-mailové a SMS zprávy vrátit podle očekávání.
Pár posledních bodů, které je potřeba zvážit, než přejdete k dalšímu cvičení:
- Je důležité mít ve smyčce člověka, který kontroluje vygenerované zprávy. V tomto příkladu vrací dokončování Azure OpenAI navrhované e-mailové a SMS zprávy, ale uživatel je může před odesláním přepsat. Pokud plánujete automatizovat e-maily, je důležité mít nějaký typ procesu kontroly člověkem, který zajistí, že se schválené zprávy odesílají. Podívejte se na AI jako na kopírku, ne jako na autopilot.
- Dokončení bude pouze tak dobré jako pravidla, která přidáte do výzvy. Vyzkoušejte výzvy a vrácené dokončení. Pozvěte ostatní účastníky projektu, aby si také zkontrolovali dokončení projektu.
- Možná budete muset zahrnout kód pro následné zpracování, aby se zajistilo správné zpracování neočekávaných výsledků.
- Pomocí systémových výzev definujte pravidla a informace, kterými by se měla asistent AI řídit. Pomocí výzev uživatele definujte pravidla a informace, které chce koncový uživatel zahrnout do dokončování.

AI: Používání vlastních dat

102 min zbývá

Integrace funkcí zpracování přirozeného jazyka (NLP) a funkcí pro dokončování v Azure OpenAI nabízí významný potenciál pro zvýšení produktivity uživatelů. Díky využití vhodných výzev a pravidel může asistent AI efektivně generovat různé formy komunikace, jako jsou e-mailové zprávy, ZPRÁVY SMS a další. Tato funkce vede ke zvýšení uživatelské efektivity a efektivnějším pracovním postupům.

I když je tato funkce sama o sobě poměrně výkonná, můžou existovat případy, kdy uživatelé potřebují generovat dokončení na základě vlastních dat vaší společnosti. Můžete mít například kolekci příruček k produktům, které můžou být pro uživatele náročné, když pomáhají zákazníkům s instalací. Alternativně můžete udržovat komplexní sadu nejčastějších dotazů souvisejících s výhodami zdravotní péče, které mohou být pro uživatele náročné přečíst a získat potřebné odpovědi. V těchto a mnoha dalších případech služba Azure OpenAI umožňuje využít vlastní data ke generování dokončení a zajistit tak přizpůsobenou a kontextově přesnější odpověď na dotazy uživatelů.

Tady je rychlý přehled toho, jak funguje funkce Přineste si vlastní data z dokumentace k Azure OpenAI.

Poznámka

Jednou z klíčových funkcí Azure OpenAI pro vaše data je její schopnost načítat a využívat data způsobem, který vylepšuje výstup modelu. Azure OpenAI u vašich dat společně s Azure Cognitive Search určuje, jaká data se mají načíst z určeného zdroje dat na základě vstupu uživatele a poskytnuté historie konverzací. Tato data se pak rozšíří a znovu odešle jako výzva k modelu OpenAI, přičemž načtené informace se připojí k původní výzvě. I když se načtená data připojují k výzvě, výsledný vstup model stále zpracovává stejně jako jakákoli jiná výzva. Jakmile se data načtou a do modelu se odešle výzva, model tyto informace použije k dokončení.

Toto cvičení zahrnuje:

Vytvořte vlastní zdroj dat pomocí Azure AI Studio.
Nasaďte model vkládání pomocí Azure AI Studio.
Nahrajte vlastní dokumenty.
Zahajte chatovací relaci v chatovacím prostředí a experimentujte s generováním dokončení na základě vlastních dat.
Prozkoumejte kód, který používá Azure Cognitive Search a Azure OpenAI k vygenerování dokončení na základě vašich vlastních dat.

Začněme nasazením modelu vložení a přidáním vlastního zdroje dat do Azure AI Studio.

Přidání vlastního zdroje dat do Azure AI Studio

Přejděte do Azure OpenAI Studia a přihlaste se pomocí přihlašovacích údajů, které mají přístup k vašemu prostředku Azure OpenAI.
V navigační nabídce vyberte Nasazení .
Vyberte Vytvořit nové nasazení a zadejte následující hodnoty:
- Model: text-embedding-ada-002.
- Verze modelu: Výchozí.
- Název nasazení: text-embedding-ada-002.
Po vytvoření modelu vyberte v navigační nabídce Azure OpenAI a přejděte na úvodní obrazovku.
Na úvodní obrazovce vyhledejte dlaždici Přineste si vlastní data a vyberte Vyzkoušet.
V rozevíracím seznamu Vybrat zdroj dat vyberte Nahrát soubory.
V rozevíracím seznamu Vybrat prostředek úložiště objektů blob v Azure vyberte Vytvořit nový prostředek úložiště objektů blob v Azure.
Tím přejdete na Azure Portal, kde můžete provádět následující úlohy:
- Zadejte jedinečný název účtu úložiště, například byodstorage[Vaše příjmení].
- Vyberte oblast, která je blízko vaší polohy.
- Vyberte Zkontrolovat a pak Vytvořit.
Po vytvoření prostředku úložiště objektů blob se vraťte do dialogového okna Azure AI Studio a v rozevíracím seznamu Vybrat prostředek úložiště objektů blob vyberte nově vytvořený prostředek úložiště objektů blob. Pokud ho v seznamu nevidíte, vyberte ikonu aktualizace vedle rozevíracího seznamu.
Aby bylo možné získat přístup k účtu úložiště, musí být zapnuté sdílení prostředků mezi zdroji (CORS). V dialogovém okně Azure AI Studio vyberte Zapnout CORS.
V rozevíracím seznamu Vybrat prostředek Azure Cognitive Search vyberte Vytvořit nový prostředek Azure Cognitive Search.
Tím se vrátíte do Azure Portal, kde můžete provádět následující úlohy:
- Zadejte jedinečný název prostředku služby Cognitive Search, například byodsearch[Vaše příjmení].
- Vyberte oblast, která je blízko vaší polohy.
- V části Cenová úroveň vyberte Změnit cenovou úroveň a vyberte Basic a pak Vyberte Vybrat. Bezplatná úroveň se nepodporuje, takže prostředek služby Cognitive Search vyčistíte na konci tohoto kurzu.
- Vyberte Zkontrolovat a pak Vytvořit.
Po vytvoření prostředku služby Cognitive Search přejděte na stránku Přehled prostředku a zkopírujte hodnotu url do místního souboru.
V levé navigační nabídce vyberte Klíče a zkopírujte hodnotu Primární klíč správce do místního souboru. Tyto hodnoty budete potřebovat později ve cvičení.
V levé navigační nabídce vyberte Sémantický ranker a ujistěte se, že je vybraná možnost Free .

Poznámka

Pokud chcete zkontrolovat, jestli je sémantický nástroj k dispozici v konkrétní oblasti, podívejte se na stránku Produkty dostupné v jednotlivých oblastech na webu Azure a zjistěte, jestli je uvedená vaše oblast.
Zpět do dialogového okna Azure AI Studio Přidat data a v rozevíracím seznamu Vybrat prostředek Azure Cognitive Search vyberte nově vytvořený prostředek vyhledávání. Pokud ho v seznamu nevidíte, vyberte ikonu aktualizace vedle rozevíracího seznamu.
Do pole Zadejte název indexu zadejte hodnotu byod-search-index.
Zaškrtněte políčko Přidat vektorové vyhledávání do tohoto vyhledávacího prostředku .
V rozevíracím seznamu Vyberte model vložení vyberte model text-embedding-ada-002 , který jste vytvořili dříve.
Zaškrtněte políčko následované dalšími.
V dialogovém okně Nahrát soubory vyberte Vyhledat soubor.
Přejděte do složky dokumentů zákazníka projektu (nachází se v kořenovém adresáři projektu) a vyberte následující soubory:
- Instalační Instructions.docxhodin A102
- FAQs.docxspolečnosti
Poznámka

Tato funkce aktuálně podporuje následující formáty souborů pro vytváření místních indexů: .txt, .md, .html, .pdf, .docx a .pptx.
Vyberte Nahrát soubory. Soubory se nahrají do kontejneru fileupload-byod-search-index v prostředku úložiště objektů blob, který jste vytvořili dříve.
Výběrem možnosti Další přejděte do dialogového okna Správa dat .
V rozevíracím seznamu Typ hledání vyberte Hybridní a sémantický.

Poznámka

Tato možnost poskytuje podporu pro vyhledávání klíčových slov a vektorů. Po vrácení výsledků se na sadu výsledků použije sekundární proces řazení pomocí modelů hlubokého učení, což zvyšuje relevanci vyhledávání pro uživatele. Další informace o sémantickém vyhledávání najdete v dokumentaci k sémantickému vyhledávání v Azure Cognitive Search.
Zaškrtnutím políček potvrďte náklady spojené s používáním sémantického vyhledávání a vkládání vektorů.
Vyberte Další, zkontrolujte podrobnosti a vyberte Uložit a zavřít.
Teď, když se vaše vlastní data nahrála, se indexují a budou k dispozici pro použití v chatovacím prostředí. Tento proces může trvat několik minut. Po dokončení pokračujte k další části.

Použití vlastního zdroje dat v chatovacím prostředí

Na stránce vyhledejte část Chat session (Relace chatu) v Azure AI Studio a zadejte následující zprávu:
```
What safety rules are required to install a clock?
```
Měl by se zobrazit výsledek podobný následujícímu:
Rozbalte část 1 reference v odpovědi chatu a všimněte si, že je uveden instalační soubor clock A102 Instructions.docx a že ho můžete vybrat a zobrazit dokument.

Zadejte následující zprávu uživatele:

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

Měl by se zobrazit výsledek podobný následujícímu:
Teď experimentujme s dokumentem Nejčastější dotazy společnosti. Do pole Zpráva uživatele zadejte následující text:
```
What is the company's policy on vacation time?
```
Měli byste vidět, že se pro danou žádost nenašly žádné informace.
Do pole Zpráva uživatele zadejte následující text:
```
How should I handle refund requests?
```
Měl by se zobrazit výsledek podobný následujícímu:
V odpovědi na chat rozbalte 1 reference a všimněte si, že je uvedený soubor Company FAQs.docx a že ho můžete vybrat a dokument zobrazit.
V horní části části Chat session (Chat session) vyberte View code (Zobrazit kód).
Všimněte si, že můžete přepínat mezi různými jazyky, zobrazit koncový bod a získat přístup ke klíči koncového bodu. Zavřete dialogové okno Vzorový kód .
V relaci *Chat zapněte přepínač Show raw JSON (Zobrazit nezpracovaný JSON). Všimněte si, že relace chatu začíná zprávou podobnou následující:
```
{
    "role": "system",
    "content": "You are an AI assistant that helps people find information."
}
```
Teď, když jste vytvořili vlastní zdroj dat a experimentovali jste s ním v chatovacím prostředí, se podíváme, jak ho můžete použít v aplikaci projektu.

Použití funkce Přineste si vlastní data v aplikaci

Zpět do projektu v editoru Visual Studio Code a otevřete soubor .env. Aktualizujte následující hodnoty názvem koncového bodu, klíče a indexu služeb Cognitive Services. Dříve v tomto cvičení jste zkopírovali koncový bod a klíč do místního souboru.
```
AZURE_COGNITIVE_SEARCH_ENDPOINT=<COGNITIVE_SERVICES_ENDPOINT_VALUE>
AZURE_COGNITIVE_SEARCH_KEY=<COGNITIVE_SERVICES_KEY_VALUE>
AZURE_COGNITIVE_SEARCH_INDEX=byod-search-index
```
V předchozím cvičení jste spustili databázi, rozhraní API a aplikaci. Aktualizovali .env jste také soubor. Pokud jste tyto kroky nedokončili, postupujte před pokračováním podle pokynů na konci předchozího cvičení.
Jakmile se aplikace načte v prohlížeči, vyberte ikonu Chat Help (Nápověda chatu ) v pravém horním rohu aplikace.
V dialogovém okně chatu by se měl zobrazit následující text:
```
How should I handle refund requests?
```
Vyberte tlačítko Získat nápovědu . Měly by se zobrazit výsledky vrácené z dokumentu společnosti FAQs.docx, který jste nahráli dříve v Azure AI Studio. Pokud si chcete dokument přečíst, najdete ho ve složce dokumentů zákazníka v kořenovém adresáři projektu.
Změňte text na následující a vyberte tlačítko Získat nápovědu :
```
What safety rules are required to install a clock?
```
Měly by se zobrazit výsledky vrácené z dokumentu Instalace hodin A102 Instructions.docx, který jste nahráli dříve v Azure AI Studio. Tento dokument je také k dispozici ve složce dokumentů zákazníka v kořenovém adresáři projektu.

Zkoumání kódu

Tip

Pokud používáte Visual Studio Code, můžete soubory otevřít přímo tak, že vyberete:

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

Potom zadejte název souboru, který chcete otevřít.

Zpět do zdrojového kódu projektu v editoru Visual Studio Code.

Otevřete soubor server/apiRoutes.ts a vyhledejte trasu completeBYOD . Toto rozhraní API se volá, když je v dialogovém okně Nápověda k chatu vybráno tlačítko Získat nápovědu . Načte výzvu uživatele z textu požadavku a předá ji completeBYOD() funkci v souboru openAI.ts serveru . Výsledky se pak vrátí klientovi.

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

Otevřete soubor server/openAI.ts a vyhledejte completeBYOD() funkci .
```
async function completeBYOD(userPrompt: string): Promise<string> {
    const systemPrompt = 'You are an AI assistant that helps people find information.';
    // Pass that we're using Cognitive Search along with Azure OpenAI.
    return await callOpenAI(systemPrompt, userPrompt, 0, true);
}
```
Tato funkce má následující funkce:
- Parametr userPrompt obsahuje informace, které uživatel zadal do dialogového okna nápovědy chatu.
- Proměnná systemPrompt definuje, že se použije asistent AI navržená tak, aby uživatelům pomohla najít informace.
- callOpenAI() se používá k volání rozhraní API Azure OpenAI a vrácení výsledků. Předá systemPrompt hodnoty a userPrompt a následující parametry:
  - temperature - Míra kreativity, která se má zahrnout do reakce. Uživatel potřebuje v tomto případě konzistentní (méně kreativní) odpovědi, takže hodnota je nastavená na 0.
  - useBYOD – Logická hodnota, která označuje, jestli se má společně s Azure OpenAI používat cognitive search, nebo ne. V tomto případě je nastavená tak, aby true se používala funkce kognitivního hledání.

Funkce callOpenAI() přijímá useBYOD parametr, který se používá k určení funkce OpenAI, která se má volat. V tomto případě nastaví useBYOD na true , aby se getAzureOpenAIBYODCompletion() funkce volala.

function callOpenAI(systemPrompt: string, userPrompt: string, temperature = 0, useBYOD = false) {
    const isAzureOpenAI = OPENAI_API_KEY && OPENAI_ENDPOINT && OPENAI_MODEL;

    if (isAzureOpenAI && useBYOD) {
        // Azure OpenAI + Cognitive Search: Bring Your Own Data
        return getAzureOpenAIBYODCompletion(systemPrompt, userPrompt, temperature);
    }

    if (isAzureOpenAI) {
        // Azure OpenAI
        return getAzureOpenAICompletion(systemPrompt, userPrompt, temperature);
    }

    // OpenAI
    return getOpenAICompletion(systemPrompt, userPrompt, temperature);
}

getAzureOpenAIBYODCompletion() Vyhledejte funkci na serveru nebo openAI.ts. Je docela podobná getAzureOpenAICompletion() funkci, kterou jste prozkoumali dříve, ale zobrazuje se jako samostatná funkce, která zvýrazňuje několik klíčových rozdílů, které jsou jedinečné pro scénář "Přineste si vlastní data", který je k dispozici v Azure OpenAI.

Hodnota fetchUrl zahrnuje extensions segment v adrese URL, zatímco adresa URL pro standardní rozhraní Azure OpenAI API ne.

const fetchUrl = `${OPENAI_ENDPOINT}/openai/deployments/${OPENAI_MODEL}/extensions/chat/completions?api-version=${OPENAI_API_VERSION}`;

Do dataSources objektu odeslaného messageData do Azure OpenAI se přidá vlastnost. Vlastnost dataSources obsahuje hodnoty , keya indexName prostředku endpointslužby Cognitive Search, které byly přidány do .env souboru dříve v tomto cvičení.

const messageData: ChatGPTData = {
    max_tokens: 1024,
    temperature,
    messages: [
        { role: 'system', content: systemPrompt },
        { role: 'user', content: userPrompt }
    ],
    // Adding BYOD data source so that Cognitive Search is used with Azure OpenAI
    dataSources: [
        {
            type: 'AzureCognitiveSearch',
            parameters: {
                endpoint: AZURE_COGNITIVE_SEARCH_ENDPOINT,
                key: AZURE_COGNITIVE_SEARCH_KEY,
                indexName: AZURE_COGNITIVE_SEARCH_INDEX
            }
        }
    ]
};

Objekt headersBody obsahuje chatpgpt_url vlastnosti a chatgpt_key , které se po získání výsledků služby Cognitive Search používají k volání Azure OpenAI.

const headersBody: OpenAIHeadersBody = {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'api-key': OPENAI_API_KEY,
        chatgpt_url: fetchUrl.replace('extensions/', ''),
        chatgpt_key: OPENAI_API_KEY
    },
    body: JSON.stringify(messageData),
};

Odpověď vrácená službou Azure OpenAI zahrnuje dvě chyby s rolemi tool a assistant. Ukázková aplikace použije druhou zprávu s role z k poskytnutí požadovaných assistant informací uživateli. V případech, kdy chcete poskytnout další informace o dokumentech použitých k vytvoření odpovědi (jak jste viděli dříve v Azure AI Studio testovacím prostředí), můžete použít první zprávu, která obsahuje url dokumenty.

{
    "id": "12345678-1a2b-3c4e5f-a123-12345678abcd",
    "model": "",
    "created": 1684304924,
    "object": "chat.completion",
    "choices": [
        {
            "index": 0,
            "messages": [
                {
                    "role": "tool",
                    "content": "{\"citations\": [{\"content\": \"\\nCognitive Services are cloud-based artificial intelligence (AI) services...\", \"id\": null, \"title\": \"What is Cognitive Services\", \"filepath\": null, \"url\": null, \"metadata\": {\"chunking\": \"orignal document size=250. Scores=0.4314117431640625 and 1.72564697265625.Org Highlight count=4.\"}, \"chunk_id\": \"0\"}], \"intent\": \"[\\\"Learn about Azure Cognitive Services.\\\"]\"}",
                    "end_turn": false
                },
                {
                    "role": "assistant",
                    "content": " \nAzure Cognitive Services are cloud-based artificial intelligence (AI) services that help developers build cognitive intelligence into applications without having direct AI or data science skills or knowledge. [doc1]. Azure Machine Learning is a cloud service for accelerating and managing the machine learning project lifecycle. [doc1].",
                    "end_turn": true
                }
            ]
        }
    ]
}

Následující kód se používá v getAzureOpenAIBYODCompletion() nástroji pro přístup ke zprávům. I když se citace v tomto příkladu nepoužívají, zaprotokolují se do konzoly, abyste viděli typ vrácených dat.

const completion = await fetchAndParse(fetchUrl, headersBody);
console.log(completion);

if (completion.error) {
    console.error('Azure OpenAI BYOD Error: \n', completion.error);
    return completion.error.message;
}

const citations = (completion.choices[0]?.messages[0]?.content?.trim() ?? '') as string;
console.log('Azure OpenAI BYOD Citations: \n', citations);

let content = (completion.choices[0]?.messages[1]?.content?.trim() ?? '') as string;
console.log('Azure OpenAI BYOD Output: \n', content);

return content;

Pár posledních bodů, které je potřeba zvážit, než přejdete k dalšímu cvičení:
- Funkce Přineste si vlastní data v Azure OpenAI je aktuálně ve verzi Preview. V tuto chvíli se nedoporučuje používat v produkčních aplikacích.
- Ukázková aplikace používá v Azure Cognitive Search jeden index. S Azure OpenAI můžete použít více indexů a zdrojů dat. Vlastnost dataSources ve getAzureOpenAIBYODCompletion() funkci je možné podle potřeby aktualizovat tak, aby zahrnovala více zdrojů dat.
- U tohoto typu scénáře je potřeba pečlivě vyhodnotit zabezpečení. Uživatelé by neměli mít možnost klást otázky a získávat výsledky z dokumentů, ke kterým nemají přístup.
Teď, když jste se seznámili s Azure OpenAI, výzvami, dokončováními a tím, jak můžete používat vlastní data, přejděme k dalšímu cvičení, kde se dozvíte, jak se komunikační funkce dají použít k vylepšení aplikace. Další informace o Azure OpenAI najdete v školicím obsahu Začínáme se službou Azure OpenAI . Další informace o používání vlastních dat s Azure OpenAI najdete v dokumentaci k datům v tématu Azure OpenAI .

Komunikace: Vytvoření prostředku Azure Communication Services

87 min zbývá

Efektivní komunikace je nezbytná pro úspěšné vlastní obchodní aplikace. Pomocí služby Azure Communication Services (ACS) můžete do svých aplikací přidávat funkce, jako jsou telefonní hovory, živý chat, hlasové hovory nebo videohovory a e-maily a zprávy SMS. Dříve jste se dozvěděli, jak Azure OpenAI může generovat dokončení e-mailových a SMS zpráv. Teď se dozvíte, jak zprávy odeslat. ACS a OpenAI mohou společně vylepšit vaše aplikace tím, že zjednodušují komunikaci, zlepšují interakce a zvyšují produktivitu firmy.

Toto cvičení zahrnuje:

Vytvořte prostředek Azure Communication Services (ACS).
Přidejte bezplatné telefonní číslo s funkcemi volání a SMS.
Připojení e-mailové domény
Aktualizujte soubor .env projektu pomocí hodnot z vašeho prostředku služby ACS.

Přehled scénáře Microsoft Cloud

Vytvoření prostředku Azure Communication Services

Přejděte na Azure Portal v prohlížeči a přihlaste se, pokud jste to ještě neudělali.
Do vyhledávacího panelu v horní části stránky zadejte komunikační služby a ze zobrazených možností vyberte Komunikační služby.
Na panelu nástrojů vyberte Vytvořit .
Proveďte následující úlohy:
- Vyberte své předplatné Azure.
- Vyberte skupinu prostředků, kterou chcete použít (vytvořte novou, pokud neexistuje).
- Zadejte název prostředku služby ACS. Tato hodnota musí být jedinečná.
- Vyberte umístění dat.
Vyberte Zkontrolovat a vytvořit a pak Vytvořit.
Úspěšně jste vytvořili nový prostředek Azure Communication Services. V dalším kroku povolíte funkce telefonního hovoru a SMS. K prostředku také připojíte e-mailovou doménu.

Povolení funkcí telefonních hovorů a SMS

Přidejte telefonní číslo a ujistěte se, že je na telefonním čísle povolené možnosti volání. Toto telefonní číslo použijete k volání na telefon z aplikace.
- Vyberte Phone numbers v nabídce Prostředek.
- Na + Get panelu nástrojů vyberte (nebo vyberte tlačítko Získat číslo ) a zadejte následující informace:
  - Země nebo oblast: United States
  - Případ použití: Vyberte An application will be making calls or sending SMS mesages
  - Typ čísla: Bezplatná linka
  Poznámka
  
  K vytvoření bezplatného čísla se ve vašem předplatném Azure vyžaduje platební karta. Pokud kartu nemáte v souboru, můžete přeskočit přidání telefonního čísla a přejít k další části cvičení, která propojuje e-mailovou doménu. Aplikaci můžete dál používat, ale nebudete moct volat na telefonní číslo.
  - Volání: Make calls
  - SMS: Send and receive SMS
Vyberte Další: Čísla.
Vyberte předponu (například 877) a ponechte množství na hodnotě 1. Vyberte Vyhledat.
Jakmile se zobrazí číslo bezplatné linky, vyberte Další: Souhrn.
Zkontrolujte podrobnosti a vyberte Zadat objednávku a přidejte telefonní číslo do prostředku služby ACS.
Po vytvoření telefonního čísla se jeho výběrem dostanete na panel Funkce . Ujistěte se, že jsou nastavené následující hodnoty:
- V části Volání vyberte Make calls.
- V části SMS vyberte Send and receive SMS.
- Vyberte Uložit.
Zkopírujte hodnotu telefonního čísla do souboru pro pozdější použití.

Připojení Email domény

Provedením následujících úloh vytvořte pro prostředek služby ACS připojenou e-mailovou doménu, abyste mohli posílat e-maily. Použije se k odesílání e-mailů z aplikace.
- V nabídce Prostředek vyberte Domény .
- Na panelu nástrojů vyberte Připojit doménu .
- Vyberte předplatné a skupinu prostředků.
- V rozevíracím seznamu Email Service vyberte Add an email service.
- Zadejte název e-mailové služby, například acs-demo-email-service.
- Vyberte Review + create a pak Create.
- Po dokončení nasazení vyberte Go to resourcea výběrem 1-click add přidejte bezplatnou subdoménu Azure.
- Po přidání subdomény (nasazení bude chvíli trvat), vyberte ji.
- Jakmile budete na obrazovce AzureManagedDomain , v nabídce Prostředek vyberte PoštaZ adres .
- Zkopírujte hodnotu MailFrom do souboru. Použijete ho později při aktualizaci souboru .env .
- Zpět k prostředku Azure Communication Services a vyberte Domains z nabídky Prostředek.
- Vyberte Add domain a zadejte MailFrom hodnotu z předchozího kroku (ujistěte se, že jste vybrali správné předplatné, skupinu prostředků a e-mailovou službu). Vyberte tlačítko Connect.

`.env` Aktualizace souboru

Teď, když máte telefonní číslo služby ACS (s povoleným voláním a sms) a e-mailovou doménu připravené, aktualizujte v souboru .env v projektu následující klíče a hodnoty:
```
ACS_CONNECTION_STRING=<ACS_CONNECTION_STRING>
ACS_PHONE_NUMBER=<ACS_PHONE_NUMBER>
ACS_EMAIL_ADDRESS=<ACS_EMAIL_ADDRESS>
CUSTOMER_EMAIL_ADDRESS=<EMAIL_ADDRESS_TO_SEND_EMAIL_TO>
CUSTOMER_PHONE_NUMBER=<UNITED_STATES_BASED_NUMBER_TO_SEND_SMS_TO>
```
- ACS_CONNECTION_STRING: Hodnota connection string z oddílu Klíče vašeho prostředku služby ACS.
- ACS_PHONE_NUMBER: Přiřaďte k hodnotě číslo bezplatné linky ACS_PHONE_NUMBER .
- ACS_EMAIL_ADDRESS: Přiřaďte hodnotu adresy e-mailu MailTo.
- CUSTOMER_EMAIL_ADDRESS: Přiřaďte e-mailovou adresu, na kterou chcete odesílat e-maily z aplikace (protože zákaznická data v databázi aplikace jsou jenom ukázková data). Můžete použít osobní e-mailovou adresu.
- CUSTOMER_PHONE_NUMBER: Budete muset zadat telefonní číslo založené na USA (od dnešního dne) kvůli dodatečnému ověření, které se vyžaduje v jiných zemích pro odesílání SMS zpráv. Pokud číslo v USA nemáte, můžete ho nechat prázdné.

Spuštění nebo restartování aplikačních serverů a serverů rozhraní API

Na základě cvičení, která jste do tohoto okamžiku dokončili, proveďte jeden z následujících kroků:

Pokud jste databázi, server rozhraní API a webový server spustili v dřívějším cvičení, musíte zastavit server rozhraní API a webový server a restartovat je, aby se změny souboru .env projevily. Databázi můžete nechat spuštěnou.

Vyhledejte okna terminálu, na kterých běží server rozhraní API a webový server, a stisknutím ctrl + C je zastavte. Spusťte je znovu zadáním npm start do každého okna terminálu a stisknutím klávesy Enter. Pokračujte dalším cvičením.
Pokud jste ještě nespustili databázi, server rozhraní API a webový server, proveďte následující kroky:
1. V následujících krocích vytvoříte v editoru Visual Studio Code tři okna terminálu.
2. Klikněte pravým tlačítkem na soubor .env v seznamu souborů editoru Visual Studio Code a vyberte Otevřít v integrovaném terminálu. Než budete pokračovat, ujistěte se, že je váš terminál v kořenovém adresáři projektu – openai-acs-msgraph .
3. Pro spuštění databáze PostgreSQL zvolte jednu z následujících možností:
  - Pokud máte nainstalovaný a spuštěný Docker Desktop , spusťte docker-compose up v okně terminálu příkaz a stiskněte Enter.
  - Pokud máte nainstalovaný a spuštěný Podman s podman-compose , spusťte podman-compose up v okně terminálu a stiskněte Enter.
  - Pokud chcete kontejner PostgreSQL spustit přímo pomocí Docker Desktopu, Podmanu, nerdctl nebo jiného nainstalovaného modulu runtime kontejneru, spusťte v okně terminálu následující příkaz:
    - Mac, Linux nebo Subsystém Windows pro 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 s PowerShellem:
```
[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 spuštění kontejneru databáze vytvořte stisknutím + ikony na panelu nástrojů Terminálu editoru Visual Studio Code druhé okno terminálu.
5. cd do složky server/typescript a spuštěním následujících příkazů nainstalujte závislosti a spusťte server rozhraní API.
  - npm install
  - npm start
6. + Dalším stisknutím ikony na panelu nástrojů Terminálu editoru Visual Studio Code vytvořte třetí okno terminálu.
7. cd do klientské složky a spuštěním následujících příkazů nainstalujte závislosti a spusťte webový server.
  - npm install
  - npm start
8. Spustí se prohlížeč a budete přesměrováni na http://localhost:4200adresu .

Komunikace: Telefonní hovor

79 min zbývá

Integrace funkcí telefonních hovorů Azure Communication Services do vlastní obchodní aplikace nabízí podnikům a jejich uživatelům několik klíčových výhod:

Umožňuje bezproblémovou komunikaci mezi zaměstnanci, zákazníky a partnery v reálném čase přímo z obchodní aplikace a eliminuje potřebu přepínat mezi několika platformami nebo zařízeními.
Zlepšuje uživatelské prostředí a zlepšuje celkovou provozní efektivitu.
Usnadňuje rychlé řešení problémů, protože se uživatelé mohou rychle a snadno spojit s příslušnými týmy podpory nebo odborníky na danou problematiku.

Toto cvičení zahrnuje:

Prozkoumejte funkci telefonního hovoru v aplikaci.
Projděte si kód a zjistěte, jak je funkce telefonního volání sestavená.

Použití funkce telefonního hovoru

V předchozím cvičení jste vytvořili prostředek Azure Communication Services (ACS) a spustili databázi, webový server a server rozhraní API. Aktualizovali jste také následující hodnoty v souboru .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>
```
Než budete pokračovat, ujistěte se, že jste dokončili předchozí cvičení .
Zpět do prohlížeče (http://localhost:4200), vyhledejte datovou mřížku a v prvním řádku vyberte Kontaktovat zákazníka a pak zavolejte zákazníkovi.
Do záhlaví se přidá součást telefonního hovoru. Zadejte svoje telefonní číslo (ujistěte se, že začíná na + a obsahuje směrové číslo země) a vyberte Volat. Zobrazí se výzva k povolení přístupu k mikrofonu.
Pokud chcete hovor ukončit, vyberte Zavěsit . Výběrem možnosti Zavřít zavřete součást telefonního hovoru.

Prozkoumání telefonního telefonního kódu

Tip

Pokud používáte Visual Studio Code, můžete soubory otevřít přímo tak, že vyberete:

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

Pak zadejte název souboru, který chcete otevřít.

Otevřete soubor customers-list.component.ts . Úplná cesta k souboru je client/src/app/customers-list/customers-list.component.ts.
Všimněte si, že openCallDialog() odešle CustomerCall zprávu a telefonní číslo zákazníka pomocí sběrnice událostí.
```
openCallDialog(data: Phone) {
    this.eventBus.emit({ name: Events.CustomerCall, value: data });
}
```
Poznámka

Kód sběrnice událostí najdete v souboru eventbus.service.ts , pokud ho chcete prozkoumat více. Úplná cesta k souboru je client/src/app/core/eventbus.service.ts.

Funkce komponenty ngOnInit() záhlaví se přihlásí k odběru CustomerCall události odeslané sběrnici událostí a zobrazí součást telefonního hovoru. Tento kód najdete v 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
        })
    );
}

Otevřete phone-call.component.ts. Chvíli si udělejte, než kód vyložíte. Úplná cesta k souboru je client/src/app/phone-call/phone-call.component.ts. Všimněte si následujících klíčových funkcí:
- Načte přístupový token Azure Communication Services voláním acsService.getAcsToken() funkce v ngOnInit().
- Přidá na stránku "telefonní číselník". Číselník zobrazíte kliknutím na zadání telefonního čísla v záhlaví.
- Spustí a ukončí volání pomocí startCall() funkcí a endCall() v uvedeném pořadí.
Než se podíváme na kód, který provádí telefonní hovor, pojďme se podívat, jak se načítá přístupový token služby ACS a jak se vytvářejí objekty pro telefonní hovory. ngOnInit() Vyhledejte funkci v 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);
            })
        );
    }
}
```
Tato funkce provede následující akce:
- Načte id uživatele ACS a přístupový token voláním acsService.getAcsToken() funkce.
- Po načtení přístupového tokenu kód provede následující akce:
  - Vytvoří novou instanci CallClient a AzureCommunicationTokenCredential pomocí přístupového tokenu.
  - Vytvoří novou instanci CallAgent pomocí CallClient objektů a AzureCommunicationTokenCredential . Později uvidíte, že CallAgent se používá k zahájení a ukončení hovoru.
Otevřete acs.services.ts a vyhledejte getAcsToken() funkci. Úplná cesta k souboru je client/src/app/core/acs.service.ts. Funkce vytvoří požadavek HTTP GET na trasu /acstoken vystavenou serverem rozhraní API.
```
getAcsToken(): Observable<AcsUser> {
    return this.http.get<AcsUser>(this.apiUrl + 'acstoken')
    .pipe(
        catchError(this.handleError)
    );
}
```
Funkce serveru ROZHRANÍ API s názvem createACSToken() načte id uživatele a přístupový token a vrátí je klientovi. Najdete ho v souboru 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 = await tokenClient.createUser();
    const userToken = await tokenClient.getToken(user, ["voip"]);
    return { userId: user.communicationUserId, ...userToken };    
}
```
Tato funkce provede následující akce:
- Zkontroluje, jestli je k dispozici hodnota ACS connectionString . Pokud ne, vrátí objekt s prázdnými userId a token.
- Vytvoří novou instanci CommunicationIdentityClient a předá connectionString jí hodnotu.
- Vytvoří nového uživatele pomocí tokenClient.createUser().
- Získá token pro nového uživatele s oborem "voip" pomocí tokenClient.getToken().
- Vrátí objekt obsahující userId hodnoty a token .
Teď, když jste viděli, jak se načítají id uživatele a token, se vraťte k phone-call.component.ts a vyhledejte startCall() funkci.

Tato funkce se volá, když je v komponentě telefonního hovoru vybrána možnost Volat . CallAgent Používá objekt uvedený výše k zahájení volání. Funkce callAgent.startCall() přijme objekt představující číslo, které se má volat, a telefonní číslo služby ACS použité k provedení hovoru.

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

Funkce stopCall() se zavolá, když je v komponentě telefonního hovoru vybraná možnost Zavěsit .
```
endCall() {
    if (this.call) {
        this.call.hangUp({ forEveryone: true });
        this.call = undefined;
        this.inCall = false;
    }
    else {
        this.hangup.emit();
    }
}
```
Pokud probíhá volání, call.hangUp() zavolá se funkce, která hovor ukončí. Pokud neprobíhá žádné volání, hangup událost se vygeneruje do nadřazené komponenty záhlaví, aby se komponenta telefonního hovoru skryla.
Než přejdeme k dalšímu cvičení, pojďme se podívat na klíčové koncepty popsané v tomto cvičení:
- Id uživatele ACS a přístupový token se načítají ze serveru rozhraní API pomocí acsService.getAcsToken() funkce .
- Token se používá k vytvoření objektu CallClient a CallAgent .
- Objekt CallAgent se používá ke spuštění a ukončení volání volání funkcí callAgent.startCall() a callAgent.hangUp() v uvedeném pořadí.
Teď, když jste se dozvěděli, jak lze telefonní hovory integrovat do aplikace, se zaměříme na používání Azure Communication Services k odesílání e-mailů a SMS zpráv.

Komunikace: Odesílání Email a SMS zpráv

69 min zbývá

Kromě telefonních hovorů může Azure Communication Services posílat také e-maily a SMS zprávy. To může být užitečné, když chcete poslat zprávu zákazníkovi nebo jinému uživateli přímo z aplikace.

Toto cvičení zahrnuje:

Prozkoumejte, jak se z aplikace dají posílat e-maily a SMS zprávy.
Projděte si kód a zjistěte, jak se implementují funkce e-mailu a SMS.

Použití funkcí Email a SMS

V předchozím cvičení jste vytvořili prostředek Azure Communication Services (ACS) a spustili databázi, webový server a server rozhraní API. Aktualizovali jste také následující hodnoty v souboru .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>
```
Než budete pokračovat, ujistěte se, že jste cvičení dokončili.
Zpět do prohlížeče (http://localhost:4200) a v prvním řádku vyberte Kontaktovat zákazníka a potom Email/SMS Customer.
Vyberte kartu Email/SMS a proveďte následující úlohy:
- Zadejte Email Předmět a Text a vyberte tlačítko Odeslat Email.
- Zadejte SMS zprávu a vyberte tlačítko Odeslat SMS .
Zkontrolujte, že jste dostali e-maily a SMS zprávy. Připomínáme, že e-mailová zpráva se odešle na hodnotu definovanou pro CUSTOMER_EMAIL_ADDRESS a sms zpráva se odešle na hodnotu definovanou pro CUSTOMER_PHONE_NUMBER v souboru .env . Pokud se vám nepodařilo zadat telefonní číslo založené na USA pro sms zprávy, můžete tento krok přeskočit.

Poznámka

Pokud nevidíte e-mailovou zprávu ve složce Doručená pošta pro adresu, pro kterou jste definovali CUSTOMER_EMAIL_ADDRESS v souboru .env , zkontrolujte složku spamu.

Zkoumání kódu Email

Tip

Pokud používáte Visual Studio Code, můžete soubory otevřít přímo tak, že vyberete:

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

Pak zadejte název souboru, který chcete otevřít.

Otevřete soubor customers-list.component.ts . Úplná cesta k souboru je client/src/app/customers-list/customers-list.component.ts.

Když jste v datové mřížce vybrali Možnost Kontaktovat zákazníka a potom Email/ZÁKAZNÍK SMS, customer-list komponenta zobrazila dialogové okno. To zpracovává openEmailSmsDialog() funkce v souboru 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.');
    }
}

Funkce openEmailSmsDialog() provádí následující úlohy:

Zkontroluje, jestli data objekt (který představuje řádek z datové mřížky) obsahuje phone vlastnost a email . Pokud ano, vytvoří dialogData objekt, který obsahuje informace, které se mají předat do dialogového okna.
EmailSmsDialogComponent Otevře dialogové okno a předá dialogData do něj objekt.
Přihlásí se k odběru afterClosed() události dialogového okna. Tato událost se aktivuje, když je dialogové okno zavřené. Objekt response obsahuje informace, které byly zadány do dialogového okna.

Otevřete soubor email-sms-dialog.component.ts . Úplná cesta k souboru je client/src/app/email-sms-dialog/email-sms-dialog.component.ts.
sendEmail() Vyhledejte funkci:
```
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
    }
}
```
Funkce sendEmail() provádí následující úlohy:
- Zkontroluje, jestli acsEmailEnabled je příznak funkce nastavený na true. Tento příznak zkontroluje, jestli ACS_EMAIL_ADDRESS proměnná prostředí má přiřazenou hodnotu.
- Pokud acsEmailEnabled je tato hodnota pravdivá, acsService.sendEmail() zavolá se funkce a předá se předmět e-mailu, text, jméno zákazníka a e-mailová adresa zákazníka. Vzhledem k tomu, že databáze obsahuje ukázková data, CUSTOMER_EMAIL_ADDRESS použije se místo proměnné prostředí proměnná this.data.emailprostředí . V reálné aplikaci by se hodnota použila this.data.email .
- Přihlásí se k odběru sendEmail() funkce ve službě acsService . Tato funkce vrátí pozorovatelný objekt RxJS, který obsahuje odpověď ze služby na straně klienta.
- Pokud se e-mail úspěšně odeslal, emailSent vlastnost je nastavená na true.
Aby bylo možné zajistit lepší zapouzdření kódu a opakované použití, používají se služby na straně klienta, jako je acs.service.ts , v celé aplikaci. To umožňuje konsolidovat všechny funkce služby ACS do jednoho místa.
Otevřete acs.service.ts a vyhledejte sendEmail() funkci. Úplná cesta k souboru je 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)
    );
}
```
Funkce sendEmail() v nástroji AcsService provádí následující úlohy:
- http.post() Zavolá funkci a předá jí předmět e-mailu, zprávu, jméno zákazníka a e-mailovou adresu zákazníka. Funkce http.post() vrátí pozorovatelnou hodnotu RxJS, která obsahuje odpověď z volání rozhraní API.
- Zpracovává všechny chyby vrácené http.post() funkcí pomocí operátoru RxJS catchError .
Teď se podíváme, jak aplikace komunikuje s e-mailovou funkcí služby ACS. Otevřete soubor acs.ts a vyhledejte sendEmail() funkci. Úplná cesta k souboru je server/typescript/acs.ts.
Funkce sendEmail() provádí následující úlohy:
- Vytvoří nový EmailClient objekt a předá mu připojovací řetězec služby ACS (tato hodnota se načte z ACS_CONNECTION_STRING proměnné prostředí).
```
const emailClient = new EmailClient(connectionString);
```
- Vytvoří nový EmailMessage objekt a předá informace o odesílateli, předmětu, zprávě a příjemci.
```
const msgObject: EmailMessage = {
    senderAddress: process.env.ACS_EMAIL_ADDRESS as string,
    content: {
        subject: subject,
        plainText: message,
    },
    recipients: {
        to: [
        {
            address: customerEmailAddress,
            displayName: customerName,
        },
        ],
    },
};
```
- Odešle e-mail pomocí emailClient.beginSend() funkce a vrátí odpověď. I když funkce v tomto příkladu odesílá pouze jednomu příjemci, beginSend() dá se použít i k odesílání více příjemcům.
```
const poller = await emailClient.beginSend(msgObject);
```
- Počká, poller až objekt signalizují, že je hotovo, a odešle odpověď volajícímu.

Prozkoumání kódu SMS

Zpět do email-sms-dialog.component.ts souboru, který jste otevřeli dříve. Úplná cesta k souboru je client/src/app/email-sms-dialog/email-sms-dialog.component.ts.
sendSms() Vyhledejte funkci:
```
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;
    }
}
```
Funkce sendSMS() provádí následující úlohy:
- Zkontroluje, jestli acsPhoneEnabled je příznak funkce nastavený na true. Tento příznak zkontroluje, jestli ACS_PHONE_NUMBER proměnná prostředí má přiřazenou hodnotu.
- Pokud acsPhoneEnabled je tato hodnota pravdivá, acsService.SendSms() zavolá se funkce a předá se zpráva SMS a telefonní číslo zákazníka. Vzhledem k tomu, že databáze obsahuje ukázková data, CUSTOMER_PHONE_NUMBER použije se místo proměnné prostředí proměnná this.data.customerPhoneNumberprostředí . V reálné aplikaci by se hodnota použila this.data.customerPhoneNumber .
- Přihlásí se k odběru sendSms() funkce ve službě acsService . Tato funkce vrátí pozorovatelný objekt RxJS, který obsahuje odpověď ze služby na straně klienta.
- Pokud se zpráva SMS úspěšně odeslala, nastaví smsSent vlastnost na true.
Otevřete acs.service.ts a vyhledejte sendSms() funkci. Úplná cesta k souboru je 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)
    );
}  
```
Funkce sendSms() provádí následující úlohy:
- http.post() Zavolá funkci a předá jí zprávu a telefonní číslo zákazníka. Funkce http.post() vrátí pozorovatelnou hodnotu RxJS, která obsahuje odpověď z volání rozhraní API.
- Zpracovává všechny chyby vrácené http.post() funkcí pomocí operátoru RxJS catchError .
Nakonec se podíváme, jak aplikace komunikuje s funkcí ACS SMS. Otevřete soubor acs.ts . Úplná cesta k souboru je server/typescript/acs.ts a vyhledejte sendSms() funkci.
Funkce sendSms() provádí následující úlohy:
- Vytvoří nový SmsClient objekt a předá mu připojovací řetězec služby ACS (tato hodnota se načte z ACS_CONNECTION_STRING proměnné prostředí).
```
const smsClient = new SmsClient(connectionString);
```
- smsClient.send() Zavolá funkci a předá telefonní číslo služby ACS (from), telefonní číslo zákazníka (to) a sms zprávu:
```
const sendResults = await smsClient.send({
    from: process.env.ACS_PHONE_NUMBER as string,
    to: [customerPhoneNumber],
    message: message
});
return sendResults;
```
- Vrátí odpověď volajícímu.
Další informace o funkcích e-mailu a SMS služby ACS najdete v následujících článcích:
- Email v destinaci Azure Communication Services
- SMS v Azure Communication Services
Než přejdeme k dalšímu cvičení, pojďme se podívat na klíčové koncepty popsané v tomto cvičení:
- Soubor acs.service.ts zapouzdřuje funkce e-mailu a SMS služby ACS používané aplikací na straně klienta. Zpracovává volání rozhraní API na server a vrací odpověď volajícímu.
- Rozhraní API na straně serveru používá službu ACS EmailClient a SmsClient objekty k odesílání e-mailových a SMS zpráv.
Teď, když jste se dozvěděli, jak se dají posílat e-maily a SMS zprávy, se zaměříme na integraci dat organizace do aplikace.

Organizační data: Vytvoření registrace aplikace Microsoft Entra ID

59 min zbývá

Zvyšte produktivitu uživatelů integrací dat organizace (e-mailů, souborů, chatů a událostí kalendáře) přímo do vlastních aplikací. Pomocí rozhraní Microsoft Graph API a Microsoft Entra ID můžete v aplikacích bezproblémově načítat a zobrazovat relevantní data, což uživatelům snižuje potřebu přepínat kontext. Ať už jde o odkazování na e-mail odeslaný zákazníkovi, kontrolu zprávy v Teams nebo přístup k souboru, uživatelé můžou rychle najít potřebné informace, aniž by museli opustit vaši aplikaci, a zefekvidovat tak svůj rozhodovací proces.

Toto cvičení zahrnuje:

Vytvořte registraci aplikace Microsoft Entra ID, aby měl Microsoft Graph přístup k datům organizace a vnesl je do aplikace.
Vyhledejte team id a channel z Microsoft Teams, která jsou potřebná k odesílání chatových zpráv do konkrétního kanálu.
Aktualizujte soubor .env projektu hodnotami z registrace aplikace Microsoft Entra ID.

Přehled scénářů Microsoft Cloud

Vytvoření registrace aplikace Microsoft Entra ID

Přejděte na Azure Portal a vyberte Microsoft Entra ID.
Vyberte kartu Registrace aplikace a pak + Nová registrace.
Vyplňte podrobnosti registračního formuláře nové aplikace, jak je znázorněno níže, a vyberte Zaregistrovat:
- Název: microsoft-graph-app
- Podporované typy účtů: Účty v libovolném adresáři organizace (Libovolný Microsoft Entra ID tenant – Víceklient)
- Identifikátor URI:
  - Vyberte Jednostránková aplikace (SPA) a zadejte http://localhost:4200 do pole Identifikátor URI přesměrování .
- Vyberte Zaregistrovat a vytvořte registraci aplikace.

V nabídce Prostředek vyberte Přehled a zkopírujte Application (client) ID hodnotu do schránky.

Aktualizace souboru .env projektu

Otevřete soubor .env v editoru a přiřaďte Application (client) ID hodnotu .ENTRAID_CLIENT_ID
```
ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
```
Pokud chcete povolit možnost posílat zprávy z aplikace do kanálu Teams, přihlaste se k Microsoft Teams pomocí svého účtu vývojového tenanta Microsoft 365.
Po přihlášení rozbalte tým a najděte kanál, do kterého chcete odesílat zprávy z aplikace. Můžete například vybrat tým společnosti a kanál Obecné (nebo jakýkoli tým nebo kanál, který chcete použít).
V záhlaví týmu klikněte na tři tečky (...) a vyberte Get link to team.
V odkazu, který se zobrazí v automaticky otevíraných oknech, je ID týmu řetězec písmen a číslic za team/. Například v odkazu "https://teams.microsoft.com/l/team/19%3ae9b9.../", ID týmu je 19%3ae9b9... až do následujícího / znaku.
Zkopírujte ID týmu a přiřaďte ho do TEAM_ID souboru .env .
V záhlaví kanálu klikněte na tři tečky (...) a vyberte Get link to channel.
V odkazu, který se zobrazí v místním okně, je ID kanálu řetězec písmen a číslic za channel/. Například v odkazu "https://teams.microsoft.com/l/channel/19%3aQK02.../", ID kanálu je 19%3aQK02... až do následujícího / znaku.
Zkopírujte ID kanálu a přiřaďte ho do CHANNEL_ID souboru .env .
Než budete pokračovat, uložte soubor env .

Spuštění nebo restartování aplikačních serverů a serverů rozhraní API

Na základě cvičení, která jste do tohoto okamžiku dokončili, proveďte jeden z následujících kroků:

Pokud jste databázi, server rozhraní API a webový server spustili v dřívějším cvičení, musíte zastavit server rozhraní API a webový server a restartovat je, aby se změny souboru .env projevily. Databázi můžete nechat spuštěnou.

Vyhledejte okna terminálu, na kterých běží server rozhraní API a webový server, a stisknutím ctrl + C je zastavte. Spusťte je znovu zadáním npm start do každého okna terminálu a stisknutím klávesy Enter. Pokračujte dalším cvičením.
Pokud jste ještě nespustili databázi, server rozhraní API a webový server, proveďte následující kroky:
1. V následujících krocích vytvoříte v editoru Visual Studio Code tři okna terminálu.
2. Klikněte pravým tlačítkem na soubor .env v seznamu souborů editoru Visual Studio Code a vyberte Otevřít v integrovaném terminálu. Než budete pokračovat, ujistěte se, že je váš terminál v kořenovém adresáři projektu – openai-acs-msgraph .
3. Pro spuštění databáze PostgreSQL zvolte jednu z následujících možností:
  - Pokud máte nainstalovaný a spuštěný Docker Desktop , spusťte docker-compose up v okně terminálu příkaz a stiskněte Enter.
  - Pokud máte nainstalovaný a spuštěný Podman s podman-compose , spusťte podman-compose up v okně terminálu a stiskněte Enter.
  - Pokud chcete kontejner PostgreSQL spustit přímo pomocí Docker Desktopu, Podmanu, nerdctl nebo jiného nainstalovaného modulu runtime kontejneru, spusťte v okně terminálu následující příkaz:
    - Mac, Linux nebo Subsystém Windows pro 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 s PowerShellem:
```
[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 spuštění kontejneru databáze vytvořte stisknutím + ikony na panelu nástrojů Terminálu editoru Visual Studio Code druhé okno terminálu.
5. cd do složky server/typescript a spuštěním následujících příkazů nainstalujte závislosti a spusťte server rozhraní API.
  - npm install
  - npm start
6. + Dalším stisknutím ikony na panelu nástrojů Terminálu editoru Visual Studio Code vytvořte třetí okno terminálu.
7. cd do klientské složky a spuštěním následujících příkazů nainstalujte závislosti a spusťte webový server.
  - npm install
  - npm start
8. Spustí se prohlížeč a budete přesměrováni na http://localhost:4200adresu .

Organizační data: Přihlášení uživatele a získání přístupového tokenu

51 min zbývá

Aby mohl Microsoft Graph přistupovat k datům organizace, musí se uživatelé ověřit pomocí Microsoft Entra ID. V tomto cvičení se dozvíte, jak je možné použít komponentu mgt-login sady Microsoft Graph Toolkit k ověřování uživatelů a načtení přístupového tokenu. Přístupový token se pak dá použít k volání Microsoft Graphu.

Poznámka

Pokud s Microsoft Graphem začínáte, můžete se o něm dozvědět více ve studijním programu Základy Microsoft Graphu .

Toto cvičení zahrnuje:

Zjistěte, jak přidružit aplikaci Microsoft Entra ID k sadě Microsoft Graph Toolkit, aby ji bylo možné použít k ověřování uživatelů a načítání dat organizace.
Přečtěte si o důležitosti rozsahů.
Zjistěte, jak je možné použít komponentu mgt-login sady Microsoft Graph Toolkit k ověřování uživatelů a načtení přístupového tokenu.

V předchozím cvičení jste vytvořili registraci aplikace v Microsoft Entra ID a spustili jste aplikační server a server rozhraní API. Aktualizovali jste také následující hodnoty v .env souboru.
```
ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
TEAM_ID=<TEAMS_TEAM_ID>
CHANNEL_ID=<TEAMS_CHANNEL_ID>
```
Než budete pokračovat, ujistěte se, že jste dokončili předchozí cvičení .
Zpět do prohlížeče (http://localhost:4200), v záhlaví vyberte Přihlásit se a přihlaste se pomocí uživatelského účtu správce z vašeho tenanta Microsoft 365 Developer.

Tip

Přihlaste se pomocí účtu správce vývojářského tenanta Microsoft 365. Další uživatele ve vývojářském tenantovi můžete zobrazit tak, že přejdete na Centrum pro správu Microsoftu 365.
Pokud se k aplikaci přihlašujete poprvé, zobrazí se výzva k vyjádření souhlasu s oprávněními požadovanými aplikací. Další informace o těchto oprávněních (označovaných také jako "obory") se dozvíte v další části při zkoumání kódu. Pokračujte výběrem možnosti Přijmout .
Po přihlášení by se v záhlaví mělo zobrazit jméno uživatele.

Teď, když jste se přihlásili, se podívejme na kód použitý k přihlášení uživatele a načtení přístupového tokenu a profilu uživatele. Dozvíte se o webové komponentě mgt-login , která je součástí sady Microsoft Graph Toolkit.

Tip

Pokud používáte Visual Studio Code, můžete soubory otevřít přímo tak, že vyberete:

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

Pak zadejte název souboru, který chcete otevřít.

Otevřete klienta nebo package.json a všimněte si, že @microsoft/mgt balíček je součástí závislostí. Tento balíček obsahuje funkce zprostředkovatele MSAL (Microsoft Authentication Library) a také webové komponenty, jako je mgt-login a další, které se dají použít k přihlašování uživatelů a načítání a zobrazování dat organizace.
Pokud chcete k přihlašování uživatelů použít komponentu mgt-login, je potřeba odkazovat na ID klienta aplikace Microsoft Entra ID (uložené v souboru .env jako ENTRAID_CLIENT_ID).
Otevřete graph.service.ts a vyhledejte init() funkci. Úplná cesta k souboru je client/src/app/core/graph.service.ts. Zobrazí se následující kód:
```
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']
});
```
Tento kód vytvoří nový Msal2Provider objekt a předá id klienta Microsoft Entra ID z registrace aplikace a scopes id, pro který bude aplikace požadovat přístup. Slouží scopes k vyžádání přístupu k prostředkům Microsoft Graphu, ke kterým bude aplikace přistupovat. Msal2Provider Po vytvoření je objekt přiřazen k objektuProviders.globalProvider, který je používán komponentami sady Microsoft Graph Toolkit k načtení dat z Microsoft Graphu.
Otevřete header.component.html v editoru a vyhledejte komponentu mgt-login . Úplná cesta k souboru je client/src/app/header/header.component.html.
```
<mgt-login *ngIf="featureFlags.microsoft365Enabled" class="mgt-dark" (loginCompleted)="loginCompleted()"></mgt-login>
```
Komponenta mgt-login umožňuje přihlášení uživatele a načtení přístupového tokenu pro použití s Microsoft Graphem. Po úspěšném přihlášení loginCompleted se událost aktivuje a následně zavolá loginCompleted() funkci. I když se v tomto příkladu používá mgt-login v rámci komponenty Angular, je kompatibilní s libovolnou webovou aplikací.

Zobrazení komponenty mgt-login závisí na hodnotě featureFlags.microsoft365Enabled nastavené na true. Tento vlastní příznak zkontroluje přítomnost ENTRAID_CLIENT_ID proměnné prostředí a ověří, jestli je aplikace správně nakonfigurovaná a dokáže se ověřit v Microsoft Entra ID. Příznak se přidá, aby vyhovoval případům, kdy se uživatelé rozhodnou v rámci kurzu dokončit pouze cvičení AI nebo Komunikace, a ne sledovat celou sekvenci.
Otevřete header.component.ts a vyhledejte loginCompleted funkci. Tato funkce se volá při vygenerování loginCompleted události a použije se k načtení profilu přihlášeného uživatele pomocí Providers.globalProvider.
```
async loginCompleted() {
    const me = await Providers.globalProvider.graph.client.api('me').get();
    this.userLoggedIn.emit(me);
}
```
V tomto příkladu se do rozhraní Microsoft Graph me API volá, aby se načetl profil uživatele (me představuje aktuálně přihlášeného uživatele). Příkaz this.userLoggedIn.emit(me) kódu vygeneruje událost z komponenty, která předá data profilu nadřazené komponentě. Nadřazená komponenta je v tomto případě app.component.ts soubor, což je kořenová komponenta aplikace.

Další informace o komponentě mgt-login najdete v dokumentaci k sadě Microsoft Graph Toolkit .
Teď, když jste se přihlásili k aplikaci, se podíváme na to, jak se dají načíst data organizace.

Data organizace: Načítání souborů, chatů a odesílání zpráv do Teams

41 min zbývá

V dnešním digitálním prostředí pracují uživatelé se širokou škálou dat organizace, včetně e-mailů, chatů, souborů, událostí kalendáře a dalších. To může vést k častým kontextům – přepínání mezi úkoly nebo aplikacemi – což může narušit soustředění a snížit produktivitu. Například uživatel pracující na projektu může potřebovat přepnout ze své aktuální aplikace na Outlook, aby v e-mailu našel důležité podrobnosti, nebo přepnout na OneDrive pro firmy najít související soubor. Tato akce naruší soustředění a ztrácí čas, který by bylo možné lépe věnovat danému úkolu.

Pro zvýšení efektivity můžete data organizace integrovat přímo do aplikací, které uživatelé používají každý den. Díky tomu, že do vašich aplikací přinášejí data organizace, můžou uživatelé snadněji přistupovat k informacím a spravovat je, minimalizovat kontextové posuny a zlepšit produktivitu. Tato integrace navíc poskytuje cenné přehledy a kontext a umožňuje uživatelům činit informovaná rozhodnutí a pracovat efektivněji.

Toto cvičení zahrnuje:

Zjistěte, jak je možné použít webovou komponentu mgt-search-results v sadě Microsoft Graph Toolkit k hledání souborů.
Přečtěte si, jak přímo volat Microsoft Graph, abyste získali soubory z OneDrive pro firmy a chatovacích zpráv z Microsoft Teams.
Zjistěte, jak odesílat chatovací zprávy do kanálů Microsoft Teams pomocí Microsoft Graphu.

Poznámka

Komponenta mgt-search-results je aktuálně ve verzi Preview a může se změnit. Kromě toho, že cvičení ukazují, jak je možné výsledky hledání použít, také ukazují, jak provádět stejné úlohy přímo pomocí Microsoft Graphu.

Použití funkce organizačních dat

V předchozím cvičení jste vytvořili registraci aplikace v Microsoft Entra ID a spustili aplikační server a server rozhraní API. Aktualizovali jste také následující hodnoty v .env souboru.
```
ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
TEAM_ID=<TEAMS_TEAM_ID>
CHANNEL_ID=<TEAMS_CHANNEL_ID>
```
Než budete pokračovat, ujistěte se, že jste dokončili předchozí cvičení .
Zpět do prohlížeče (http://localhost:4200). Pokud jste se ještě nepřihlásili, vyberte v záhlaví Přihlásit se a přihlaste se pomocí uživatele z vašeho tenanta Microsoft 365 Developer.
Poznámka

Kromě ověřování uživatele webová komponenta mgt-login také načte přístupový token, který může Microsoft Graph použít pro přístup k souborům, chatům, e-mailům, událostem kalendáře a dalším datům organizace. Přístupový token obsahuje obory (oprávnění), jako Chat.ReadWritejsou , Files.Read.Alla další, které jste viděli dříve:
```
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']
});
```
Vyberte Zobrazit související obsah pro řádek Adatum Corporation v datové mřížce. To způsobí, že se data organizace, jako jsou soubory, chaty, e-maily a události kalendáře, načtou pomocí Microsoft Graphu. Jakmile se data načtou, zobrazí se pod datovou mřížkou v rozhraní s kartami. Je důležité zmínit, že v tomto okamžiku se nemusí zobrazit žádná data, protože jste ještě nepřidali žádné soubory, chaty, e-maily ani události kalendáře pro uživatele ve vašem vývojářském tenantovi Microsoftu 365. Pojďme to opravit v dalším kroku.
Váš tenant Microsoft 365 nemusí mít v této fázi žádná související organizační data pro Adatum Corporation . Pokud chcete přidat nějaká ukázková data, proveďte alespoň jednu z následujících akcí:
- Přidejte soubory tak, že navštívíte https://onedrive.com a přihlásíte se pomocí přihlašovacích údajů tenanta Microsoft 365 Developer.
  - V levém navigačním panelu vyberte Moje soubory .
  - V nabídce vyberte Nahrát a pak Složku .
  - Vyberte složku dokumentů openai-acs-msgraph/customer z projektu, který jste naklonovali.
- Přidejte chatové zprávy a události kalendáře tak, https://teams.microsoft.com že navštívíte a přihlásíte se pomocí přihlašovacích údajů tenanta Microsoft 365 Developer.
  - V levém navigačním panelu vyberte Teams .
  - Vyberte tým a kanál.
  - Vyberte Nová konverzace.
  - Zadejte Nová objednávka zadaná pro Adatum Corporation a vyberte tlačítko Odeslat .
    
    Nebojte se přidat další chatové zprávy, které zmiňují jiné společnosti používané v aplikaci, jako jsou Adventure Works Cycles, Contoso Pharmaceuticals a Tailwind Traders.
  - V levém navigačním panelu vyberte Kalendář .
  - Vyberte Nová schůzka.
  - Jako název a text zadejte "Meet with Adatum Corporation about project schedule" (Schůzka s Adatum Corporation o plánu projektu).
  - Vyberte Uložit.
- Přidejte e-maily tak, že navštívíte https://outlook.com a přihlásíte se pomocí přihlašovacích údajů tenanta Microsoft 365 Developer.
  - Vyberte Nová pošta.
  - Do pole Do zadejte svoji osobní e-mailovou adresu.
  - Zadejte New order placed for Adatum Corporation for the subject andything you's like for the body.
  - Vyberte Odeslat.
Zpět do aplikace v prohlížeči a aktualizujte stránku. Znovu vyberte Zobrazit související obsah pro řádek Adatum Corporation . Teď by se na kartách měla zobrazovat data v závislosti na tom, které úkoly jste provedli v předchozím kroku.
Pojďme se podívat na kód, který v aplikaci umožňuje funkci dat organizace. K načtení dat používá část aplikace na straně klienta přístupový token načtený komponentou mgt-login , na kterou jste se podívali dříve, k volání rozhraní Microsoft Graph API.

Zkoumání kódu pro vyhledávání souborů

Tip

Pokud používáte Visual Studio Code, můžete soubory otevřít přímo tak, že vyberete:

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

Pak zadejte název souboru, který chcete otevřít.

Začněme tím, že se podíváme, jak se data souborů načítají z OneDrive pro firmy. Otevřete files.component.html a chvíli si prohlédněte kód. Úplná cesta k souboru je client/src/app/files/files.component.html.
Vyhledejte komponentu mgt-search-results a poznamenejte si následující atributy:
```
<mgt-search-results 
    class="search-results" 
    entity-types="driveItem" 
    [queryString]="searchText"
    (dataChange)="dataChange($any($event))" 
/>
```
Komponenta mgt-search-results je součástí sady Microsoft Graph Toolkit a jak název napovídá, používá se k zobrazení výsledků hledání z Microsoft Graphu. Komponenta v tomto příkladu používá následující funkce:
- Atribut class slouží k určení, že se na komponentu search-results má použít třída CSS.
- Atribut entity-types slouží k určení typu dat, která se mají hledat. V tomto případě se driveItem hodnota používá k hledání souborů v OneDrive pro firmy.
- Atribut queryString slouží k zadání hledaného termínu. V tomto případě je hodnota vázána na searchText vlastnost, která je předána do komponenty files , když uživatel vybere Zobrazit související obsah pro řádek v datové mřížce. Hranaté závorky kolem queryString označují, že vlastnost je vázána na searchText hodnotu.
- Událost se dataChange aktivuje, když se změní výsledky hledání. V tomto případě se v komponentě files volá funkce zákazníka s názvem dataChange() a data událostí se předají funkci. Závorky kolem dataChange označují, že událost je vázána na dataChange() funkci.
- Vzhledem k tomu, že není zadána žádná vlastní šablona, použije se k zobrazení výsledků hledání předdefinovaná mgt-search-results výchozí šablona.
Alternativou k použití komponent, jako je mgt-search-results, je volání rozhraní Microsoft Graph API přímo pomocí kódu. Pokud chcete zjistit, jak to funguje, otevřete soubor graph.service.ts a vyhledejte searchFiles() funkci. Úplná cesta k souboru je client/src/app/core/graph.service.ts.
- Všimněte si, že query se funkci předá parametr. Toto je hledaný termín, který se předá, když uživatel vybere Zobrazit související obsah pro řádek v datové mřížce. Pokud se nepředá žádný hledaný termín, vrátí se prázdné pole.
```
async searchFiles(query: string) {
    const files: DriveItem[] = [];
    if (!query) return files;

    ...
}
```
- Potom se vytvoří filtr, který definuje typ vyhledávání, které se má provést. V tomto případě kód hledá soubory v OneDrive pro firmy takže driveItem se používá stejně, jako jste viděli dříve u mgt-search-results komponenty. Je to stejné jako předání driveItem v entity-types komponentě mgt-search-results , kterou jste viděli dříve. Parametr query se pak přidá do queryString filtru spolu s parametrem ContentType:Document.
```
const filter = {
    "requests": [
        {
            "entityTypes": [
                "driveItem"
            ],
            "query": {
                "queryString": `${query} AND ContentType:Document`
            }
        }
    ]
};
```
- Pomocí funkce se pak provede volání microsoftu /search/query Graph APIProviders.globalProvider.graph.client.api(). Objekt filter se předá post() funkci, která odesílá data do rozhraní API.
```
const searchResults = await Providers.globalProvider.graph.client.api('/search/query').post(filter);
```
- Výsledky hledání se pak iteují a vyhledá se hits. Každý hit obsahuje informace o nalezených dokumentech. Vlastnost s názvem resource obsahuje metadata dokumentu a je přidána files do pole.
```
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);
        }
        }
    }
}
```
- Pole files se pak vrátí volajícímu.
```
return files;
```
Když se podíváte na tento kód, uvidíte, že webová komponenta mgt-search-results , kterou jste prozkoumali dříve, dělá spoustu práce za vás a výrazně snižuje množství kódu, který musíte napsat! Můžou ale existovat scénáře, ve kterých chcete volat Microsoft Graph přímo, abyste měli větší kontrolu nad daty odesílaným do rozhraní API nebo nad tím, jak se výsledky zpracovávají.
Otevřete soubor files.component.ts a vyhledejte search() funkci. Úplná cesta k souboru je client/src/app/files/files.component.ts.

I když je text této funkce zakomentován kvůli použité komponentě mgt-search-results , je možné tuto funkci použít k volání Microsoft Graphu, když uživatel vybere Zobrazit související obsah pro řádek v datové mřížce. Funkce search() zavolá searchFiles()v graph.service.ts a předá query jí parametr (název společnosti v tomto příkladu). Výsledky hledání jsou pak přiřazeny vlastnosti data komponenty.
```
override async search(query: string) {
    this.data = await this.graphService.searchFiles(query);
}
```
Komponenta files pak může použít data vlastnost k zobrazení výsledků hledání. Můžete to vyřešit pomocí vlastních vazeb HTML nebo pomocí jiného ovládacího prvku Microsoft Graph Toolkit s názvem mgt-file-list. Tady je příklad vazby data vlastnosti na jednu z vlastností komponenty s názvem files a zpracování itemClick události, když uživatel pracuje se souborem.
```
<mgt-file-list (itemClick)="itemClick($any($event))" [files]="data"></mgt-file-list>
```
To, jestli se rozhodnete použít dříve zobrazenou komponentu mgt-search-results nebo napsat vlastní kód pro volání Microsoft Graphu, bude záviset na vašem konkrétním scénáři. V tomto příkladu se komponenta mgt-search-results používá ke zjednodušení kódu a snížení množství práce, kterou musíte udělat.

Prozkoumání kódu hledání zpráv chatu v Teams

Zpět funkci graph.service.ts a vyhledejte searchChatMessages() ji. Uvidíte, že je podobná searchFiles() funkci, na kterou jste se dívali dříve.
- Publikuje data filtru do rozhraní API Microsoft Graphu /search/query a převede výsledky na pole objektů, které obsahují informace o teamIdobjektech , channelIda messageId , které odpovídají hledanému výrazu.
- Pokud chcete načíst zprávy kanálu Teams, provede se /teams/${chat.teamId}/channels/${chat.channelId}/messages/${chat.messageId} druhé volání rozhraní API a teamIdpředají se , channelIda messageId . Tím se vrátí úplné podrobnosti zprávy.
- Provádí se další úlohy filtrování a výsledné zprávy se vrátí volajícímu searchChatMessages() .

Otevřete soubor chats.component.ts a vyhledejte search() funkci. Úplná cesta k souboru je client/src/app/chats/chats.component.ts. Funkce search() zavolá searchChatMessages()v graph.service.ts a předá query jí parametr.

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

Výsledky hledání jsou přiřazeny vlastnosti data komponenty a datová vazba se používá k iteraci pole výsledků a vykreslení dat. V tomto příkladu se k zobrazení výsledků hledání používá komponenta karty Angular Material.

<div *ngIf="data.length">
    <mat-card *ngFor="let chatMessage of data">
        <mat-card-header>
            <mat-card-title [innerHTML]="chatMessage.summary"></mat-card-title>
        </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>

Zobrazení chatů v Teams

Odeslání zprávy do kanálu Microsoft Teams

Kromě vyhledávání chatových zpráv v Microsoft Teams aplikace také umožňuje uživateli posílat zprávy do kanálu Microsoft Teams. Můžete to provést voláním koncového /teams/${teamId}/channels/${channelId}/messages bodu Microsoft Graphu.

V následujícím kódu uvidíte, že se vytvoří adresa URL, která obsahuje teamId hodnoty a channelId . Hodnoty proměnných prostředí se v tomto příkladu používají pro ID týmu a ID kanálu, ale tyto hodnoty se dají dynamicky načítat také pomocí Microsoft Graphu. Konstanta body obsahuje zprávu k odeslání. Potom se vytvoří požadavek POST a výsledky se vrátí volajícímu.

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

Využití tohoto typu funkcí v Microsoft Graphu poskytuje skvělý způsob, jak vylepšit uživatelské produkty tím, že uživatelům umožňuje komunikovat s Microsoft Teams přímo z aplikace, kterou už používají.

Data organizace: Načítání e-mailů a událostí kalendáře

21 min zbývá

V předchozím cvičení jste zjistili, jak načítat soubory z OneDrive pro firmy a chatů z Microsoft Teams pomocí Microsoft Graphu a komponenty mgt-search-results ze sady Microsoft Graph Toolkit. Dozvěděli jste se také, jak odesílat zprávy do kanálů Microsoft Teams. V tomto cvičení se dozvíte, jak načíst e-mailové zprávy a události kalendáře z Microsoft Graphu a integrovat je do aplikace.

Toto cvičení zahrnuje:

Zjistěte, jak se dá webová komponenta mgt-search-results v sadě Microsoft Graph Toolkit použít k vyhledávání e-mailů a událostí kalendáře.
Zjistěte, jak přizpůsobit komponentu mgt-search-results tak, aby se výsledky hledání vykreslovat vlastním způsobem.
Přečtěte si, jak přímo volat Microsoft Graph a načíst e-maily a události kalendáře.

Zkoumání kódu vyhledávání zpráv Email

Tip

Pokud používáte Visual Studio Code, můžete soubory otevřít přímo tak, že vyberete:

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

Potom zadejte název souboru, který chcete otevřít.

V předchozím cvičení jste vytvořili registraci aplikace v Microsoft Entra ID a spustili aplikační server a server rozhraní API. V souboru jste také aktualizovali .env následující hodnoty.
```
ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
TEAM_ID=<TEAMS_TEAM_ID>
CHANNEL_ID=<TEAMS_CHANNEL_ID>
```
Než budete pokračovat, ujistěte se, že jste dokončili předchozí cvičení .
Otevřete emails.component.html a prohlédněte si kód. Úplná cesta k souboru je client/src/app/emails/emails.component.html.
Vyhledejte komponentu 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>
```
Tento příklad komponenty mgt-search-results je nakonfigurovaný stejným způsobem jako ta, na kterou jste se dívali dříve. Jediným rozdílem entity-types je, že atribut je nastaven na , který message se používá k vyhledávání e-mailových zpráv, a je zadána prázdná šablona.
- Atribut class slouží k určení, že search-results se třída CSS má použít na komponentu.
- Atribut entity-types slouží k určení typu dat, která se mají hledat. V tomto případě je messagehodnota .
- Atribut queryString slouží k zadání hledaného termínu.
- Událost se dataChange aktivuje při změně výsledků hledání. Zavolá se dataChange() funkce komponenty email, předají se jí výsledky a v komponentě se aktualizuje vlastnost s názvem data .
- Pro komponentu je definována prázdná šablona. Tento typ šablony se obvykle používá k definování způsobu vykreslení výsledků hledání. V tomto scénáři ale komponentě říkáme, aby nevykreslila žádná data zpráv. Místo toho vykreslíme data sami pomocí standardní datové vazby (v tomto případě se používá Angular, ale můžete použít libovolnou knihovnu nebo architekturu, kterou chcete).

Datové vazby použité k vykreslení e-mailových zpráv najdete pod komponentou mgt-search-results v emails.component.html . Tento příklad iteruje data vlastnost a zapíše předmět e-mailu, náhled textu a odkaz pro zobrazení celé e-mailové zprávy.

<div *ngIf="data.length">
    <mat-card *ngFor="let email of data">
        <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>

Zobrazení Email zpráv

Kromě použití komponenty mgt-search-results k načítání zpráv nabízí Microsoft Graph několik rozhraní API, která se dají použít také k vyhledávání e-mailů. Rozhraní /search/query API, které jste viděli dříve, by se určitě dalo použít, ale jednodušší možností je messages rozhraní API.

Pokud chcete zjistit, jak volat toto rozhraní API, vraťte se do graph.service.ts a vyhledejte searchEmailMessages() funkci . Vytvoří adresu URL, kterou lze použít k volání messages koncového bodu Microsoft Graphu, a přiřadí query hodnotu parametru $search . Kód pak vytvoří požadavek GET a vrátí výsledky volajícímu. Operátor $search vyhledá query hodnotu v polích předmět, text a odesílatel automaticky.

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

Komponenta emailů umístěná v emails.component.ts zavolá searchEmailMessages() a zobrazí výsledky v uživatelském rozhraní.
```
override async search(query: string) {
    this.data = await this.graphService.searchEmailMessages(query);
}
```

Zkoumání kódu vyhledávání událostí kalendáře

Hledání událostí kalendáře je také možné provést pomocí komponenty mgt-search-results . Dokáže zpracovat vykreslení výsledků za vás, ale můžete také definovat vlastní šablonu, kterou uvidíte později v tomto cvičení.
Otevřete calendar-events.component.html a prohlédněte si kód. Úplná cesta k souboru je client/src/app/calendar-events/calendar-events.component.html. Uvidíte, že je velmi podobná komponentám pro soubory a e-maily, které jste si prohlíželi dříve.
```
<mgt-search-results 
    class="search-results" 
    entity-types="event" 
    [queryString]="searchText"
    (dataChange)="dataChange($any($event))">
    <template data-type="result-event"></template>
</mgt-search-results>
```
Tento příklad komponenty mgt-search-results je nakonfigurovaný stejným způsobem jako ty, na které jste se dívali dříve. Jediným rozdílem entity-types je, že atribut je nastaven na , který event se používá k vyhledávání událostí kalendáře, a je zadána prázdná šablona.
- Atribut class slouží k určení, že search-results se třída CSS má použít na komponentu.
- Atribut entity-types slouží k určení typu dat, která se mají hledat. V tomto případě je eventhodnota .
- Atribut queryString slouží k zadání hledaného termínu.
- Událost se dataChange aktivuje při změně výsledků hledání. Zavolá se dataChange() funkce komponenty události kalendáře, předají se jí výsledky a v komponentě se aktualizuje vlastnost s názvem data .
- Pro komponentu je definována prázdná šablona. V tomto scénáři říkáme komponentě, aby nevykreslila žádná data. Místo toho vykreslíme data sami pomocí standardní datové vazby.

Hned pod komponentou mgt-search-results v calendar-events.component.html najdete datové vazby používané k vykreslení událostí kalendáře. Tento příklad iteruje data vlastnost a zapíše počáteční datum, čas a předmět události. Vlastní funkce zahrnuté v komponentě, například dayFromDateTime() a timeRangeFromEvent() , se volají ke správnému formátování dat. Vazby HTML také obsahují odkaz pro zobrazení události kalendáře v aplikaci Outlook a umístění události, pokud je zadáno.

<div *ngIf="data.length">
    <div class="root" *ngFor='let event of data'>
        <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">
                <div *ngIf="!event.resource.bodyPreview?.includes('Join Microsoft Teams Meeting')"
                    class="inner-circle"></div>
            </div>
            <div class="vertical-line bottom"></div>
        </div>

        <div class="details">
            <div class="subject">{{ event.resource.subject }}</div>
            <div class="location" *ngIf="event.resource.location?.displayName">
                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>
            <div class="attendees" *ngIf="event.resource.attendees?.length">
                <span class="attendee" *ngFor="let attendee of event.resource.attendees">
                    <mgt-person person-query="{{attendee.emailAddress.name}}"></mgt-person>
                </span>
            </div>
            <div class="online-meeting"
                *ngIf="event.resource.bodyPreview?.includes('Join Microsoft Teams 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>

Kromě vyhledávání událostí kalendáře pomocí search/query rozhraní API poskytuje events Microsoft Graph také rozhraní API, které lze použít také k vyhledávání událostí kalendáře. searchCalendarEvents() Vyhledejte funkci v graph.service.ts.
Funkce searchCalendarEvents() vytvoří hodnoty počátečního a koncového data a času, které se používají k definování hledaného časového období. Potom vytvoří adresu URL, kterou lze použít k volání events koncového bodu Microsoft Graphu, a obsahuje parametr a proměnné počátečního query a koncového data a času. Potom se vytvoří požadavek GET a výsledky se vrátí volajícímu.
```
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;
}
```
- Tady je rozpis vytvořené adresy URL:
  - Část /me/events adresy URL slouží k určení, že se mají načíst události přihlášeného uživatele.
  - Parametry startdatetime a enddatetime se používají k definování časového období, které se má prohledávat. V takovém případě vyhledávání vrátí události, které začnou během následujících 7 dnů.
  - Parametr $filter dotazu slouží k filtrování výsledků podle query hodnoty (v tomto případě název společnosti vybraný z datové mřížky). Funkce contains() se používá k vyhledání query hodnoty ve subject vlastnosti události kalendáře.
  - Parametr $orderby dotazu slouží k seřazení výsledků podle start/dateTime vlastnosti .
url Po vytvoření se na Graph API Microsoftu vytvoří požadavek GET s použitím hodnoty url a výsledky se vrátí volajícímu.
Stejně jako u předchozích komponent volá komponenta calendar-events (soubor calendar-events.component.ts ) search() a zobrazí výsledky.
```
override async search(query: string) {
    this.data = await this.graphService.searchCalendarEvents(query);
}
```
Poznámka

Volání Microsoft Graphu můžete provádět také z vlastního rozhraní API nebo aplikace na straně serveru. Projděte si následující kurz a podívejte se na příklad volání Graph API Microsoftu z funkce Azure Functions.
Teď jste viděli příklad použití Microsoft Graphu k načítání souborů, chatů, e-mailových zpráv a událostí kalendáře. Stejné koncepty je možné použít i pro další rozhraní Microsoft Graph API. Můžete například použít rozhraní Microsoft Graph Users API k vyhledání uživatelů ve vaší organizaci. K vyhledání skupin ve vaší organizaci můžete použít také rozhraní API pro skupiny Microsoft Graphu. Úplný seznam rozhraní Microsoft Graph API najdete v dokumentaci.

Share via

Integrace funkcí OpenAI, komunikace a organizačních dat do obchodní aplikace

Co vytvoříte v tomto kurzu

Zvolte si vlastní dobrodružství

Požadavky

Cloudové technologie Microsoftu použité v tomto kurzu

Klonování projektu

Naklonujte úložiště GitHub a vytvořte .env soubor.

AI: Vytvoření prostředku Azure OpenAI a nasazení modelu

Vytvoření prostředku služby Azure OpenAI

Aktualizace souboru projektu .env

Spuštění aplikačních služeb

AI: Přirozený jazyk pro SQL

Použití funkce SQL z přirozeného jazyka

Zkoumání přirozeného jazyka pro kód SQL

AI: Generování dokončení

Použití funkce dokončování GPT

Zkoumání kódu dokončování GPT

AI: Používání vlastních dat

Přidání vlastního zdroje dat do Azure AI Studio

Použití vlastního zdroje dat v chatovacím prostředí

Použití funkce Přineste si vlastní data v aplikaci

Zkoumání kódu

Komunikace: Vytvoření prostředku Azure Communication Services

Vytvoření prostředku Azure Communication Services

Povolení funkcí telefonních hovorů a SMS

Připojení Email domény

.env Aktualizace souboru

Spuštění nebo restartování aplikačních serverů a serverů rozhraní API

Komunikace: Telefonní hovor

Použití funkce telefonního hovoru

Prozkoumání telefonního telefonního kódu

Komunikace: Odesílání Email a SMS zpráv

Použití funkcí Email a SMS

Zkoumání kódu Email

Prozkoumání kódu SMS

Organizační data: Vytvoření registrace aplikace Microsoft Entra ID

Vytvoření registrace aplikace Microsoft Entra ID

Aktualizace souboru .env projektu

Spuštění nebo restartování aplikačních serverů a serverů rozhraní API

Organizační data: Přihlášení uživatele a získání přístupového tokenu

Použití funkce přihlášení

Prozkoumání přihlašovacího kódu

Data organizace: Načítání souborů, chatů a odesílání zpráv do Teams

Použití funkce organizačních dat

Zkoumání kódu pro vyhledávání souborů

Prozkoumání kódu hledání zpráv chatu v Teams

Odeslání zprávy do kanálu Microsoft Teams

Data organizace: Načítání e-mailů a událostí kalendáře

Zkoumání kódu vyhledávání zpráv Email

Zkoumání kódu vyhledávání událostí kalendáře

Gratulujeme!

Dokončili jste tento kurz.

Vyčištění prostředků Azure

Další kroky

Dokumentace

Trénovací obsah

Váš názor

Naklonujte úložiště GitHub a vytvořte `.env` soubor.

Aktualizace souboru projektu `.env`

`.env` Aktualizace souboru