OpenAI, İletişim ve Kurumsal Veri Özelliklerini İş Kolu Uygulamasıyla Tümleştirme
Düzey: Ara
Bu öğreticide Azure OpenAI, Azure İletişim Hizmetleri ve Microsoft Graph/Microsoft Graph Toolkit'in kullanıcı üretkenliğini artırmak, kullanıcı deneyimini yükseltmek ve LOB uygulamalarını bir sonraki düzeye çıkarmak için İş Kolu (LOB) uygulamalarıyla nasıl tümleştirilebileceği gösterilmektedir.
- Yapay zeka: Kullanıcıların doğal dilde sorular sormasını ve yanıtlarını bir veritabanını sorgulamak için kullanılabilecek SQL'e dönüştürmesini, kullanıcıların otomatik olarak e-posta ve SMS iletileri oluşturmak için kullanılabilecek kurallar tanımlamasına olanak tanıyabilir ve kendi özel veri kaynaklarınızdan veri almak için doğal dilin nasıl kullanılabileceğini öğrenebilirsiniz. Azure OpenAI bu özellikler için kullanılır.
- İletişim: Azure İletişim Hizmetleri kullanarak müşterilere uygulama içi telefon çağrısını ve Email/SMS işlevselliğini etkinleştirin.
- Kuruluş Verileri: Bağlam değiştirmeden kaçınmak için müşterilerle birlikte çalışırken kullanıcıların ihtiyaç duyabileceği ilgili kuruluş verilerini (belgeler, sohbetler, e-postalar, takvim olayları) çekin. Bu tür kuruluş verilerine erişim sağlamak kullanıcının Outlook, Teams, OneDrive, diğer özel uygulamalar, telefonu vb. geçiş yapma gereksinimini azaltır çünkü ihtiyaç duyduğu belirli veriler ve işlevler doğrudan uygulamada sağlanır. Bu özellik için Microsoft Graph ve Microsoft Graph Araç Seti kullanılır.
Uygulama, kullanıcıların müşterilerini ve ilgili verileri yönetmesine olanak tanıyan basit bir müşteri yönetim uygulamasıdır. Verileri almak, yapay zeka işlevleriyle etkileşime geçmek, e-posta/SMS mesajları göndermek ve kuruluş verilerini çekmek için arka uç API'lerini çağıran TypeScript kullanılarak oluşturulmuş bir ön uçtan oluşur. İşte bu öğreticide iz göreceğiniz uygulama çözümüne genel bir bakış:
Öğretici, gerekli Azure ve Microsoft 365 kaynaklarını ayarlama işleminde size yol gösterir. Ayrıca yapay zeka, iletişim ve kurumsal veri özelliklerini uygulamak için kullanılan kodda size yol gösterir. Kod kopyalayıp yapıştırmanız gerekmeyecek olsa da, bazı alıştırmalarda farklı senaryoları denemek için kodu değiştirmeniz gerekir.
Bu Öğreticide Oluşturacakların
Kendi Maceranı Seç
Öğreticinin tamamını baştan sona tamamlayabilir veya ilgilendiğiniz belirli konuları tamamlayabilirsiniz. Öğretici aşağıdaki konu alanlarına ayrılmıştır:
- Proje Alıştırması'nı (gerekli alıştırma) kopyalama.
- Yapay Zeka Alıştırmaları: Bir Azure OpenAI kaynağı oluşturun ve bunu kullanarak doğal dili SQL'e dönüştürün, e-posta/SMS iletileri oluşturun ve kendi verileriniz ve belgelerinizle çalışın.
- İletişim Alıştırmaları: bir Azure İletişim Hizmetleri kaynağı oluşturun ve bunu kullanarak uygulamadan telefon aramaları yapın ve e-posta/SMS mesajları gönderin.
- Kurumsal Veri Alıştırmaları: Kuruluş verilerinin kimliğini doğrulamak ve uygulamaya çekmek için Microsoft Graph ve Microsoft Graph Toolkit'in kullanılabilmesi için bir Microsoft Entra ID uygulama kaydı oluşturun.
Önkoşullar
- Node - Bu proje için Düğüm 16+ ve npm 7+ kullanılacak
- git
- Visual Studio Code (Visual Studio Code önerilmesine rağmen, herhangi bir düzenleyici kullanılabilir)
- Azure aboneliği
- Microsoft 365 geliştirici kiracısı
- Docker Desktop veya Podman gibi başka bir OCI (Open Container Initiative) uyumlu kapsayıcı çalışma zamanı veya kapsayıcı çalıştırabilen nerdctl .
Bu Öğreticide Kullanılan Microsoft Bulut Teknolojileri
- Microsoft Entra Kimlik
- Azure İletişim Hizmetleri
- Azure OpenAI Service
- Microsoft Graph
- Microsoft Graph Araç Seti
Projeyi Kopyalama
Bu öğreticide kullanılan kod projesine adresinden https://github.com/microsoft/MicrosoftCloudulaşabilirsiniz. Projenin deposu, projeyi çalıştırmak için gereken hem istemci tarafı hem de sunucu tarafı kodu içerir ve yapay zeka (AI), iletişim ve kuruluş verileriyle ilgili tümleşik özellikleri keşfetmenizi sağlar. Ayrıca proje, benzer özellikleri kendi uygulamalarınıza dahil etme konusunda size yol gösteren bir kaynak görevi görür.
Bu alıştırmada şunları yapacaksınız:
- GitHub deposunu kopyalayın.
- Projeye bir .env dosyası ekleyin ve güncelleştirin.
Devam etmeden önce, bu öğreticinin Önkoşullar bölümünde özetlendiği gibi tüm önkoşulların yüklü ve yapılandırılmış olduğundan emin olun.
GitHub Deposunu Kopyalama ve Dosya Oluşturma .env
Aşağıdaki komutu çalıştırarak Microsoft Cloud GitHub Deposunu makinenize kopyalayın.
git clone https://github.com/microsoft/MicrosoftCloud
Visual Studio Code'da MicrosoftCloud/samples/openai-acs-msgraph klasörünü açın.
Not
Bu öğretici boyunca Visual Studio Code kullanacağız ancak örnek projeyle çalışmak için herhangi bir kod düzenleyicisi kullanılabilir.
Aşağıdaki klasörlere ve dosyalara dikkat edin:
- client: İstemci tarafı uygulama kodu.
- sunucu: Sunucu tarafı API kodu.
- docker-compose.yml: Yerel bir PostgreSQL veritabanını çalıştırmak için kullanılır.
Projenin kökündeki .env.example dosyasını .env olarak yeniden adlandırın.
.env dosyasını açın ve aşağıdaki anahtarlara göz atın:
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=
.env dosyasında aşağıdaki değerleri güncelleştirin. Bu değerler API sunucusu tarafından yerel PostgreSQL veritabanına bağlanmak için kullanılır.
POSTGRES_USER=web POSTGRES_PASSWORD=web-password
Artık projeyi tamamladığınıza göre, uygulama özelliklerinden bazılarını deneyelim ve bunların nasıl derlendiğini öğrenelim. İçindekiler tablosunu kullanarak belirli bir alıştırmaya devam etmek veya bu alıştırmaya atlamak için aşağıdaki İleri düğmesini seçin.
Yapay Zeka: Azure OpenAI Kaynağı Oluşturma ve Model Dağıtma
Uygulamalarınızda Azure OpenAI kullanmaya başlamak için bir Azure OpenAI Hizmeti oluşturmanız ve doğal dili SQL'e dönüştürme, e-posta/SMS iletisi içeriği oluşturma gibi görevleri gerçekleştirmek için kullanılabilecek bir model dağıtmanız gerekir.
Bu alıştırmada şunları yapacaksınız:
- Azure OpenAI Hizmeti kaynağı oluşturun.
- Model dağıtma.
- .env dosyasını Azure OpenAI Hizmeti kaynağınızdaki değerlerle güncelleştirin.
Azure OpenAI Hizmet Kaynağı oluşturma
Tarayıcınızda Azure portal ziyaret edin ve oturum açın.
Portal sayfasının üst kısmındaki arama çubuğunaopenai yazın ve görüntülenen seçeneklerden Azure OpenAI'yi seçin.
Araç çubuğunda Oluştur'u seçin.
Not
Aboneliğinizde Azure OpenAI'yi etkinleştirmek için bir başvuru formunu tamamlama hakkında bir ileti görürseniz Azure OpenAI hizmetine erişim istemek için buraya tıklayın bağlantısını seçin ve formu tamamlayın. Formu tamamladıktan sonra Azure OpenAI ekibinin isteğinizi onaylamasını beklemeniz gerekir. Onay bildiriminizi aldıktan sonra bu alıştırmaya geri dönebilir ve kaynağı oluşturabilirsiniz.
Bu öğretici Azure OpenAI'ye odaklansa da, openAI API anahtarınız varsa ve Bunu Azure OpenAI'ye erişim beklerken kullanmak istiyorsanız, bu bölümü atlayabilir ve doğrudan aşağıdaki Projenin .env Dosyasını Güncelleştirme bölümüne gidebilirsiniz. OpenAI API anahtarınızı
OPENAI_API_KEY
.env dosyasında öğesine atayın (OpenAI ile ilgili diğer.env
yönergeleri yoksayabilirsiniz). Azure OpenAI erişiminiz olduğunda bu alıştırmayı yeniden ziyaret edin, kaynak ve modeli oluşturun ve .env dosyasını Azure OpenAI kaynağınızdaki değerlerle güncelleştirin.Aşağıdaki görevleri gerçekleştirin:
- Azure aboneliğinizi seçin.
- Kullanılacak kaynak grubunu seçin (gerekirse yeni bir grup oluşturun).
- Kullanmak istediğiniz bölgeyi seçin.
- Kaynak adını girin. Bu, benzersiz bir değer olmalıdır.
- Standart S0 fiyatlandırma katmanını seçin.
Gözden Geçir ve gönder ekranına gelene kadar İleri'yi seçin. Oluştur’u seçin.
Azure OpenAI kaynağınız oluşturulduktan sonra kaynağınıza gidin ve Kaynak Yönetimi bölümünde Anahtarlar ve Uç Nokta'yı seçin.
KEY 1 ve Endpoint değerlerini bulun. Sonraki bölümde her iki değeri de kullanacaksınız, bu nedenle bunları yerel bir dosyaya kopyalayın.
Kaynak Yönetimi bölümünde Model dağıtımları'nı seçin.
Azure OpenAI Studio'ya gitmek için Dağıtımları Yönet düğmesini seçin.
Araç çubuğunda Yeni dağıtım oluştur'u seçin.
Aşağıdaki değerleri girin:
- Model: gpt-35-turbo.
- Model sürümü: Varsayılana otomatik güncelleştirme.
- Dağıtım adı: gpt-35-turbo.
Not
Azure OpenAI birkaç farklı model türünü destekler. Her model farklı senaryoları işlemek için kullanılabilir.
Oluştur’u seçin.
Model dağıtıldıktan sonra Oyun Alanı bölümünde Tamamlamalar'ı seçin.
Dağıtımlar açılan listesinden gpt-35-turbo modelini seçin. Örnekler açılan listesinden E-posta oluştur'a tıklayın.
Sağlanan istem metnini okumak için biraz zaman ayırın. Modelin oluşturduğu metni görmek için Oluştur'a tıklayın.
Uyarı
Modelin hazır olmadığıyla ilgili bir hata iletisi alırsanız birkaç dakika bekleyin ve yeniden deneyin. Modelin tamamen dağıtılması ve kullanıma hazır olması birkaç dakika sürebilir.
"Tamamlama işlemi belirtilen modelle çalışmıyor" hatasını alırsanız, bu normalde varsayılan sürüm yerine daha yeni bir model sürümü seçtiğiniz anlamına gelir. Dağıtımlar'ı seçin ve daha önce oluşturduğunuz modeli silin. Yeni bir gpt-35-turbo model dağıtımı oluşturun, Model sürümü için varsayılan olarak Otomatik güncelleştir'i seçtiğinizden emin olun, gpt-35-turbo adını verin ve modelin tam olarak dağıtılmasını bekleyin. Dağıtıldıktan sonra Oyun Alanı'na geri dönün ve tamamlama işlemini yeniden deneyin.
Birden çok kez yeniden oluştur'u seçin. Metnin her seferinde farklı olduğunu unutmayın.
Ekranın sağ kısmında Sıcaklık gibi özelliklerin listelendiğini görürsünüz. Sıcaklık değerini 0 olarak değiştirin ve Yeniden Oluştur'u yeniden seçin. Oluşturulan e-posta metnini okuyun.
Son bir kez yeniden oluştur'u seçin ve e-posta metninin daha önce oluşturulan metinle aynı olduğuna dikkat edin.
Not
Sıcaklığı düşürmek, modelin daha yinelenen ve belirleyici yanıtlar üreteceği anlamına gelir. Sıcaklığı artırmak daha beklenmedik veya yaratıcı yanıtlara neden olur.
Projenin .env
Dosyasını Güncelleştirme
Visual Studio Code Geri dön ve dosyayı projenin kökünde açın
.env
.Azure OpenAI kaynağınızdan KEY 1 değerini kopyalayın ve openai-acs-msgraph klasörünün kökünde bulunan .env dosyasına atayın
OPENAI_API_KEY
:OPENAI_API_KEY=<KEY_1_VALUE>
*Endpoint değerini kopyalayın ve .env dosyasında öğesine atayın
OPENAI_ENDPOINT
./
Varsa, değerin sonundaki karakteri kaldırın.OPENAI_ENDPOINT=<ENDPOINT_VALUE>
Not
ve değerlerinin
OPENAI_MODEL
OPENAI_API_VERSION
.env dosyasında zaten ayarlandığını görürsünüz. Model değeri, bu alıştırmada daha önce oluşturduğunuz model adıyla eşleşmesi gereken gpt-35-turbo olarak ayarlanır. API sürümü, Azure OpenAI başvuru belgelerinde tanımlanan desteklenen bir değere ayarlanır..env dosyasını kaydedin.
Application Services'ı başlatma
Veritabanı, API sunucusu ve web sunucusu gibi uygulama hizmetlerinizi başlatma zamanı geldi.
Aşağıdaki adımlarda, Visual Studio Code'da üç terminal penceresi oluşturacaksınız.
Visual Studio Code dosya listesinde .env dosyasına sağ tıklayın ve Tümleşik Terminalde Aç'ı seçin. Devam etmeden önce terminalinizin projenin kökünde ( openai-acs-msgraph ) olduğundan emin olun.
PostgreSQL veritabanını başlatmak için aşağıdaki seçeneklerden birini seçin:
Docker Desktop'ı yüklediyseniz ve çalıştırıyorsanız terminal penceresinde komutunu çalıştırın
docker-compose up
ve Enter tuşuna basın.Podman-compose yüklü ve çalışır durumda olan Podman'larınız varsa terminal penceresinde komutunu çalıştırın
podman-compose up
ve Enter tuşuna basın.PostgreSQL kapsayıcısını doğrudan Docker Desktop, Podman, nerdctl veya yüklediğiniz başka bir kapsayıcı çalışma zamanını kullanarak çalıştırmak için terminal penceresinde aşağıdaki komutu çalıştırın:
Mac, Linux veya Linux için Windows Alt Sistemi (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
PowerShell ile Windows:
[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
Veritabanı kapsayıcısı başlatıldıktan sonra, ikinci bir terminal penceresi oluşturmak için Visual Studio Code Terminal araç çubuğundaki simgeye basın+.
cd
server /typescript klasörüne gidin ve bağımlılıkları yüklemek ve API sunucusunu başlatmak için aşağıdaki komutları çalıştırın.npm install
npm start
+ Üçüncü bir terminal penceresi oluşturmak için Visual Studio Code Terminal araç çubuğundaki simgeye yeniden basın.
cd
ve aşağıdaki komutları çalıştırarak bağımlılıkları yükleyin ve web sunucusunu başlatın.npm install
npm start
Bir tarayıcı başlatılır ve adresine yönlendirilirsiniz http://localhost:4200.
Yapay Zeka: Doğal Dilden SQL'e
Yapay zeka özellikleri hakkında düşünürken "Yalnızca bunu yapabileceğiniz anlamına gelmez" alıntısı yararlı bir kılavuzdur. Örneğin, Azure OpenAI'nin doğal dilden SQL özelliği, kullanıcıların veritabanı sorgularını düz İngilizce yapmasını sağlar ve bu da üretkenliğini artırmak için güçlü bir araç olabilir. Ancak , güçlü her zaman uygun veya güvenli anlamına gelmez. Bu alıştırmada bu yapay zeka özelliğinin nasıl kullanılacağı gösterilirken, uygulamaya karar vermeden önce dikkat edilmesi gereken önemli noktalar ele alınacaktır.
Aşağıda veritabanından veri almak için kullanılabilecek doğal dil sorgusu örneği verilmişti:
Get the the total revenue for all companies in London.
Uygun istemlerle, Azure OpenAI bu sorguyu veritabanından sonuç döndürmek için kullanılabilecek SQL'e dönüştürür. Sonuç olarak, iş analistleri, pazarlamacılar ve yöneticiler dahil olmak üzere teknik olmayan kullanıcılar karmaşık SQL söz dizimi ile boğuşmadan veya kısıtlanmış veri kılavuzlarına ve filtrelere güvenmeden veritabanlarından değerli bilgileri daha kolay alabilir. Bu kolaylaştırılmış yaklaşım, kullanıcıların teknik uzmanlardan yardım isteme gereksinimini ortadan kaldırarak üretkenliği artırabilir.
Bu alıştırma, SQL'in doğal dilinin nasıl çalıştığını anlamanıza, bazı önemli noktaları size tanıtmanıza, artıları ve dezavantajları düşünmenize yardımcı olacak ve başlamanız için gereken kodu gösterecek bir başlangıç noktası sağlar.
Bu alıştırmada şunları yapacaksınız:
- Doğal dili SQL'e dönüştürmek için GPT istemlerini kullanın.
- Farklı GPT istemleriyle denemeler yapın.
- Daha önce başlatılan PostgreSQL veritabanını sorgulamak için oluşturulan SQL'i kullanın.
- PostgreSQL'den sorgu sonuçlarını döndürerek tarayıcıda görüntüleyin.
Doğal dili SQL'e dönüştürmek için kullanılabilecek farklı GPT istemlerini deneyerek başlayalım.
Doğal Dilden SQL'e Özelliğini Kullanma
Önceki alıştırmada veritabanını, API'leri ve uygulamayı başlattınız. Dosyayı da güncelleştirmişsiniz
.env
. Bu adımları tamamlamadıysanız devam etmeden önce alıştırmanın sonundaki yönergeleri izleyin.Tarayıcıya (http://localhost:4200) Geri dön ve datagrid'in altındaki sayfanın Özel Sorgu bölümünü bulun. Örnek sorgu değerinin zaten dahil olduğuna dikkat edin: Tüm siparişler için toplam geliri alın. Şirkete göre gruplandırın ve şehri dahil edin.
Sorguyu Çalıştır düğmesini seçin. Bu, kullanıcının doğal dil sorgusunu Azure OpenAI'ye geçirerek SQL'e dönüştürür. Sql sorgusu daha sonra veritabanını sorgulamak ve olası sonuçları döndürmek için kullanılır.
Aşağıdaki Özel Sorguyu çalıştırın:
Get the total revenue for Adventure Works Cycles. Include the contact information as well.
API sunucusunu çalıştıran terminal penceresini Visual Studio Code görüntüleyin ve Azure OpenAI'den döndürülen SQL sorgusunu görüntülediğine dikkat edin. JSON verileri sunucu tarafı API'leri tarafından PostgreSQL veritabanını sorgulamak için kullanılır. Sorguya dahil edilen tüm dize değerleri, SQL ekleme saldırılarını önlemek için parametre değerleri olarak eklenir:
{ "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"] }
Tarayıcıya Geri dön ve veri kılavuzunda tüm müşterileri yeniden görüntülemek için Verileri Sıfırla'yı seçin.
Sql Code'a Doğal Dili Keşfetme
İpucu
Visual Studio Code kullanıyorsanız, şunları seçerek dosyaları doğrudan açabilirsiniz:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Ardından açmak istediğiniz dosyanın adını yazın.
Not
Bu alıştırmanın amacı, SQL işlevselliği için doğal dil ile mümkün olan şeyleri göstermek ve kullanmaya nasıl başlanabilmektir. Daha önce belirtildiği gibi, herhangi bir uygulamaya geçmeden önce bu tür yapay zekanın kuruluşunuz için uygun olup olmadığını tartışmanız önemlidir. Yetkisiz erişimi önlemek ve hassas verileri korumak için uygun istem kurallarını ve veritabanı güvenlik önlemlerini planlamak da zorunlu olur .
Sql'e doğal dil özelliğinin nasıl uygulandığını artık inceleyelim.
Sunucu/apiRoutes.ts dosyasını açın ve yolu bulun
generateSql
. Bu API yolu, tarayıcıda çalışan istemci tarafı uygulaması tarafından çağrılır ve doğal dil sorgusundan SQL oluşturmak için kullanılır. SQL sorgusu alındıktan sonra veritabanını sorgulamak ve sonuçları döndürmek için kullanılır.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.' }); } });
Yolda aşağıdaki işlevlere
generateSql
dikkat edin:- kullanıcı sorgu değerini 'den
req.body.query
alır ve adlıuserQuery
bir değişkene atar. Bu değer GPT isteminde kullanılır. - Doğal dili SQL'e dönüştürmek için bir
getSQLFromNLP()
işlev çağırır. - Oluşturulan SQL'i, SQL sorgusunu yürüten ve veritabanından sonuçları döndüren adlı
queryDb
bir işleve geçirir.
- kullanıcı sorgu değerini 'den
Düzenleyicinizde sunucu/openAI.ts dosyasını açın ve işlevi bulun
getSQLFromNLP()
. Bu işlev yol tarafından çağrılırgeneratesql
ve doğal dili SQL'e dönüştürmek için kullanılır.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; }
-
userPrompt
İşleve bir parametre geçirilir.userPrompt
Değer, tarayıcıda kullanıcı tarafından girilen doğal dil sorgusudur. - A
systemPrompt
, kullanılacak yapay zeka yardımcı türünü ve uyulması gereken kuralları tanımlar. Bu, Azure OpenAI'nin veritabanı yapısını, hangi kuralların uygulanacağını ve oluşturulan SQL sorgusunu ve parametrelerini nasıl döndüreceği hakkında bilgi edinmesi için yardımcı olur. - adlı
callOpenAI()
bir işlev çağrılır vesystemPrompt
veuserPrompt
değerleri bu işleve geçirilir. - Sonuçlar, oluşturulan SQL sorgusuna yasaklanmış değerlerin dahil olmadığından emin olmak için denetlenir. Yasaklanmış değerler bulunursa, SQL sorgusu boş bir dizeye ayarlanır.
-
Şimdi sistem isteminde daha ayrıntılı bir şekilde ilerleyelim:
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. `;
Kullanılacak yapay zeka yardımcı türü tanımlanır. Bu durumda bir "SQL botu için doğal dil".
Veritabanındaki tablo adları ve sütunlar tanımlanır. İstemde yer alan üst düzey şema server/db.schema dosyasında bulunabilir ve aşağıdaki gibi görünü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)
İpucu
Yalnızca kullanıcıların SQL'e doğal dil kullanarak sorgulamasına izin verilen verileri içeren salt okunur görünümler oluşturmayı düşünebilirsiniz.
SQL ekleme saldırılarını önlemek için herhangi bir dize değerini parametreli sorgu değerine dönüştürmek için bir kural tanımlanır.
Sql sorgusu ve içindeki parametre değerleriyle her zaman bir JSON nesnesi (ve başka hiçbir şey) döndürmek için bir kural tanımlanır.
Döndürülecek JSON nesnesinin türü için bir örnek verilmiştir.
Örnek kullanıcı istemleri ve beklenen SQL sorgusu ve parametre değerleri sağlanır. Bu, "az çekim" öğrenme olarak adlandırılır. LLM'ler büyük miktarda veri üzerinde eğitilse de, yalnızca birkaç örnekle yeni görevlere uyarlanabilir. Alternatif bir yaklaşım, örnek sağlanmayan ve modelin doğru SQL sorgusunu ve parametre değerlerini oluşturmasının beklendiği "sıfır çekim" öğrenme yaklaşımıdır.
Sistem isteminin alt kısmında iki kritik kural tekrarlanır ve "karşılıklılık yanlılığı" önlenir.
İpucu
Azure OpenAI belgelerinde recency bias hakkında daha fazla bilgi edinin.
işlevi,
getSQLFromNLP()
sistemi ve kullanıcı istemlerini sunucu/openAI.ts dosyasında bulunan adlıcallOpenAI()
bir işleve gönderir. işlevi,callOpenAI()
ortam değişkenlerini denetleyerek Azure OpenAI hizmetinin mi yoksa OpenAI hizmetinin mi çağrılması gerektiğini belirler. Ortam değişkenlerinde bir anahtar, uç nokta ve model varsa Azure OpenAI çağrılır, aksi takdirde OpenAI çağrılır.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); }
Not
Bu öğretici boyunca Azure OpenAI'ye odaklanacağız ancak .env dosyasında yalnızca bir
OPENAI_API_KEY
değer sağlarsanız, uygulama bunun yerine OpenAI kullanır. Azure OpenAI yerine OpenAI kullanmayı seçerseniz bazı durumlarda farklı sonuçlar görebilirsiniz.getAzureOpenAICompletion()
işlevini bulun.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; } }
Bu işlev aşağıdakileri yapar:
systemPrompt
,userPrompt
vetemperature
parametrelerini kabul eder.-
systemPrompt
: Azure OpenAI modelinin hangi rolü oynaması gerektiğini ve hangi kurallara uyması gerektiğini bilmesini sağlar. -
userPrompt
: Uygulamaya girilen doğal dil veya çıkış oluşturmak için model tarafından kullanılacak kurallar gibi kullanıcı bilgileri. -
temperature
: Yanıt oluştururken modelin ne kadar yaratıcı olması gerektiğini belirler. Daha yüksek bir değer, modelin daha fazla risk alacağı anlamına gelir.
-
çağrısı
checkRequiredEnvVars()
yaparak geçerli bir Azure OpenAI API anahtarının, uç noktasının ve modelinin kullanılabilir olmasını sağlar.Azure OpenAI'nin REST API'sini çağırmak için kullanılan bir
fetchUrl
değer oluşturur ve ortam değişkenlerinden uç nokta, model ve API sürüm değerlerini URL'ye ekler.Azure OpenAI'ye göndermek için ,
temperature
vemessages
içerenmax_token
birmessageData
nesne oluşturur.-
max_tokens
: Tamamlanmada oluşturulacak en fazla belirteç sayısı. İsteminizin belirteç sayısı artı max_tokens modelin bağlam uzunluğunu aşamaz. Eski modellerin bağlam uzunluğu 2.048 belirteçken, yeni modeller kullanılan modele bağlı olarak 4.096, 8.192 ve hatta 32.768 belirteci destekler. -
temperature
: Hangi örnekleme sıcaklığının kullanılacağı. Daha yüksek değerler, modelin daha fazla risk alacağı anlamına gelir. Daha yaratıcı uygulamalar için 0,9 ve iyi tanımlanmış bir yanıta sahip olanlar için 0'ı deneyin. -
messages
: Sohbet biçiminde için sohbet tamamlamaları oluşturulacak iletileri temsil eder. Bu örnekte iki ileti geçirilir: biri sistem için, diğeri de kullanıcı için. Sistem iletisi kullanılacak genel davranışı ve kuralları tanımlarken, kullanıcı iletisi kullanıcı tarafından sağlanan istem metnini tanımlar.
-
ve
headersBody
değerlerini Azure OpenAI'yefetchUrl
göndermek için çağrılarfetchAndParse()
.Değeri alarak
completion.choices[0].message.content
yanıtı işler. Yanıt beklenen sonuçları içeriyorsa, kod yanıttan JSON nesnesini ayıklar ve döndürür.Not
Azure OpenAI başvuru belgelerinde bu parametreler ve diğerleri hakkında daha fazla bilgi edinebilirsiniz.
İşlevde aşağıdaki satırları açıklama satırı yapın
getSQLFromNLP()
:// if (isProhibitedQuery(queryData.sql)) { // queryData.sql = ''; // }
openAI.ts kaydedin. API sunucusu TypeScript kodunu otomatik olarak yeniden oluşturur ve sunucuyu yeniden başlatır.
Tarayıcıya Geri dön ve Özel Sorgu girişine Veritabanındaki tüm tablo adlarını seçin yazın. Sorgu Çalıştır'ı seçin. Tablo adları görüntüleniyor mu?
sunucu/openAI.ts işlevine
getSQLFromNLP()
Geri dön ve sistem istemininRules:
bölümüne aşağıdaki kuralı ekleyin ve dosyayı kaydedin.- Do not allow the SELECT query to return table names, function names, or procedure names.
tarayıcıya Geri dön ve aşağıdaki görevleri gerçekleştirin:
- Özel Sorgugirişine Veritabanındaki tüm tablo adlarını seçin yazın. Sorgu Çalıştır'ı seçin. Tablo adları görüntüleniyor mu?
- Veritabanındaki tüm işlev adlarını seçin yazın.Özel Sorgu girişine sorguyu çalıştır'ı yeniden seçin. İşlev adları görüntüleniyor mu?
SORU: Tablo adlarına, işlev adlarına ve yordam adlarına izin verilmediğini belirten bir kural eklendikten sonra bu neden hala çalışıyor?
CEVAP: Bunun nedeni "yalnızca JSON" kuralıdır. Kurallar daha esnekse ve JSON nesnesinin döndürülmesini gerektirmediyse, Azure OpenAI'nin görevi gerçekleştiremediğine ilişkin bir ileti görebilirsiniz.
Not
OpenAI modellerinin bazen tanımladığınız kurallarla eşleşmeyen beklenmeyen sonuçlar döndürebileceğini unutmayın. Kodunuzda bunu planlamak önemlidir.
dosyasından aşağıdaki kuralı
systemPrompt
çıkararak dosyayı kaydedin.- 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.
Veritabanı sorgusundaki tüm tablo adlarını seç'i yeniden çalıştırın.
İletinin artık tarayıcıda görüntülendiğine dikkat edin. Aşağıdaki kural nedeniyle Azure OpenAI görevi gerçekleştiremiyor. "Yalnızca JSON" kuralını kaldırdığımız için yanıt, görevin neden gerçekleştirilemiyorsa ek ayrıntılar sağlayabilir.
- Do not allow the SELECT query to return table names, function names, or procedure names.
Belirli kurallarınız olsa bile yapay zekanın beklenmeyen sonuçlar oluşturabileceğini görebilirsiniz. Bu nedenle, istem metninizi ve kurallarınızı dikkatle planlamanız, ayrıca beklenmeyen sonuçlar aldığınız durumları işlemek için kodunuza bir işlem sonrası adımı eklemeyi planlamanız gerekir.
sunucuya/openAI.ts Geri dön ve işlevi bulun
isProhibitedQuery()
. Bu, Azure OpenAI sonuçları döndürdüğünde çalıştırılabilen işlem sonrası kod örneğidir. Oluşturulan SQL sorgusundasql
yasaklanmış anahtar sözcükler döndürülürse özelliği boş bir dizeye ayarlar. Bu, Azure OpenAI'den beklenmeyen sonuçlar döndürülürse SQL sorgusunun veritabanında çalıştırılmamasını sağlar.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)); }
Not
Bunun yalnızca tanıtım kodu olduğunu unutmayın. Doğal dili SQL'e dönüştürmeyi seçerseniz, belirli kullanım durumlarınızı kapsaması için başka yasaklanmış anahtar sözcükler gerekebilir. Bu, veritabanında yalnızca geçerli SQL sorgularının döndürülmesini ve çalıştırılmasını sağlamak için planlamanız ve dikkatli bir şekilde kullanmanız gereken bir özelliktir. Yasaklanmış anahtar sözcüklere ek olarak, güvenliği de dikkate almanız gerekir.
sunucuya/openAI.ts Geri dön ve işlevde aşağıdaki kodun
getSQLFromNLP()
açıklamasını kaldırın. Dosyayı kaydedin.if (isProhibitedQuery(queryData.sql)) { queryData.sql = ''; }
Aşağıdaki kuralı'ndan
systemPrompt
kaldırın ve dosyayı kaydedin.- Do not allow the SELECT query to return table names, function names, or procedure names.
Tarayıcıya Geri dön Veritabanındaki tüm tablo adlarını seçin ifadesini özel sorgu girişine yeniden girin ve Sorguyu Çalıştır düğmesini seçin.
Tablo sonuçları görüntüleniyor mu? Kural yerinde olmasa bile,
isProhibitedQuery()
işlem sonrası kodu bu tür bir sorgunun veritabanında çalıştırılmasını engeller.Daha önce de açıklandığı gibi, doğal dili iş uygulamaları doğrultusunda SQL ile tümleştirmek kullanıcılar için oldukça yararlı olabilir, ancak kendi dikkate alınması gerekenler kümesiyle birlikte gelir.
Avantaj -ları:
Kullanıcı dostu olma: Bu özellik, veritabanı etkileşimini teknik uzmanlığa sahip olmayan kullanıcılar için daha erişilebilir hale getirerek SQL bilgisi ihtiyacını azaltabilir ve işlemleri hızlandırabilir.
Artan üretkenlik: İş analistleri, pazarlamacılar, yöneticiler ve diğer teknik olmayan kullanıcılar, teknik uzmanlara güvenmek zorunda kalmadan veritabanlarından değerli bilgileri alabilir ve böylece verimliliği artırabilir.
Geniş uygulama: Gelişmiş dil modelleri kullanılarak, uygulamalar çok çeşitli kullanıcılara ve kullanım örneklerine uygun olacak şekilde tasarlanabilir.
Husus -lar:
Güvenlik: En büyük endişelerden biri güvenliktir. Kullanıcılar doğal dil kullanarak veritabanlarıyla etkileşim kurabiliyorsa yetkisiz erişimi veya kötü amaçlı sorguları önlemek için sağlam güvenlik önlemlerinin alınması gerekir. Kullanıcıların verileri değiştirmesini önlemek için salt okunur bir mod uygulamayı düşünebilirsiniz.
Veri Gizliliği: Belirli veriler hassas olabilir ve kolayca erişilmemelidir, bu nedenle uygun korumaların ve kullanıcı izinlerinin sağlandığından emin olmanız gerekir.
Doğruluk: Doğal dil işleme önemli ölçüde geliştirilmiş olsa da mükemmel değildir. Kullanıcı sorgularının yanlış yorumlanması yanlış sonuçlara veya beklenmeyen davranışlara yol açabilir. Beklenmeyen sonuçların nasıl işlendiğini planlamanız gerekir.
Verimlilik: Doğal dil sorgusundan döndürülen SQL'in verimli olacağının garantisi yoktur. Bazı durumlarda, işlem sonrası kuralları SQL sorgularıyla ilgili sorunları algılarsa Azure OpenAI'ye yönelik ek çağrılar gerekebilir.
Eğitim ve Kullanıcı Uyarlaması: Kullanıcıların sorgularını doğru şekilde formüle etmek için eğitilmesi gerekir. SQL öğrenmekten daha kolay olsa da bir öğrenme eğrisi söz konusu olabilir.
Sonraki alıştırmaya geçmeden önce dikkate alınması gereken birkaç son nokta:
- Unutmayın, "Çünkü bunu yapmalısınız anlamına gelmez" burada geçerlidir. Doğal dili SQL ile bir uygulamayla tümleştirmeden önce çok dikkatli ve dikkatli planlama yapın. Olası riskleri anlamak ve bunları planlamak önemlidir.
- Bu tür bir teknolojiyi kullanmadan önce, kuruluşunuz için uygun olduğundan emin olmak için ekibiniz, veritabanı yöneticileriniz, güvenlik ekibi, proje katılımcıları ve diğer ilgili taraflarla olası senaryoları tartışın. SQL'de doğal dilin güvenlik, gizlilik ve kuruluşunuzun karşılamış olabileceği diğer gereksinimleri karşılayıp karşılamamadığını tartışmanız önemlidir.
- Güvenlik öncelikli bir konu olmalı ve planlama, geliştirme ve dağıtım sürecini temel almalıdır.
- SQL'e doğal dil çok güçlü olsa da, istemlerin gerekli kurallara sahip olduğundan ve işlem sonrası işlevselliğin dahil olduğundan emin olmak için dikkatli bir planlama yapılmalıdır. Bu tür işlevleri uygulamak ve test etmek ve beklenmeyen sonuçların döndürüldüğü senaryoları hesaba eklemek için ek süre planlayın.
- Azure OpenAI ile müşteriler, OpenAI ile aynı modelleri çalıştırırken Microsoft Azure'ın güvenlik özelliklerine sahip olur. Azure OpenAI özel ağ, bölgesel kullanılabilirlik ve sorumlu yapay zeka içerik filtrelemesi sunar. Azure OpenAI Hizmeti için veriler, gizlilik ve güvenlik hakkında daha fazla bilgi edinin.
Artık doğal dili SQL'e dönüştürmek için Azure OpenAI'yi nasıl kullanacağınızı gördünüz ve bu tür işlevleri uygulamanın avantajları ve dezavantajları hakkında bilgi edindiniz. Sonraki alıştırmada Azure OpenAI kullanılarak e-posta ve SMS iletilerinin nasıl oluşturulabileceğini öğreneceksiniz.
Yapay Zeka: Tamamlamalar Oluşturma
Sql'e doğal dil özelliğine ek olarak, kullanıcı üretkenliğini artırmak ve iletişim iş akışlarını kolaylaştırmak için e-posta ve SMS iletileri oluşturmak için Azure OpenAI Hizmeti'ni de kullanabilirsiniz. Kullanıcılar, Azure OpenAI'nin dil oluşturma özelliklerini kullanarak "Sipariş 5 gün geciktirildi" gibi belirli kurallar tanımlayabilir ve sistem bu kurallara göre bağlamsal olarak uygun e-posta ve SMS iletilerini otomatik olarak oluşturur.
Bu özellik kullanıcılar için bir "hızlı başlangıç" işlevi görür ve göndermeden önce kolayca özelleştirebilecekleri, özenle hazırlanmış bir ileti şablonu sağlar. Sonuç, iletileri oluşturmak için gereken zaman ve çabada önemli bir azalmadır ve kullanıcıların diğer önemli görevlere odaklanmasına olanak sağlar. Ayrıca, Azure OpenAI'nin dil oluşturma teknolojisi otomasyon iş akışlarıyla tümleştirilebilir ve sistemin önceden tanımlanmış tetikleyicilere yanıt olarak otonom olarak ileti oluşturmasını ve göndermesini sağlar. Bu otomasyon düzeyi yalnızca iletişim süreçlerini hızlandırmakla kalmaz, aynı zamanda çeşitli senaryolarda tutarlı ve doğru mesajlaşma sağlar.
Bu alıştırmada şunları yapacaksınız:
- Farklı GPT istemleriyle denemeler yapın.
- E-posta ve SMS iletileri için tamamlamalar oluşturmak için GPT istemlerini kullanın.
- GPT tamamlamalarını etkinleştiren kodu keşfedin.
- İstem mühendisliğinin önemi ve istemlerinize kurallar ekleme hakkında bilgi edinin.
E-posta ve SMS iletileri oluşturmak için kullanılabilecek farklı kurallarla denemeler yaparak başlayalım.
GPT Tamamlamaları Özelliğini Kullanma
Önceki alıştırmada veritabanını, API'leri ve uygulamayı başlatmıştınız. Dosyayı da güncelleştirmişsiniz
.env
. Bu adımları tamamlamadıysanız devam etmeden önce alıştırmanın sonundaki yönergeleri izleyin.Tarayıcıya (http://localhost:4200) Geri dön ve İleti Oluşturucu ekranına ulaşmak için datagrid'deki herhangi bir satırda Müşteriyle İletişim Kur'u ve ardından Email/SMS Müşterisi'ni seçin.
Bu, tanımladığınız ileti kurallarını Email/SMS iletilerine dönüştürmek için Azure OpenAI kullanır. Aşağıdaki görevleri gerçekleştirin:
Girişe Sipariş 5 gün geciktirildi gibi bir kural girin ve Email/SMS İletileri Oluştur düğmesini seçin.
E-posta için oluşturulan bir konu ve gövde ile SMS için oluşturulan kısa bir ileti görürsünüz.
Not
Azure İletişim Hizmetleri henüz etkinleştirilmediğinden, e-postayı veya SMS iletilerini gönderemezsiniz.
Tarayıcıda e-posta/SMS iletişim kutusunu kapatın. Şimdi bu özelliğin nasıl uygulandığını inceleyelim.
GPT Tamamlama Kodunu Keşfetme
İpucu
Visual Studio Code kullanıyorsanız, şunları seçerek dosyaları doğrudan açabilirsiniz:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Ardından açmak istediğiniz dosyanın adını yazın.
Sunucu/apiRoutes.ts dosyasını açın ve yolu bulun
completeEmailSmsMessages
. Bu API, Email/SMS İletileri Oluştur düğmesi seçildiğinde uygulamanın ön uç bölümü tarafından çağrılır. Kullanıcı istemi, şirket ve kişi adı değerlerini gövdeden alır ve bunları sunucu/openAI.ts dosyasındaki işlevecompleteEmailSMSMessages()
geçirir. Sonuçlar daha sonra istemciye döndürülür.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); });
server/openAI.ts dosyasını açın ve işlevini bulun
completeEmailSMSMessages()
.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; }
Bu işlev aşağıdaki özelliklere sahiptir:
-
systemPrompt
E-posta ve SMS mesajları oluşturabilen bir yapay zeka yardımcı gerekli olduğunu tanımlamak için kullanılır. ayrıcasystemPrompt
şunları içerir:- İletilerin tonunu, başlangıç ve bitiş biçimini, SMS iletilerinin maksimum uzunluğunu ve daha fazlasını denetlemek için izleyebileceğiniz yardımcı kuralları.
- Yanıta eklenmesi gereken veriler hakkında bilgi : bu örnekte bir JSON nesnesi ve yalnızca JSON nesnesi.
- Sistem isteminin alt kısmında iki kritik kural tekrarlanır ve "karşılıklılık yanlılığı" önlenir.
-
userPrompt
, son kullanıcının e-posta ve SMS iletileri oluşturulurken eklemek istediğiniz kuralları ve kişi adını tanımlamak için kullanılır. Sipariş 5 gün gecikir kuralına daha önce girdiğiniz kural ekleniruserPrompt
. - işlevi, e-posta ve SMS tamamlamalarını oluşturmak için daha önce incelediğiniz işlevi çağırır
callOpenAI()
.
-
Tarayıcıya Geri dön sayfayı yenileyin ve İleti Oluşturucu ekranına yeniden ulaşmak için herhangi bir satırda Müşteriyle iletişime geçin'i ve ardından Email/SMS Müşterisi'ni seçin.
İleti Oluşturucu girişine aşağıdaki kuralları girin:
- Sipariş, zamanlamanın önüne geçti.
- Müşteriye bir daha bizden sipariş vermemesini söyleyin.
Email/SMS Mesajları Oluştur'a tıklayın ve iletiyi not edin.
All messages should have a friendly tone and never use inappropriate language.
Sistem istemindeki kural, kullanıcı istemindeki negatif kuralı geçersiz kılıyor.Düzenleyicinizde sunucuya/openAI.ts* Geri dön ve kuralı işlevdeki
completeEmailSMSMessages()
isteminden kaldırınAll messages should have a friendly tone and never use inappropriate language.
. Dosyayı kaydedin.Tarayıcıda e-posta/SMS ileti oluşturucusunun Geri dön ve aynı kuralları yeniden çalıştırın:
- Sipariş, zamanlamanın önüne geçti.
- Müşteriye bir daha bizden sipariş vermemesini söyleyin.
Email/SMS İletileri Oluştur'a tıklayın ve döndürülen iletiye dikkat edin.
Bu senaryolarda neler oluyor? Azure OpenAI kullanırken, uygun dilin her zaman kullanıldığından emin olmak için içerik filtreleme uygulanır. OpenAI kullanıyorsanız, döndürülen iletinin uygun olduğundan emin olmak için sistem isteminde tanımlanan kural kullanılır.
Not
Bu, doğru sonuçların döndürülmesini sağlamak için istemlerinizi doğru bilgiler ve kurallarla tasarlamanın önemini gösterir. Bu işlem hakkında daha fazla bilgi için bkz. Bilgi istemi mühendisliğine giriş belgeleri.
içinde
completeEmailSMSMessages()
yaptığınızsystemPrompt
değişiklikleri geri alın, dosyayı kaydedin ve yeniden çalıştırın, ancak yalnızca kuralı kullanınOrder is ahead of schedule.
(negatif kuralı dahil etmeyin). Bu kez e-posta ve SMS iletilerinin beklendiği gibi döndürüldiğini görmeniz gerekir.Sonraki alıştırmaya geçmeden önce dikkate alınması gereken birkaç son nokta:
- Oluşturulan iletileri gözden geçirmek için döngüde bir insanın olması önemlidir. Bu örnekte Azure OpenAI tamamlamaları önerilen e-posta ve SMS iletilerini döndürür, ancak kullanıcı gönderilmeden önce bunları geçersiz kılabilir. E-postaları otomatikleştirmeyi planlıyorsanız, onaylanan iletilerin gönderilmesini sağlamak için bir tür insan inceleme sürecine sahip olmak önemlidir. Yapay zekayı otomatik pilot değil copilot olarak görün.
- Tamamlamalar yalnızca istemde eklediğiniz kurallar kadar iyi olacaktır. İstemlerinizi ve döndürülen tamamlamaları test etmek için zaman alın. Diğer proje katılımcılarını da tamamlamaları gözden geçirmeye davet edin.
- Beklenmeyen sonuçların düzgün şekilde işlenmesini sağlamak için işlem sonrası kodu eklemeniz gerekebilir.
- Yapay zeka yardımcı uyması gereken kuralları ve bilgileri tanımlamak için sistem istemlerini kullanın. Son kullanıcının tamamlamalara eklemek istediğiniz kuralları ve bilgileri tanımlamak için kullanıcı istemlerini kullanın.
AI: Kendi Verilerinizi Getirin
Azure OpenAI Doğal Dil İşleme (NLP) ve tamamlama özelliklerinin tümleştirilmesi, kullanıcı üretkenliğini artırmaya yönelik önemli bir potansiyel sunar. Yapay zeka yardımcı, uygun istemlerden ve kurallardan yararlanarak e-posta iletileri, SMS mesajları ve daha fazlası gibi çeşitli iletişim biçimlerini verimli bir şekilde oluşturabilir. Bu işlevsellik, kullanıcı verimliliğinin ve kolaylaştırılmış iş akışlarının artmasına yol açar.
Bu özellik kendi başına oldukça güçlü olsa da, kullanıcıların şirketinizin özel verilerine göre tamamlamalar oluşturması gereken durumlar olabilir. Örneğin, kullanıcıların müşterilere yükleme sorunları konusunda yardımcı olduklarında gezinmeleri zor olabilecek bir ürün kılavuzları koleksiyonunuz olabilir. Alternatif olarak, kullanıcıların okuması ve ihtiyaç duydukları yanıtları alması zor olabilecek sağlık hizmetleri avantajlarıyla ilgili kapsamlı bir dizi Sık Sorulan Sorular (SSS) bulundurabilirsiniz. Bu gibi durumlarda ve diğer birçok durumda Azure OpenAI Hizmeti, tamamlamalar oluşturmak için kendi verilerinizden yararlanmanıza olanak tanır ve kullanıcı sorularına daha uyarlanmış ve bağlamsal olarak doğru bir yanıt sağlar.
Azure OpenAI belgelerinden "kendi verilerinizi getirin" özelliğinin nasıl çalıştığına hızlı bir genel bakış aşağıda verilmiştir.
Not
Azure OpenAI'nin verilerinizdeki temel özelliklerinden biri, verileri modelin çıkışını geliştirecek şekilde alıp kullanabilmesidir. Verilerinizde Azure OpenAI, Azure Bilişsel Arama ile birlikte kullanıcı girişine ve sağlanan konuşma geçmişine göre belirlenen veri kaynağından hangi verilerin alındığını belirler. Bu veriler daha sonra genişletilir ve OpenAI modeline bir istem olarak yeniden gönderilir ve alınan bilgiler özgün istemin sonuna eklenir. Alınan veriler istemin sonuna eklense de, sonuçta elde edilen giriş diğer istemler gibi model tarafından yine işlenir. Veriler alındıktan ve istem modele gönderildikten sonra, model tamamlama sağlamak için bu bilgileri kullanır.
Bu alıştırmada şunları yapacaksınız:
- Azure Yapay Zeka Stüdyosu kullanarak özel bir veri kaynağı oluşturun.
- Azure Yapay Zeka Stüdyosu kullanarak ekleme modeli dağıtma.
- Özel belgeleri karşıya yükleyin.
- Kendi verilerinize göre tamamlamalar oluşturmayı denemek için Sohbet oyun alanında bir sohbet oturumu başlatın.
- Kendi verilerinize dayalı tamamlamalar oluşturmak için Azure Bilişsel Arama ve Azure OpenAI kullanan kodu keşfedin.
Ekleme modeli dağıtarak ve Azure Yapay Zeka Stüdyosu özel veri kaynağı ekleyerek başlayalım.
Azure Yapay Zeka Stüdyosu'a Özel Veri Kaynağı Ekleme
Azure OpenAI Studio'ya gidin ve Azure OpenAI kaynağınıza erişimi olan kimlik bilgileriyle oturum açın.
Gezinti menüsünden Dağıtımlar'ı seçin.
Yeni dağıtım oluştur'u seçin ve aşağıdaki değerleri girin:
- Model: text-embedding-ada-002.
- Model sürümü: Varsayılan.
- Dağıtım adı: text-embedding-ada-002.
Model oluşturulduktan sonra hoş geldiniz ekranına gitmek için gezinti menüsünden Azure OpenAI'yi seçin.
Hoş geldiniz ekranında Kendi verilerinizi getirin kutucuğunu bulun ve Şimdi deneyin'i seçin.
Veri kaynağı seçin açılan listesinden Dosyaları karşıya yükle'yi seçin.
Azure Blob depolama kaynağını seçin açılan listesinde Yeni Azure Blob depolama kaynağı oluştur'u seçin.
Bu sizi aşağıdaki görevleri gerçekleştirebileceğiniz Azure portal götürür:
- Depolama hesabı için byodstorage[Soyadınız] gibi benzersiz bir ad girin.
- Konumunuza yakın bir bölge seçin.
- Gözden Geçir'i ve ardından Oluştur'u seçin.
Blob depolama kaynağı oluşturulduktan sonra Azure Yapay Zeka Stüdyosu iletişim kutusuna dönün ve Azure Blob depolama kaynağını seçin açılan listesinden yeni oluşturulan blob depolama kaynağınızı seçin. Listede görmüyorsanız açılan listenin yanındaki yenile simgesini seçin.
Depolama hesabınıza erişilebilmesi için çıkış noktaları arası kaynak paylaşımının (CORS) açık olması gerekir. Azure Yapay Zeka Stüdyosu iletişim kutusunda CORS'yi aç'ı seçin.
Azure Bilişsel Arama kaynağı seçin açılan listesinde Yeni Azure Bilişsel Arama kaynağı oluştur'u seçin.
Bu sizi aşağıdaki görevleri gerçekleştirebileceğiniz Azure portal geri götürür:
- Bilişsel Arama kaynağı için byodsearch[Soyadınız] gibi benzersiz bir ad girin.
- Konumunuza yakın bir bölge seçin.
- Fiyatlandırma katmanı bölümünde Fiyatlandırma KatmanınıDeğiştir'i ve ardından Temel'i ve ardından Seç'i seçin. Ücretsiz katman desteklenmez, bu nedenle bu öğreticinin sonunda Bilişsel Arama kaynağını temizleyeceksiniz.
- Gözden Geçir'i ve ardından Oluştur'u seçin.
Bilişsel Arama kaynağı oluşturulduktan sonra kaynağa Genel Bakış sayfasına gidin ve Url değerini yerel bir dosyaya kopyalayın.
Sol gezinti menüsünde Anahtarlar'ı seçin ve Birincil yönetici anahtarı değerini yerel bir dosyaya kopyalayın. Alıştırmanın ilerleyen bölümlerinde bu değerlere ihtiyacınız olacak.
Sol gezinti menüsünden Anlam dereceleyicisi'ni seçin ve Ücretsiz seçeneğinin belirlendiğinden emin olun.
Not
Semantik dereceleyicinin belirli bir bölgede kullanılabilir olup olmadığını denetlemek için Bölgenizin listelenip listelenmediğini görmek için Azure web sitesindeki Bölgeye Göre Kullanılabilir Ürünler sayfasını gözden geçirin .
Azure Yapay Zeka Stüdyosu Veri Ekle iletişim kutusuna Geri dön ve Azure Bilişsel Arama kaynağı seç açılan listesinden yeni oluşturduğunuz arama kaynağını seçin. Listede görmüyorsanız açılan listenin yanındaki yenile simgesini seçin.
Dizin adını girin değeri için byod-search-index değerini girin.
Bu arama kaynağına vektör araması ekle onay kutusunu seçin.
Ekleme modeli seçin açılan listesinde, daha önce oluşturduğunuz text-embedding-ada-002 modelini seçin.
Onay kutusunu ve ardından İleri'yi seçin.
Dosyaları karşıya yükle iletişim kutusunda Dosyaya gözat'ı seçin.
Projenin müşteri belgeleri klasörüne gidin (projenin kökünde bulunur) ve aşağıdaki dosyaları seçin:
- Saat A102 Yükleme Instructions.docx
- Şirket FAQs.docx
Not
Bu özellik şu anda yerel dizin oluşturmak için şu dosya biçimlerini destekler: .txt, .md, .html, .pdf, .docx ve .pptx.
Dosyaları karşıya yükle'yi seçin. Dosyalar, daha önce oluşturduğunuz blob depolama kaynağındaki fileupload-byod-search-index kapsayıcısına yüklenir.
Veri yönetimi iletişim kutusuna gitmek için İleri'yi seçin.
Arama türü açılan listesinde Karma + semantik'i seçin.
Not
Bu seçenek anahtar sözcük ve vektör araması için destek sağlar. Sonuçlar döndürüldükten sonra, derin öğrenme modelleri kullanılarak sonuç kümesine ikincil bir derecelendirme işlemi uygulanır ve bu da kullanıcının arama ilgi düzeyini artırır. Anlam arama hakkında daha fazla bilgi edinmek için Azure Bilişsel Arama belgelerinde Anlamsal arama'yı görüntüleyin.
Anlamsal arama ve vektör eklemelerini kullanmayla ilişkili maliyetleri onaylamak için onay kutularını seçin.
İleri'yi seçin, ayrıntıları gözden geçirin ve Kaydet ve kapat'ı seçin.
Artık özel verileriniz karşıya yüklendiğinden, veriler dizine alınacaktır ve Sohbet oyun alanında kullanılabilir. Bu işlem birkaç dakika sürebilir. İşlem tamamlandıktan sonra sonraki bölüme geçin.
Sohbet Oyun Alanında Özel Veri Kaynağınızı Kullanma
Azure Yapay Zeka Stüdyosu'da sayfanın Sohbet oturumu bölümünü bulun ve aşağıdaki Kullanıcı iletisini girin:
What safety rules are required to install a clock?
Aşağıdakine benzer bir sonuç görüntülenmelidir:
Sohbet yanıtında 1 başvuru bölümünü genişletin ve Saat A102 Yükleme Instructions.docx dosyasının listelendiğine ve belgeyi görüntülemek için seçebileceğinize dikkat edin.
Aşağıdaki Kullanıcı iletisini girin:
What should I do to mount the clock on the wall?
Aşağıdakine benzer bir sonuç görüntülenmelidir:
Şimdi Şirket hakkında SSS belgesini deneyelim. Kullanıcı iletisi alanına aşağıdaki metni girin:
What is the company's policy on vacation time?
Bu istek için hiçbir bilgi bulunamadığını görmeniz gerekir.
Kullanıcı iletisi alanına aşağıdaki metni girin:
How should I handle refund requests?
Aşağıdakine benzer bir sonuç görüntülenmelidir:
Sohbet yanıtında 1 başvuru bölümünü genişletin ve Şirket FAQs.docx dosyasının listelendiğine ve belgeyi görüntülemek için seçebileceğinize dikkat edin.
Sohbet oturumu bölümünün üst kısmındaki Kodu görüntüle'yi seçin.
Farklı diller arasında geçiş yapabileceğinizi, uç noktayı görüntüleyebileceğinizi ve uç noktanın anahtarına erişebileceğinizi unutmayın. Örnek Kod iletişim kutusunu kapatın.
*Sohbet oturumundaHam JSON göster iki durumlu düğmesini açın. Sohbet oturumunun aşağıdakine benzer bir iletiyle başladığına dikkat edin:
{ "role": "system", "content": "You are an AI assistant that helps people find information." }
Artık sohbet oyun alanında özel bir veri kaynağı oluşturduğunuza ve bu kaynakla denemeler yaptığınıza göre, şimdi bunu projenin uygulamasında nasıl kullanabileceğinizi görelim.
Uygulamada Kendi Verilerinizi Getir Özelliğini Kullanma
Visual Studio Code'da projeye Geri dön ve .env dosyasını açın. Bilişsel Hizmetler uç noktanız, anahtarınız ve dizin adınızla aşağıdaki değerleri güncelleştirin. Bu alıştırmanın önceki bölümlerinde uç noktayı ve anahtarı yerel bir dosyaya kopyalamıştınız.
AZURE_COGNITIVE_SEARCH_ENDPOINT=<COGNITIVE_SERVICES_ENDPOINT_VALUE> AZURE_COGNITIVE_SEARCH_KEY=<COGNITIVE_SERVICES_KEY_VALUE> AZURE_COGNITIVE_SEARCH_INDEX=byod-search-index
Önceki bir alıştırmada veritabanını, API'leri ve uygulamayı başlattınız. Ayrıca dosyayı güncelleştirmişsinizdir
.env
. Bu adımları tamamlamadıysanız devam etmeden önce önceki alıştırmanın sonundaki yönergeleri izleyin.Uygulama tarayıcıya yüklendikten sonra uygulamanın sağ üst köşesindeki Sohbet Yardımı simgesini seçin.
Sohbet iletişim kutusunda aşağıdaki metin görüntülenmelidir:
How should I handle refund requests?
Yardım Al düğmesini seçin. Daha önce Azure Yapay Zeka Stüdyosu'da karşıya yüklediğiniz Şirket FAQs.docx belgesinden döndürülen sonuçları görmeniz gerekir. Belgeyi okumak isterseniz, projenin kökündeki müşteri belgeleri klasöründe bulabilirsiniz.
Metni aşağıdaki şekilde değiştirin ve Yardım Al düğmesini seçin:
What safety rules are required to install a clock?
Daha önce Azure Yapay Zeka Stüdyosu'de karşıya yüklediğiniz Saat A102 Yükleme Instructions.docx belgesinden döndürülen sonuçları görmeniz gerekir. Bu belge, projenin kökündeki müşteri belgeleri klasöründe de kullanılabilir.
Kodu Keşfetme
İpucu
Visual Studio Code kullanıyorsanız, şunları seçerek dosyaları doğrudan açabilirsiniz:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Ardından açmak istediğiniz dosyanın adını yazın.
Visual Studio Code'daki proje kaynak koduna Geri dön.
sunucu/apiRoutes.ts dosyasını açın ve yolu bulun
completeBYOD
. Bu API, Sohbet Yardımı iletişim kutusunda Yardım Al düğmesi seçildiğinde çağrılır. İstek gövdesinden kullanıcı istemini alır ve sunucu/openAI.ts dosyasındaki işlevecompleteBYOD()
geçirir. Ardından sonuçlar istemciye döndürülür.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); });
server/openAI.ts dosyasını açın ve işlevini bulun
completeBYOD()
.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); }
Bu işlev aşağıdaki özelliklere sahiptir:
- parametresi,
userPrompt
kullanıcının sohbet yardımı iletişim kutusuna yazdığı bilgileri içerir. -
systemPrompt
değişkeni, kişilerin bilgileri bulmasına yardımcı olmak için tasarlanmış bir yapay zeka yardımcı kullanılacağını tanımlar. -
callOpenAI()
, Azure OpenAI API'sini çağırmak ve sonuçları döndürmek için kullanılır. Aşağıdaki parametrelerinsystemPrompt
yanı sıra veuserPrompt
değerlerini geçirir:-
temperature
- Yanıta eklenecek yaratıcılık miktarı. Kullanıcının bu durumda tutarlı (daha az yaratıcı) yanıtlara ihtiyacı olduğundan değer 0 olarak ayarlanır. -
useBYOD
- Bilişsel Arama'nın Azure OpenAI ile birlikte kullanılıp kullanılmayacağını gösteren boole değeri. Bu durumda, Bilişsel Arama işlevselliğinin kullanılabilmesi içintrue
olarak ayarlanır.
-
- parametresi,
işlevi
callOpenAI()
, çağrılacak OpenAI işlevini belirlemek için kullanılan biruseBYOD
parametreyi kabul eder. Bu durumda işlevingetAzureOpenAIBYODCompletion()
çağrılacağı şekildetrue
olarak ayarlanıruseBYOD
.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()
sunucu/openAI.ts işlevini bulun. Daha önce incelediğiniz işlevegetAzureOpenAICompletion()
oldukça benzer, ancak Azure OpenAI'de kullanılabilen "kendi verilerinizi getirin" senaryosuna özgü birkaç önemli farkı vurgulamak için ayrı bir işlev olarak gösterilir.Değer URL'de
fetchUrl
birextensions
kesim içerirken standart Azure OpenAI API'sinin URL'si içermez.const fetchUrl = `${OPENAI_ENDPOINT}/openai/deployments/${OPENAI_MODEL}/extensions/chat/completions?api-version=${OPENAI_API_VERSION}`;
dataSources
Azure OpenAI'yemessageData
gönderilen nesneye bir özellik eklenir. özelliği,dataSources
bu alıştırmanın önceki bölümlerinde dosyaya eklenen Bilişsel Arama kaynağınınendpoint
.env
,key
veindexName
değerlerini içerir.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 } } ] };
Nesnesi,
headersBody
Bilişsel Arama sonuçları alındıktan sonra Azure OpenAI'yi çağırmak için kullanılan vechatgpt_key
özelliklerini içerirchatpgpt_url
.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), };
Azure OpenAI tarafından döndürülen yanıt, ve
assistant
rollerinetool
sahip iki dağınıklık içerir. Örnek uygulama, kullanıcıya istediği bilgileri sağlamak için ile ikinci iletiyirole
assistant
kullanır. Yanıtı oluşturmak için kullanılan belgeler hakkında ek bilgi sağlamak istediğiniz durumlarda (daha önce Azure Yapay Zeka Stüdyosu oyun alanında gördüğünüz gibi), belgeleri içerenurl
ilk iletiyi kullanabilirsiniz.{ "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 } ] } ] }
İletilere erişmek için içinde
getAzureOpenAIBYODCompletion()
aşağıdaki kod kullanılır. Alıntılar bu örnekte kullanılmasa da, döndürülen veri türünü görebilmeniz için konsolda günlüğe kaydedilir.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;
Sonraki alıştırmaya geçmeden önce dikkate alınması gereken birkaç son nokta:
- Azure OpenAI'nin "kendi verilerinizi getirin" özelliği şu anda önizleme aşamasındadır. Şu anda üretim uygulamalarında kullanılması önerilmez.
- Örnek uygulama Azure Bilişsel Arama'de tek bir dizin kullanır. Azure OpenAI ile birden çok dizin ve veri kaynağı kullanabilirsiniz.
dataSources
işlevindekigetAzureOpenAIBYODCompletion()
özelliği, gerektiğinde birden çok veri kaynağı içerecek şekilde güncelleştirilebilir. - Güvenlik, bu tür senaryolarla dikkatle değerlendirilmelidir. Kullanıcılar soru sormamalı ve erişemedikleri belgelerden sonuç alamamalıdır.
Azure OpenAI, istemler, tamamlamalar ve kendi verilerinizi nasıl kullanabileceğinizi öğrendiğinize göre, uygulamayı geliştirmek için iletişim özelliklerinin nasıl kullanılabileceğini öğrenmek için bir sonraki alıştırmaya geçelim. Azure OpenAI hakkında daha fazla bilgi edinmek isterseniz Azure OpenAI Hizmeti ile çalışmaya başlama eğitim içeriğini görüntüleyin. Azure OpenAI ile kendi verilerinizi kullanma hakkında ek bilgileri , veri belgelerinizdeki Azure OpenAI'de bulabilirsiniz.
İletişim: Azure İletişim Hizmetleri Kaynağı Oluşturma
Etkili iletişim, başarılı özel iş uygulamaları için gereklidir. Azure İletişim Hizmetleri (ACS) kullanarak uygulamalarınıza telefon aramaları, canlı sohbet, sesli/görüntülü aramalar, e-posta ve SMS mesajlaşması gibi özellikler ekleyebilirsiniz. Daha önce, Azure OpenAI'nin e-posta ve SMS iletileri için tamamlamaları nasıl oluşturabileceğini öğrendiniz. Şimdi iletileri nasıl göndereceğinizi öğreneceksiniz. ACS ve OpenAI birlikte iletişimi basitleştirerek, etkileşimleri geliştirerek ve iş üretkenliğini artırarak uygulamalarınızı geliştirebilir.
Bu alıştırmada şunları yapacaksınız:
- bir Azure İletişim Hizmetleri (ACS) kaynağı oluşturun.
- Arama ve SMS özellikleriyle ücretsiz bir telefon numarası ekleyin.
- E-posta etki alanını bağlama.
- Projenin .env dosyasını ACS kaynağınızdaki değerlerle güncelleştirin.
Azure İletişim Hizmetleri Kaynağı Oluşturma
Tarayıcınızda Azure portal ziyaret edin ve henüz yapmadıysanız oturum açın.
Sayfanın üst kısmındaki arama çubuğunailetişim hizmetleri yazın ve görüntülenen seçeneklerden İletişim Hizmetleri'ni seçin.
Araç çubuğunda Oluştur'u seçin.
Aşağıdaki görevleri gerçekleştirin:
- Azure aboneliğinizi seçin.
- Kullanılacak kaynak grubunu seçin (yoksa yeni bir grup oluşturun).
- Bir ACS kaynak adı girin. Bu, benzersiz bir değer olmalıdır.
- Bir veri konumu seçin.
Gözden Geçir + Oluştur'u ve ardından Oluştur'u seçin.
Yeni bir Azure İletişim Hizmetleri kaynağını başarıyla oluşturdunuz! Ardından, telefon araması ve SMS özelliklerini etkinleştireceksiniz. Ayrıca kaynağa bir e-posta etki alanı bağlayacaksınız.
Telefon Araması ve SMS Özelliklerini Etkinleştirme
Bir telefon numarası ekleyin ve telefon numarasında arama özelliklerinin etkinleştirildiğinden emin olun. Bu telefon numarasını, uygulamadan bir telefona çağrı yapmak için kullanacaksınız.
Kaynak menüsünden öğesini seçin
Phone numbers
.Araç çubuğunda öğesini seçin
+ Get
(veya Sayı al düğmesini seçin) ve aşağıdaki bilgileri girin:-
Ülke veya bölge:
United States
-
Kullanım örneği:
An application will be making calls or sending SMS mesages
- Sayı türü: Ücretsiz
Not
Ücretsiz numarayı oluşturmak için Azure aboneliğinizde bir kredi kartı gereklidir. Dosyada kart yoksa, telefon numarası eklemeyi atlayıp alıştırmanın bir e-posta etki alanını bağlayan sonraki bölümüne atlayabilirsiniz. Uygulamayı kullanmaya devam edebilirsiniz, ancak telefon numarasını arayamazsınız.
-
Arama:
Make calls
-
SMS:
Send and receive SMS
-
Ülke veya bölge:
İleri: Sayılar'ı seçin.
Bir Ön Ek seçin (örneğin
877
) ve Quantity değerini 1 olarak bırakın. Ara’yı seçin.Ücretsiz bir numara görüntülendiğinde İleri: Özet'i seçin.
Ayrıntıları gözden geçirin ve SIPARIŞ ver'i seçerek telefon numarasını ACS kaynağınıza ekleyin.
Telefon numarası oluşturulduktan sonra Özellikler paneline ulaşmak için numarayı seçin. Aşağıdaki değerlerin ayarlandığından emin olun:
-
Arama bölümünde öğesini seçin
Make calls
. -
SMS bölümünde öğesini seçin
Send and receive SMS
. - Kaydet’i seçin.
-
Arama bölümünde öğesini seçin
Telefon numarası değerini daha sonra kullanmak üzere bir dosyaya kopyalayın.
Email Etki Alanı Bağlama
E-posta gönderebilmeniz için ACS kaynağınız için bağlı bir e-posta etki alanı oluşturmak üzere aşağıdaki görevleri gerçekleştirin. Bu, uygulamadan e-posta göndermek için kullanılır.
- Kaynak menüsünden Etki Alanları'nı seçin.
- Araç çubuğundan Etki alanını bağla'yı seçin.
- Abonelik ve Kaynak grubunuzu seçin.
-
Email Hizmeti açılan listesinde öğesini seçin
Add an email service
. - E-posta hizmetine gibi
acs-demo-email-service
bir ad verin. - öğesini ve ardından
Create
öğesini seçinReview + create
. - Dağıtım tamamlandıktan sonra öğesini seçin
Go to resource
ve ücretsiz bir Azure alt etki alanı eklemek için öğesini seçin1-click add
. - Alt etki alanı eklendikten sonra (dağıtılması birkaç dakika sürer), seçin.
- AzureManagedDomain ekranına geldikten sonra, Kaynak menüsünden MailFrom adresleri'ni seçin.
- MailFrom değerini bir dosyaya kopyalayın. Daha sonra .env dosyasını güncelleştirirken kullanacaksınız.
- Azure İletişim Hizmetleri kaynağınıza Geri dön ve Kaynak menüsünden öğesini seçin
Domains
. - Önceki adımdaki
MailFrom
değeri seçinAdd domain
ve girin (doğru aboneliği, kaynak grubunu ve e-posta hizmetini seçtiğinizden emin olun).Connect
düğmesini seçin.
.env
Dosyayı Güncelleştirme
ACS telefon numaranız (arama ve SMS etkinken) ve e-posta etki alanınız hazır olduğuna göre, projenizdeki .env dosyasında aşağıdaki anahtarları/değerleri güncelleştirin:
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
connection string
: ACS kaynağınızın Anahtarlar bölümündeki değer.ACS_PHONE_NUMBER
: Ücretsiz numaranızı değere atayınACS_PHONE_NUMBER
.ACS_EMAIL_ADDRESS
: E-posta "MailTo" adres değerinizi atayın.CUSTOMER_EMAIL_ADDRESS
: Uygulamadan e-posta gönderilmesini istediğiniz bir e-posta adresi atayın (uygulamanın veritabanındaki müşteri verileri yalnızca örnek veriler olduğundan). Kişisel bir e-posta adresi kullanabilirsiniz.CUSTOMER_PHONE_NUMBER
: Sms mesajları göndermek için diğer ülkelerde gerekli olan ek doğrulama nedeniyle (bugün itibariyle) Birleşik Devletler tabanlı bir telefon numarası sağlamanız gerekir. ABD tabanlı bir numaranız yoksa, bu numarayı boş bırakabilirsiniz.
Uygulama ve API Sunucularını Başlatma/Yeniden Başlatma
Bu noktaya kadar tamamladığınız alıştırmalara göre aşağıdaki adımlardan birini gerçekleştirin:
Veritabanını, API sunucusunu ve web sunucusunu önceki bir alıştırmada başlattıysanız, .env dosya değişikliklerini almak için API sunucusunu ve web sunucusunu durdurmanız ve yeniden başlatmanız gerekir. Veritabanını çalışır durumda bırakabilirsiniz.
API sunucusunu ve web sunucusunu çalıştıran terminal pencerelerini bulun ve durdurmak için CTRL + C tuşlarına basın. Her terminal penceresine yazıp
npm start
Enter tuşuna basarak bunları yeniden başlatın. Sonraki alıştırmaya devam edin.Veritabanını, API sunucusunu ve web sunucusunu henüz başlatmadıysanız aşağıdaki adımları tamamlayın:
Aşağıdaki adımlarda Visual Studio Code'da üç terminal penceresi oluşturacaksınız.
Visual Studio Code dosya listesinde .env dosyasına sağ tıklayın ve Tümleşik Terminalde Aç'ı seçin. Devam etmeden önce terminalinizin projenin kökünde ( openai-acs-msgraph ) olduğundan emin olun.
PostgreSQL veritabanını başlatmak için aşağıdaki seçeneklerden birini seçin:
Docker Desktop'ı yükleyip çalıştırıyorsanız terminal penceresinde komutunu çalıştırın
docker-compose up
ve Enter tuşuna basın.Podman-compose yüklü ve çalışıyor podman varsa, terminal penceresinde komutunu çalıştırın
podman-compose up
ve Enter tuşuna basın.PostgreSQL kapsayıcısını docker Desktop, Podman, nerdctl veya yüklediğiniz başka bir kapsayıcı çalışma zamanını kullanarak doğrudan çalıştırmak için terminal penceresinde aşağıdaki komutu çalıştırın:
Mac, Linux veya Linux için Windows Alt Sistemi (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
PowerShell ile Windows:
[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
Veritabanı kapsayıcısı başlatıldıktan sonra, ikinci bir terminal penceresi oluşturmak için Visual Studio Code Terminal araç çubuğundaki simgeye basın+.
cd
yazın ve aşağıdaki komutları çalıştırarak bağımlılıkları yükleyin ve API sunucusunu başlatın.npm install
npm start
+ Üçüncü bir terminal penceresi oluşturmak için Visual Studio Code Terminal araç çubuğundaki simgeye yeniden basın.
cd
ve aşağıdaki komutları çalıştırarak bağımlılıkları yükleyin ve web sunucusunu başlatın.npm install
npm start
Bir tarayıcı başlatılır ve adresine yönlendirilirsiniz http://localhost:4200.
İletişim: Telefon Görüşmesi Yapma
Azure İletişim Hizmetleri telefon arama özelliklerini özel bir İş Kolu (LOB) uygulamasıyla tümleştirmek, işletmeler ve kullanıcılarına çeşitli önemli avantajlar sağlar:
- Doğrudan LOB uygulamasının içinden çalışanlar, müşteriler ve iş ortakları arasında sorunsuz ve gerçek zamanlı iletişim sağlayarak birden çok platform veya cihaz arasında geçiş yapma gereksinimini ortadan kaldırır.
- Kullanıcı deneyimini geliştirir ve genel operasyonel verimliliği artırır.
- Kullanıcılar ilgili destek ekipleriyle veya konu uzmanlarıyla hızlı ve kolay bir şekilde bağlantı kurabildiği için hızlı sorun çözmeyi kolaylaştırır.
Bu alıştırmada şunları yapacaksınız:
- Uygulamadaki telefon arama özelliğini keşfedin.
- Telefon arama özelliğinin nasıl derlenmiş olduğunu öğrenmek için kodu inceleyin.
Telefon Arama Özelliğini Kullanma
Önceki alıştırmada bir Azure İletişim Hizmetleri (ACS) kaynağı oluşturdunuz ve veritabanını, web sunucusunu ve API sunucusunu başlattınız. . env dosyasında aşağıdaki değerleri de güncelleştirmişsinizdir.
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>
Devam etmeden önce önceki alıştırmayı tamamladığınızdan emin olun.
tarayıcıya ()http://localhost:4200 Geri dön datagrid'i bulun ve müşteriyle iletişime geçin'i ve ardından ilk satırda Müşteriyi Ara'yı seçin.
Üst bilgi içine bir telefon araması bileşeni eklenir. Telefon numaranızı girin (+ ile başladığından ve ülke kodunu içerdiğinden emin olun) ve Ara'yı seçin. Mikrofonunuza erişime izin vermeniz istenir.
Aramayı sonlandırmak için Kapat'ı seçin. Telefon araması bileşenini kapatmak için Kapat'ı seçin.
Telefon Arama Kodunu Keşfetme
İpucu
Visual Studio Code kullanıyorsanız, şunları seçerek dosyaları doğrudan açabilirsiniz:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Ardından açmak istediğiniz dosyanın adını yazın.
customers-list.component.ts dosyasını açın. Dosyanın tam yolu client/src/app/customers-list/customers-list.component.ts şeklindedir.
openCallDialog()
Olay veri yolunu kullanarak birCustomerCall
ileti ve müşteri telefon numarası gönderdiğini unutmayın.openCallDialog(data: Phone) { this.eventBus.emit({ name: Events.CustomerCall, value: data }); }
Not
Olay veri yolu kodunu daha fazla keşfetmek istiyorsanız eventbus.service.ts dosyasında bulabilirsiniz. Dosyanın tam yolu client/src/app/core/eventbus.service.ts şeklindedir.
Üst bilgi bileşeninin
ngOnInit()
işlevi, olay veri yolu tarafından gönderilen olaya aboneCustomerCall
olur ve telefon araması bileşenini görüntüler. Bu kodu header.component.ts bulabilirsiniz.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 }) ); }
phone-call.component.ts açın. Kodu açığa çıkarmak için biraz zaman ayırın. Dosyanın tam yolu client/src/app/phone-call/phone-call.component.ts şeklindedir. Aşağıdaki önemli özelliklere dikkat edin:
- işlevini
ngOnInit()
içinde çağırarakacsService.getAcsToken()
bir Azure İletişim Hizmetleri erişim belirteci alır; - Sayfaya bir "telefon çeviricisi" ekler. Üst bilgideki telefon numarası girişlerine tıklayarak çeviriciyi görebilirsiniz.
- Sırasıyla ve işlevlerini kullanarak
startCall()
bir çağrı başlatır veendCall()
sonlandırır.
- işlevini
Telefon araması yapan koda bakmadan önce ACS erişim belirtecinin nasıl alındığını ve telefon arama nesnelerinin nasıl oluşturulduğunu inceleyelim.
ngOnInit()
phone-call.component.ts'de işlevini bulun.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); }) ); } }
Bu işlev aşağıdaki eylemleri gerçekleştirir:
- işlevini çağırarak bir ACS userId ve erişim belirteci
acsService.getAcsToken()
alır. - Erişim belirteci alındıktan sonra kod aşağıdaki eylemleri gerçekleştirir:
- Erişim belirtecini
CallClient
kullanarak yeni bir veAzureCommunicationTokenCredential
örneği oluşturur. - ve
AzureCommunicationTokenCredential
nesnelerini kullanarakCallClient
yeni bir örneğiCallAgent
oluşturur. Daha sonra bir aramayı başlatmak ve sonlandırmak için bunun kullanıldığını göreceksinizCallAgent
.
- Erişim belirtecini
- işlevini çağırarak bir ACS userId ve erişim belirteci
acs.services.ts açın ve işlevi bulun
getAcsToken()
. Dosyanın tam yolu client/src/app/core/acs.service.ts şeklindedir. işlevi, API sunucusu tarafından kullanıma sunulan yola bir HTTP GET isteğinde/acstoken
bulunur.getAcsToken(): Observable<AcsUser> { return this.http.get<AcsUser>(this.apiUrl + 'acstoken') .pipe( catchError(this.handleError) ); }
adlı
createACSToken()
BIR API sunucusu işlevi userId ve erişim belirtecini alır ve istemciye döndürür. Sunucu/typescript/acs.ts dosyasında bulunabilir.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 }; }
Bu işlev aşağıdaki eylemleri gerçekleştirir:
- Bir ACS
connectionString
değerinin kullanılabilir olup olmadığını denetler. Aksi takdirde, ve boşuserId
token
olan bir nesnesi döndürür. - öğesinin
CommunicationIdentityClient
yeni bir örneğini oluşturur ve değerini bu örneğeconnectionString
geçirir. - kullanarak
tokenClient.createUser()
yeni bir kullanıcı oluşturur. - kullanarak
tokenClient.getToken()
"voip" kapsamına sahip yeni kullanıcı için bir belirteç alır. - ve
token
değerlerini içerenuserId
bir nesne döndürür.
- Bir ACS
UserId ve belirtecin nasıl alındığını gördüğünüze göre işlevine
phone-call.component.ts
geri dönün ve işlevi bulunstartCall()
.Bu işlev, telefon araması bileşeninde Arama seçildiğinde çağrılır. Çağrı başlatmak için daha önce bahsedilen nesneyi kullanır
CallAgent
. İşlev,callAgent.startCall()
çağrılacak numarayı ve aramayı yapmak için kullanılan ACS telefon numarasını temsil eden bir nesneyi kabul eder.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; }
İşlev
stopCall()
, telefon araması bileşeninde Kapat seçildiğinde çağrılır.endCall() { if (this.call) { this.call.hangUp({ forEveryone: true }); this.call = undefined; this.inCall = false; } else { this.hangup.emit(); } }
Bir çağrı devam ederse, çağrıyı
call.hangUp()
sonlandırmak için işlevi çağrılır. Devam eden bir çağrı yoksa,hangup
olay üst bilgi üst bileşenine iletilir ve telefon araması bileşenini gizler.Bir sonraki alıştırmaya geçmeden önce bu alıştırmada ele alınan temel kavramları gözden geçirelim:
- ACS userId ve erişim belirteci, işlevi kullanılarak API sunucusundan
acsService.getAcsToken()
alınır. - Belirteç, bir
CallClient
veCallAgent
nesnesi oluşturmak için kullanılır. -
CallAgent
nesnesi, sırasıyla vecallAgent.hangUp()
işlevlerini çağırarak bir çağrıyıcallAgent.startCall()
başlatmak ve sonlandırmak için kullanılır.
- ACS userId ve erişim belirteci, işlevi kullanılarak API sunucusundan
Telefon aramalarının bir uygulamayla nasıl tümleştirilebileceğini öğrendiğinize göre, e-posta ve SMS mesajları göndermek için odağımızı Azure İletişim Hizmetleri kullanmaya geçirelim.
İletişim: Email ve SMS mesajları gönderme
telefon aramalarına ek olarak, Azure İletişim Hizmetleri e-posta ve SMS mesajları da gönderebilir. Bu, doğrudan uygulamadan bir müşteriye veya başka bir kullanıcıya ileti göndermek istediğinizde yararlı olabilir.
Bu alıştırmada şunları yapacaksınız:
- E-posta ve SMS iletilerinin uygulamadan nasıl gönderilebileceğini keşfedin.
- E-posta ve SMS işlevselliğinin nasıl uygulandığını öğrenmek için kodu inceleyin.
Email ve SMS Özelliklerini Kullanma
Önceki bir alıştırmada bir Azure İletişim Hizmetleri (ACS) kaynağı oluşturdunuz ve veritabanını, web sunucusunu ve API sunucusunu başlattınız. . env dosyasında aşağıdaki değerleri de güncelleştirmişsinizdir.
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>
Devam etmeden önce alıştırmayı tamamladığınızdan emin olun.
Tarayıcıya (http://localhost:4200) Geri dön ve ardından müşteriyle iletişime geçin'i ve ardından ilk satırda Email/SMS Müşterisi'ni seçin.
Email/SMS sekmesini seçin ve aşağıdaki görevleri gerçekleştirin:
- Bir Email Konu ve Gövde girin ve Email Gönder düğmesini seçin.
- Bir SMS iletisi girin ve SMS Gönder düğmesini seçin.
E-posta ve SMS iletilerini alıp almadığınızdan kontrol edin. Anımsatıcı olarak, e-posta iletisi için tanımlanan
CUSTOMER_EMAIL_ADDRESS
değere, SMS iletisi ise .env dosyasında tanımlananCUSTOMER_PHONE_NUMBER
değere gönderilir. SMS mesajları için kullanmak üzere Birleşik Devletler tabanlı bir telefon numarası sağlayamıyorsanız bu adımı atlayabilirsiniz.Not
Gelen kutunuzda .env dosyasında tanımladığınız
CUSTOMER_EMAIL_ADDRESS
adresin e-posta iletisini görmüyorsanız istenmeyen posta klasörünüzü denetleyin.
Email Kodunu Keşfetme
İpucu
Visual Studio Code kullanıyorsanız, şunları seçerek dosyaları doğrudan açabilirsiniz:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Ardından açmak istediğiniz dosyanın adını yazın.
customers-list.component.ts dosyasını açın. Dosyanın tam yolu client/src/app/customers-list/customers-list.component.ts şeklindedir.
Müşteriyle İletişim Kur'u ve ardından datagrid'de Email/SMS Müşterisi'ni
customer-list
seçtiğinizde, bileşen bir iletişim kutusu görüntüledi. Bu, customer-list.component.ts dosyasındaki işlev tarafındanopenEmailSmsDialog()
işlenir.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.'); } }
openEmailSmsDialog()
işlevi aşağıdaki görevleri gerçekleştirir:- Nesnenin
data
(datagrid'den satırı temsil eden) birphone
andemail
özelliği içerdiğini denetler. Varsa, iletişim kutusuna geçirecek bilgileri içeren birdialogData
nesne oluşturur. -
EmailSmsDialogComponent
İletişim kutusunu açar ve nesneyi ona geçirirdialogData
. -
afterClosed()
İletişim kutusunun olayına abonedir. İletişim kutusu kapatıldığında bu olay tetiklenir.response
nesnesi, iletişim kutusuna girilen bilgileri içerir.
- Nesnenin
email-sms-dialog.component.ts dosyasını açın. Dosyanın tam yolu client/src/app/email-sms-dialog/email-sms-dialog.component.ts şeklindedir.
İşlevi
sendEmail()
bulun: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 } }
sendEmail()
işlevi aşağıdaki görevleri gerçekleştirir:- Özellik bayrağının
acsEmailEnabled
olarak ayarlandığınıtrue
denetler. Bu bayrak, ortam değişkenininACS_EMAIL_ADDRESS
atanmış bir değeri olup olmadığını denetler. - Doğruysa
acsEmailEnabled
işlev çağrılıracsService.sendEmail()
ve e-posta konusu, gövdesi, müşteri adı ve müşteri e-posta adresi geçirilir. Veritabanı örnek veriler içerdiğindenCUSTOMER_EMAIL_ADDRESS
, yerinethis.data.email
ortam değişkeni kullanılır. Gerçek dünyadaki bir uygulamadathis.data.email
değer kullanılır. - Hizmetteki işleve
sendEmail()
acsService
abonedir. Bu işlev, istemci tarafı hizmetinden gelen yanıtı içeren bir RxJS gözlemlenebilir döndürür. - E-posta başarıyla gönderildiyse özelliği
emailSent
olaraktrue
ayarlanır.
- Özellik bayrağının
Daha iyi kod kapsüllemesi ve yeniden kullanılması için uygulama genelinde acs.service.ts gibi istemci tarafı hizmetleri kullanılır. Bu, tüm ACS işlevlerinin tek bir yerde birleştirilmesini sağlar.
acs.service.ts açın ve işlevi bulun
sendEmail()
. Dosyanın tam yolu client/src/app/core/acs.service.ts şeklindedir.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) ); }
içindeki
sendEmail()
AcsService
işlevi aşağıdaki görevleri gerçekleştirir:- İşlevi
http.post()
çağırır ve e-posta konusunu, iletiyi, müşteri adını ve müşteri e-posta adresini ona geçirir. İşlev,http.post()
API çağrısının yanıtını içeren bir RxJS gözlemlenebilir döndürür. - RxJS
catchError
işlecinihttp.post()
kullanarak işlev tarafından döndürülen hataları işler.
- İşlevi
Şimdi uygulamanın ACS e-posta özelliğiyle nasıl etkileşime geçtiğini inceleyelim. acs.ts dosyasını açın ve işlevini bulun
sendEmail()
. Dosyanın tam yolu server/typescript/acs.ts şeklindedir.sendEmail()
işlevi aşağıdaki görevleri gerçekleştirir:Yeni
EmailClient
bir nesne oluşturur ve ACS bağlantı dizesi ona geçirir (bu değer ortam değişkenindenACS_CONNECTION_STRING
alınır).const emailClient = new EmailClient(connectionString);
Yeni
EmailMessage
bir nesne oluşturur ve gönderen, konu, ileti ve alıcı bilgilerini geçirir.const msgObject: EmailMessage = { senderAddress: process.env.ACS_EMAIL_ADDRESS as string, content: { subject: subject, plainText: message, }, recipients: { to: [ { address: customerEmailAddress, displayName: customerName, }, ], }, };
e-postayı işlevini kullanarak
emailClient.beginSend()
gönderir ve yanıtı döndürür. İşlev bu örnekte yalnızca bir alıcıya gönderiliyor olsa da,beginSend()
işlevi birden çok alıcıya göndermek için de kullanılabilir.const poller = await emailClient.beginSend(msgObject);
Nesnenin
poller
tamamlandı olarak işaretlemesini bekler ve yanıtı çağırana gönderir.
SMS Kodunu Keşfetme
Daha önce açtığınız email-sms-dialog.component.ts dosyasına Geri dön. Dosyanın tam yolu client/src/app/email-sms-dialog/email-sms-dialog.component.ts şeklindedir.
İşlevi
sendSms()
bulun: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; } }
sendSMS()
işlevi aşağıdaki görevleri gerçekleştirir:- Özellik bayrağının
acsPhoneEnabled
olarak ayarlandığınıtrue
denetler. Bu bayrak, ortam değişkenininACS_PHONE_NUMBER
atanmış bir değeri olup olmadığını denetler. -
acsPhoneEnabled
True ise işlev çağrılıracsService.SendSms()
ve SMS iletisi ile müşteri telefon numarası geçirilir. Veritabanı örnek veriler içerdiğindenCUSTOMER_PHONE_NUMBER
, yerinethis.data.customerPhoneNumber
ortam değişkeni kullanılır. Gerçek dünyadaki bir uygulamadathis.data.customerPhoneNumber
değer kullanılır. - Hizmetteki işleve
sendSms()
acsService
abonedir. Bu işlev, istemci tarafı hizmetinden gelen yanıtı içeren bir RxJS gözlemlenebilir döndürür. - SMS iletisi başarıyla gönderildiyse, özelliği olarak
true
ayarlarsmsSent
.
- Özellik bayrağının
acs.service.ts açın ve işlevi bulun
sendSms()
. Dosyanın tam yolu client/src/app/core/acs.service.ts şeklindedir.sendSms(message: string, customerPhoneNumber: string) : Observable<EmailSmsResponse> { return this.http.post<EmailSmsResponse>(this.apiUrl + 'sendsms', { message, customerPhoneNumber }) .pipe( catchError(this.handleError) ); }
sendSms()
işlevi aşağıdaki görevleri gerçekleştirir:- İşlevi
http.post()
çağırır ve iletiyi ve müşteri telefon numarasını ona geçirir. İşlev,http.post()
API çağrısının yanıtını içeren bir RxJS gözlemlenebilir döndürür. - RxJS
catchError
işlecinihttp.post()
kullanarak işlev tarafından döndürülen hataları işler.
- İşlevi
Son olarak uygulamanın ACS SMS özelliğiyle nasıl etkileşime geçtiğini inceleyelim. acs.ts dosyasını açın. Dosyanın tam yolu server/typescript/acs.ts şeklindedir ve işlevi bulun
sendSms()
.sendSms()
işlevi aşağıdaki görevleri gerçekleştirir:Yeni
SmsClient
bir nesne oluşturur ve ACS bağlantı dizesi ona geçirir (bu değer ortam değişkenindenACS_CONNECTION_STRING
alınır).const smsClient = new SmsClient(connectionString);
İşlevi
smsClient.send()
çağırır ve ACS telefon numarasını (from
), müşteri telefon numarasını ()to
ve SMS iletisini geçirir:const sendResults = await smsClient.send({ from: process.env.ACS_PHONE_NUMBER as string, to: [customerPhoneNumber], message: message }); return sendResults;
Çağıranın yanıtını döndürür.
ACS e-postası ve SMS işlevselliği hakkında daha fazla bilgiyi aşağıdaki makalelerde bulabilirsiniz:
Bir sonraki alıştırmaya geçmeden önce bu alıştırmada ele alınan temel kavramları gözden geçirelim:
- acs.service.ts dosyası, istemci tarafı uygulaması tarafından kullanılan ACS e-posta ve SMS işlevselliğini kapsüller. Sunucuya yapılan API çağrılarını işler ve yanıtı çağırana döndürür.
- Sunucu tarafı API'sinde e-posta ve
SmsClient
SMS iletileri göndermek için ACSEmailClient
ve nesneler kullanılır.
E-posta ve SMS iletilerinin nasıl gönderilebileceğini öğrendiğinize göre, şimdi kuruluş verilerini uygulamayla tümleştirmeye odaklanalım.
Kuruluş Verileri: Microsoft Entra ID Uygulama Kaydı Oluşturma
Kuruluş verilerini (e-postalar, dosyalar, sohbetler ve takvim olayları) doğrudan özel uygulamalarınızla tümleştirerek kullanıcı üretkenliğini artırın. Microsoft Graph API'lerini ve Microsoft Entra ID kullanarak uygulamalarınızda ilgili verileri sorunsuz bir şekilde alıp görüntüleyerek kullanıcıların bağlam değiştirme gereksinimini azaltabilirsiniz. İster müşteriye gönderilen bir e-postaya başvuruyor, Teams iletisini gözden geçiriyor, ister bir dosyaya erişiyor olsun, kullanıcılar uygulamanızdan çıkmadan ihtiyaç duydukları bilgileri hızla bulabilir ve karar alma sürecini basitleştirebilir.
Bu alıştırmada şunları yapacaksınız:
- Microsoft Graph'ın kuruluş verilerine erişebilmesi ve uygulamaya ekleyebilmesi için bir Microsoft Entra ID uygulama kaydı oluşturun.
- Microsoft Teams'de belirli bir kanala sohbet iletileri göndermek için gereken ve
channel
kimliklerini bulunteam
. - Projenin .env dosyasını Microsoft Entra ID uygulama kaydınızdaki değerlerle güncelleştirin.
Microsoft Entra ID Uygulama Kaydı oluşturma
Azure portal'a gidin ve Microsoft Entra ID'ı seçin.
Uygulama kaydı sekmesini ve ardından + Yeni kayıt'ı seçin.
Yeni uygulama kayıt formu ayrıntılarını aşağıda gösterildiği gibi doldurun ve Kaydet'i seçin:
- Ad: microsoft-graph-app
- Desteklenen hesap türleri: Herhangi bir kuruluş dizinindeki hesaplar (Herhangi bir Microsoft Entra ID kiracısı - Çok Kiracılı)
- Yeniden Yönlendirme URI’si:
-
Tek sayfalı uygulama (SPA) öğesini seçin ve Yeniden Yönlendirme URI'si alanına girin
http://localhost:4200
.
-
Tek sayfalı uygulama (SPA) öğesini seçin ve Yeniden Yönlendirme URI'si alanına girin
- Uygulama kaydını oluşturmak için Kaydet'i seçin.
Kaynak menüsünde Genel Bakış'ı seçin ve değeri panonuza kopyalayın
Application (client) ID
.
Projenin .env Dosyasını Güncelleştirme
Düzenleyicinizde .env dosyasını açın ve değerini öğesine
ENTRAID_CLIENT_ID
atayınApplication (client) ID
.ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
Uygulamadan Teams Kanalına ileti gönderme özelliğini etkinleştirmek istiyorsanız Microsoft 365 geliştirme kiracı hesabınızı kullanarak Microsoft Teams'de oturum açın.
Oturum açtıktan sonra ekibi genişletin ve uygulamadan ileti göndermek istediğiniz kanalı bulun. Örneğin, Şirket ekibini ve Genel kanalını (veya kullanmak istediğiniz ekip/kanal) seçebilirsiniz.
Ekip üst bilgisinde üç noktaya (...) tıklayın ve öğesini seçin
Get link to team
.Açılan pencerede görüntülenen bağlantıda ekip kimliği, sonrasındaki
team/
harf ve sayı dizesidir. Örneğin, "https://teams.microsoft.com/l/team/19%3ae9b9.../"" bağlantısında ekip kimliği %19%3ae9b9... aşağıdaki/
karaktere kadar.Ekip kimliğini kopyalayın ve .env dosyasında öğesine atayın
TEAM_ID
.Kanal üst bilgisinde üç noktaya (...) tıklayın ve öğesini seçin
Get link to channel
.Açılan pencerede görüntülenen bağlantıda kanal kimliği, sonrasındaki
channel/
harf ve sayı dizesidir. Örneğin, "https://teams.microsoft.com/l/channel/19%3aQK02.../"" bağlantısında kanal kimliği %19%3aQK02... aşağıdaki/
karaktere kadar.Kanal kimliğini kopyalayın ve .env dosyasında adresine atayın
CHANNEL_ID
.Devam etmeden önce env dosyasını kaydedin.
Uygulama ve API Sunucularını Başlatma/Yeniden Başlatma
Bu noktaya kadar tamamladığınız alıştırmalara göre aşağıdaki adımlardan birini gerçekleştirin:
Veritabanını, API sunucusunu ve web sunucusunu önceki bir alıştırmada başlattıysanız, .env dosya değişikliklerini almak için API sunucusunu ve web sunucusunu durdurmanız ve yeniden başlatmanız gerekir. Veritabanını çalışır durumda bırakabilirsiniz.
API sunucusunu ve web sunucusunu çalıştıran terminal pencerelerini bulun ve durdurmak için CTRL + C tuşlarına basın. Her terminal penceresine yazıp
npm start
Enter tuşuna basarak bunları yeniden başlatın. Sonraki alıştırmaya devam edin.Veritabanını, API sunucusunu ve web sunucusunu henüz başlatmadıysanız aşağıdaki adımları tamamlayın:
Aşağıdaki adımlarda, Visual Studio Code'da üç terminal penceresi oluşturacaksınız.
Visual Studio Code dosya listesinde .env dosyasına sağ tıklayın ve Tümleşik Terminalde Aç'ı seçin. Devam etmeden önce terminalinizin projenin kökünde ( openai-acs-msgraph ) olduğundan emin olun.
PostgreSQL veritabanını başlatmak için aşağıdaki seçeneklerden birini seçin:
Docker Desktop'ı yüklediyseniz ve çalıştırıyorsanız terminal penceresinde komutunu çalıştırın
docker-compose up
ve Enter tuşuna basın.Podman-compose yüklü ve çalışır durumda olan Podman'larınız varsa terminal penceresinde komutunu çalıştırın
podman-compose up
ve Enter tuşuna basın.PostgreSQL kapsayıcısını doğrudan Docker Desktop, Podman, nerdctl veya yüklediğiniz başka bir kapsayıcı çalışma zamanını kullanarak çalıştırmak için terminal penceresinde aşağıdaki komutu çalıştırın:
Mac, Linux veya Linux için Windows Alt Sistemi (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
PowerShell ile Windows:
[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
Veritabanı kapsayıcısı başlatıldıktan sonra, ikinci bir terminal penceresi oluşturmak için Visual Studio Code Terminal araç çubuğundaki simgeye basın+.
cd
server /typescript klasörüne gidin ve bağımlılıkları yüklemek ve API sunucusunu başlatmak için aşağıdaki komutları çalıştırın.npm install
npm start
+ Üçüncü bir terminal penceresi oluşturmak için Visual Studio Code Terminal araç çubuğundaki simgeye yeniden basın.
cd
ve aşağıdaki komutları çalıştırarak bağımlılıkları yükleyin ve web sunucusunu başlatın.npm install
npm start
Bir tarayıcı başlatılır ve adresine yönlendirilirsiniz http://localhost:4200.
Kuruluş Verileri: Bir Kullanıcıda Oturum Açma ve Erişim Belirteci Alma
Microsoft Graph'ın kuruluş verilerine erişebilmesi için kullanıcıların Microsoft Entra ID kimlik doğrulamasına sahip olması gerekir. Bu alıştırmada Microsoft Graph Araç Seti'nin mgt-login
bileşeninin kullanıcıların kimliğini doğrulamak ve erişim belirteci almak için nasıl kullanılabileceğini göreceksiniz. Erişim belirteci daha sonra Microsoft Graph'a çağrı yapmak için kullanılabilir.
Not
Microsoft Graph'ı yeni kullanıyorsanız, Microsoft Graph Temel Bilgileri öğrenme yolunda bu konuda daha fazla bilgi edinebilirsiniz.
Bu alıştırmada şunları yapacaksınız:
- Kullanıcıların kimliğini doğrulamak ve kuruluş verilerini almak için kullanılabilmesi için bir Microsoft Entra ID uygulamasını Microsoft Graph Araç Seti ile ilişkilendirmeyi öğrenin.
- Kapsamların önemi hakkında bilgi edinin.
- Microsoft Graph Toolkit'in mgt-login bileşeninin kullanıcıların kimliğini doğrulamak ve erişim belirteci almak için nasıl kullanılabileceğini öğrenin.
Oturum Açma Özelliğini Kullanma
Önceki alıştırmada Microsoft Entra ID'de bir uygulama kaydı oluşturdunuz ve uygulama sunucusu ile API sunucusunu başlattınız. Dosyada aşağıdaki değerleri
.env
de güncelleştirmişsinizdir.ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE> TEAM_ID=<TEAMS_TEAM_ID> CHANNEL_ID=<TEAMS_CHANNEL_ID>
Devam etmeden önce önceki alıştırmayı tamamladığınızdan emin olun.
Tarayıcıya ()http://localhost:4200 Geri dön üst bilgide Oturum Aç'ı seçin ve Microsoft 365 Geliştirici kiracınızdan bir yönetici kullanıcı hesabı kullanarak oturum açın.
İpucu
Microsoft 365 geliştirici kiracısı yönetici hesabınızla oturum açın. Microsoft 365 yönetim merkezi giderek geliştirici kiracınızdaki diğer kullanıcıları görüntüleyebilirsiniz.
Uygulamada ilk kez oturum açıyorsanız, uygulama tarafından istenen izinleri onaylamanız istenir. Kodu keşfederken sonraki bölümde bu izinler ("kapsamlar" olarak da adlandırılır) hakkında daha fazla bilgi edineceksiniz. Devam etmek için Kabul Et'i seçin.
Oturum açtıktan sonra üst bilgide görüntülenen kullanıcının adını görmeniz gerekir.
Oturum Açma Kodunu Keşfetme
Artık oturum açtığınıza göre, kullanıcıda oturum açmak ve erişim belirteci ile kullanıcı profilini almak için kullanılan koda bakalım. Microsoft Graph Araç Seti'nin bir parçası olan mgt-login web bileşeni hakkında bilgi edineceksiniz.
İpucu
Visual Studio Code kullanıyorsanız, şunları seçerek dosyaları doğrudan açabilirsiniz:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Ardından açmak istediğiniz dosyanın adını yazın.
İstemciyi/package.json açın ve paketin
@microsoft/mgt
bağımlılıklara dahil olduğuna dikkat edin. Bu paket, MSAL (Microsoft Authentication Library) sağlayıcı özelliklerinin yanı sıra kullanıcıları oturum açmak ve kuruluş verilerini almak ve görüntülemek için kullanılabilecek mgt-login ve diğerleri gibi web bileşenlerini içerir.Kullanıcıları oturum açmak için mgt-login bileşenini kullanmak için, Microsoft Entra ID uygulamasının istemci kimliğine (.env dosyasında olduğu gibi
ENTRAID_CLIENT_ID
depolanır) başvurulması ve kullanılması gerekir.graph.service.ts açın ve işlevi bulun
init()
. Dosyanın tam yolu client/src/app/core/graph.service.ts şeklindedir. Aşağıdaki kodu görürsünüz: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'] });
Bu kod, uygulama kaydınızdan
scopes
ve uygulamanın erişim isteğinde bulunacağı Microsoft Entra ID istemci kimliğini geçirerek yeniMsal2Provider
bir nesne oluşturur.scopes
, uygulamanın erişeceği Microsoft Graph kaynaklarına erişim istemek için kullanılır.Msal2Provider
Nesne oluşturulduktan sonra, Microsoft Graph Toolkit bileşenleri tarafından Microsoft Graph'tan veri almak için kullanılan nesneye atanırProviders.globalProvider
.Düzenleyicinizde header.component.html açın ve mgt-login bileşenini bulun. Dosyanın tam yolu client/src/app/header/header.component.htmlşeklindedir.
<mgt-login *ngIf="featureFlags.microsoft365Enabled" class="mgt-dark" (loginCompleted)="loginCompleted()"></mgt-login>
mgt-login bileşeni, Microsoft Graph ile kullanılmak üzere kullanıcı oturum açma ve erişim belirteci alma işlemlerine olanak tanır. Oturum başarıyla açıldıktan
loginCompleted
sonra olay tetiklendiğinde işlev çağrılırloginCompleted()
. Bu örnekteki bir Angular bileşeninde mgt-login kullanılmış olsa da, herhangi bir web uygulamasıyla uyumludur.mgt-login bileşeninin görüntülenmesi, olarak ayarlanan değere
true
bağlıdırfeatureFlags.microsoft365Enabled
. Bu özel bayrak, uygulamanın düzgün yapılandırıldığını ve Microsoft Entra ID karşı kimlik doğrulaması yapabildiğinden emin olmak için ortam değişkeninin varlığınıENTRAID_CLIENT_ID
denetler. Bayrağı, kullanıcıların tüm diziyi takip etmek yerine yalnızca öğreticideki yapay zeka veya İletişim alıştırmalarını tamamlamayı tercih ettiği durumları karşılamak için eklenir.header.component.ts açın ve işlevi bulun
loginCompleted
. Olay yayıldığındaloginCompleted
ve kullanarakProviders.globalProvider
oturum açmış kullanıcının profilini almak için kullanıldığında bu işlev çağrılır.async loginCompleted() { const me = await Providers.globalProvider.graph.client.api('me').get(); this.userLoggedIn.emit(me); }
Bu örnekte, kullanıcı profillerini almak için Microsoft Graph
me
API'sine bir çağrı yapılmaktadır (me
geçerli oturum açmış kullanıcıyı temsil eder). Kod deyimi,this.userLoggedIn.emit(me)
profil verilerini üst bileşene geçirmek için bileşenden bir olay yayar. Üst bileşen, bu durumda uygulamanın kök bileşeni olan app.component.ts dosyasıdır.mgt-login bileşeni hakkında daha fazla bilgi edinmek için Microsoft Graph Toolkit belgelerini ziyaret edin.
Artık uygulamada oturum açtığınıza göre kuruluş verilerinin nasıl alınabileceğine bakalım.
Kuruluş Verileri: Dosyaları Alma, Sohbetler ve Teams'e İleti Gönderme
Günümüzün dijital ortamında kullanıcılar e-postalar, sohbetler, dosyalar, takvim etkinlikleri ve daha fazlası gibi çok çeşitli kuruluş verileriyle çalışır. Bu, sık sık bağlam kaydırmalarına (görevler veya uygulamalar arasında geçiş yapma) yol açabilir ve bu da odağı kesintiye uğratabilir ve üretkenliği azaltabilir. Örneğin, bir proje üzerinde çalışan bir kullanıcının e-postadaki önemli ayrıntıları bulmak için geçerli uygulamasından Outlook'a geçmesi veya ilgili dosyayı bulmak için OneDrive İş geçmesi gerekebilir. Bu ileri geri eylem odaklanmayı kesintiye uğratır ve eldeki göreve daha iyi harcanabilecek zamanı boşa harcar.
Verimliliği artırmak için kuruluş verilerini kullanıcıların her gün kullandığı uygulamalarla doğrudan tümleştirebilirsiniz. Kullanıcılar, uygulamalarınıza kuruluş verileri getirerek bilgilere daha sorunsuz bir şekilde erişebilir ve bu bilgileri yönetebilir, bağlam değişikliklerini en aza indirir ve üretkenliği artırır. Buna ek olarak, bu tümleştirme değerli içgörüler ve bağlam sağlayarak kullanıcıların bilinçli kararlar almalarına ve daha etkili çalışmalarına olanak tanır.
Bu alıştırmada şunları yapacaksınız:
- Microsoft Graph Araç Seti'ndeki mgt-search-results web bileşeninin dosyaları aramak için nasıl kullanılabileceğini öğrenin.
- OneDrive İş ve Microsoft Teams'den sohbet iletilerinden dosya almak için Microsoft Graph'ı doğrudan çağırmayı öğrenin.
- Microsoft Graph kullanarak Microsoft Teams kanallarına sohbet iletileri göndermeyi öğrenin.
Not
mgt-search-results bileşeni şu anda önizleme aşamasındadır ve değiştirilebilir. Alıştırmalar, mgt-search-results'ın nasıl kullanılabileceğini göstermenin yanı sıra, aynı görevlerin doğrudan Microsoft Graph kullanılarak nasıl gerçekleştirileceğini de gösterir.
Kuruluş Verileri Özelliğini Kullanma
Önceki bir alıştırmada Microsoft Entra ID'da bir uygulama kaydı oluşturdunuz ve uygulama sunucusu ile API sunucusunu başlattınız. Dosyada aşağıdaki değerleri
.env
de güncelleştirmişsinizdir.ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE> TEAM_ID=<TEAMS_TEAM_ID> CHANNEL_ID=<TEAMS_CHANNEL_ID>
Devam etmeden önce önceki alıştırmayı tamamladığınızdan emin olun.
tarayıcıya (http://localhost:4200) Geri dön. Henüz oturum açmadıysanız, üst bilgide Oturum Aç'ı seçin ve Microsoft 365 Geliştirici kiracınızdan bir kullanıcıyla oturum açın.
Not
Mgt-login web bileşeni, kullanıcının kimliğini doğrulamaya ek olarak Microsoft Graph tarafından dosyalara, sohbetlere, e-postalara, takvim olaylarına ve diğer kuruluş verilerine erişmek için kullanılabilecek bir erişim belirteci de alır. Erişim belirteci, , gibi kapsamları (izinleri)
Chat.ReadWrite
Files.Read.All
ve daha önce gördüğünüz diğer öğeleri içerir: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'] });
Datagrid'deki Adatum Corporation satırı için İlgili İçeriği Görüntüle'yi seçin. Bu, dosyalar, sohbetler, e-postalar ve takvim olayları gibi kuruluş verilerinin Microsoft Graph kullanılarak alınmasına neden olur. Veriler yüklendikten sonra, sekmeli bir arabirimde datagrid'in altında görüntülenir. Microsoft 365 geliştirici kiracınızda kullanıcı için henüz hiçbir dosya, sohbet, e-posta veya takvim etkinliği eklemediğiniz için bu noktada veri göremeyebileceğini belirtmek önemlidir. Bunu bir sonraki adımda düzeltelim.
Microsoft 365 kiracınız bu aşamada Adatum Corporation için ilgili kuruluş verilerine sahip olmayabilir. Örnek veriler eklemek için aşağıdaki eylemlerden en az birini gerçekleştirin:
Microsoft 365 Geliştirici kiracı kimlik bilgilerinizi ziyaret edip https://onedrive.com oturum açarak dosyaları ekleyin.
- Sol gezinti bölmesinden Dosyalarım'ı seçin.
- Karşıya Yükle'yi ve ardından menüden Klasör'e tıklayın.
- Kopyaladığınız projeden openai-acs-msgraph/customer documents klasörünü seçin.
Microsoft 365 Geliştirici kiracısı kimlik bilgilerinizi ziyaret edip https://teams.microsoft.com oturum açarak sohbet iletileri ve takvim etkinlikleri ekleyin.
Sol gezinti bölmesinden Teams'i seçin.
Bir ekip ve kanal seçin.
Yeni konuşma'ya tıklayın.
Adatum Corporation için yeni sipariş ver'i girin ve Gönder düğmesini seçin.
Adventure Works Cycles, Contoso Pharmaceuticals ve Tailwind Traders gibi uygulamada kullanılan diğer şirketlerden bahseden ek sohbet mesajları ekleyebilirsiniz.
Sol gezinti bölmesinde Takvim'i seçin.
Yeni toplantı'ya tıklayın.
Başlık ve gövde için "Proje zamanlaması hakkında Adatum Corporation ile toplantı yap" yazın.
Kaydet’i seçin.
Microsoft 365 Geliştirici kiracı kimlik bilgilerinizi kullanarak ziyaret edip https://outlook.com oturum açarak e-posta ekleyin.
Yeni posta'ya tıklayın.
Kişisel e-posta adresinizi Son alanına girin.
Konu için Adatum Corporation için yeni sipariş ve gövde için istediğiniz her şeyi girin.
Gönder’i seçin.
Tarayıcıda uygulamaya Geri dön ve sayfayı yenileyin. Adatum Corporation satırı için İlgili İçeriği Görüntüle'yi yeniden seçin. Şimdi, önceki adımda hangi görevleri gerçekleştirdiğinize bağlı olarak sekmelerde görüntülenen verileri görmeniz gerekir.
Şimdi uygulamada kurumsal veri özelliğini etkinleştiren kodu inceleyelim. Verileri almak için uygulamanın istemci tarafı bölümü, Microsoft Graph API'lerine çağrı yapmak için daha önce baktığınız mgt-login bileşeni tarafından alınan erişim belirtecini kullanır.
Dosya Arama Kodunu Keşfetme
İpucu
Visual Studio Code kullanıyorsanız, şunları seçerek dosyaları doğrudan açabilirsiniz:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Ardından açmak istediğiniz dosyanın adını yazın.
Dosya verilerinin OneDrive İş nasıl alınıyor konusuna bakarak başlayalım. files.component.html açın ve kodu incelemek için biraz zaman ayırın. Dosyanın tam yolu client/src/app/files/files.component.htmlşeklindedir.
mgt-search-results bileşenini bulun ve aşağıdaki öznitelikleri not edin:
<mgt-search-results class="search-results" entity-types="driveItem" [queryString]="searchText" (dataChange)="dataChange($any($event))" />
mgt-search-results bileşeni Microsoft Graph Araç Seti'nin bir parçasıdır ve adından da anlaşılacağı gibi Microsoft Graph'tan gelen arama sonuçlarını görüntülemek için kullanılır. Bileşen bu örnekte aşağıdaki özellikleri kullanır:
class
özniteliği, CSS sınıfının bileşene uygulanması gerektiğini belirtmeksearch-results
için kullanılır.entity-types
özniteliği, aranacak veri türünü belirtmek için kullanılır. Bu durumda değeridriveItem
, OneDrive İş dosyaları aramak için kullanılır.queryString
özniteliği, arama terimini belirtmek için kullanılır. Bu durumda değer, kullanıcı datagrid'dekisearchText
bir satır için İlgili İçeriği Görüntüle'yi seçtiğinde dosyalar bileşenine geçirilen özelliğine bağlıdır. ÇevresindekiqueryString
köşeli ayraçlar özelliğin değeresearchText
bağlı olduğunu gösterir.Arama
dataChange
sonuçları değiştiğinde olay tetikler. Bu durumda, dosya bileşeninde adlıdataChange()
bir müşteri işlevi çağrılır ve olay verileri işleve geçirilir. EtrafındakidataChange
parantez, olayın işlevedataChange()
bağlı olduğunu gösterir.Özel şablon sağlanmadığından, arama sonuçlarını görüntülemek için yerleşik
mgt-search-results
varsayılan şablon kullanılır.
mgt-search-results gibi bileşenleri kullanmanın bir alternatifi, Microsoft Graph API'lerini doğrudan kod kullanarak çağırmaktır. Bunun nasıl çalıştığını görmek için graph.service.ts dosyasını açın ve işlevini bulun
searchFiles()
. Dosyanın tam yolu client/src/app/core/graph.service.ts şeklindedir.İşleve bir
query
parametre geçirildiğini göreceksiniz. Bu, kullanıcı veri kılavuzundaki bir satır için İlgili İçeriği Görüntüle'yi seçtiğinde geçirilen arama terimidir. Hiçbir arama terimi geçirilmezse boş bir dizi döndürülür.async searchFiles(query: string) { const files: DriveItem[] = []; if (!query) return files; ... }
Ardından gerçekleştirilecek arama türünü tanımlayan bir filtre oluşturulur. Bu durumda kod OneDrive İş dosyaları arar, bu nedenle
driveItem
bileşendemgt-search-results
daha önce gördüğünüz gibi kullanılır. Bu, daha önce gördüğünüz mgt-search-results bileşeninde öğesine geçirmedriveItem
entity-types
işlemiyle aynıdır. Ardındanquery
parametresi ileContentType:Document
birlikte filtreyequeryString
eklenir.const filter = { "requests": [ { "entityTypes": [ "driveItem" ], "query": { "queryString": `${query} AND ContentType:Document` } } ] };
Ardından işlevi kullanılarak
Providers.globalProvider.graph.client.api()
Microsoft Graph API bir çağrı yapılır/search/query
.filter
nesnesi, verileri API'yepost()
gönderen işleve geçirilir.const searchResults = await Providers.globalProvider.graph.client.api('/search/query').post(filter);
Arama sonuçları daha sonra konumunu
hits
bulmak için yinelenir. Herhit
biri, bulunan bir belge hakkında bilgi içerir. adlıresource
özellik belge meta verilerini içerir ve diziyefiles
eklenir.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); } } } }
Dizi
files
daha sonra çağırana döndürülür.return files;
Bu koda baktığınızda, daha önce keşfettiniz mgt-search-results web bileşeninin sizin için çok fazla iş yaptığını ve yazmanız gereken kod miktarını önemli ölçüde azalttığını görebilirsiniz! Ancak, API'ye gönderilen veriler veya sonuçların nasıl işlendiği üzerinde daha fazla denetim sahibi olmak için Doğrudan Microsoft Graph'ı çağırmak istediğiniz senaryolar olabilir.
files.component.ts dosyasını açın ve işlevini bulun
search()
. Dosyanın tam yolu client/src/app/files/files.component.ts şeklindedir.Bu işlevin gövdesi , kullanılan mgt-search-results bileşeni nedeniyle açıklama satırı yapılsa da, kullanıcı datagrid'deki bir satır için İlgili İçeriği Görüntüle'yi seçtiğinde Microsoft Graph'a çağrı yapmak için işlev kullanılabilir. İşlev,
search()
graph.service.ts çağırırsearchFiles()
ve parametresiniquery
bu parametreye geçirir (bu örnekte şirketin adı). Aramanın sonuçları daha sonra bileşenindata
özelliğine atanır.override async search(query: string) { this.data = await this.graphService.searchFiles(query); }
Dosyalar bileşeni daha sonra arama sonuçlarını görüntülemek için özelliğini kullanabilir
data
. Bunu özel HTML bağlamaları kullanarak veya adlımgt-file-list
başka bir Microsoft Graph Araç Seti denetimi kullanarak işleyebilirsiniz. Aşağıda, özelliği bileşenin adlıfiles
özelliklerinden birine bağlamadata
ve kullanıcı bir dosyayla etkileşim kurarken olayı işlemeitemClick
örneği verilmiştir.<mgt-file-list (itemClick)="itemClick($any($event))" [files]="data"></mgt-file-list>
Daha önce gösterilen mgt-search-results bileşenini kullanmayı veya Microsoft Graph'ı çağırmak için özel kod yazmayı tercih edip etmediğiniz, senaryonuza bağlıdır. Bu örnekte, kodu basitleştirmek ve yapmanız gereken iş miktarını azaltmak için mgt-search-results bileşeni kullanılır.
Teams Sohbet İletileri Arama Kodunu Keşfetme
graph.service.ts ve işlevini bulmak
searchChatMessages()
için Geri dön. Daha önce baktığınız işlevesearchFiles()
benzer olduğunu göreceksiniz.- Filtre verilerini Microsoft Graph API'sine
/search/query
gönderir ve sonuçları ,channelId
ve hakkındateamId
bilgi içeren vemessageId
arama terimiyle eşleşen bir nesne dizisine dönüştürür. - Teams kanal iletilerini almak için API'ye
/teams/${chat.teamId}/channels/${chat.channelId}/messages/${chat.messageId}
ve , öğesinechannelId
ikinci bir çağrı yapılır veteamId
messageId
bu çağrı geçirilir. Bu, ileti ayrıntılarının tamamını döndürür. - Ek filtreleme görevleri gerçekleştirilir ve sonuçta elde edilen iletiler çağırana döndürülür
searchChatMessages()
.
- Filtre verilerini Microsoft Graph API'sine
chats.component.ts dosyasını açın ve işlevini bulun
search()
. Dosyanın tam yolu client/src/app/chats/chats.component.ts şeklindedir. İşlev,search()
graph.service.ts çağırırsearchChatMessages()
ve parametresiniquery
ona geçirir.override async search(query: string) { this.data = await this.graphService.searchChatMessages(query); }
Aramanın sonuçları bileşenin
data
özelliğine atanır ve sonuç dizisinde yineleme yapmak ve verileri işlemek için veri bağlama kullanılır. Bu örnekte, arama sonuçlarını görüntülemek için bir Angular Malzeme kartı bileşeni kullanılır.<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>
Microsoft Teams Kanalına İleti Gönderme
Uygulama, Microsoft Teams sohbet iletilerini aramaya ek olarak kullanıcının Microsoft Teams kanalına ileti göndermesine de izin verir. Bu, Microsoft Graph'ın
/teams/${teamId}/channels/${channelId}/messages
uç noktasını çağırarak yapılabilir.Aşağıdaki kodda ve
channelId
değerlerini içeren bir URL oluşturulduğunuteamId
göreceksiniz. Ortam değişkeni değerleri bu örnekte ekip kimliği ve kanal kimliği için kullanılır, ancak bu değerler Microsoft Graph kullanılarak da dinamik olarak alınabilir. sabitibody
gönderilecek iletiyi içerir. Ardından bir POST isteği yapılır ve sonuçlar çağırana döndürülür.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' }; }
Microsoft Graph'ta bu tür işlevlerden yararlanılması, kullanıcıların microsoft teams ile doğrudan kullanmakta oldukları uygulamadan etkileşim kurmasına olanak tanıyarak kullanıcı üretkenliğini artırmak için harika bir yol sağlar.
Kuruluş Verileri: E-postaları ve Takvim Olaylarını Alma
Önceki alıştırmada Microsoft Graph'ı ve Microsoft Graph Araç Seti'ndeki mgt-search-results bileşenini kullanarak Microsoft Teams'den OneDrive İş ve sohbetlerden dosya almayı öğrendiniz. Ayrıca Microsoft Teams kanallarına ileti göndermeyi de öğrendiniz. Bu alıştırmada, Microsoft Graph'tan e-posta iletilerini ve takvim olaylarını almayı ve bunları uygulamayla tümleştirmeyi öğreneceksiniz.
Bu alıştırmada şunları yapacaksınız:
- Microsoft Graph Araç Seti'ndeki mgt-search-results web bileşeninin e-postaları ve takvim olaylarını aramak için nasıl kullanılabileceğini öğrenin.
- Arama sonuçlarını özel bir şekilde işlemek için mgt-search-results bileşenini özelleştirmeyi öğrenin.
- E-postaları ve takvim olaylarını almak için doğrudan Microsoft Graph'ı çağırmayı öğrenin.
Email İleti arama kodunu keşfetme
İpucu
Visual Studio Code kullanıyorsanız, şunları seçerek dosyaları doğrudan açabilirsiniz:
- Windows/Linux: Ctrl + P
- Mac: Cmd + P
Ardından açmak istediğiniz dosyanın adını yazın.
Önceki bir alıştırmada Microsoft Entra ID'da bir uygulama kaydı oluşturdunuz ve uygulama sunucusu ile API sunucusunu başlattınız. Dosyada aşağıdaki değerleri
.env
de güncelleştirmişsinizdir.ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE> TEAM_ID=<TEAMS_TEAM_ID> CHANNEL_ID=<TEAMS_CHANNEL_ID>
Devam etmeden önce önceki alıştırmayı tamamladığınızdan emin olun.
emails.component.html açın ve kodu incelemek için biraz bekleyin. Dosyanın tam yolu client/src/app/email/emails.component.htmlşeklindedir.
mgt-search-results bileşenini bulun:
<mgt-search-results class="search-results" entity-types="message" [queryString]="searchText" (dataChange)="dataChange($any($event))"> <template data-type="result-message"></template> </mgt-search-results>
Mgt-search-results bileşeninin bu örneği, daha önce baktığınız bileşenle aynı şekilde yapılandırılmıştır. Tek fark, özniteliğin
entity-types
e-posta iletilerini aramak için kullanılan ve boş bir şablonun sağlandığı ayarıdırmessage
.-
class
özniteliği, CSS sınıfının bileşene uygulanması gerektiğini belirtmeksearch-results
için kullanılır. -
entity-types
özniteliği, aranacak veri türünü belirtmek için kullanılır. Bu durumda, değeri şeklindedirmessage
. -
queryString
özniteliği, arama terimini belirtmek için kullanılır. - Arama
dataChange
sonuçları değiştiğinde olay tetikler. E-posta bileşeninindataChange()
işlevi çağrılır, sonuçlar bu işleve geçirilir ve adlıdata
bir özellik bileşende güncelleştirilir. - Bileşen için boş bir şablon tanımlanır. Bu şablon türü normalde arama sonuçlarının nasıl işlendiğini tanımlamak için kullanılır. Ancak bu senaryoda bileşene ileti verilerini işlememelerini söylüyoruz. Bunun yerine, standart veri bağlamayı kullanarak verileri kendimiz işleyeceğiz (bu durumda Angular kullanılır, ancak istediğiniz herhangi bir kitaplığı/çerçeveyi kullanabilirsiniz).
-
E-posta iletilerini işlemek için kullanılan veri bağlamalarını bulmak için emails.component.html'daki mgt-search-results bileşeninin altına bakın. Bu örnek özelliğinde
data
yinelenir ve e-posta konusunu, gövde önizlemesini ve e-posta iletisinin tamamını görüntülemek için bir bağlantı yazar.<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>
Microsoft Graph, iletileri almak için mgt-search-results bileşenini kullanmanın yanı sıra e-postaları aramak için de kullanılabilecek çeşitli API'ler sağlar.
/search/query
Daha önce gördüğünüz API kesinlikle kullanılabilir, ancak api daha kolay bir seçenektirmessages
.Bu API'yi çağırmayı görmek için graph.service.ts dönün ve işlevi bulun
searchEmailMessages()
. Microsoft Graph uç noktasını çağırmakmessages
için kullanılabilecek bir URL oluşturur ve değeri parametresine$search
atarquery
. Kod daha sonra bir GET isteği yapar ve sonuçları çağırana döndürür.$search
işleci konu, gövde ve gönderen alanlarındaki değeri otomatik olarak ararquery
.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; }
emails.component.ts içinde bulunan e-posta bileşeni çağrılar
searchEmailMessages()
ve sonuçları kullanıcı arabiriminde görüntüler.override async search(query: string) { this.data = await this.graphService.searchEmailMessages(query); }
Takvim Olayları Arama Kodunu Keşfetme
Takvim olaylarını arama , mgt-search-results bileşeni kullanılarak da gerçekleştirilebilir. Sonuçları sizin için işlemeyi işleyebilir, ancak bu alıştırmanın devamında göreceğiniz kendi şablonunuzu da tanımlayabilirsiniz.
calendar-events.component.html açın ve kodu incelemek için biraz bekleyin. Dosyanın tam yolu client/src/app/calendar-events/calendar-events.component.htmlşeklindedir. Daha önce baktığınız dosya ve e-posta bileşenlerine çok benzediğini göreceksiniz.
<mgt-search-results class="search-results" entity-types="event" [queryString]="searchText" (dataChange)="dataChange($any($event))"> <template data-type="result-event"></template> </mgt-search-results>
Mgt-search-results bileşeninin bu örneği, daha önce baktığınız bileşenlerle aynı şekilde yapılandırılmıştır. Tek fark, özniteliğinin
entity-types
takvim olaylarını aramak için kullanıldığı ve boş bir şablonun sağlandığı ayarlanmışevent
olmasıdır.-
class
özniteliği, CSS sınıfının bileşene uygulanması gerektiğini belirtmeksearch-results
için kullanılır. -
entity-types
özniteliği, aranacak veri türünü belirtmek için kullanılır. Bu durumda, değeri şeklindedirevent
. -
queryString
özniteliği, arama terimini belirtmek için kullanılır. - Arama
dataChange
sonuçları değiştiğinde olay tetikler. Takvim olayı bileşeninindataChange()
işlevi çağrılır, sonuçlar buna geçirilir ve adlıdata
bir özellik bileşende güncelleştirilir. - Bileşen için boş bir şablon tanımlanır. Bu senaryoda bileşene veri işlememesi gerektiğini söylüyoruz. Bunun yerine, standart veri bağlamayı kullanarak verileri kendimiz işleyeceğiz.
-
calendar-events.component.html bileşenin
mgt-search-results
hemen altında takvim olaylarını işlemek için kullanılan veri bağlamalarını bulabilirsiniz. Bu örnek özelliğindedata
yinelenir ve olayın başlangıç tarihini, saatini ve konusunu yazar. Ve gibidayFromDateTime()
timeRangeFromEvent()
bileşene dahil edilen özel işlevler, verileri düzgün biçimlendirmek için çağrılır. HTML bağlamaları ayrıca Outlook'taki takvim olayını ve belirtildiyse olayın konumunu görüntülemek için bir bağlantı içerir.<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>
Microsoft Graph, API kullanarak
search/query
takvim olaylarını aramaya ek olarak takvim olaylarını aramak için de kullanılabilecek birevents
API sağlar.searchCalendarEvents()
graph.service.ts'de işlevini bulun.İşlev,
searchCalendarEvents()
aranacak zaman aralığını tanımlamak için kullanılan başlangıç ve bitiş tarihi/saat değerlerini oluşturur. Ardından Microsoft Graph'ın uç noktasını çağırmakevents
için kullanılabilecek bir URL oluşturur ve parametre ilequery
başlangıç ve bitiş tarih/saat değişkenlerini içerir. Daha sonra bir GET isteği yapılır ve sonuçlar çağırana döndürülür.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; }
Oluşturulan URL'nin dökümü aşağıdadır:
- URL'nin
/me/events
bölümü, oturum açmış kullanıcının olaylarının alınması gerektiğini belirtmek için kullanılır. -
startdatetime
veenddatetime
parametreleri, aranacak zaman aralığını tanımlamak için kullanılır. Bu durumda, arama sonraki 7 gün içinde başlayan olayları döndürür. - Sorgu
$filter
parametresi, sonuçlarıquery
değere göre filtrelemek için kullanılır (bu örnekte veri kılavuzundan seçilen şirket adı).contains()
işlevi, takvim olayınınquery
özelliğindekisubject
değeri aramak için kullanılır. - Sorgu
$orderby
parametresi, sonuçlarıstart/dateTime
özelliğine göre sıralamak için kullanılır.
- URL'nin
url
oluşturulduktan sonra, değeriniurl
kullanarak Microsoft Graph API bir GET isteği yapılır ve sonuçlar çağırana döndürülür.Önceki bileşenlerde olduğu gibi , takvim olayları bileşeni (calendar-events.component.ts dosyası) çağrılar
search()
ve sonuçları görüntüler.override async search(query: string) { this.data = await this.graphService.searchCalendarEvents(query); }
Not
Microsoft Graph çağrılarını özel bir API'den veya sunucu tarafı uygulamasından da yapabilirsiniz. Azure İşlevi'nden Microsoft Graph API çağırma örneğini görmek için aşağıdaki öğreticiyi görüntüleyin.
Artık dosyaları, sohbetleri, e-posta iletilerini ve takvim olaylarını almak için Microsoft Graph kullanma örneğini gördünüz. Aynı kavramlar diğer Microsoft Graph API'lerine de uygulanabilir. Örneğin, kuruluşunuzdaki kullanıcıları aramak için Microsoft Graph kullanıcıları API'sini kullanabilirsiniz. Kuruluşunuzdaki grupları aramak için Microsoft Graph grupları API'sini de kullanabilirsiniz. Microsoft Graph API'lerinin tam listesini belgelerde görüntüleyebilirsiniz.
Tebrikler!
Bu öğreticiyi tamamladınız
Tebrikler! Azure OpenAI'nin kullanıcı üretkenliğini artırmak için nasıl kullanılabileceğini, iletişim özelliklerini tümleştirmek için Azure İletişim Hizmetleri nasıl kullanılabileceğini ve Microsoft Graph API'leri ile bileşenlerinin kuruluş verilerini almak ve görüntülemek için nasıl kullanılabileceğini öğrendiniz. Bu teknolojileri kullanarak, bağlam kaymalarını en aza indirerek ve gerekli karar alma bilgilerini sağlayarak kullanıcı üretkenliğini artıran etkili çözümler oluşturabilirsiniz.
Azure Kaynaklarını Temizleme
Hesabınıza ek ücret yansıtılmasını önlemek için Azure kaynaklarınızı temizleyin. Azure portal gidin ve aşağıdaki kaynakları silin:
- Azure Bilişsel Arama kaynağı
- Azure Depolama kaynağı
- Azure OpenAI kaynağı
- Azure İletişim Hizmetleri kaynağı
Sonraki Adımlar
Belgeler
- Azure OpenAI Belgeleri
- Verilerinizde Azure OpenAI
- Azure İletişim Hizmetleri Belgeleri
- Microsoft Graph Belgeleri
- Microsoft Graph Araç Seti Belgeleri
- Microsoft Teams Geliştirici Belgeleri
Eğitim İçeriği
- Azure OpenAI Hizmeti ile istem mühendisliği uygulama
- Azure OpenAI Hizmetini kullanmaya başlama
- Azure İletişim Hizmetleri giriş
- Microsoft Graph Ile İlgili Temel Bilgiler
- Video Kursu: Yeni Başlayanlar için Microsoft Graph TemelLeri
- JavaScript geliştirme için Microsoft Graph senaryolarını keşfedin
- ASP.NET Core geliştirme için Microsoft Graph senaryolarını keşfetme
- Microsoft Graph Toolkit'i kullanmaya başlama
- Visual Studio Code için Teams Toolkit kullanarak Microsoft Teams için uygulama derleme ve dağıtma
Bu bölümle ilgili bir sorununuz mu var? Öyleyse bu bölümü iyileştirebilmemiz için lütfen geri bildirimde bulunun.