Integrace funkcí OpenAI, komunikace a organizačních dat do obchodní aplikace
Ú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:
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.
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
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
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.
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
aOPENAI_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
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ázvemuserQuery
. 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.
- Načte hodnotu uživatelského dotazu z
Otevřete soubor serveru nebo openAI.ts v editoru
getSQLFromNLP()
a vyhledejte funkci. Tato funkce je volána trasougeneratesql
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. HodnotauserPrompt
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()
asystemPrompt
předávají se jí hodnoty auserPrompt
. - 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.
- Do
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ázvemcallOpenAI()
, která je také umístěna v souboru serveru nebo openAI.ts . FunkcecallOpenAI()
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á
systemPrompt
parametry ,userPrompt
atemperature
.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ý obsahujemax_token
,temperature
amessages
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 aheadersBody
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 doRules:
čá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í
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 funkcicompleteEmailSMSMessages()
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:
systemPrompt
Slouží k definování, že se vyžaduje asistent umělé inteligence schopné generovat e-mailové a SMS zprávy. ObsahujesystemPrompt
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ýzvycompleteEmailSMSMessages()
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
vcompleteEmailSMSMessages()
, uložte soubor a znovu ho spusťte, ale použijteOrder 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
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á jicompleteBYOD()
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 auserPrompt
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, abytrue
se používala funkce kognitivního hledání.
- Parametr
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
natrue
, aby segetAzureOpenAIBYODCompletion()
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
zahrnujeextensions
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éhomessageData
do Azure OpenAI se přidá vlastnost. VlastnostdataSources
obsahuje hodnoty ,key
aindexName
prostředkuendpoint
služ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
obsahujechatpgpt_url
vlastnosti achatgpt_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
aassistant
. Ukázková aplikace použije druhou zprávu srole
z k poskytnutí požadovanýchassistant
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á obsahujeurl
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
vegetAzureOpenAIBYODCompletion()
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
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.
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
- Země nebo oblast:
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.
- V části Volání vyberte
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 pakCreate
. - Po dokončení nasazení vyberte
Go to resource
a výběrem1-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 zadejteMailFrom
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čítkoConnect
.
.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
: Hodnotaconnection string
z oddílu Klíče vašeho prostředku služby ACS.ACS_PHONE_NUMBER
: Přiřaďte k hodnotě číslo bezplatné linkyACS_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:
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 .
Komunikace: Telefonní hovor
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šleCustomerCall
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ěruCustomerCall
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 vngOnInit()
. - 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í aendCall()
v uvedeném pořadí.
- Načte přístupový token Azure Communication Services voláním
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
aAzureCommunicationTokenCredential
pomocí přístupového tokenu. - Vytvoří novou instanci
CallAgent
pomocíCallClient
objektů aAzureCommunicationTokenCredential
. Později uvidíte, žeCallAgent
se používá k zahájení a ukončení hovoru.
- Vytvoří novou instanci
- Načte id uživatele ACS a přístupový token voláním
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ýmiuserId
atoken
. - 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 atoken
.
- Zkontroluje, jestli je k dispozici hodnota ACS
Teď, když jste viděli, jak se načítají id uživatele a token, se vraťte k
phone-call.component.ts
a vyhledejtestartCall()
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í. FunkcecallAgent.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
aCallAgent
. - Objekt
CallAgent
se používá ke spuštění a ukončení volání volání funkcícallAgent.startCall()
acallAgent.hangUp()
v uvedeném pořadí.
- Id uživatele ACS a přístupový token se načítají ze serveru rozhraní API pomocí
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
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 proCUSTOMER_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) obsahujephone
vlastnost aemail
. 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é. Objektresponse
obsahuje informace, které byly zadány do dialogového okna.
- Zkontroluje, jestli
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ý natrue
. Tento příznak zkontroluje, jestliACS_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.email
prostředí . V reálné aplikaci by se hodnota použilathis.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á natrue
.
- Zkontroluje, jestli
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ástrojiAcsService
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. Funkcehttp.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 RxJScatchError
.
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 zACS_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ý natrue
. Tento příznak zkontroluje, jestliACS_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.customerPhoneNumber
prostředí . V reálné aplikaci by se hodnota použilathis.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 natrue
.
- Zkontroluje, jestli
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. Funkcehttp.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 RxJScatchError
.
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 zACS_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:
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
aSmsClient
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
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 achannel
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.
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 Jednostránková aplikace (SPA) a zadejte
- 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:
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 .
Organizační data: Přihlášení uživatele a získání přístupového tokenu
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.
Použití funkce přihlášení
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.
Prozkoumání přihlašovacího kódu
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 ascopes
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é natrue
. Tento vlastní příznak zkontroluje přítomnostENTRAID_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říkazthis.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
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.ReadWrite
jsou ,Files.Read.All
a 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 komponentusearch-results
má použít třída CSS.Atribut
entity-types
slouží k určení typu dat, která se mají hledat. V tomto případě sedriveItem
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 nasearchText
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 kolemqueryString
označují, že vlastnost je vázána nasearchText
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ázvemdataChange()
a data událostí se předají funkci. Závorky kolemdataChange
označují, že událost je vázána nadataChange()
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 umgt-search-results
komponenty. Je to stejné jako předánídriveItem
ventity-types
komponentě mgt-search-results , kterou jste viděli dříve. Parametrquery
se pak přidá doqueryString
filtru spolu s parametremContentType: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()
. Objektfilter
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ázvemresource
obsahuje metadata dokumentu a je přidánafiles
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 vlastnostidata
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ázvemmgt-file-list
. Tady je příklad vazbydata
vlastnosti na jednu z vlastností komponenty s názvemfiles
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 oteamId
objektech ,channelId
amessageId
, 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 ateamId
předají se ,channelId
amessageId
. 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()
.
- Publikuje data filtru do rozhraní API Microsoft Graphu
Otevřete soubor chats.component.ts a vyhledejte
search()
funkci. Úplná cesta k souboru je client/src/app/chats/chats.component.ts. Funkcesearch()
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>
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 achannelId
. 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. Konstantabody
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
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í, žesearch-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ě jemessage
hodnota . - Atribut
queryString
slouží k zadání hledaného termínu. - Událost se
dataChange
aktivuje při změně výsledků hledání. Zavolá sedataChange()
funkce komponenty email, předají se jí výsledky a v komponentě se aktualizuje vlastnost s názvemdata
. - 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).
- Atribut
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>
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í jemessages
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í, žesearch-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ě jeevent
hodnota . - Atribut
queryString
slouží k zadání hledaného termínu. - Událost se
dataChange
aktivuje při změně výsledků hledání. Zavolá sedataChange()
funkce komponenty události kalendáře, předají se jí výsledky a v komponentě se aktualizuje vlastnost s názvemdata
. - 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.
- Atribut
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 iterujedata
vlastnost a zapíše počáteční datum, čas a předmět události. Vlastní funkce zahrnuté v komponentě, napříkladdayFromDateTime()
atimeRangeFromEvent()
, 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 poskytujeevents
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íhoquery
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
aenddatetime
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ů podlequery
hodnoty (v tomto případě název společnosti vybraný z datové mřížky). Funkcecontains()
se používá k vyhledáníquery
hodnoty vesubject
vlastnosti události kalendáře. - Parametr
$orderby
dotazu slouží k seřazení výsledků podlestart/dateTime
vlastnosti .
- Část
url
Po vytvoření se na Graph API Microsoftu vytvoří požadavek GET s použitím hodnotyurl
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.
Gratulujeme!
Dokončili jste tento kurz.
Gratulujeme! Dozvěděli jste se, jak se dá Azure OpenAI použít ke zvýšení produktivity uživatelů, jak se dají Azure Communication Services použít k integraci komunikačních funkcí a jak se dají rozhraní Microsoft Graph API a komponenty použít k načtení a zobrazení dat organizace. Pomocí těchto technologií můžete vytvářet efektivní řešení, která zvyšují produktivitu uživatelů minimalizací kontextových posunů a poskytováním nezbytných informací o rozhodování.
Vyčištění prostředků Azure
Vyčistěte prostředky Azure, abyste se vyhnuli dalším poplatkům za váš účet. Přejděte na Azure Portal a odstraňte následující prostředky:
- Prostředek Azure Cognitive Search
- Prostředek služby Azure Storage
- Prostředek Azure OpenAI
- Prostředek Azure Communication Services
Další kroky
Dokumentace
- Dokumentace k Azure OpenAI
- Azure OpenAI pro vaše data
- Dokumentace k Azure Communication Services
- Dokumentace k Microsoft Graphu
- Dokumentace k sadě Microsoft Graph Toolkit
- Dokumentace pro vývojáře v Microsoft Teams
Trénovací obsah
- Použití rychlé přípravy pomocí služby Azure OpenAI
- Začínáme se službou Azure OpenAI
- Úvod do Azure Communication Services
- Základy Microsoft Graphu
- Video kurz: Základy Microsoft Graphu pro začátečníky
- Prozkoumejte scénáře Microsoft Graphu pro vývoj v JavaScriptu
- Prozkoumání scénářů Microsoft Graphu pro vývoj ASP.NET Core
- Začínáme se sadou Microsoft Graph Toolkit
- Vytváření a nasazování aplikací pro Microsoft Teams pomocí sady Nástrojů Teams pro Visual Studio Code
Máte s touto částí nějaké problémy? Pokud ano, dejte nám prosím vědět, abychom tuto část mohli vylepšit.
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro