Bagikan melalui


Percakapan berbasis peristiwa menggunakan penanganan aktivitas

BERLAKU UNTUK: SDK v4

Penanganan aktivitas adalah cara berbasis peristiwa untuk mengatur logika percakapan untuk bot Anda. Setiap jenis atau subjenis aktivitas yang berbeda mewakili jenis peristiwa percakapan yang berbeda. Di bawah sampul, handler giliran bot memanggil penangan aktivitas individu untuk jenis aktivitas apa pun yang diterimanya.

Misalnya, jika bot menerima aktivitas pesan, penangan giliran akan melihat bahwa aktivitas masuk dan mengirimkannya ke penanganan aktivitas aktivitas pesan. Saat membangun bot Anda, logika bot Anda untuk menangani dan merespons pesan akan masuk ke ini pada penanganan aktivitas pesan. Demikian juga, logika Anda untuk menangani anggota yang ditambahkan ke percakapan akan masuk ke handler yang ditambahkan anggota Anda, yang dipanggil setiap kali anggota ditambahkan ke percakapan.

Untuk cara lain untuk mengatur logika bot Anda, lihat bagian logika bot dalam cara kerja bot.

Catatan

Bot Framework JavaScript, C#, dan Python SDK akan terus didukung, namun, Java SDK dihentikan dengan dukungan jangka panjang akhir yang berakhir pada November 2023.

Bot yang ada yang dibangun dengan Java SDK akan terus berfungsi.

Untuk pembuatan bot baru, pertimbangkan untuk menggunakan Microsoft Copilot Studio dan baca tentang memilih solusi salinan yang tepat.

Untuk informasi selengkapnya, lihat Masa depan pembuatan bot.

Untuk menerapkan logika Anda untuk handler ini, Anda akan mengambil alih metode ini di bot Anda, seperti di bagian penangan aktivitas sampel di bawah ini. Untuk setiap handler ini, tidak ada implementasi dasar, jadi cukup tambahkan logika yang Anda inginkan dalam penimpaan Anda.

Ada situasi tertentu di mana Anda ingin mengambil alih penangan giliran dasar, seperti menyimpan status di akhir giliran. Saat melakukannya, pastikan untuk terlebih dahulu memanggil await base.OnTurnAsync(turnContext, cancellationToken); untuk memastikan implementasi OnTurnAsync dasar dijalankan sebelum kode tambahan Anda. Implementasi dasar itu, antara lain, bertanggung jawab untuk memanggil seluruh penangan aktivitas seperti OnMessageActivityAsync.

Penanganan aktivitas

Logika bot memproses aktivitas masuk dari satu atau beberapa saluran dan menghasilkan aktivitas keluar sebagai respons.

Logika bot utama didefinisikan dalam kode bot. Untuk mengimplementasikan bot sebagai penanganan aktivitas, dapatkan kelas bot Anda dari ActivityHandler, yang mengimplementasikan IBot antarmuka. ActivityHandler mendefinisikan berbagai handler untuk berbagai jenis aktivitas, seperti OnMessageActivityAsync, dan OnMembersAddedAsync. Metode ini dilindungi, tetapi dapat ditimpa, karena kita berasal dari ActivityHandler.

Handler yang didefinisikan adalah ActivityHandler :

Kejadian Penghandel Deskripsi
Jenis aktivitas apa pun yang diterima OnTurnAsync Memanggil salah satu penangan lainnya, berdasarkan jenis aktivitas yang diterima.
Aktivitas pesan diterima OnMessageActivityAsync Ambil alih ini untuk menangani message aktivitas.
Aktivitas pembaruan percakapan diterima OnConversationUpdateActivityAsync conversationUpdate Pada aktivitas, memanggil handler jika anggota selain bot bergabung atau meninggalkan percakapan.
Anggota non-bot bergabung dalam percakapan OnMembersAddedAsync Ambil alih ini untuk menangani anggota yang bergabung dalam percakapan.
Anggota non-bot meninggalkan percakapan OnMembersRemovedAsync Ambil alih ini untuk menangani anggota yang meninggalkan percakapan.
Aktivitas peristiwa diterima OnEventActivityAsync event Pada aktivitas, memanggil handler khusus untuk jenis peristiwa.
Aktivitas peristiwa respons token diterima OnTokenResponseEventAsync Ambil alih ini untuk menangani peristiwa respons token.
Aktivitas peristiwa non-token-response diterima OnEventAsync Ambil alih ini untuk menangani jenis peristiwa lainnya.
Aktivitas reaksi pesan diterima OnMessageReactionActivityAsync messageReaction Pada aktivitas, memanggil handler jika satu atau beberapa reaksi ditambahkan atau dihapus dari pesan.
Reaksi pesan ditambahkan ke pesan OnReactionsAddedAsync Ambil alih ini untuk menangani reaksi yang ditambahkan ke pesan.
Reaksi pesan dihapus dari pesan OnReactionsRemovedAsync Ambil alih ini untuk menangani reaksi yang dihapus dari pesan.
Aktivitas pembaruan penginstalan diterima OnInstallationUpdateActivityAsync installationUpdate Pada aktivitas, memanggil handler berdasarkan apakah bot diinstal atau dihapus instalasinya.
Bot terpasang OnInstallationUpdateAddAsync Ambil alih ini untuk menambahkan logika saat bot diinstal dalam unit organisasi.
Bot dihapus instalasinya OnInstallationUpdateRemoveAsync Ambil alih ini untuk menambahkan logika saat bot dihapus instalasinya dalam unit organisasi.
Jenis aktivitas lain yang diterima OnUnrecognizedActivityTypeAsync Ambil alih ini untuk menangani jenis aktivitas apa pun jika tidak ditangani.

Handler yang berbeda ini memiliki turnContext yang menyediakan informasi tentang aktivitas masuk, yang sesuai dengan permintaan HTTP masuk. Aktivitas dapat dari berbagai jenis, sehingga setiap handler menyediakan aktivitas yang sangat ditik dalam parameter konteks gilirannya; dalam kebanyakan kasus, OnMessageActivityAsync akan selalu ditangani, dan umumnya adalah yang paling umum.

Seperti pada versi 4.x sebelumnya dari kerangka kerja ini, ada juga opsi untuk menerapkan metode OnTurnAsyncpublik . Saat ini, implementasi dasar metode ini menangani pemeriksaan kesalahan dan kemudian memanggil masing-masing handler tertentu (seperti dua yang kami tentukan dalam sampel ini) tergantung pada jenis aktivitas masuk. Dalam kebanyakan kasus, Anda dapat membiarkan metode itu sendirian dan menggunakan penangan individual, tetapi jika situasi Anda memerlukan implementasi OnTurnAsynckustom , itu masih merupakan opsi.

Penting

Jika Anda mengambil alih OnTurnAsync metode , Anda harus memanggil base.OnTurnAsync untuk mendapatkan implementasi dasar untuk memanggil semua handler lain On<activity>Async atau memanggil handler tersebut sendiri. Jika tidak, handler tersebut tidak akan dipanggil dan kode tersebut tidak akan dijalankan.

Penangan aktivitas sampel

Misalnya, Anda dapat menangani anggota yang ditambahkan untuk menyambut pengguna ke percakapan, dan menangani pesan untuk menggemakan kembali pesan yang mereka kirim ke bot.

public class EchoBot : ActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var replyText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
    }

    protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
    {
        var welcomeText = "Hello and welcome!";
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text(welcomeText, welcomeText), cancellationToken);
            }
        }
    }
}

Langkah berikutnya

  • Saluran Microsoft Teams memperkenalkan beberapa aktivitas khusus Teams yang perlu didukung bot Anda untuk bekerja dengan baik dengan Teams. Untuk memahami konsep utama pengembangan bot untuk Microsoft Teams, lihat Cara kerja bot Microsoft Teams
  • Handler aktivitas adalah cara yang baik untuk merancang bot yang tidak perlu melacak status percakapan antar belokan. Pustaka dialog menyediakan cara untuk mengelola percakapan yang berjalan lama dengan pengguna.