Mulai cepat: Menambahkan bot ke aplikasi obrolan Anda

Artikel
07/27/2022
8 menit untuk membaca

Penting

Fungsionalitas ini dalam pratinjau privat, dan dibatasi untuk sejumlah pengadopsi awal Azure Communication Services yang terbatas. Anda dapat mengirimkan formulir ini untuk meminta partisipasi dalam pratinjau dan kami akan meninjau skenario Anda dan mengevaluasi partisipasi Anda dalam pratinjau.

API Pratinjau Pribadi dan SDK disediakan tanpa perjanjian tingkat layanan, dan tidak sesuai untuk beban kerja produksi dan hanya boleh digunakan dengan pengguna uji dan data uji. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk mengetahui informasi selengkapnya, lihat Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure.

Dalam mulai cepat ini, kita akan mempelajari cara membangun pengalaman AI percakapan di aplikasi obrolan kita menggunakan saluran pesan 'Communication Services-Chat' yang tersedia di bawah Azure Bot Services. Kami akan membuat bot menggunakan BotFramework SDK dan mempelajari cara mengintegrasikan bot ini ke dalam aplikasi obrolan kami yang dibangun menggunakan Communication Services Chat SDK.

Anda akan mempelajari cara:

Membuat dan menyebarkan bot
Mendapatkan Sumber Daya Azure Communication Services
Mengaktifkan Saluran Obrolan Communication Services untuk bot
Membuat aplikasi obrolan dan menambahkan bot sebagai peserta
Menjelajahi fitur tambahan yang tersedia untuk bot

Prasyarat

Membuat akun Azure dengan langganan aktif. Untuk mengetahui detailnya, lihat Membuat akun secara gratis
Visual Studio (2019 dan lebih baru)
.NET Core 3.1 (Pastikan untuk menginstal versi yang sesuai dengan instans visual studio Anda, 32 vs 64 bit)

Langkah 1 - Membuat dan menyebarkan bot

Untuk menggunakan obrolan Azure Communication Services sebagai saluran di Azure Bot Service, langkah pertama adalah menyebarkan bot. Silakan ikuti langkah-langkah berikut:

Memprovisikan sumber daya layanan bot di Azure

Klik opsi buat sumber daya di portal Microsoft Azure.

Create a new resource

Cari Azure Bot dalam daftar jenis sumber daya yang tersedia.

Pilih Azure Bot untuk membuatnya.

Creat Azure Bot

Terakhir, buat sumber daya Azure Bot. Anda dapat menggunakan ID aplikasi Microsoft yang sudah ada atau menggunakan ID baru yang dibuat secara otomatis.

Mendapatkan MicrosoftAppId bot dan MicrosoftAppPassword

Setelah membuat sumber daya Azure Bot, langkah selanjutnya adalah mengatur kata sandi untuk ID Aplikasi yang kami tetapkan untuk kredensial Bot jika Anda memilih untuk membuatnya secara otomatis di langkah pertama.

Pilih Azure Active Directory

Azure Active Directory

Temukan aplikasi Anda di bilah Pendaftaran Aplikasi
Buat kata sandi baru untuk aplikasi Anda dari bilah Certificates and Secrets dan simpan kata sandi yang Anda buat karena Anda tidak akan dapat menyalinnya lagi.

Membuat Aplikasi Web tempat logika bot aktual berada

Buat Aplikasi Web tempat logika bot aktual berada. Anda dapat memeriksa beberapa sampel di Sampel Bot Builder dan mengubahnya atau menggunakan Bot Builder SDK untuk membuatnya: dokumentasi Bot Builder. Salah satu yang paling sederhana untuk dimainkan adalah Echo Bot yang terletak di sini dengan langkah-langkah tentang cara menggunakannya dan itu adalah yang digunakan dalam contoh ini Echo Bot. Umumnya, Bot Service mengharapkan Bot Application Web App Controller mengekspos titik /api/messagesakhir , yang menangani semua pesan yang mencapai bot. Untuk membuat aplikasi Bot, ikuti langkah-langkah ini.

Seperti yang ditunjukkan sebelumnya, buat sumber daya dan pilih Web App dalam pencarian.

Web app

Konfigurasikan opsi yang ingin Anda atur termasuk wilayah tempat Anda ingin menyebarkannya.

Web App Create Options

Tinjau opsi Anda dan buat Aplikasi Web dan pindah ke sumber daya setelah disediakan dan salin URL nama host yang diekspos oleh Aplikasi Web.

Web App endpoint

Mengonfigurasi Azure Bot

Konfigurasikan Azure Bot yang kami buat dengan titik akhir Aplikasi Web tempat logika bot berada. Untuk melakukan ini, salin URL nama host Aplikasi Web dan tambahkan dengan /api/messages

Menyebarkan Azure Bot

Langkah terakhir adalah menyebarkan logika bot ke Aplikasi Web yang kami buat. Seperti yang kami sebutkan untuk tutorial ini, kita akan menggunakan Bot Echo. Bot ini hanya menunjukkan serangkaian kemampuan terbatas, seperti menggemakan input pengguna. Berikut cara kami menyebarkannya ke Azure Web App.

Untuk menggunakan sampel, kloning repositori GitHub ini menggunakan Git. git clone https://github.com/Microsoft/BotBuilder-Samples.gitcd BotBuilder-Samples
Buka proyek yang terletak di sini bot Echo di Visual Studio.
Buka file appsettings.json di dalam proyek dan salin ID aplikasi dan kata sandi yang kami buat di langkah 2 di tempat masing-masing.
```
{
  "MicrosoftAppId": "<App-registration-id>",
  "MicrosoftAppPassword": "<App-password>"
}
```
Klik proyek untuk menerbitkan kode Aplikasi Web ke Azure. Pilih opsi terbitkan di Visual Studio.

Publish app

Klik Baru untuk membuat profil penerbitan baru, pilih Azure sebagai target, dan Azure App Service sebagai target tertentu.

Select Azure as Target

Select App Service

Terakhir, opsi di atas membuka konfigurasi penyebaran. Pilih Aplikasi Web yang telah kami sediakan dari daftar opsi yang muncul setelah masuk ke akun Azure Anda. Setelah siap klik Finish untuk memulai penyebaran.

Langkah 2 - Mendapatkan Sumber Daya Azure Communication Services

Sekarang setelah Anda mendapatkan bagian bot yang diurutkan, kita harus mendapatkan sumber daya Azure Communication Services, yang akan kami gunakan untuk mengonfigurasi saluran Azure Communication Services.

Membuat sumber daya Azure Communication Services. Untuk detailnya, lihat Membuat sumber daya Azure Communication Services.
Buat Pengguna Azure Communication Services dan terbitkan token akses pengguna Token Akses Pengguna. Pastikan untuk mengatur cakupan ke obrolan, dan catat string token serta string userId.

Langkah 3 - Aktifkan Saluran Obrolan Azure Communication Services

Dengan sumber daya Azure Communication Services, kita dapat mengonfigurasi saluran Azure Communication Services di Azure Bot untuk mengikat ID Pengguna Azure Communication Services dengan bot. Perhatikan bahwa saat ini, hanya akun Azure yang diizinkan yang dapat melihat saluran Azure Communication Services - Obrolan.

Buka sumber daya Bot Services Anda di portal Microsoft Azure. Navigasi ke Channels bilah dan klik Azure Communications Services - Chat saluran dari daftar yang disediakan.
Pilih dari daftar dropdown sumber daya Azure Communication Services yang ingin Anda sambungkan.
Setelah detail sumber daya yang disediakan diverifikasi, Anda akan melihat ID Azure Communication Services bot yang ditetapkan. Dengan ID ini, Anda dapat menambahkan bot ke percakapan kapan pun sesuai menggunakan Api AddParticipant Obrolan. Setelah bot ditambahkan sebagai peserta obrolan, bot akan mulai menerima aktivitas terkait obrolan dan dapat merespons kembali di utas obrolan.

Langkah 4 - Membuat aplikasi obrolan dan menambahkan bot sebagai peserta

Sekarang setelah Anda memiliki ID Azure Communication Services bot, Anda akan dapat membuat utas obrolan dengan bot sebagai peserta.

Membuat aplikasi C# baru

dotnet new console -o ChatQuickstart

Ubah direktori Anda ke folder aplikasi yang baru dibuat dan gunakan perintah dotnet build untuk mengompilasi aplikasi Anda.

cd ChatQuickstart
dotnet build

Menginstal paket

Menginstal Azure Communication Chat SDK untuk .NET

dotnet add package Azure.Communication.Chat

Membuat klien obrolan

Untuk membuat klien obrolan, Anda akan menggunakan titik akhir Communication Services dan token akses yang dihasilkan sebagai bagian dari Langkah 2. Anda perlu menggunakan kelas CommunicationIdentityClient dari SDK Identitas untuk membuat pengguna dan menerbitkan token untuk diteruskan ke klien obrolan Anda.

Salin cuplikan kode berikut dan tempelkan ke file sumber: Program.cs

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Azure Communication service endpoint
            Uri endpoint = new Uri("https://<RESOURCE_NAME>.communication.azure.com");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

Memulai utas obrolan dengan bot

createChatThread Gunakan metode pada chatClient untuk membuat utas obrolan, ganti dengan ID Azure Communication Services bot yang Anda peroleh.

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<BOT_ID>"))
{
    DisplayName = "BotDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello Bot!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

Mendapatkan klien utas obrolan

Metode GetChatThreadClient mengembalikan klien utas untuk utas yang sudah ada.

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Mengirim pesan ke utas obrolan

Gunakan SendMessage untuk mengirim pesan ke utas.

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Hello World",
    MessageType = ChatMessageType.Text
};

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Menerima pesan obrolan dari utas obrolan

Anda dapat mengambil pesan obrolan dengan mengumpulkan metode GetMessages pada klien utas obrolan pada interval yang ditentukan.

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

Anda akan melihat balasan gema bot ke "Halo Dunia" dalam daftar pesan. Saat membuat aplikasi obrolan yang sebenarnya, Anda juga dapat menerima pesan obrolan real-time dengan berlangganan untuk mendengarkan pesan masuk baru menggunakan JavaScript atau SDK seluler kami. Contoh menggunakan JavaScript SDK adalah:

// open notifications channel
await chatClient.startRealtimeNotifications();
// subscribe to new notification
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // your code here
});

Menyebarkan aplikasi obrolan C#

Jika Anda ingin menyebarkan aplikasi obrolan, Anda dapat mengikuti langkah-langkah berikut:

Buka proyek obrolan di Visual Studio.
Klik kanan pada proyek ChatQuickstart dan klik Terbitkan

Lebih banyak hal yang dapat Anda lakukan dengan bot

Selain pesan teks sederhana, bot juga dapat menerima dan mengirim banyak aktivitas lain termasuk

Pembaruan percakapan
Pembaruan pesan
Penghapusan pesan
Indikator pengetikan
Aktivitas peristiwa

Mengirim pesan selamat datang saat pengguna baru ditambahkan ke utas

Dengan logika Bot Echo saat ini, ia menerima input dari pengguna dan menggemakannya kembali. Jika Anda ingin menambahkan logika tambahan seperti merespons peristiwa Azure Communication Services yang ditambahkan peserta, salin cuplikan kode berikut dan tempelkan ke file sumber: EchoBot.cs

using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;

namespace Microsoft.BotBuilderSamples.Bots
{
    public class EchoBot : ActivityHandler
    {
        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        {
            if (turnContext.Activity.Type == ActivityTypes.Message)
            {
                var replyText = $"Echo: {turnContext.Activity.Text}";
                await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
            }
            else if (ActivityTypes.ConversationUpdate.Equals(turnContext.Activity.Type))
            {
                if (turnContext.Activity.MembersAdded != null)
                {
                    foreach (var member in turnContext.Activity.MembersAdded)
                    {
                        if (member.Id != turnContext.Activity.Recipient.Id)
                        {
                            await turnContext.SendActivityAsync(MessageFactory.Text("Hello and welcome to chat with EchoBot!"), cancellationToken);
                        }
                    }
                }
            }
        }
    }
}

Mengirim kartu adaptif

Untuk membantu Anda meningkatkan keterlibatan dan efisiensi serta berkomunikasi dengan pengguna dengan berbagai cara, Anda dapat mengirim kartu adaptif ke utas obrolan. Anda dapat mengirim kartu adaptif dari bot dengan menambahkannya sebagai lampiran aktivitas bot.

var reply = Activity.CreateMessageActivity();
var adaptiveCard = new Attachment()
{
    ContentType = "application/vnd.microsoft.card.adaptive",
    Content = {/* the adaptive card */}
};
reply.Attachments.Add(adaptiveCard);   
await turnContext.SendActivityAsync(reply, cancellationToken);

Anda dapat menemukan contoh payload untuk kartu adaptif di Sampel dan Templat

Dan di sisi Pengguna Azure Communication Services, bidang metadata pesan Azure Communication Services akan menunjukkan ini adalah pesan dengan lampiran. Kuncinya adalah microsoft.azure.communication.chat.bot.contenttype, yang diatur ke nilai azurebotservice.adaptivecard. Ini adalah contoh pesan obrolan yang akan diterima:

{
 "content": "{\"attachments\":[{\"contentType\":\"application/vnd.microsoft.card.adaptive\",\"content\":{/* the adaptive card */}}]}",
 "senderDisplayName": "BotDisplayName",
 "metadata": {
  "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
 },
 "messageType": "Text"
}

Langkah berikutnya

Coba Aplikasi Sampel, yang menampilkan obrolan 1:1 antara pengguna akhir dan bot obrolan, dan menggunakan komponen antarmuka pengguna WebChat BotFramework.