Integrera OpenAI-, kommunikations- och organisationsdatafunktioner i en branschspecifik app
Nivå: Mellanliggande
Den här självstudien visar hur Azure OpenAI, Azure Communication Services och Microsoft Graph/Microsoft Graph Toolkit kan integreras i verksamhetsspecifika program (LOB) för att förbättra användarproduktiviteten, höja användarupplevelsen och ta verksamhetsspecifika appar till nästa nivå.
- AI: Gör det möjligt för användare att ställa frågor på naturligt språk och konvertera sina svar till SQL som kan användas för att fråga en databas, tillåta användare att definiera regler som kan användas för att automatiskt generera e-postmeddelanden och SMS och lära sig hur naturligt språk kan användas för att hämta data från dina egna anpassade datakällor. Azure OpenAI används för dessa funktioner.
- Kommunikation: Aktivera telefonsamtal i appen till kunder och Email/SMS-funktioner med hjälp av Azure Communication Services.
- Organisationsdata: Hämta relaterade organisationsdata som användarna kan behöva (dokument, chattar, e-postmeddelanden, kalenderhändelser) när de arbetar med kunder för att undvika kontextväxling. Genom att ge åtkomst till den här typen av organisationsdata minskar användarens behov av att växla till Outlook, Teams, OneDrive, andra anpassade appar, deras telefon osv. eftersom de specifika data och funktioner som de behöver tillhandahålls direkt i appen. Microsoft Graph och Microsoft Graph Toolkit används för den här funktionen.
Programmet är en enkel kundhanteringsapp som gör att användarna kan hantera sina kunder och relaterade data. Den består av en klientdel som skapats med TypeScript och som anropar serverdels-API:er för att hämta data, interagera med AI-funktioner, skicka e-post/SMS och hämta organisationsdata. Här är en översikt över den programlösning som du går igenom i den här självstudien:
Självstudien vägleder dig genom processen med att konfigurera nödvändiga Azure- och Microsoft 365-resurser. Den vägleder dig också genom den kod som används för att implementera AI-, kommunikations- och organisationsdatafunktionerna. Du behöver inte kopiera och klistra in kod, men i vissa av övningarna får du ändra koden för att prova olika scenarier.
Det här skapar du i den här självstudien
Välj ditt eget äventyr
Du kan slutföra hela självstudien från början till slut eller slutföra specifika ämnen av intresse. Självstudien är uppdelad i följande ämnesområden:
- Klona projektövningen (obligatorisk övning).
- AI-övningar: Skapa en Azure OpenAI-resurs och använd den för att konvertera naturligt språk till SQL, generera e-postmeddelanden/SMS och arbeta med dina egna data och dokument.
- Kommunikationsövningar: Skapa en Azure Communication Services resurs och använd den för att ringa telefonsamtal från appen och skicka e-post/SMS.
- Organisationsdataövningar: Skapa en Microsoft Entra ID appregistrering så att Microsoft Graph och Microsoft Graph Toolkit kan användas för att autentisera och hämta organisationsdata till programmet.
Förutsättningar
- Node – Node 16+ och npm 7+ används för det här projektet
- git
- Visual Studio Code (även om Visual Studio Code rekommenderas kan alla redigeringsprogram användas)
- Azure-prenumeration
- Microsoft 365 Developer-klientorganisation
- Docker Desktop eller en annan OCI-kompatibel containerkörning (Open Container Initiative), till exempel Podman eller nerdctl , som kan köra en container.
Microsoft Cloud Technologies som används i den här självstudien
- Microsoft Entra ID
- Azure Communication Services
- Azure OpenAI Service
- Microsoft Graph
- Microsoft Graph Toolkit
Klona projektet
Kodprojektet som används i den här självstudien finns på https://github.com/microsoft/MicrosoftCloud. Projektets lagringsplats innehåller både kod på klientsidan och på serversidan som krävs för att köra projektet, så att du kan utforska de integrerade funktionerna som rör artificiell intelligens (AI), kommunikation och organisationsdata. Dessutom fungerar projektet som en resurs som hjälper dig att införliva liknande funktioner i dina egna program.
I den här övningen kommer du att:
- Klona github-lagringsplatsen.
- Lägg till en .env-fil i projektet och uppdatera den.
Innan du fortsätter kontrollerar du att alla krav är installerade och konfigurerade enligt beskrivningen i avsnittet Förutsättningar i den här självstudien.
Klona GitHub-lagringsplatsen och skapa en .env
fil
Kör följande kommando för att klona GitHub-lagringsplatsen för Microsoft Cloud till datorn.
git clone https://github.com/microsoft/MicrosoftCloud
Öppna mappen MicrosoftCloud/samples/openai-acs-msgraph i Visual Studio Code.
Anteckning
Även om vi använder Visual Studio Code i den här självstudien kan alla kodredigerare användas för att arbeta med exempelprojektet.
Observera följande mappar och filer:
- klient: Programkod på klientsidan.
- server: API-kod på serversidan.
- docker-compose.yml: Används för att köra en lokal PostgreSQL-databas.
Byt namn på .env.example i projektets rot till .env.
Öppna .env-filen och ta en stund att titta igenom de nycklar som ingår:
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=
Uppdatera följande värden i .env. Dessa värden används av API-servern för att ansluta till den lokala PostgreSQL-databasen.
POSTGRES_USER=web POSTGRES_PASSWORD=web-password
Nu när du har projektet på plats ska vi prova några av programfunktionerna och lära oss hur de skapas. Välj knappen Nästa nedan för att fortsätta eller gå vidare till en specifik övning med hjälp av innehållsförteckningen.
AI: Skapa en Azure OpenAI-resurs och distribuera en modell
För att komma igång med Azure OpenAI i dina program måste du skapa en Azure OpenAI-tjänst och distribuera en modell som kan användas för att utföra uppgifter som att konvertera naturligt språk till SQL, generera e-post-/SMS-meddelandeinnehåll med mera.
I den här övningen kommer du att:
- Skapa en Azure OpenAI-tjänstresurs.
- Distribuera en modell.
- Uppdatera .env-filen med värden från din Azure OpenAI-tjänstresurs.
Skapa en Azure OpenAI-tjänstresurs
Gå till Azure Portal i webbläsaren och logga in.
Skriv openai i sökfältet överst på portalsidan och välj Azure OpenAI bland de alternativ som visas.
Välj Skapa i verktygsfältet.
Anteckning
Om du ser ett meddelande om att fylla i ett programformulär för att aktivera Azure OpenAI för din prenumeration väljer du länken Klicka här för att begära åtkomst till Azure OpenAI-tjänsten och fylla i formuläret. När du har fyllt i formuläret måste du vänta tills Azure OpenAI-teamet har godkänt din begäran. När du har fått ditt godkännandemeddelande kan du gå tillbaka till den här övningen och skapa resursen.
Den här självstudien fokuserar på Azure OpenAI, men om du har en OpenAI API-nyckel och vill använda den medan du väntar på åtkomst till Azure OpenAI kan du hoppa över det här avsnittet och gå direkt till avsnittet Uppdatera projektets .env-fil nedan. Tilldela din OpenAI API-nyckel till
OPENAI_API_KEY
i .env-filen (du kan ignorera andra.env
instruktioner som rör OpenAI). När du har åtkomst till Azure OpenAI går du tillbaka till den här övningen, skapar resursen och modellen och uppdaterar .env-filen med värdena från din Azure OpenAI-resurs.Utför följande uppgifter:
- Välj din Azure-prenumeration.
- Välj den resursgrupp som ska användas (skapa en ny om det behövs).
- Välj den region som du vill använda.
- Ange resursnamnet. Det måste vara ett unikt värde.
- Välj prisnivån Standard S0 .
Välj Nästa tills du kommer till skärmen Granska + skicka . Välj Skapa.
När din Azure OpenAI-resurs har skapats navigerar du till den och väljer Nycklar och slutpunkt i avsnittet Resurshantering .
Leta upp nyckel 1 - och slutpunktsvärdena . Du använder båda värdena i nästa avsnitt så kopiera dem till en lokal fil.
Välj Modelldistributioner i avsnittet Resurshantering .
Välj knappen Hantera distributioner för att gå till Azure OpenAI Studio.
Välj Skapa ny distribution i verktygsfältet.
Ange följande värden:
- Modell: gpt-35-turbo.
- Modellversion: Uppdatera automatiskt till standard.
- Distributionsnamn: gpt-35-turbo.
Anteckning
Azure OpenAI stöder flera olika typer av modeller. Varje modell kan användas för att hantera olika scenarier.
Välj Skapa.
När modellen har distribuerats väljer du Slutföranden i avsnittet Playground .
Välj modellen gpt-35-turbo i listrutan Distributioner . Välj Generera ett e-postmeddelande i listrutan Exempel .
Ta en stund att läsa igenom prompttexten som tillhandahålls. Välj Generera för att se texten som modellen genererar.
Varning
Om du får ett felmeddelande om att modellen inte är klar väntar du några minuter och försöker igen. Det kan ta några minuter innan modellen är helt distribuerad och redo att användas.
Om du får ett felmeddelande om att slutförandeåtgärden inte fungerar med den angivna modellen. Innebär det normalt att du har valt en nyare modellversion i stället för standardversionen. Välj Distributioner och ta bort modellen som du skapade tidigare. Skapa en ny gpt-35-turbomodelldistribution , se till att du väljer Automatisk uppdatering till standard för modellversionen, ger den ett namn på gpt-35-turbo och väntar på att modellen ska distribueras fullständigt. När den har distribuerats går du tillbaka till Playground och försöker slutföra igen.
Välj Återskapa flera gånger. Observera att texten skiljer sig åt varje gång.
Till höger på skärmen visas egenskaper som temperatur. Ändra temperaturvärdet till 0 och välj Återskapa igen. Läs igenom e-posttexten som genereras.
Välj Återskapa en sista gång och observera att e-posttexten är samma som den text som genererades tidigare.
Anteckning
Att sänka temperaturen innebär att modellen ger mer repetitiva och deterministiska svar. Att öka temperaturen resulterar i mer oväntade eller kreativa svar.
Uppdatera projektets .env
fil
Gå tillbaka till Visual Studio Code och öppna
.env
filen i projektets rot.Kopiera värdet KEY 1 från Azure OpenAI-resursen och tilldela det till
OPENAI_API_KEY
i .env-filen i roten i mappen openai-acs-msgraph :OPENAI_API_KEY=<KEY_1_VALUE>
Kopiera värdet *Slutpunkt och tilldela det till
OPENAI_ENDPOINT
i .env-filen ./
Ta bort tecknet från slutet av värdet om det finns.OPENAI_ENDPOINT=<ENDPOINT_VALUE>
Anteckning
Du ser att värdena för
OPENAI_MODEL
ochOPENAI_API_VERSION
redan har angetts i .env-filen . Modellvärdet är inställt på gpt-35-turbo som ska matcha modellnamnet som du skapade tidigare i den här övningen. API-versionen är inställd på ett värde som stöds och definieras i Azure OpenAI-referensdokumentationen.Spara .env-filen .
Starta Application Services
Det är dags att starta dina programtjänster, inklusive databasen, API-servern och webbservern.
I följande steg skapar du tre terminalfönster i Visual Studio Code.
Högerklicka på .env-filen i Visual Studio Code-fillistan och välj Öppna i integrerad terminal. Kontrollera att terminalen finns i projektets rot – openai-acs-msgraph – innan du fortsätter.
Välj något av följande alternativ för att starta PostgreSQL-databasen:
Om du har Docker Desktop installerat och igång kör du
docker-compose up
i terminalfönstret och trycker på Retur.Om du har Podman med podman-compose installerat och igång kör
podman-compose up
du i terminalfönstret och trycker på Retur.Kör PostgreSQL-containern direkt med antingen Docker Desktop, Podman, nerdctl eller en annan containerkörning som du har installerat genom att köra följande kommando i terminalfönstret:
Mac, Linux eller Windows-undersystem för Linux (WSL):
[docker | podman | nerdctl] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v $(pwd)/data:/var/lib/postgresql/data -p 5432:5432 postgres
Windows med PowerShell:
[docker | podman] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v ${PWD}/data:/var/lib/postgresql/data -p 5432:5432 postgres
När databascontainern startar trycker du på + ikonen i Visual Studio Code Terminal-verktygsfältet för att skapa ett andra terminalfönster.
cd
i mappen server/typescript och kör följande kommandon för att installera beroendena och starta API-servern.npm install
npm start
Tryck på + ikonen igen i verktygsfältet Visual Studio Code Terminal för att skapa ett tredje terminalfönster.
cd
i klientmappen och kör följande kommandon för att installera beroendena och starta webbservern.npm install
npm start
En webbläsare startas och du tas till http://localhost:4200.
AI: Naturligt språk för SQL
Citatet "Bara för att du kan betyder inte att du borde" är en användbar guide när du tänker på AI-funktioner. Azure OpenAI:s naturliga språk till SQL-funktion gör det till exempel möjligt för användare att göra databasfrågor på vanlig engelska, vilket kan vara ett kraftfullt verktyg för att förbättra deras produktivitet. Kraftfull betyder dock inte alltid lämpligt eller säkert. Den här övningen visar hur du använder den här AI-funktionen samtidigt som du diskuterar viktiga saker att tänka på innan du bestämmer dig för att implementera den.
Här är ett exempel på en fråga med naturligt språk som kan användas för att hämta data från en databas:
Get the the total revenue for all companies in London.
Med rätt uppmaningar konverterar Azure OpenAI den här frågan till SQL som kan användas för att returnera resultat från databasen. Därför kan icke-tekniska användare, inklusive affärsanalytiker, marknadsförare och chefer, lättare hämta värdefull information från databaser utan att brottas med invecklad SQL-syntax eller förlita sig på begränsade datagrids och filter. Den här strömlinjeformade metoden kan öka produktiviteten genom att eliminera användarnas behov av att söka hjälp från tekniska experter.
Den här övningen ger en startpunkt som hjälper dig att förstå hur naturligt språk i SQL fungerar, introducera några viktiga överväganden, få dig att tänka på för- och nackdelar och visa dig koden för att komma igång.
I den här övningen kommer du att:
- Använd GPT-prompter för att konvertera naturligt språk till SQL.
- Experimentera med olika GPT-frågor.
- Använd den genererade SQL för att köra frågor mot PostgreSQL-databasen som startades tidigare.
- Returnera frågeresultat från PostgreSQL och visa dem i webbläsaren.
Vi börjar med att experimentera med olika GPT-frågor som kan användas för att konvertera naturligt språk till SQL.
Använda funktionen Naturligt språk till SQL
I föregående övning startade du databasen, API:erna och programmet. Du har också uppdaterat
.env
filen. Om du inte slutförde de här stegen följer du anvisningarna i slutet av övningen innan du fortsätter.Gå tillbaka till webbläsaren (http://localhost:4200) och leta upp avsnittet Anpassad fråga på sidan nedanför datagrid. Observera att ett exempel på ett frågevärde redan ingår: Hämta den totala intäkten för alla beställningar. Gruppera efter företag och inkludera staden.
Välj knappen Kör fråga . Detta skickar användarens fråga med naturligt språk till Azure OpenAI som konverterar den till SQL. SQL-frågan används sedan för att köra frågor mot databasen och returnera eventuella resultat.
Kör följande anpassade fråga:
Get the total revenue for Adventure Works Cycles. Include the contact information as well.
Visa terminalfönstret som kör API-servern i Visual Studio Code och observera att den visar SQL-frågan som returneras från Azure OpenAI. JSON-data används av API:erna på serversidan för att köra frågor mot PostgreSQL-databasen. Alla strängvärden som ingår i frågan läggs till som parametervärden för att förhindra SQL-inmatningsattacker:
{ "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"] }
Gå tillbaka till webbläsaren och välj Återställ data för att visa alla kunder igen i datagrid.
Utforska naturligt språk till SQL Code
Tips
Om du använder Visual Studio Code kan du öppna filer direkt genom att välja:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Skriv sedan namnet på den fil som du vill öppna.
Anteckning
Målet med den här övningen är att visa vad som är möjligt med naturligt språk för SQL-funktioner och visa hur du kommer igång med den. Som tidigare nämnts är det viktigt att diskutera om den här typen av AI är lämplig för din organisation innan du fortsätter med någon implementering. Det är också absolut nödvändigt att planera för lämpliga promptregler och databassäkerhetsåtgärder för att förhindra obehörig åtkomst och skydda känsliga data.
Nu när du har sett funktionen naturligt språk till SQL i praktiken ska vi undersöka hur den implementeras.
Öppna filen server/apiRoutes.ts och leta upp
generateSql
vägen. Den här API-vägen anropas av programmet på klientsidan som körs i webbläsaren och används för att generera SQL från en fråga på naturligt språk. När SQL-frågan har hämtats används den för att fråga databasen och returnera resultat.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.' }); } });
Observera följande funktioner i vägen
generateSql
:- Den hämtar användarfrågevärdet från
req.body.query
och tilldelar det till en variabel med namnetuserQuery
. Det här värdet används i GPT-prompten. - Den anropar en
getSQLFromNLP()
funktion för att konvertera naturligt språk till SQL. - Den skickar den genererade SQL-filen till en funktion med namnet
queryDb
som kör SQL-frågan och returnerar resultat från databasen.
- Den hämtar användarfrågevärdet från
Öppna filen server/openAI.ts i redigeringsprogrammet och leta upp
getSQLFromNLP()
funktionen . Den här funktionen anropas avgeneratesql
vägen och används för att konvertera naturligt språk till 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; }
- En
userPrompt
parameter skickas till funktionen . VärdetuserPrompt
är den fråga på naturligt språk som användaren anger i webbläsaren. - A
systemPrompt
definierar vilken typ av AI-assistent som ska användas och vilka regler som ska följas. Detta hjälper Azure OpenAI att förstå databasstrukturen, vilka regler som ska tillämpas och hur du returnerar den genererade SQL-frågan och parametrarna. - En funktion med namnet
callOpenAI()
anropas ochsystemPrompt
värdena ochuserPrompt
skickas till den. - Resultaten kontrolleras för att säkerställa att inga förbjudna värden ingår i den genererade SQL-frågan. Om otillåtna värden hittas anges SQL-frågan till en tom sträng.
- En
Nu ska vi gå igenom systemprompten i detalj:
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. `;
Typen av AI-assistent som ska användas definieras. I det här fallet en "naturlig språk till SQL bot".
Tabellnamn och kolumner i databasen definieras. Det övergripande schemat som ingår i prompten finns i filen server/db.schema och ser ut så här.
- 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)
Tips
Du kan överväga att skapa skrivskyddade vyer som endast innehåller de data som användarna får köra frågor mot med naturligt språk till SQL.
En regel definieras för att konvertera alla strängvärden till ett parametriserat frågevärde för att undvika SQL-inmatningsattacker.
En regel definieras för att alltid returnera ett JSON-objekt (och inget annat) med SQL-frågan och parametervärdena i den.
Ett exempel ges för vilken typ av JSON-objekt som ska returneras.
Exempel på användarfrågor och förväntade SQL-fråge- och parametervärden tillhandahålls. Detta kallas "few-shot"-inlärning. Även om LLM:er tränas på stora mängder data kan de anpassas till nya uppgifter med bara några få exempel. En alternativ metod är "zero-shot"-inlärning där inget exempel anges och modellen förväntas generera rätt SQL-fråge- och parametervärden.
Två kritiska regler upprepas igen längst ned i systemprompten för att undvika "recency bias".
Tips
Läs mer om bias för recency i Azure OpenAI-dokumentationen.
Funktionen
getSQLFromNLP()
skickar system- och användarfrågor till en funktion med namnetcallOpenAI()
som också finns i filen server/openAI.ts . FunktionencallOpenAI()
avgör om Azure OpenAI-tjänsten eller OpenAI-tjänsten ska anropas genom att kontrollera miljövariabler. Om en nyckel, slutpunkt och modell är tillgängliga i miljövariablerna anropas Azure OpenAI, annars anropas 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); }
Anteckning
Även om vi fokuserar på Azure OpenAI i den här självstudien, använder programmet OpenAI i stället om du bara anger ett
OPENAI_API_KEY
värde i .env-filen . Om du väljer att använda OpenAI i stället för Azure OpenAI kan du se olika resultat i vissa fall.getAzureOpenAICompletion()
Leta upp funktionen .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; } }
Den här funktionen gör följande:
Accepterar parametrarna
systemPrompt
,userPrompt
ochtemperature
.systemPrompt
: Låter Azure OpenAI-modellen veta vilken roll den ska spela och vilka regler som ska följas.userPrompt
: Användarinformation som anges i programmet, till exempel naturligt språk eller regler som ska användas av modellen för att generera utdata.temperature
: Avgör hur kreativ modellen ska vara när du genererar ett svar. Ett högre värde innebär att modellen tar fler risker.
Säkerställer att en giltig Azure OpenAI API-nyckel, slutpunkt och modell är tillgängliga genom att anropa
checkRequiredEnvVars()
.Skapar ett
fetchUrl
värde som används för att anropa Rest-API:et för Azure OpenAI och bäddar in värdena för slutpunkt, modell och API-version från miljövariablerna i URL:en.Skapar ett
messageData
objekt som innehållermax_token
,temperature
ochmessages
som ska skickas till Azure OpenAI.max_tokens
: Det maximala antalet token som ska genereras i slutförandet. Antalet token för prompten plus max_tokens får inte överskrida modellens kontextlängd. Äldre modeller har en kontextlängd på 2 048 token medan nyare har stöd för 4 096, 8 192 eller till och med 32 768 token beroende på vilken modell som används.temperature
: Vilken samplingstemperatur som ska användas. Högre värden innebär att modellen tar fler risker. Prova 0,9 för mer kreativa program och 0 för dem med ett väldefinierat svar.messages
: Representerar de meddelanden som ska genereras för chatten i chattformatet. I det här exemplet skickas två meddelanden: ett för systemet och ett för användaren. Systemmeddelandet definierar det övergripande beteendet och reglerna som ska användas, medan användarmeddelandet definierar den prompttext som tillhandahålls av användaren.
Anrop
fetchAndParse()
för att skickafetchUrl
värdena ochheadersBody
till Azure OpenAI.Bearbetar svaret genom att
completion.choices[0].message.content
hämta värdet. Om svaret innehåller förväntade resultat extraherar koden JSON-objektet från svaret och returnerar det.Anteckning
Du kan läsa mer om dessa parametrar och andra i referensdokumentationen för Azure OpenAI.
Kommentera ut följande rader i
getSQLFromNLP()
funktionen:// if (isProhibitedQuery(queryData.sql)) { // queryData.sql = ''; // }
Spara openAI.ts. API-servern återskapar automatiskt TypeScript-koden och startar om servern.
Gå tillbaka till webbläsaren och ange Välj alla tabellnamn från databasen i indata för anpassad fråga. Välj Kör fråga. Visas tabellnamn?
Gå tillbaka till
getSQLFromNLP()
funktionen i server/openAI.ts och lägg till följande regel iRules:
avsnittet i systemprompten och spara sedan filen.- Do not allow the SELECT query to return table names, function names, or procedure names.
Gå tillbaka till webbläsaren och utför följande uppgifter:
- Ange Välj alla tabellnamn från databasen i Indata för anpassad fråga . Välj Kör fråga. Visas tabellnamn?
- Ange Välj alla funktionsnamn från databasen. I Indata för anpassad fråga och välj Kör fråga igen. Visas funktionsnamn?
FRÅGA: Varför fungerar detta fortfarande när du har lagt till en regel som säger att tabellnamn, funktionsnamn och procedurnamn inte tillåts?
SVAR: Detta beror på regeln "endast JSON". Om reglerna var mer flexibla och inte krävde att ett JSON-objekt skulle returneras kan du se ett meddelande om att Azure OpenAI inte kan utföra uppgiften.
Anteckning
Det är viktigt att observera att OpenAI-modeller ibland kan returnera oväntade resultat som kanske inte matchar de regler som du har definierat. Det är viktigt att planera för det i koden.
Ta bort följande regel från
systemPrompt
och spara filen.- 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.
Kör Välj alla tabellnamn från databasfrågan igen.
Observera att meddelandet nu visas i webbläsaren. Azure OpenAI kan inte utföra uppgiften på grund av följande regel. Eftersom vi har tagit bort regeln "endast JSON" kan svaret ge ytterligare information om varför uppgiften inte kan utföras.
- Do not allow the SELECT query to return table names, function names, or procedure names.
Du kan se att AI kan generera oväntade resultat även om du har specifika regler på plats. Det är därför du måste planera din prompttext och dina regler noggrant, men även planera att lägga till ett efterbearbetningssteg i koden för att hantera fall där du får oväntade resultat.
Gå tillbaka till server/openAI.ts och leta upp
isProhibitedQuery()
funktionen. Det här är ett exempel på efterbearbetningskod som kan köras när Azure OpenAI returnerar resultat. Observera att egenskapensql
anges till en tom sträng om otillåtna nyckelord returneras i den genererade SQL-frågan. Detta säkerställer att sql-frågan inte körs mot databasen om oväntade resultat returneras från Azure OpenAI.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)); }
Anteckning
Observera att detta bara är demokod. Det kan finnas andra förbjudna nyckelord som krävs för att täcka dina specifika användningsfall om du väljer att konvertera naturligt språk till SQL. Det här är en funktion som du måste planera för och använda med försiktighet för att säkerställa att endast giltiga SQL-frågor returneras och körs mot databasen. Förutom förbjudna nyckelord måste du också ta hänsyn till säkerheten.
Gå tillbaka till server/openAI.ts och avkommenteras följande kod i
getSQLFromNLP()
funktionen. Spara filen.if (isProhibitedQuery(queryData.sql)) { queryData.sql = ''; }
Ta bort följande regel från
systemPrompt
och spara filen.- Do not allow the SELECT query to return table names, function names, or procedure names.
Gå tillbaka till webbläsaren anger du Välj alla tabellnamn från databasen i Custom Query-indata igen och väljer knappen Kör fråga.
Visas några tabellresultat? Även utan regeln på plats
isProhibitedQuery()
förbjuder efterbearbetningskoden den typen av fråga från att köras mot databasen.Som tidigare nämnts kan integrering av naturligt språk i SQL i branschspecifika program vara ganska fördelaktigt för användarna, men det har en egen uppsättning överväganden.
Fördelar:
Användarvänlighet: Den här funktionen kan göra databasinteraktion mer tillgänglig för användare utan teknisk expertis, vilket minskar behovet av SQL-kunskap och potentiellt påskyndar åtgärder.
Ökad produktivitet: Affärsanalytiker, marknadsförare, chefer och andra icke-tekniska användare kan hämta värdefull information från databaser utan att behöva förlita sig på tekniska experter, vilket ökar effektiviteten.
Brett program: Med hjälp av avancerade språkmodeller kan program utformas för att tillgodose en mängd olika användare och användningsfall.
Överväganden:
Säkerhet: Ett av de största problemen är säkerhet. Om användarna kan interagera med databaser med naturligt språk måste det finnas robusta säkerhetsåtgärder för att förhindra obehörig åtkomst eller skadliga frågor. Du kan överväga att implementera ett skrivskyddat läge för att förhindra att användare ändrar data.
Datasekretess: Vissa data kan vara känsliga och bör inte vara lättillgängliga, så du måste se till att rätt skydd och användarbehörigheter finns på plats.
Noggrannhet: Bearbetningen av naturligt språk har förbättrats avsevärt, men den är inte perfekt. Felaktig tolkning av användarfrågor kan leda till felaktiga resultat eller oväntat beteende. Du måste planera för hur oväntade resultat ska hanteras.
Effektivitet: Det finns inga garantier för att SQL som returneras från en fråga med naturligt språk är effektiv. I vissa fall kan ytterligare anrop till Azure OpenAI krävas om efterbearbetningsregler identifierar problem med SQL-frågor.
Utbildning och användaranpassning: Användarna måste tränas att formulera sina frågor korrekt. Även om det är enklare än att lära sig SQL kan det fortfarande finnas en inlärningskurva.
Några sista saker att tänka på innan du går vidare till nästa övning:
- Kom ihåg att "Bara för att du kan betyder inte att du borde" gäller här. Var mycket försiktig och planera noggrant innan du integrerar naturligt språk i SQL i ett program. Det är viktigt att förstå de potentiella riskerna och planera för dem.
- Innan du använder den här typen av teknik bör du diskutera potentiella scenarier med ditt team, databasadministratörer, säkerhetsteam, intressenter och andra relevanta parter för att säkerställa att det passar din organisation. Det är viktigt att diskutera om naturligt språk i SQL uppfyller säkerhet, sekretess och andra krav som din organisation kan ha på plats.
- Säkerhet bör vara ett primärt problem och inbyggt i planerings-, utvecklings- och distributionsprocessen.
- Även om det naturliga språket i SQL kan vara mycket kraftfullt, måste noggrann planering gå in i det för att säkerställa att uppmaningar har nödvändiga regler och att efterbearbetningsfunktioner ingår. Planera för ytterligare tid för att implementera och testa den här typen av funktioner och för att ta hänsyn till scenarier där oväntade resultat returneras.
- Med Azure OpenAI får kunderna säkerhetsfunktionerna i Microsoft Azure samtidigt som de kör samma modeller som OpenAI. Azure OpenAI erbjuder privat nätverk, regional tillgänglighet och ansvarsfull AI-innehållsfiltrering. Läs mer om data, sekretess och säkerhet för Azure OpenAI-tjänsten.
Nu har du sett hur du använder Azure OpenAI för att konvertera naturligt språk till SQL och lärt dig om för- och nackdelarna med att implementera den här typen av funktioner. I nästa övning får du lära dig hur e-postmeddelanden och SMS kan genereras med hjälp av Azure OpenAI.
AI: Generera slutföranden
Förutom funktionen för naturligt språk till SQL kan du också använda Azure OpenAI-tjänsten för att generera e-post och SMS för att förbättra användarproduktiviteten och effektivisera kommunikationsarbetsflöden. Genom att använda Azure OpenAI:s språkgenereringsfunktioner kan användarna definiera specifika regler, till exempel "Beställningen fördröjs 5 dagar", och systemet genererar automatiskt kontextuellt lämpliga e-postmeddelanden och SMS baserat på dessa regler.
Den här funktionen fungerar som en "snabbstart" för användare, vilket ger dem en genomtänkt utformad meddelandemall som de enkelt kan anpassa innan de skickar. Resultatet är en betydande minskning av den tid och det arbete som krävs för att skapa meddelanden, så att användarna kan fokusera på andra viktiga uppgifter. Dessutom kan Azure OpenAI:s språkgenereringsteknik integreras i automatiseringsarbetsflöden, vilket gör det möjligt för systemet att generera och skicka meddelanden autonomt som svar på fördefinierade utlösare. Den här automatiseringsnivån påskyndar inte bara kommunikationsprocesserna, utan garanterar även konsekventa och korrekta meddelanden i olika scenarier.
I den här övningen kommer du att:
- Experimentera med olika GPT-prompter.
- Använd GPT-prompter för att generera slutföranden för e-post och SMS.
- Utforska kod som möjliggör GPT-slutföranden.
- Lär dig mer om vikten av snabbteknik och att inkludera regler i dina frågor.
Nu ska vi komma igång genom att experimentera med olika regler som kan användas för att generera e-post och SMS.
Använda gpt-slutförandefunktionen
I en tidigare övning startade du databasen, API:erna och programmet. Du har också uppdaterat
.env
filen. Om du inte har slutfört de här stegen följer du anvisningarna i slutet av övningen innan du fortsätter.Gå tillbaka till webbläsaren (http://localhost:4200) och välj Kontakta kunden på valfri rad i datagrid följt av Email/SMS-kund för att komma till skärmen Meddelandegenerator.
Detta använder Azure OpenAI för att konvertera meddelanderegler som du definierar till Email/SMS. Utför följande uppgifter:
Ange en regel som Order is delayed 5 days in the input (Order is delayed 5 days in the input) och välj knappen Generate Email/SMS Messages (Generera Email/SMS).
Ett ämne och en brödtext genereras för e-postmeddelandet och ett kort meddelande genereras för SMS:et.
Anteckning
Eftersom Azure Communication Services inte är aktiverat ännu kan du inte skicka e-postmeddelandet eller SMS:et.
Stäng dialogrutan e-post/SMS i webbläsaren. Nu när du har sett den här funktionen i praktiken ska vi titta på hur den implementeras.
Utforska koden för GPT-slutförande
Tips
Om du använder Visual Studio Code kan du öppna filer direkt genom att välja:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Skriv sedan namnet på den fil som du vill öppna.
Öppna filen server/apiRoutes.ts och leta upp
completeEmailSmsMessages
vägen. Det här API:et anropas av klientdelen av appen när knappen Generera Email/SMS har valts. Den hämtar värdena för användarprompt, företag och kontaktnamn från brödtexten och skickar dem tillcompleteEmailSMSMessages()
funktionen i filen server/openAI.ts . Resultatet returneras sedan till klienten.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); });
Öppna filen server/openAI.ts och leta upp
completeEmailSMSMessages()
funktionen .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; }
Den här funktionen har följande funktioner:
systemPrompt
används för att definiera att en AI-assistent som kan generera e-post och SMS krävs. InnehållersystemPrompt
även:- Regler för assistent att följa för att kontrollera tonen i meddelandena, start- och slutformatet, den maximala längden på SMS-meddelanden med mera.
- Information om data som ska ingå i svaret – ett JSON-objekt i det här fallet och endast ett JSON-objekt.
- Två kritiska regler upprepas igen längst ned i systemprompten för att undvika "recency bias".
userPrompt
används för att definiera de regler och kontaktnamn som slutanvändaren vill inkludera när e-postmeddelandet och SMS genereras. Regeln Order fördröjs 5 dagar som du angav tidigare ingår iuserPrompt
.- Funktionen anropar funktionen
callOpenAI()
som du utforskade tidigare för att generera slutförandet av e-post och SMS.
Gå tillbaka till webbläsaren uppdaterar du sidan och väljer Kontakta kunden på valfri rad följt av Email/SMS-kund för att komma till skärmen Meddelandegenerator igen.
Ange följande regler i meddelandegeneratorns indata:
- Ordern ligger före schemat.
- Säg till kunden att aldrig beställa från oss igen, vi vill inte ha deras verksamhet.
Välj Generera Email/SMS och notera meddelandet. Regeln
All messages should have a friendly tone and never use inappropriate language.
i systemprompten åsidosatte den negativa regeln i användarprompten.Gå tillbaka till server/openAI.ts* i redigeringsprogrammet och ta bort
All messages should have a friendly tone and never use inappropriate language.
regeln från promptencompleteEmailSMSMessages()
i funktionen. Spara filen.Gå tillbaka till generatorn för e-post/SMS-meddelanden i webbläsaren och kör samma regler igen:
- Ordern ligger före schemat.
- Säg till kunden att aldrig beställa från oss igen, vi vill inte ha deras verksamhet.
Välj Generera Email/SMS och lägg märke till meddelandet som returneras.
Vad händer i dessa scenarier? När du använder Azure OpenAI tillämpas innehållsfiltrering för att säkerställa att lämpligt språk alltid används. Om du använder OpenAI används regeln som definierats i systemprompten för att säkerställa att meddelandet som returneras är lämpligt.
Anteckning
Detta illustrerar vikten av att skapa dina frågor med rätt information och regler för att säkerställa att rätt resultat returneras. Läs mer om den här processen i introduktionen till teknisk dokumentation.
Ångra ändringarna du gjorde
systemPrompt
icompleteEmailSMSMessages()
, spara filen och kör den igen men användOrder is ahead of schedule.
bara regeln (inkludera inte den negativa regeln). Den här gången bör du se att e-postmeddelanden och SMS returneras som förväntat.Några sista saker att tänka på innan du går vidare till nästa övning:
- Det är viktigt att ha en människa i loopen för att granska genererade meddelanden. I det här exemplet returnerar Azure OpenAI-slutföranden föreslagna e-postmeddelanden och SMS, men användaren kan åsidosätta dem innan de skickas. Om du planerar att automatisera e-postmeddelanden är det viktigt att ha någon typ av mänsklig granskningsprocess för att säkerställa att godkända meddelanden skickas ut. Se AI som en andrepilot, inte en autopilot.
- Slutföranden är bara lika bra som de regler som du lägger till i prompten. Ta dig tid att testa dina frågor och slutföranden som returneras. Bjud in andra projektintressenter att granska slutförandena också.
- Du kan behöva inkludera kod efter bearbetning för att säkerställa att oväntade resultat hanteras korrekt.
- Använd systemprompter för att definiera de regler och den information som AI-assistent ska följa. Använd användarprompter för att definiera de regler och den information som slutanvändaren vill inkludera i slutförandena.
AI: Ta med dina egna data
Integreringen av Azure OpenAI Natural Language Processing (NLP) och slutförandefunktionerna ger en betydande potential för att förbättra användarproduktiviteten. Genom att använda lämpliga uppmaningar och regler kan en AI-assistent effektivt generera olika former av kommunikation, till exempel e-postmeddelanden, SMS med mera. Den här funktionen leder till ökad användareffektivitet och effektivare arbetsflöden.
Även om den här funktionen är ganska kraftfull på egen hand kan det finnas fall där användarna behöver generera slutföranden baserat på företagets anpassade data. Du kan till exempel ha en samling produkthandböcker som kan vara svåra för användarna att navigera när de hjälper kunder med installationsproblem. Alternativt kan du ha en omfattande uppsättning vanliga frågor och svar om sjukvårdsförmåner som kan visa sig vara utmanande för användarna att läsa igenom och få de svar de behöver. I dessa fall och många andra gör Azure OpenAI Service att du kan använda dina egna data för att generera slutföranden, vilket säkerställer ett mer skräddarsytt och kontextuellt korrekt svar på användarfrågor.
Här är en snabb översikt över hur funktionen "bring your own data" fungerar i Azure OpenAI-dokumentationen.
Anteckning
En av de viktigaste funktionerna i Azure OpenAI för dina data är möjligheten att hämta och använda data på ett sätt som förbättrar modellens utdata. Azure OpenAI för dina data, tillsammans med Azure Cognitive Search, avgör vilka data som ska hämtas från den avsedda datakällan baserat på användarindata och tillhandahållen konversationshistorik. Dessa data utökas sedan och skickas på nytt som en uppmaning till OpenAI-modellen, där hämtad information läggs till i den ursprungliga prompten. Även om hämtade data läggs till i prompten bearbetas de resulterande indata fortfarande av modellen som alla andra uppmaningar. När data har hämtats och prompten har skickats till modellen använder modellen den här informationen för att tillhandahålla ett slutförande.
I den här övningen kommer du att:
- Skapa en anpassad datakälla med Azure AI-Studio.
- Distribuera en inbäddningsmodell med Azure AI-Studio.
- Ladda upp anpassade dokument.
- Starta en chattsession i Chattlekplatsen för att experimentera med att generera slutföranden baserat på dina egna data.
- Utforska kod som använder Azure Cognitive Search och Azure OpenAI för att generera slutföranden baserat på dina egna data.
Nu ska vi komma igång genom att distribuera en inbäddningsmodell och lägga till en anpassad datakälla i Azure AI-Studio.
Lägga till en anpassad datakälla i Azure AI-Studio
Gå till Azure OpenAI Studio och logga in med autentiseringsuppgifter som har åtkomst till din Azure OpenAI-resurs.
Välj Distributioner på navigeringsmenyn .
Välj Skapa ny distribution och ange följande värden:
- Modell: text-embedding-ada-002.
- Modellversion: Standard.
- Distributionsnamn: text-embedding-ada-002.
När modellen har skapats väljer du Azure OpenAI på navigeringsmenyn för att gå till välkomstskärmen.
Leta upp panelen Bring your own data (Ta med egna data ) på välkomstskärmen och välj Prova nu.
Välj Ladda upp filer i listrutan Välj datakälla .
Under listrutan Välj Azure Blob Storage-resurs väljer du Skapa en ny Azure Blob Storage-resurs.
Då kommer du till Azure Portal där du kan utföra följande uppgifter:
- Ange ett unikt namn för lagringskontot, till exempel byodstorage[Ditt efternamn].
- Välj en region som ligger nära din plats.
- Välj Granska följt av Skapa.
När bloblagringsresursen har skapats går du tillbaka till dialogrutan Azure AI-Studio och väljer den nya bloblagringsresursen i listrutan Välj Azure Blob Storage-resurs. Om du inte ser den i listan väljer du uppdateringsikonen bredvid listrutan.
Resursdelning mellan ursprung (CORS) måste aktiveras för att ditt lagringskonto ska kunna nås. Välj Aktivera CORS i dialogrutan Azure AI-Studio.
Under listrutan Välj Azure Cognitive Search resurs väljer du Skapa en ny Azure Cognitive Search resurs.
Detta tar dig tillbaka till Azure Portal där du kan utföra följande uppgifter:
- Ange ett unikt namn för Cognitive Search-resursen, till exempel byodsearch[Ditt efternamn].
- Välj en region som ligger nära din plats.
- I avsnittet Prisnivå väljer du Ändra prisnivå och sedan Basic följt av Välj. Den kostnadsfria nivån stöds inte, så du rensar cognitive search-resursen i slutet av den här självstudien.
- Välj Granska följt av Skapa.
När cognitive search-resursen har skapats går du till resursens översiktssida och kopierar URL-värdet till en lokal fil.
Välj Nycklar i den vänstra navigeringsmenyn och kopiera värdet primär administratörsnyckel till en lokal fil. Du behöver dessa värden senare i övningen.
Välj Semantic ranker i den vänstra navigeringsmenyn och se till att Kostnadsfri är valt.
Anteckning
Om du vill kontrollera om semantisk ranker är tillgängligt i en viss region kontrollerar du sidan Tillgängliga produkter per region på Azure-webbplatsen för att se om din region visas.
Gå tillbaka till dialogrutan Azure AI-Studio Lägg till data och välj din nyligen skapade sökresurs i listrutan Välj Azure Cognitive Search resurs. Om du inte ser den i listan väljer du uppdateringsikonen bredvid listrutan.
Ange ett värde för byod-search-index för värdet Ange indexnamn .
Markera kryssrutan Lägg till vektorsökning i den här sökresursen .
I listrutan Välj en inbäddningsmodell väljer du modellen text-embedding-ada-002 som du skapade tidigare.
Markera kryssrutan följt av Nästa.
I dialogrutan Ladda upp filer väljer du Bläddra efter en fil.
Gå till mappen kunddokument för projektet (som finns i projektets rot) och välj följande filer:
- Klocka A102 Installation Instructions.docx
- Företagets FAQs.docx
Anteckning
Den här funktionen stöder för närvarande följande filformat för att skapa lokala index: .txt, .md, .html, .pdf, .docx och .pptx.
Välj Ladda upp filer. Filerna laddas upp till en container för fileupload-byod-search-index i bloblagringsresursen som du skapade tidigare.
Välj Nästa för att gå till dialogrutan Datahantering .
I listrutan Söktyp väljer du Hybrid + semantik.
Anteckning
Det här alternativet ger stöd för nyckelords- och vektorsökning. När resultaten har returnerats tillämpas en sekundär rankningsprocess på resultatuppsättningen med hjälp av djupinlärningsmodeller som förbättrar sökrelevansen för användaren. Mer information om semantisk sökning finns i semantisk sökning i Azure Cognitive Search dokumentation.
Markera kryssrutorna för att bekräfta kostnaderna för att använda semantisk sökning och vektorinbäddningar.
Välj Nästa, granska informationen och välj Spara och stäng.
Nu när dina anpassade data har laddats upp indexeras data och är tillgängliga för användning i Chattlekplatsen. Den här processen kan ta ett par minuter. När det är klart fortsätter du till nästa avsnitt.
Använda din anpassade datakälla i Chat Playground
Leta upp avsnittet Chattsession på sidan i Azure AI-Studio och ange följande användarmeddelande:
What safety rules are required to install a clock?
Du bör se ett resultat som liknar följande som visas:
Expandera avsnittet 1 referenser i chattsvaret och observera att filen Clock A102 Installation Instructions.docx visas och att du kan välja den för att visa dokumentet.
Ange följande användarmeddelande:
What should I do to mount the clock on the wall?
Du bör se ett resultat som liknar följande som visas:
Nu ska vi experimentera med dokumentet Vanliga frågor och svar om företag. Ange följande text i fältet Användarmeddelande :
What is the company's policy on vacation time?
Du bör se att ingen information hittades för den begäran.
Ange följande text i fältet Användarmeddelande :
How should I handle refund requests?
Du bör se ett resultat som liknar följande som visas:
Expandera avsnittet 1 referenser i chattsvaret och observera att filen Company FAQs.docx visas och att du kan välja den för att visa dokumentet.
Välj Visa kod överst i avsnittet Chattsession .
Observera att du kan växla mellan olika språk, visa slutpunkten och komma åt slutpunktens nyckel. Stäng dialogrutan Exempelkod .
Aktivera växlingsknappen Visa rå JSON i *Chat-sessionen. Observera att chattsessionen börjar med ett meddelande som liknar följande:
{ "role": "system", "content": "You are an AI assistant that helps people find information." }
Nu när du har skapat en anpassad datakälla och experimenterat med den i Chattlekplatsen ska vi se hur du kan använda den i projektets program.
Använda funktionen Bring Your Own Data i programmet
Gå tillbaka till projektet i Visual Studio Code och öppna .env-filen. Uppdatera följande värden med cognitive services-slutpunkten, nyckeln och indexnamnet. Du kopierade slutpunkten och nyckeln till en lokal fil tidigare i den här övningen.
AZURE_COGNITIVE_SEARCH_ENDPOINT=<COGNITIVE_SERVICES_ENDPOINT_VALUE> AZURE_COGNITIVE_SEARCH_KEY=<COGNITIVE_SERVICES_KEY_VALUE> AZURE_COGNITIVE_SEARCH_INDEX=byod-search-index
I en tidigare övning startade du databasen, API:erna och programmet. Du har också uppdaterat
.env
filen. Om du inte slutförde de här stegen följer du anvisningarna i slutet av den tidigare övningen innan du fortsätter.När programmet har lästs in i webbläsaren väljer du ikonen Chatthjälp längst upp till höger i programmet.
Följande text bör visas i chattdialogrutan:
How should I handle refund requests?
Välj knappen Hämta hjälp . Du bör se resultat som returneras från dokumentet Company FAQs.docx som du laddade upp tidigare i Azure AI-Studio. Om du vill läsa igenom dokumentet kan du hitta det i mappen kunddokument i projektets rot.
Ändra texten till följande och välj knappen Hämta hjälp :
What safety rules are required to install a clock?
Du bör se resultat som returneras från dokumentet Clock A102 Installation Instructions.docx som du laddade upp tidigare i Azure AI-Studio. Det här dokumentet är också tillgängligt i mappen kunddokument i projektets rot.
Utforska koden
Tips
Om du använder Visual Studio Code kan du öppna filer direkt genom att välja:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Skriv sedan namnet på den fil som du vill öppna.
Gå tillbaka till projektets källkod i Visual Studio Code.
Öppna filen server/apiRoutes.ts och leta upp
completeBYOD
vägen. Det här API:et anropas när knappen Hämta hjälp väljs i dialogrutan Chatthjälp. Den hämtar användarprompten från begärandetexten och skickar dencompleteBYOD()
till funktionen i filen server/openAI.ts . Resultatet returneras sedan till klienten.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); });
Öppna filen server/openAI.ts och leta upp
completeBYOD()
funktionen.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); }
Den här funktionen har följande funktioner:
- Parametern
userPrompt
innehåller den information som användaren skrev i chatthjälpdialogrutan. - variabeln
systemPrompt
definierar att en AI-assistent som är utformad för att hjälpa människor att hitta information kommer att användas. callOpenAI()
används för att anropa Azure OpenAI API och returnera resultatet. Den skickarsystemPrompt
värdena ochuserPrompt
samt följande parametrar:temperature
- Mängden kreativitet som ska ingå i svaret. Användaren behöver konsekventa (mindre kreativa) svar i det här fallet så värdet är inställt på 0.useBYOD
– Ett booleskt värde som anger om cognitive search ska användas tillsammans med Azure OpenAI eller inte. I det här fallet är det inställt på så atttrue
Cognitive Search-funktioner används.
- Parametern
Funktionen
callOpenAI()
accepterar enuseBYOD
parameter som används för att avgöra vilken OpenAI-funktion som ska anropas. I det här fallet angesuseBYOD
dengetAzureOpenAIBYODCompletion()
till så atttrue
funktionen anropas.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()
Leta upp funktionen i server/openAI.ts. Det liknar dengetAzureOpenAICompletion()
funktion som du undersökte tidigare, men visas som en separat funktion för att markera några viktiga skillnader som är unika för scenariot "Bring Your Own Data" som är tillgängligt i Azure OpenAI.Värdet
fetchUrl
innehåller ettextensions
segment i URL:en medan URL:en för standard-API:et för Azure OpenAI inte gör det.const fetchUrl = `${OPENAI_ENDPOINT}/openai/deployments/${OPENAI_MODEL}/extensions/chat/completions?api-version=${OPENAI_API_VERSION}`;
En
dataSources
egenskap läggs till i objektet sommessageData
skickas till Azure OpenAI. EgenskapendataSources
innehåller cognitive search-resursensendpoint
,key
ochindexName
värden som lades till i filen tidigare i den här övningen.env
.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 } } ] };
Objektet
headersBody
innehållerchatpgpt_url
ochchatgpt_key
egenskaper som används för att anropa Azure OpenAI när Cognitive Search-resultaten har hämtats.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), };
Svaret som returneras av Azure OpenAI innehåller två problem med roller för
tool
ochassistant
. Exempelprogrammet använder det andra meddelandet med ettrole
avassistant
för att ge användaren den information som de begärde. Om du vill ange ytterligare information om de dokument som används för att skapa svaret (som du såg tidigare i Azure AI-Studio playground) kan du använda det första meddelandet som innehållerurl
till dokumenten.{ "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 } ] } ] }
Följande kod används i
getAzureOpenAIBYODCompletion()
för att komma åt meddelandena. Även om citat inte används i det här exemplet loggas de till konsolen så att du kan se vilken typ av data som returneras.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;
Några sista saker att tänka på innan du går vidare till nästa övning:
- Funktionen "Bring Your Own Data" i Azure OpenAI är för närvarande i förhandsversion. Vi rekommenderar inte att du använder det i produktionsprogram just nu.
- Exempelprogrammet använder ett enda index i Azure Cognitive Search. Du kan använda flera index och datakällor med Azure OpenAI. Egenskapen
dataSources
i funktionen kan uppdateras så att dengetAzureOpenAIBYODCompletion()
innehåller flera datakällor efter behov. - Säkerheten måste utvärderas noggrant med den här typen av scenario. Användarna ska inte kunna ställa frågor och få resultat från dokument som de inte kan komma åt.
Nu när du har lärt dig om Azure OpenAI, frågor, slutföranden och hur du kan använda dina egna data går vi vidare till nästa övning för att lära dig hur kommunikationsfunktioner kan användas för att förbättra programmet. Om du vill veta mer om Azure OpenAI kan du visa utbildningsinnehållet Kom igång med Azure OpenAI-tjänsten . Ytterligare information om hur du använder dina egna data med Azure OpenAI finns i Azure OpenAI i din datadokumentation .
Kommunikation: Skapa en Azure Communication Services resurs
Effektiv kommunikation är viktigt för lyckade anpassade affärsprogram. Med hjälp av Azure Communication Services (ACS) kan du lägga till funktioner som telefonsamtal, livechatt, ljud-/videosamtal samt e-post och SMS i dina program. Tidigare har du lärt dig hur Azure OpenAI kan generera slutföranden för e-post och SMS. Nu får du lära dig hur du skickar meddelandena. Tillsammans kan ACS och OpenAI förbättra dina program genom att förenkla kommunikationen, förbättra interaktionerna och öka affärsproduktiviteten.
I den här övningen kommer du att:
- Skapa en Azure Communication Services resurs (ACS).
- Lägg till ett avgiftsfritt telefonnummer med samtals- och SMS-funktioner.
- Anslut en e-postdomän.
- Uppdatera projektets .env-fil med värden från ACS-resursen.
Skapa en Azure Communication Services resurs
Besök Azure Portal i webbläsaren och logga in om du inte redan har gjort det.
Skriv kommunikationstjänster i sökfältet överst på sidan och välj Kommunikationstjänster bland de alternativ som visas.
Välj Skapa i verktygsfältet.
Utför följande uppgifter:
- Välj din Azure-prenumeration.
- Välj den resursgrupp som ska användas (skapa en ny om den inte finns).
- Ange ett ACS-resursnamn. Det måste vara ett unikt värde.
- Välj en dataplats.
Välj Granska + skapa följt av Skapa.
Du har skapat en ny Azure Communication Services resurs! Därefter aktiverar du funktioner för telefonsamtal och SMS. Du ansluter också en e-postdomän till resursen.
Aktivera funktioner för telefonsamtal och SMS
Lägg till ett telefonnummer och se till att telefonnumret har samtalsfunktioner aktiverade. Du använder det här telefonnumret för att ringa till en telefon från appen.
Välj
Phone numbers
på menyn Resurs.Välj
+ Get
i verktygsfältet (eller välj knappen Hämta ett nummer ) och ange följande information:- Land eller region:
United States
- Användningsfall: Välj
An application will be making calls or sending SMS mesages
- Nummertyp: Avgiftsfritt
Anteckning
Ett kreditkort krävs för din Azure-prenumeration för att skapa det avgiftsfria numret. Om du inte har ett kort i filen kan du hoppa över att lägga till ett telefonnummer och gå vidare till nästa avsnitt i övningen som ansluter en e-postdomän. Du kan fortfarande använda appen, men kan inte ringa till ett telefonnummer.
- Samtal:
Make calls
- SMS:
Send and receive SMS
- Land eller region:
Välj Nästa: Tal.
Välj ett prefix (till exempel
877
) och lämna Kvantitet på 1. Välj Sök.När ett avgiftsfritt nummer visas väljer du Nästa: Sammanfattning.
Granska informationen och välj Placera beställning för att lägga till telefonnumret till din ACS-resurs.
När telefonnumret har skapats väljer du det för att gå till panelen Funktioner . Kontrollera att följande värden har angetts:
- I avsnittet Samtal väljer du
Make calls
. - I sms-avsnittet väljer du
Send and receive SMS
. - Välj Spara.
- I avsnittet Samtal väljer du
Kopiera värdet för telefonnummer till en fil för senare användning.
Ansluta en Email domän
Utför följande uppgifter för att skapa en ansluten e-postdomän för din ACS-resurs så att du kan skicka e-post. Detta används för att skicka e-post från appen.
- Välj Domäner på menyn Resurs.
- Välj Anslut domän i verktygsfältet.
- Välj din prenumeration och resursgrupp.
- Under listrutan Email Service väljer du
Add an email service
. - Ge e-posttjänsten ett namn, till exempel
acs-demo-email-service
. - Välj
Review + create
följt avCreate
. - När distributionen är klar väljer du
Go to resource
och väljer1-click add
för att lägga till en kostnadsfri Azure-underdomän. - När underdomänen har lagts till (det tar en stund att distribuera) väljer du den.
- När du är på skärmen AzureManagedDomain väljer du E-postFrån adresser på resursmenyn.
- Kopiera värdet MailFrom till en fil. Du kommer att använda den senare när du uppdaterar .env-filen .
- Gå tillbaka till din Azure Communication Services resurs och välj
Domains
på menyn Resurs. - Välj
Add domain
och angeMailFrom
värdet från föregående steg (se till att du väljer rätt prenumeration, resursgrupp och e-posttjänst). Välj knappenConnect
.
.env
Uppdatera filen
Nu när ditt ACS-telefonnummer (med samtal och SMS aktiverat) och e-postdomänen är klara uppdaterar du följande nycklar/värden i .env-filen i projektet:
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
: Värdetconnection string
från avsnittet Nycklar i acs-resursen.ACS_PHONE_NUMBER
: Tilldela ditt avgiftsfria nummer till värdetACS_PHONE_NUMBER
.ACS_EMAIL_ADDRESS
: Tilldela e-postadressvärdet "MailTo".CUSTOMER_EMAIL_ADDRESS
: Tilldela en e-postadress som du vill att e-post ska skickas till från appen (eftersom kunddata i appens databas endast är exempeldata). Du kan använda en personlig e-postadress.CUSTOMER_PHONE_NUMBER
: Du måste ange ett USA baserat telefonnummer (från och med idag) på grund av ytterligare verifiering som krävs i andra länder för att skicka SMS. Om du inte har ett USA-baserat nummer kan du lämna det tomt.
Starta/starta om programmet och API-servrarna
Utför något av följande steg baserat på de övningar som du har slutfört fram tills nu:
Om du startade databasen, API-servern och webbservern i en tidigare övning måste du stoppa API-servern och webbservern och starta om dem för att hämta filändringarna i .env . Du kan låta databasen köras.
Leta upp terminalfönstren som kör API-servern och webbservern och tryck på CTRL + C för att stoppa dem. Starta dem igen genom att
npm start
skriva i varje terminalfönster och trycka på Retur. Fortsätt till nästa övning.Om du inte har startat databasen, API-servern och webbservern ännu utför du följande steg:
I följande steg skapar du tre terminalfönster i Visual Studio Code.
Högerklicka på .env-filen i Visual Studio Code-fillistan och välj Öppna i integrerad terminal. Kontrollera att terminalen finns i roten för projektet – openai-acs-msgraph – innan du fortsätter.
Välj något av följande alternativ för att starta PostgreSQL-databasen:
Om du har Docker Desktop installerat och igång kör
docker-compose up
du i terminalfönstret och trycker på Retur.Om du har Podman med podman-compose installerat och igång kör
podman-compose up
du i terminalfönstret och trycker på Retur.Kör PostgreSQL-containern direkt med antingen Docker Desktop, Podman, nerdctl eller en annan containerkörning som du har installerat genom att köra följande kommando i terminalfönstret:
Mac, Linux eller Windows-undersystem för Linux (WSL):
[docker | podman | nerdctl] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v $(pwd)/data:/var/lib/postgresql/data -p 5432:5432 postgres
Windows med PowerShell:
[docker | podman] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v ${PWD}/data:/var/lib/postgresql/data -p 5432:5432 postgres
När databascontainern startar trycker du på + ikonen i Visual Studio Code-terminalens verktygsfält för att skapa ett andra terminalfönster.
cd
i mappen server/typescript och kör följande kommandon för att installera beroendena och starta API-servern.npm install
npm start
Tryck på + ikonen igen i Visual Studio Code-terminalens verktygsfält för att skapa ett tredje terminalfönster.
cd
i klientmappen och kör följande kommandon för att installera beroendena och starta webbservern.npm install
npm start
En webbläsare startas och du kommer till http://localhost:4200.
Kommunikation: Ringa ett telefonsamtal
Integreringen av Azure Communication Services telefonsamtalsfunktioner i ett anpassat verksamhetsspecifikt program erbjuder flera viktiga fördelar för företag och deras användare:
- Möjliggör sömlös och realtidskommunikation mellan anställda, kunder och partner direkt från LOB-programmet, vilket eliminerar behovet av att växla mellan flera plattformar eller enheter.
- Förbättrar användarupplevelsen och förbättrar den övergripande drifteffektiviteten.
- Underlättar snabb problemlösning eftersom användarna snabbt kan ansluta till relevanta supportteam eller ämnesexperter snabbt och enkelt.
I den här övningen kommer du att:
- Utforska telefonsamtalsfunktionen i programmet.
- Gå igenom koden för att lära dig hur telefonsamtalsfunktionen skapas.
Använda funktionen Telefonsamtal
I föregående övning skapade du en Azure Communication Services resurs (ACS) och startade databasen, webbservern och API-servern. Du har också uppdaterat följande värden i .env-filen .
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>
Kontrollera att du har slutfört föregående övning innan du fortsätter.
Gå tillbaka till webbläsaren (http://localhost:4200), leta upp datagrid och välj Kontakta kund följt av Ring kund på den första raden.
En telefonsamtalskomponent läggs till i rubriken. Ange ditt telefonnummer (se till att det börjar med + och innehåller landskoden) och välj Ring. Du uppmanas att tillåta åtkomst till mikrofonen.
Välj Lägg på för att avsluta samtalet. Välj Stäng för att stänga samtalskomponenten.
Utforska telefonsamtalskoden
Tips
Om du använder Visual Studio Code kan du öppna filer direkt genom att välja:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Skriv sedan namnet på den fil som du vill öppna.
Öppna filen customers-list.component.ts . Den fullständiga sökvägen till filen är client/src/app/customers-list/customers-list.component.ts.
Observera att
openCallDialog()
skickar ettCustomerCall
meddelande och kundens telefonnummer med hjälp av en händelsebuss.openCallDialog(data: Phone) { this.eventBus.emit({ name: Events.CustomerCall, value: data }); }
Anteckning
Händelsebusskoden finns i filen eventbus.service.ts om du vill utforska den mer. Den fullständiga sökvägen till filen är client/src/app/core/eventbus.service.ts.
Huvudkomponentens
ngOnInit()
funktion prenumererar på händelsenCustomerCall
som skickas av händelsebussen och visar samtalskomponenten. Du hittar den här koden i 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 }) ); }
Öppna phone-call.component.ts. Ta en stund att visa koden. Den fullständiga sökvägen till filen är client/src/app/phone-call/phone-call.component.ts. Observera följande viktiga funktioner:
- Hämtar en Azure Communication Services åtkomsttoken genom att
acsService.getAcsToken()
anropa funktionen ingOnInit()
; - Lägger till en "telefonuppringare" på sidan. Du kan se uppringaren genom att klicka på telefonnummerinmatningen i rubriken.
- Startar och avslutar ett anrop med hjälp av
startCall()
funktionerna ochendCall()
.
- Hämtar en Azure Communication Services åtkomsttoken genom att
Innan vi tittar på koden som ringer telefonsamtalet ska vi undersöka hur ACS-åtkomsttoken hämtas och hur telefonsamtalsobjekt skapas.
ngOnInit()
Leta upp funktionen i 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); }) ); } }
Den här funktionen utför följande åtgärder:
- Hämtar ett ACS userId och en åtkomsttoken genom att
acsService.getAcsToken()
anropa funktionen. - När åtkomsttoken har hämtats utför koden följande åtgärder:
- Skapar en ny instans av
CallClient
ochAzureCommunicationTokenCredential
använder åtkomsttoken. - Skapar en ny instans av
CallAgent
att använda objektenCallClient
ochAzureCommunicationTokenCredential
. Senare ser du attCallAgent
används för att starta och avsluta ett anrop.
- Skapar en ny instans av
- Hämtar ett ACS userId och en åtkomsttoken genom att
Öppna acs.services.ts och leta upp
getAcsToken()
funktionen. Den fullständiga sökvägen till filen är client/src/app/core/acs.service.ts. Funktionen gör en HTTP GET-begäran till den väg som/acstoken
exponeras av API-servern.getAcsToken(): Observable<AcsUser> { return this.http.get<AcsUser>(this.apiUrl + 'acstoken') .pipe( catchError(this.handleError) ); }
En API-serverfunktion med namnet
createACSToken()
hämtar userId och åtkomsttoken och returnerar den till klienten. Den finns i filen 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 }; }
Den här funktionen utför följande åtgärder:
- Kontrollerar om ett ACS-värde
connectionString
är tillgängligt. Annars returnerar ett objekt med ett tomtuserId
ochtoken
. - Skapar en ny instans av
CommunicationIdentityClient
och skickarconnectionString
värdet till den. - Skapar en ny användare med .
tokenClient.createUser()
- Hämtar en token för den nya användaren med "voip"-omfånget med .
tokenClient.getToken()
- Returnerar ett objekt som innehåller
userId
värdena ochtoken
.
- Kontrollerar om ett ACS-värde
Nu när du har sett hur userId och token hämtas går du tillbaka till
phone-call.component.ts
och letar uppstartCall()
funktionen.Den här funktionen anropas när Samtal väljs i telefonsamtalskomponenten. Det använder objektet
CallAgent
som nämndes tidigare för att starta ett anrop. FunktionencallAgent.startCall()
accepterar ett objekt som representerar numret som ska anropas och det ACS-telefonnummer som används för att ringa samtalet.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; }
Funktionen
stopCall()
anropas när Hang Up väljs i telefonsamtalskomponenten.endCall() { if (this.call) { this.call.hangUp({ forEveryone: true }); this.call = undefined; this.inCall = false; } else { this.hangup.emit(); } }
Om ett anrop pågår
call.hangUp()
anropas funktionen för att avsluta anropet. Om inget samtal pågårhangup
skickas händelsen till huvudkomponenten för att dölja telefonsamtalskomponenten.Innan vi går vidare till nästa övning ska vi gå igenom de viktigaste begreppen som beskrivs i den här övningen:
- Ett ACS-userId och en åtkomsttoken hämtas från API-servern med hjälp av
acsService.getAcsToken()
funktionen . - Token används för att skapa ett
CallClient
och-objektCallAgent
. - Objektet
CallAgent
används för att starta och avsluta ett anrop genom att anropacallAgent.startCall()
funktionerna ochcallAgent.hangUp()
.
- Ett ACS-userId och en åtkomsttoken hämtas från API-servern med hjälp av
Nu när du har lärt dig hur telefonsamtal kan integreras i ett program ska vi fokusera på att använda Azure Communication Services för att skicka e-post och SMS.
Kommunikation: Skicka Email och SMS
Förutom telefonsamtal kan Azure Communication Services även skicka e-post och SMS. Detta kan vara användbart när du vill skicka ett meddelande till en kund eller en annan användare direkt från programmet.
I den här övningen kommer du att:
- Utforska hur e-postmeddelanden och SMS kan skickas från programmet.
- Gå igenom koden för att lära dig hur e-post- och SMS-funktionen implementeras.
Använda Email- och SMS-funktionerna
I en tidigare övning skapade du en Azure Communication Services-resurs (ACS) och startade databasen, webbservern och API-servern. Du har också uppdaterat följande värden i .env-filen .
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>
Kontrollera att du har slutfört övningen innan du fortsätter.
Gå tillbaka till webbläsaren (http://localhost:4200) och välj Kontakta kund följt av Email/SMS-kund på den första raden.
Välj fliken Email/SMS och utför följande uppgifter:
- Ange ett Email ämne och brödtext och välj knappen Skicka Email.
- Ange ett SMS och välj knappen Skicka SMS .
Kontrollera att du har fått e-postmeddelandet och SMS:et. Som en påminnelse skickas e-postmeddelandet till det värde som definierats för
CUSTOMER_EMAIL_ADDRESS
och SMS-meddelandet skickas till det värde som definierats förCUSTOMER_PHONE_NUMBER
i .env-filen . Om du inte kunde ange ett USA baserat telefonnummer som ska användas för SMS kan du hoppa över det steget.Anteckning
Om du inte ser e-postmeddelandet i inkorgen för den adress som du har definierat för
CUSTOMER_EMAIL_ADDRESS
i .env-filen kontrollerar du skräppostmappen.
Utforska Email Code
Tips
Om du använder Visual Studio Code kan du öppna filer direkt genom att välja:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Skriv sedan namnet på den fil som du vill öppna.
Öppna filen customers-list.component.ts . Den fullständiga sökvägen till filen är client/src/app/customers-list/customers-list.component.ts.
När du valde Kontakta kund följt av Email/SMS-kund i datagrid visade komponenten
customer-list
en dialogruta. Detta hanteras avopenEmailSmsDialog()
funktionen i customer-list.component.ts-filen .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.'); } }
Funktionen
openEmailSmsDialog()
utför följande uppgifter:- Kontrollerar om objektet
data
(som representerar raden från datagrid) innehåller enphone
och-egenskapemail
. Om den gör det skapas ettdialogData
objekt som innehåller den information som ska skickas till dialogrutan. EmailSmsDialogComponent
Öppnar dialogrutan och skickardialogData
objektet till den.- Prenumererar på
afterClosed()
händelsen i dialogrutan. Den här händelsen utlöses när dialogrutan stängs. Objektetresponse
innehåller den information som angavs i dialogrutan.
- Kontrollerar om objektet
Öppna filen email-sms-dialog.component.ts . Den fullständiga sökvägen till filen är client/src/app/email-sms-dialog/email-sms-dialog.component.ts.
sendEmail()
Leta upp funktionen: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 } }
Funktionen
sendEmail()
utför följande uppgifter:- Kontrollerar om funktionsflaggan är inställd på
acsEmailEnabled
true
. Den här flaggan kontrollerar omACS_EMAIL_ADDRESS
miljövariabeln har ett tilldelat värde. - Om
acsEmailEnabled
är santacsService.sendEmail()
anropas funktionen och e-postmeddelandets ämne, brödtext, kundnamn och kundens e-postadress skickas. Eftersom databasen innehåller exempeldataCUSTOMER_EMAIL_ADDRESS
används miljövariabeln i stället förthis.data.email
. I ett verkligt programthis.data.email
skulle värdet användas. - Prenumererar på
sendEmail()
funktionen iacsService
tjänsten. Den här funktionen returnerar en RxJS-observerbar som innehåller svaret från klienttjänsten. - Om e-postmeddelandet
emailSent
har skickats är egenskapen inställd påtrue
.
- Kontrollerar om funktionsflaggan är inställd på
För att ge bättre kodkapsling och återanvändning används tjänster på klientsidan, till exempel acs.service.ts i hela programmet. Detta gör att alla ACS-funktioner kan konsolideras till en enda plats.
Öppna acs.service.ts och leta upp
sendEmail()
funktionen. Den fullständiga sökvägen till filen är 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) ); }
Funktionen
sendEmail()
iAcsService
utför följande uppgifter:http.post()
Anropar funktionen och skickar e-postämnet, meddelandet, kundnamnet och kundens e-postadress till den. Funktionenhttp.post()
returnerar en RxJS-observerbar som innehåller svaret från API-anropet.- Hanterar eventuella fel som returneras av
http.post()
funktionen med RxJS-operatorncatchError
.
Nu ska vi undersöka hur programmet interagerar med ACS-e-postfunktionen. Öppna filen acs.ts och leta upp
sendEmail()
funktionen. Den fullständiga sökvägen till filen är server/typescript/acs.ts.Funktionen
sendEmail()
utför följande uppgifter:Skapar ett nytt
EmailClient
objekt och skickar ACS-anslutningssträng till det (det här värdet hämtas frånACS_CONNECTION_STRING
miljövariabeln).const emailClient = new EmailClient(connectionString);
Skapar ett nytt
EmailMessage
objekt och skickar avsändar-, ämnes-, meddelande- och mottagarinformation.const msgObject: EmailMessage = { senderAddress: process.env.ACS_EMAIL_ADDRESS as string, content: { subject: subject, plainText: message, }, recipients: { to: [ { address: customerEmailAddress, displayName: customerName, }, ], }, };
Skickar e-postmeddelandet med funktionen
emailClient.beginSend()
och returnerar svaret. Även om funktionen bara skickar till en mottagare i det här exempletbeginSend()
kan funktionen även användas för att skicka till flera mottagare.const poller = await emailClient.beginSend(msgObject);
poller
Väntar på att objektet ska signalera att det är klart och skickar svaret till anroparen.
Utforska SMS-koden
Gå tillbaka till den email-sms-dialog.component.ts fil som du öppnade tidigare. Den fullständiga sökvägen till filen är client/src/app/email-sms-dialog/email-sms-dialog.component.ts.
sendSms()
Leta upp funktionen: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; } }
Funktionen
sendSMS()
utför följande uppgifter:- Kontrollerar om funktionsflaggan är inställd på
acsPhoneEnabled
true
. Den här flaggan kontrollerar omACS_PHONE_NUMBER
miljövariabeln har ett tilldelat värde. - Om
acsPhoneEnabled
är santacsService.SendSms()
anropas funktionen och SMS-meddelandet och kundens telefonnummer skickas. Eftersom databasen innehåller exempeldataCUSTOMER_PHONE_NUMBER
används miljövariabeln i stället förthis.data.customerPhoneNumber
. I ett verkligt programthis.data.customerPhoneNumber
skulle värdet användas. - Prenumererar på
sendSms()
funktionen iacsService
tjänsten. Den här funktionen returnerar en RxJS-observerbar som innehåller svaret från klienttjänsten. - Om SMS-meddelandet har skickats ställs egenskapen in på
smsSent
true
.
- Kontrollerar om funktionsflaggan är inställd på
Öppna acs.service.ts och leta upp
sendSms()
funktionen. Den fullständiga sökvägen till filen är 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) ); }
Funktionen
sendSms()
utför följande uppgifter:http.post()
Anropar funktionen och skickar meddelandet och kundens telefonnummer till den. Funktionenhttp.post()
returnerar en RxJS-observerbar som innehåller svaret från API-anropet.- Hanterar eventuella fel som returneras av
http.post()
funktionen med RxJS-operatorncatchError
.
Slutligen ska vi undersöka hur programmet interagerar med ACS SMS-funktionen. Öppna filen acs.ts . Den fullständiga sökvägen till filen är server/typescript/acs.ts och leta upp
sendSms()
funktionen.Funktionen
sendSms()
utför följande uppgifter:Skapar ett nytt
SmsClient
objekt och skickar ACS-anslutningssträng till det (det här värdet hämtas frånACS_CONNECTION_STRING
miljövariabeln).const smsClient = new SmsClient(connectionString);
smsClient.send()
Anropar funktionen och skickar ACS-telefonnumret (from
), kundens telefonnummer (to
) och SMS:et:const sendResults = await smsClient.send({ from: process.env.ACS_PHONE_NUMBER as string, to: [customerPhoneNumber], message: message }); return sendResults;
Returnerar svaret till anroparen.
Du kan läsa mer om ACS-e-post och SMS-funktioner i följande artiklar:
Innan vi går vidare till nästa övning ska vi gå igenom de viktigaste begreppen som beskrivs i den här övningen:
- Den acs.service.ts filen kapslar in ACS-e-post- och SMS-funktionerna som används av programmet på klientsidan. Den hanterar API-anropen till servern och returnerar svaret till anroparen.
- API:et på serversidan använder ACS
EmailClient
ochSmsClient
objekt för att skicka e-post och SMS.
Nu när du har lärt dig hur e-postmeddelanden och SMS kan skickas ska vi fokusera på att integrera organisationsdata i programmet.
Organisationsdata: Skapa en Microsoft Entra ID appregistrering
Förbättra användarproduktiviteten genom att integrera organisationsdata (e-post, filer, chattar och kalenderhändelser) direkt i dina anpassade program. Genom att använda Microsoft Graph-API:er och Microsoft Entra ID kan du smidigt hämta och visa relevanta data i dina appar, vilket minskar användarnas behov av att byta kontext. Oavsett om det handlar om att referera till ett e-postmeddelande som skickas till en kund, granska ett Teams-meddelande eller komma åt en fil kan användarna snabbt hitta den information de behöver utan att lämna din app, vilket effektiviserar deras beslutsprocess.
I den här övningen kommer du att:
- Skapa en Microsoft Entra ID appregistrering så att Microsoft Graph kan komma åt organisationsdata och föra in dem i appen.
- Leta upp
team
ochchannel
ID:t från Microsoft Teams som behövs för att skicka chattmeddelanden till en specifik kanal. - Uppdatera projektets .env-fil med värden från din Microsoft Entra ID appregistrering.
Skapa en Microsoft Entra ID appregistrering
Gå till Azure Portal och välj Microsoft Entra ID.
Välj fliken Appregistrering följt av + Ny registrering.
Fyll i den nya appregistreringsformulärinformationen enligt nedan och välj Registrera:
- Namn: microsoft-graph-app
- Kontotyper som stöds: Konton i alla organisationskataloger (alla Microsoft Entra ID klientorganisation – flera klientorganisationer)
- Omdirigerings-URI:
- Välj Ensidesprogram (SPA) och ange
http://localhost:4200
i fältet Omdirigerings-URI .
- Välj Ensidesprogram (SPA) och ange
- Välj Registrera för att skapa appregistreringen.
Välj Översikt på resursmenyn och kopiera värdet
Application (client) ID
till Urklipp.
Uppdatera projektets .env-fil
Öppna .env-filen i redigeringsprogrammet och tilldela
Application (client) ID
värdet tillENTRAID_CLIENT_ID
.ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
Om du vill aktivera möjligheten att skicka ett meddelande från appen till en Teams-kanal loggar du in på Microsoft Teams med ditt Microsoft 365 dev-klientkonto.
När du är inloggad expanderar du ett team och hittar en kanal som du vill skicka meddelanden till från appen. Du kan till exempel välja företagsteamet och kanalen Allmänt (eller vilket team/vilken kanal du vill använda).
I teamrubriken klickar du på de tre punkterna (...) och väljer
Get link to team
.I länken som visas i popup-fönstret är team-ID:t strängen med bokstäver och siffror efter
team/
. I länken "https://teams.microsoft.com/l/team/19%3ae9b9.../"är team-ID :t till exempel 19%3ae9b9... upp till följande/
tecken.Kopiera team-ID:t och tilldela det till
TEAM_ID
i .env-filen .I kanalrubriken klickar du på de tre punkterna (...) och väljer
Get link to channel
.I länken som visas i popup-fönstret är kanal-ID:t strängen med bokstäver och siffror efter
channel/
. I länken "https://teams.microsoft.com/l/channel/19%3aQK02.../"är kanal-ID :t till exempel 19%3aQK02... upp till följande/
tecken.Kopiera kanal-ID:t och tilldela det till
CHANNEL_ID
i .env-filen .Spara env-filen innan du fortsätter.
Starta/starta om program- och API-servrarna
Utför något av följande steg baserat på de övningar som du har slutfört fram till den här punkten:
Om du startade databasen, API-servern och webbservern i en tidigare övning måste du stoppa API-servern och webbservern och starta om dem för att hämta .env-filändringarna . Du kan låta databasen köras.
Leta upp terminalfönstren som kör API-servern och webbservern och tryck på CTRL + C för att stoppa dem. Starta dem igen genom att
npm start
skriva i varje terminalfönster och trycka på Retur. Fortsätt till nästa övning.Om du inte har startat databasen, API-servern och webbservern ännu utför du följande steg:
I följande steg skapar du tre terminalfönster i Visual Studio Code.
Högerklicka på .env-filen i Visual Studio Code-fillistan och välj Öppna i integrerad terminal. Kontrollera att terminalen finns i projektets rot – openai-acs-msgraph – innan du fortsätter.
Välj något av följande alternativ för att starta PostgreSQL-databasen:
Om du har Docker Desktop installerat och igång kör du
docker-compose up
i terminalfönstret och trycker på Retur.Om du har Podman med podman-compose installerat och igång kör
podman-compose up
du i terminalfönstret och trycker på Retur.Kör PostgreSQL-containern direkt med antingen Docker Desktop, Podman, nerdctl eller en annan containerkörning som du har installerat genom att köra följande kommando i terminalfönstret:
Mac, Linux eller Windows-undersystem för Linux (WSL):
[docker | podman | nerdctl] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v $(pwd)/data:/var/lib/postgresql/data -p 5432:5432 postgres
Windows med PowerShell:
[docker | podman] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v ${PWD}/data:/var/lib/postgresql/data -p 5432:5432 postgres
När databascontainern startar trycker du på + ikonen i Visual Studio Code Terminal-verktygsfältet för att skapa ett andra terminalfönster.
cd
i mappen server/typescript och kör följande kommandon för att installera beroendena och starta API-servern.npm install
npm start
Tryck på + ikonen igen i verktygsfältet Visual Studio Code Terminal för att skapa ett tredje terminalfönster.
cd
i klientmappen och kör följande kommandon för att installera beroendena och starta webbservern.npm install
npm start
En webbläsare startas och du tas till http://localhost:4200.
Organisationsdata: Logga in en användare och hämta en åtkomsttoken
Användarna måste autentisera med Microsoft Entra ID för att Microsoft Graph ska få åtkomst till organisationsdata. I den här övningen får du se hur Microsoft Graph Toolkit-komponenten mgt-login
kan användas för att autentisera användare och hämta en åtkomsttoken. Åtkomsttoken kan sedan användas för att göra anrop till Microsoft Graph.
Anteckning
Om du inte har använt Microsoft Graph tidigare kan du lära dig mer om det i utbildningsvägen Grunderna i Microsoft Graph .
I den här övningen kommer du att:
- Lär dig hur du associerar en Microsoft Entra ID app med Microsoft Graph Toolkit så att den kan användas för att autentisera användare och hämta organisationsdata.
- Lär dig mer om omfattningens betydelse.
- Lär dig hur Microsoft Graph Toolkits mgt-login-komponent kan användas för att autentisera användare och hämta en åtkomsttoken.
Använda inloggningsfunktionen
I föregående övning skapade du en appregistrering i Microsoft Entra ID och startade programservern och API-servern. Du har också uppdaterat följande värden i
.env
filen.ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE> TEAM_ID=<TEAMS_TEAM_ID> CHANNEL_ID=<TEAMS_CHANNEL_ID>
Kontrollera att du har slutfört föregående övning innan du fortsätter.
Gå tillbaka till webbläsaren (http://localhost:4200), välj Logga in i rubriken och logga in med ett administratörsanvändarkonto från din Microsoft 365 Developer-klientorganisation.
Tips
Logga in med ditt administratörskonto för Microsoft 365-utvecklarens klientorganisation. Du kan visa andra användare i utvecklarklientorganisationen genom att gå till Administrationscenter för Microsoft 365.
Om du loggar in i programmet för första gången uppmanas du att godkänna de behörigheter som begärs av programmet. Du får lära dig mer om dessa behörigheter (kallas även "omfång") i nästa avsnitt när du utforskar koden. Välj Acceptera för att fortsätta.
När du har loggat in bör du se namnet på användaren som visas i rubriken.
Utforska inloggningskoden
Nu när du har loggat in ska vi titta på koden som används för att logga in användaren och hämta en åtkomsttoken och användarprofil. Du får lära dig mer om webbkomponenten mgt-login som ingår i Microsoft Graph Toolkit.
Tips
Om du använder Visual Studio Code kan du öppna filer direkt genom att välja:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Skriv sedan namnet på den fil som du vill öppna.
Öppna klienten/package.json och observera att
@microsoft/mgt
paketet ingår i beroendena. Det här paketet innehåller MSAL-providerfunktioner (Microsoft Authentication Library) samt webbkomponenter som mgt-login och andra som kan användas för att logga in användare och hämta och visa organisationsdata.Om du vill använda komponenten mgt-login för att logga in användare måste Microsoft Entra ID-appens klient-ID (lagras i .env-filen som
ENTRAID_CLIENT_ID
) refereras till och användas.Öppna graph.service.ts och leta upp
init()
funktionen. Den fullständiga sökvägen till filen är client/src/app/core/graph.service.ts. Följande kod visas: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'] });
Den här koden skapar ett nytt
Msal2Provider
objekt som skickar det Microsoft Entra ID klient-ID:t från din appregistrering och förscopes
vilket appen begär åtkomst.scopes
Används för att begära åtkomst till Microsoft Graph-resurser som appen kommer åt. När objektetMsal2Provider
har skapats tilldelas det objektetProviders.globalProvider
som används av Microsoft Graph Toolkit-komponenter för att hämta data från Microsoft Graph.Öppna header.component.html i redigeringsprogrammet och leta upp komponenten mgt-login . Den fullständiga sökvägen till filen är client/src/app/header/header.component.html.
<mgt-login *ngIf="featureFlags.microsoft365Enabled" class="mgt-dark" (loginCompleted)="loginCompleted()"></mgt-login>
Komponenten mgt-login aktiverar hämtning av användarinloggning och åtkomsttoken för användning med Microsoft Graph. Vid lyckad inloggning
loginCompleted
utlöses händelsen och anroparloginCompleted()
därefter funktionen. Även om mgt-login används i en Angular komponent i det här exemplet är den kompatibel med alla webbprogram.Visningen av komponenten mgt-login beror på värdet
featureFlags.microsoft365Enabled
som anges tilltrue
. Den här anpassade flaggan söker efter förekomsten avENTRAID_CLIENT_ID
miljövariabeln för att bekräfta att programmet är korrekt konfigurerat och kan autentisera mot Microsoft Entra ID. Flaggan läggs till för att hantera fall där användarna väljer att endast slutföra AI- eller kommunikationsövningarna i självstudien, i stället för att följa hela sekvensen.Öppna header.component.ts och leta upp
loginCompleted
funktionen. Den här funktionen anropas närloginCompleted
händelsen genereras och används för att hämta den inloggade användarens profil med hjälp avProviders.globalProvider
.async loginCompleted() { const me = await Providers.globalProvider.graph.client.api('me').get(); this.userLoggedIn.emit(me); }
I det här exemplet görs ett anrop till Microsoft Graph
me
API för att hämta användarprofilen (me
representerar den aktuella inloggade användaren). Kodsatsenthis.userLoggedIn.emit(me)
genererar en händelse från komponenten för att skicka profildata till den överordnade komponenten. Den överordnade komponenten är app.component.ts fil i det här fallet, som är rotkomponenten för programmet.Mer information om komponenten mgt-login finns i dokumentationen för Microsoft Graph Toolkit .
Nu när du har loggat in på programmet ska vi titta på hur organisationsdata kan hämtas.
Organisationsdata: Hämta filer, chattar och skicka meddelanden till Teams
I dagens digitala miljö arbetar användarna med en mängd olika organisationsdata, inklusive e-postmeddelanden, chattar, filer, kalenderhändelser med mera. Detta kan leda till frekventa kontextväxlingar – växling mellan uppgifter eller program – som kan störa fokus och minska produktiviteten. En användare som arbetar med ett projekt kan till exempel behöva växla från sitt aktuella program till Outlook för att hitta viktig information i ett e-postmeddelande eller växla till OneDrive för företag för att hitta en relaterad fil. Den här fram och tillbaka-åtgärden stör fokus och slösar bort tid som kan spenderas bättre på den aktuella uppgiften.
För att förbättra effektiviteten kan du integrera organisationsdata direkt i de program som användarna använder varje dag. Genom att ta in organisationsdata i dina program kan användarna komma åt och hantera information mer sömlöst, minimera kontextväxlingar och förbättra produktiviteten. Dessutom ger den här integreringen värdefulla insikter och sammanhang som gör det möjligt för användare att fatta välgrundade beslut och arbeta mer effektivt.
I den här övningen kommer du att:
- Lär dig hur webbkomponenten mgt-search-results i Microsoft Graph Toolkit kan användas för att söka efter filer.
- Lär dig hur du anropar Microsoft Graph direkt för att hämta filer från OneDrive för företag och chattmeddelanden från Microsoft Teams.
- Förstå hur du skickar chattmeddelanden till Microsoft Teams-kanaler med Microsoft Graph.
Anteckning
Komponenten mgt-search-results är för närvarande i förhandsversion och kan komma att ändras. Förutom att visa hur mgt-search-results kan användas, visar övningarna också hur du utför samma uppgifter med Hjälp av Microsoft Graph direkt.
Använda funktionen Organisationsdata
I en tidigare övning skapade du en appregistrering i Microsoft Entra ID och startade programservern och API-servern. Du har också uppdaterat följande värden i
.env
filen.ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE> TEAM_ID=<TEAMS_TEAM_ID> CHANNEL_ID=<TEAMS_CHANNEL_ID>
Kontrollera att du har slutfört föregående övning innan du fortsätter.
Gå tillbaka till webbläsaren (http://localhost:4200). Om du inte redan har loggat in väljer du Logga in i rubriken och loggar in med en användare från din Microsoft 365 Developer-klientorganisation.
Anteckning
Förutom att autentisera användaren hämtar webbkomponenten mgt-login också en åtkomsttoken som kan användas av Microsoft Graph för att komma åt filer, chattar, e-postmeddelanden, kalenderhändelser och andra organisationsdata. Åtkomsttoken innehåller de omfång (behörigheter) som
Chat.ReadWrite
,Files.Read.All
och andra som du såg tidigare: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'] });
Välj Visa relaterat innehåll för raden Adatum Corporation i datagrid. Detta gör att organisationsdata som filer, chattar, e-postmeddelanden och kalenderhändelser hämtas med hjälp av Microsoft Graph. När data har lästs in visas de under datagrid i ett gränssnitt med flikar. Det är viktigt att nämna att du kanske inte ser några data just nu eftersom du inte har lagt till några filer, chattar, e-postmeddelanden eller kalenderhändelser för användaren i din Microsoft 365 Developer-klientorganisation ännu. Nu ska vi åtgärda det i nästa steg.
Din Microsoft 365-klientorganisation kanske inte har några relaterade organisationsdata för Adatum Corporation i det här skedet. Utför minst en av följande åtgärder för att lägga till exempeldata:
Lägg till filer genom att besöka https://onedrive.com och logga in med dina autentiseringsuppgifter för Microsoft 365 Developer-klientorganisationen.
- Välj Mina filer i det vänstra navigeringsfönstret.
- Välj Ladda upp och sedan Mapp på menyn.
- Välj mappen openai-acs-msgraph/customer documents från projektet som du klonade.
Lägg till chattmeddelanden och kalenderhändelser genom att besöka https://teams.microsoft.com och logga in med dina autentiseringsuppgifter för Microsoft 365 Developer-klientorganisationen.
Välj Teams i det vänstra navigeringsfönstret.
Välj ett team och en kanal.
Välj Ny konversation.
Ange Ny beställning för Adatum Corporation och välj knappen Skicka .
Lägg gärna till ytterligare chattmeddelanden som nämner andra företag som används i programmet, till exempel Adventure Works Cycles, Contoso Pharmaceuticals och Tailwind Traders.
Välj Kalender i det vänstra navigeringsfönstret.
Välj Nytt möte.
Ange "Meet with Adatum Corporation about project schedule" (Möte med Adatum Corporation om projektschema) som rubrik och brödtext.
Välj Spara.
Lägg till e-postmeddelanden genom att besöka https://outlook.com och logga in med dina autentiseringsuppgifter för Microsoft 365 Developer-klientorganisationen.
Välj Ny e-post.
Ange din personliga e-postadress i fältet Till .
Ange Ny beställning som gjorts för Adatum Corporation för ämnet och vad du vill för brödtexten.
Välj Skicka.
Gå tillbaka till programmet i webbläsaren och uppdatera sidan. Välj Visa relaterat innehåll igen för raden Adatum Corporation . Du bör nu se data som visas på flikarna beroende på vilka uppgifter du utförde i föregående steg.
Nu ska vi utforska koden som aktiverar funktionen för organisationsdata i programmet. För att hämta data använder programmets klientdel den åtkomsttoken som hämtades av komponenten mgt-login som du tittade på tidigare för att göra anrop till Microsoft Graph-API:er.
Utforska sökkod för filer
Tips
Om du använder Visual Studio Code kan du öppna filer direkt genom att välja:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Skriv sedan namnet på den fil som du vill öppna.
Vi börjar med att titta på hur fildata hämtas från OneDrive för företag. Öppna files.component.html och titta igenom koden en stund. Den fullständiga sökvägen till filen är client/src/app/files/files.component.html.
Leta upp komponenten mgt-search-results och notera följande attribut:
<mgt-search-results class="search-results" entity-types="driveItem" [queryString]="searchText" (dataChange)="dataChange($any($event))" />
Komponenten mgt-search-results är en del av Microsoft Graph Toolkit och som namnet antyder används den för att visa sökresultat från Microsoft Graph. Komponenten använder följande funktioner i det här exemplet:
Attributet
class
används för att ange attsearch-results
CSS-klassen ska tillämpas på komponenten.Attributet
entity-types
används för att ange vilken typ av data som ska sökas efter. I det här fallet användsdriveItem
värdet för att söka efter filer i OneDrive för företag.Attributet
queryString
används för att ange söktermen. I det här fallet är värdet bundet till egenskapensearchText
som skickas till filkomponenten när användaren väljer Visa relaterat innehåll för en rad i datagrid. Hakparenteserna runtqueryString
anger att egenskapen är bunden till värdetsearchText
.Händelsen
dataChange
utlöses när sökresultatet ändras. I det här fallet anropas en kundfunktion med namnetdataChange()
i filkomponenten och händelsedata skickas till funktionen. Parentesen runtdataChange
anger att händelsen är bunden till funktionendataChange()
.Eftersom ingen anpassad mall har angetts används den inbyggda
mgt-search-results
standardmallen för att visa sökresultaten.
Ett alternativ till att använda komponenter som mgt-search-results är att anropa Microsoft Graph-API:er direkt med hjälp av kod. Om du vill se hur det fungerar öppnar du filen graph.service.ts och letar upp
searchFiles()
funktionen. Den fullständiga sökvägen till filen är client/src/app/core/graph.service.ts.Du ser att en
query
parameter skickas till funktionen . Det här är söktermen som skickas när användaren väljer Visa relaterat innehåll för en rad i datagrid. Om ingen sökterm skickas returneras en tom matris.async searchFiles(query: string) { const files: DriveItem[] = []; if (!query) return files; ... }
Ett filter skapas sedan som definierar vilken typ av sökning som ska utföras. I det här fallet söker koden efter filer i OneDrive för företag så
driveItem
används precis som du såg tidigare med komponentenmgt-search-results
. Det här är samma sak som att skickadriveItem
tillentity-types
komponenten mgt-search-results som du såg tidigare. Parameternquery
läggs sedan till iqueryString
filtret tillsammans medContentType:Document
.const filter = { "requests": [ { "entityTypes": [ "driveItem" ], "query": { "queryString": `${query} AND ContentType:Document` } } ] };
Ett anrop görs sedan till
/search/query
Microsoft Graph API med hjälp avProviders.globalProvider.graph.client.api()
funktionen . Objektetfilter
skickas till funktionenpost()
som skickar data till API:et.const searchResults = await Providers.globalProvider.graph.client.api('/search/query').post(filter);
Sökresultaten itereras sedan genom för att hitta
hits
. Varhit
och en innehåller information om ett dokument som hittades. En egenskap med namnetresource
innehåller dokumentets metadata och läggs till i matrisenfiles
.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); } } } }
Matrisen
files
returneras sedan till anroparen.return files;
När du tittar igenom den här koden kan du se att webbkomponenten mgt-search-results som du utforskade tidigare gör mycket arbete åt dig och avsevärt minskar mängden kod du måste skriva! Det kan dock finnas scenarier där du vill anropa Microsoft Graph direkt för att få mer kontroll över de data som skickas till API:et eller hur resultaten bearbetas.
Öppna filen files.component.ts och leta upp
search()
funktionen . Den fullständiga sökvägen till filen är client/src/app/files/files.component.ts.Även om brödtexten i den här funktionen kommenteras ut på grund av komponenten mgt-search-results som används, kan funktionen användas för att göra anropet till Microsoft Graph när användaren väljer Visa relaterat innehåll för en rad i datagrid. Funktionen
search()
anroparsearchFiles()
i graph.service.ts och skickar parameternquery
till den (namnet på företaget i det här exemplet). Resultatet av sökningen tilldelas sedan till komponentensdata
egenskap.override async search(query: string) { this.data = await this.graphService.searchFiles(query); }
Filkomponenten kan sedan använda
data
egenskapen för att visa sökresultaten. Du kan hantera detta med hjälp av anpassade HTML-bindningar eller med hjälp av en annan Microsoft Graph Toolkit-kontroll med namnetmgt-file-list
. Här är ett exempel på hur du binderdata
egenskapen till en av komponentens egenskaper med namnetfiles
och hanteraritemClick
händelsen när användaren interagerar med en fil.<mgt-file-list (itemClick)="itemClick($any($event))" [files]="data"></mgt-file-list>
Om du väljer att använda komponenten mgt-search-results som visades tidigare eller skriva anpassad kod för att anropa Microsoft Graph beror på ditt specifika scenario. I det här exemplet används komponenten mgt-search-results för att förenkla koden och minska mängden arbete som du måste utföra.
Utforska sökkoden för Teams chattmeddelanden
Gå tillbaka för att graph.service.ts och leta upp
searchChatMessages()
funktionen. Du ser att den liknar densearchFiles()
funktion som du tittade på tidigare.- Den publicerar filterdata till Microsoft Graphs
/search/query
API och konverterar resultatet till en matris med objekt som har information omteamId
,channelId
ochmessageId
som matchar söktermen. - För att hämta Teams-kanalmeddelanden görs ett andra anrop till API:et
/teams/${chat.teamId}/channels/${chat.channelId}/messages/${chat.messageId}
teamId
och ,channelId
ochmessageId
skickas. Detta returnerar den fullständiga meddelandeinformationen. - Ytterligare filtreringsuppgifter utförs och de resulterande meddelandena returneras från
searchChatMessages()
till anroparen.
- Den publicerar filterdata till Microsoft Graphs
Öppna filen chats.component.ts och leta upp
search()
funktionen . Den fullständiga sökvägen till filen är client/src/app/chats/chats.component.ts. Funktionensearch()
anroparsearchChatMessages()
i graph.service.ts och skickar parametern till denquery
.override async search(query: string) { this.data = await this.graphService.searchChatMessages(query); }
Resultatet av sökningen tilldelas till egenskapen för
data
komponenten och databindningen används för att iterera genom resultatmatrisen och återge data. I det här exemplet används en Angular Material-kortkomponent för att visa sökresultaten.<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>
Skicka ett meddelande till en Microsoft Teams-kanal
Förutom att söka efter Microsoft Teams-chattmeddelanden tillåter programmet även att en användare skickar meddelanden till en Microsoft Teams-kanal. Det kan du göra genom att anropa slutpunkten för
/teams/${teamId}/channels/${channelId}/messages
Microsoft Graph.I följande kod ser du att en URL skapas som innehåller
teamId
värdena ochchannelId
. Miljövariabelvärden används för team-ID och kanal-ID i det här exemplet, men dessa värden kan också hämtas dynamiskt med hjälp av Microsoft Graph. Konstantenbody
innehåller meddelandet som ska skickas. En POST-begäran görs sedan och resultatet returneras till anroparen.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' }; }
Genom att använda den här typen av funktioner i Microsoft Graph kan du förbättra användarproduktiviteten genom att låta användarna interagera med Microsoft Teams direkt från det program som de redan använder.
Organisationsdata: Hämta e-postmeddelanden och kalenderhändelser
I föregående övning lärde du dig att hämta filer från OneDrive för företag och chattar från Microsoft Teams med hjälp av Microsoft Graph och komponenten mgt-search-results från Microsoft Graph Toolkit. Du har också lärt dig hur du skickar meddelanden till Microsoft Teams-kanaler. I den här övningen får du lära dig hur du hämtar e-postmeddelanden och kalenderhändelser från Microsoft Graph och integrerar dem i programmet.
I den här övningen kommer du att:
- Lär dig hur webbkomponenten mgt-search-results i Microsoft Graph Toolkit kan användas för att söka efter e-postmeddelanden och kalenderhändelser.
- Lär dig hur du anpassar komponenten mgt-search-results för att rendera sökresultat på ett anpassat sätt.
- Lär dig hur du anropar Microsoft Graph direkt för att hämta e-postmeddelanden och kalenderhändelser.
Utforska sökkoden Email meddelanden
Tips
Om du använder Visual Studio Code kan du öppna filer direkt genom att välja:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Skriv sedan namnet på den fil som du vill öppna.
I en tidigare övning skapade du en appregistrering i Microsoft Entra ID och startade programservern och API-servern. Du har också uppdaterat följande värden i
.env
filen.ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE> TEAM_ID=<TEAMS_TEAM_ID> CHANNEL_ID=<TEAMS_CHANNEL_ID>
Kontrollera att du har slutfört föregående övning innan du fortsätter.
Öppna emails.component.html och titta igenom koden en stund. Den fullständiga sökvägen till filen är client/src/app/emails/emails.component.html.
Leta upp komponenten 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>
Det här exemplet på komponenten mgt-search-results har konfigurerats på samma sätt som du tittade på tidigare. Den enda skillnaden är att
entity-types
attributet är inställtmessage
på vilket används för att söka efter e-postmeddelanden och en tom mall anges.- Attributet
class
används för att ange attsearch-results
CSS-klassen ska tillämpas på komponenten. - Attributet
entity-types
används för att ange vilken typ av data som ska sökas efter. I det här fallet ärmessage
värdet . - Attributet
queryString
används för att ange söktermen. - Händelsen
dataChange
utlöses när sökresultatet ändras. E-postkomponentens funktion anropasdataChange()
, resultaten skickas till den och en egenskap med namnetdata
uppdateras i komponenten. - En tom mall har definierats för komponenten. Den här typen av mall används vanligtvis för att definiera hur sökresultaten ska renderas. I det här scenariot säger vi dock till komponenten att inte återge några meddelandedata. I stället renderar vi data själva med hjälp av standarddatabindning (Angular används i det här fallet, men du kan använda valfritt bibliotek/ramverk).
- Attributet
Titta under komponenten mgt-search-results i emails.component.html för att hitta de databindningar som används för att återge e-postmeddelandena. Det här exemplet itererar genom
data
egenskapen och skriver ut e-postmeddelandets ämne, brödtextförhandsvisning och en länk för att visa det fullständiga e-postmeddelandet.<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>
Förutom att använda komponenten mgt-search-results för att hämta meddelanden tillhandahåller Microsoft Graph flera API:er som även kan användas för att söka i e-postmeddelanden. Det
/search/query
API som du såg tidigare kan säkert användas, men ett enklare alternativ är API:etmessages
.Om du vill se hur du anropar det här API:et
searchEmailMessages()
går du tillbaka till graph.service.ts och letar upp funktionen. Den skapar en URL som kan användas för att anropamessages
slutpunkten för Microsoft Graph och tilldelarquery
värdet till parametern$search
. Koden gör sedan en GET-begäran och returnerar resultatet till anroparen. Operatorn$search
sökerquery
automatiskt efter värdet i ämnes-, brödtext- och avsändarfälten.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; }
E-postkomponenten som finns i emails.component.ts anropar
searchEmailMessages()
och visar resultatet i användargränssnittet.override async search(query: string) { this.data = await this.graphService.searchEmailMessages(query); }
Utforska sökkoden för kalenderhändelser
Du kan också söka efter kalenderhändelser med hjälp av komponenten mgt-search-results . Den kan hantera återgivning av resultaten åt dig, men du kan också definiera en egen mall som du ser senare i den här övningen.
Öppna calendar-events.component.html och titta igenom koden en stund. Den fullständiga sökvägen till filen är client/src/app/calendar-events/calendar-events.component.html. Du ser att det liknar de filer och e-postkomponenter som du tittade på tidigare.
<mgt-search-results class="search-results" entity-types="event" [queryString]="searchText" (dataChange)="dataChange($any($event))"> <template data-type="result-event"></template> </mgt-search-results>
Det här exemplet på komponenten mgt-search-results har konfigurerats på samma sätt som de som du tittade på tidigare. Den enda skillnaden är att
entity-types
attributet är inställtevent
på vilket används för att söka efter kalenderhändelser och en tom mall anges.- Attributet
class
används för att ange attsearch-results
CSS-klassen ska tillämpas på komponenten. - Attributet
entity-types
används för att ange vilken typ av data som ska sökas efter. I det här fallet ärevent
värdet . - Attributet
queryString
används för att ange söktermen. - Händelsen
dataChange
utlöses när sökresultatet ändras. Kalenderhändelsekomponentens funktion anropasdataChange()
, resultaten skickas till den och en egenskap med namnetdata
uppdateras i komponenten. - En tom mall har definierats för komponenten. I det här scenariot uppmanar vi komponenten att inte återge några data. I stället renderar vi data själva med hjälp av standarddatabindning.
- Attributet
Direkt under komponenten
mgt-search-results
i calendar-events.component.html hittar du de databindningar som används för att återge kalenderhändelserna. Det här exemplet itererar genomdata
egenskapen och skriver ut startdatum, tid och ämne för händelsen. Anpassade funktioner som ingår i komponenten,dayFromDateTime()
till exempel ochtimeRangeFromEvent()
anropas för att formatera data korrekt. HTML-bindningarna innehåller också en länk för att visa kalenderhändelsen i Outlook och platsen för händelsen om en har angetts.<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>
Förutom att söka efter kalenderhändelser med hjälp av API:et
search/query
tillhandahåller Microsoft Graph även ettevents
API som även kan användas för att söka efter kalenderhändelser.searchCalendarEvents()
Leta upp funktionen i graph.service.ts.Funktionen
searchCalendarEvents()
skapar värden för start- och slutdatum/-tid som används för att definiera tidsperioden för sökning. Den skapar sedan en URL som kan användas för att anropaevents
slutpunkten för Microsoft Graph och innehåller parametern samt variablernaquery
start- och slutdatum/tid. En GET-begäran görs sedan och resultaten returneras till anroparen.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; }
Här är en uppdelning av url:en som skapas:
- Delen
/me/events
av URL:en används för att ange att händelserna för den inloggade användaren ska hämtas. - Parametrarna
startdatetime
ochenddatetime
används för att definiera tidsperioden för sökning. I det här fallet returnerar sökningen händelser som startar inom de kommande 7 dagarna. - Frågeparametern
$filter
används för att filtrera resultatetquery
efter värdet (det företagsnamn som väljs från datagrid i det här fallet). Funktionencontains()
används förquery
att leta efter värdet isubject
egenskapen för kalenderhändelsen. - Frågeparametern
$orderby
används för att sortera resultatet efterstart/dateTime
egenskapen .
- Delen
När har
url
skapats görs en GET-begäran till Microsoft Graph API med hjälp avurl
värdet för och resultaten returneras till anroparen.Precis som med de tidigare komponenterna anropar
search()
komponenten calendar-events (calendar-events.component.ts fil) och visar resultatet.override async search(query: string) { this.data = await this.graphService.searchCalendarEvents(query); }
Anteckning
Du kan även göra Microsoft Graph-anrop från ett anpassat API eller ett program på serversidan. Se följande självstudie för att se ett exempel på hur du anropar en Microsoft-Graph API från en Azure-funktion.
Nu har du sett exempel på hur du kan använda Microsoft Graph för att hämta filer, chattar, e-postmeddelanden och kalenderhändelser. Samma begrepp kan även tillämpas på andra Microsoft Graph-API:er. Du kan till exempel använda API:et för Microsoft Graph-användare för att söka efter användare i din organisation. Du kan också använda API:et för Microsoft Graph-grupper för att söka efter grupper i din organisation. Du kan visa den fullständiga listan över Api:er för Microsoft Graph i dokumentationen.
Grattis!
Du har slutfört den här självstudien
Grattis! Du har lärt dig hur Azure OpenAI kan användas för att förbättra användarproduktiviteten, hur Azure Communication Services kan användas för att integrera kommunikationsfunktioner och hur Api:er och komponenter i Microsoft Graph kan användas för att hämta och visa organisationsdata. Med hjälp av dessa tekniker kan du skapa effektiva lösningar som ökar användarnas produktivitet genom att minimera kontextförskjutningar och tillhandahålla nödvändig beslutsinformation.
Rensa Azure-resurser
Rensa dina Azure-resurser för att undvika ytterligare avgifter för ditt konto. Gå till Azure Portal och ta bort följande resurser:
- Resursen Azure Cognitive Search
- Azure Storage-resursen
- Azure OpenAI-resursen
- Resursen Azure Communication Services
Nästa steg
Dokumentation
- Dokumentation om Azure OpenAI
- Azure OpenAI för dina data
- Dokumentation om Azure Communication Services
- Dokumentation om Microsoft Graph
- Dokumentation om Microsoft Graph Toolkit
- Utvecklardokumentation för Microsoft Teams
Träningsinnehåll
- Tillämpa promptteknik med Azure OpenAI-tjänsten
- Kom igång med Azure OpenAI-tjänsten
- Introduktion till Azure Communication Services
- Grunderna i Microsoft Graph
- Videokurs: Grunderna i Microsoft Graph för nybörjare
- Utforska Microsoft Graph-scenarier för JavaScript-utveckling
- Utforska Microsoft Graph-scenarier för ASP.NET Core utveckling
- Kom igång med Microsoft Graph Toolkit
- Skapa och distribuera appar för Microsoft Teams med Teams Toolkit för Visual Studio Code
Har du ett problem med det här avsnittet? Ge oss då feedback så att vi kan förbättra avsnittet.
Feedback
https://aka.ms/ContentUserFeedback.
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i:Skicka och visa feedback för