Percakapan berbasis peristiwa menggunakan penanganan aktivitas
Artikel
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 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.
JavaScript ActivityHandler menggunakan pola pemancar peristiwa dan pendengar.
Misalnya, gunakan onMessage metode untuk mendaftarkan pendengar peristiwa untuk aktivitas pesan. Anda dapat mendaftarkan lebih dari satu listener. Ketika bot menerima aktivitas pesan, penanganan aktivitas akan melihat bahwa aktivitas masuk dan mengirimkannya masing-masing onMessage pendengar aktivitas, dalam urutan terdaftar.
Saat membangun bot Anda, logika bot Anda untuk menangani dan merespons pesan akan masuk ke onMessage pendengar. Demikian juga, logika Anda untuk menangani anggota yang ditambahkan ke percakapan akan masuk ke pendengar Anda onMembersAdded , yang dipanggil setiap kali anggota ditambahkan ke percakapan.
Untuk menambahkan listener ini, Anda akan mendaftarkannya di bot seperti yang terlihat di bagian logika Bot di bawah ini. Untuk setiap pendengar, sertakan logika bot Anda, lalu pastikan untuk memanggil next() di akhir. Dengan memanggil next(), Anda memastikan bahwa pendengar berikutnya dijalankan.
Pastikan untuk menyimpan status sebelum giliran berakhir. Anda dapat melakukannya dengan mengambil alih metode handler run aktivitas dan menyimpan status setelah metode induk run selesai.
Tidak ada situasi umum di mana Anda ingin mengambil alih handler giliran dasar, jadi berhati-hatilah jika Anda mencoba melakukannya.
Ada penangan khusus yang disebut onDialog. Handler onDialog berjalan di akhir, setelah penghandel lainnya berjalan, dan tidak terkait dengan jenis aktivitas tertentu. Seperti semua handler di atas, pastikan untuk memanggil next() untuk memastikan sisa proses dibungkus.
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. Tidak ada implementasi dasar untuk setiap handler ini, jadi 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 terlebih dahulu untuk memanggil super.onTurn(turnContext); untuk memastikan implementasi onTurn dasar dijalankan sebelum kode tambahan Anda. Implementasi dasar itu, antara lain, bertanggung jawab untuk memanggil seluruh penangan aktivitas seperti onMessageActivity.
Saat membangun bot Anda, logika bot Anda untuk menangani dan merespons pesan akan masuk ke handler ini on_message_activity . Demikian juga, logika Anda untuk menangani anggota yang ditambahkan ke percakapan akan masuk ke handler Anda on_members_added , yang dipanggil setiap kali anggota ditambahkan ke percakapan.
Misalnya, jika bot menerima aktivitas pesan, penangan giliran akan melihat bahwa aktivitas masuk dan mengirimkannya ke on_message_activity penanganan aktivitas.
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 super().on_turn(turnContext); untuk memastikan implementasi on_turn dasar dijalankan sebelum kode tambahan Anda. Implementasi dasar itu, antara lain, bertanggung jawab untuk memanggil seluruh penangan aktivitas seperti on_message_activity.
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.
Logika bot utama didefinisikan dalam kode bot. Untuk menerapkan bot sebagai penanganan aktivitas, perluas ActivityHandler. ActivityHandler menentukan berbagai peristiwa untuk berbagai jenis aktivitas, dan Anda dapat memodifikasi perilaku bot Anda dengan mendaftarkan pendengar peristiwa, seperti dengan onMessage dan onConversationUpdate.
Gunakan metode ini untuk mendaftarkan listener untuk setiap jenis peristiwa:
Kejadian
Metode pendaftaran
Deskripsi
Jenis aktivitas apa pun yang diterima
onTurn
Mendaftarkan pendengar saat aktivitas apa pun diterima.
Aktivitas pesan diterima
onMessage
Mendaftarkan pendengar saat message aktivitas diterima.
Aktivitas pembaruan percakapan diterima
onConversationUpdate
Mendaftarkan pendengar saat aktivitas apa pun conversationUpdate diterima.
Anggota bergabung dalam percakapan
onMembersAdded
Mendaftarkan pendengar saat anggota bergabung dalam percakapan, termasuk bot.
Anggota meninggalkan percakapan
onMembersRemoved
Mendaftarkan pendengar saat anggota meninggalkan percakapan, termasuk bot.
Aktivitas reaksi pesan diterima
onMessageReaction
Mendaftarkan pendengar saat aktivitas apa pun messageReaction diterima.
Reaksi pesan ditambahkan ke pesan
onReactionsAdded
Mendaftarkan pendengar ketika reaksi ditambahkan ke pesan.
Reaksi pesan dihapus dari pesan
onReactionsRemoved
Mendaftarkan pendengar ketika reaksi dihapus dari pesan.
Aktivitas peristiwa diterima
onEvent
Mendaftarkan pendengar saat aktivitas apa pun event diterima.
Aktivitas peristiwa respons token diterima
onTokenResponseEvent
Mendaftarkan pendengar saat tokens/response acara diterima.
Aktivitas pembaruan penginstalan diterima
onInstallationUpdate
Mendaftarkan pendengar saat aktivitas apa pun installationUpdate diterima.
Bot terpasang
onInstallationUpdateAdd
Mendaftarkan listener saat bot diinstal dalam unit organisasi.
Bot dihapus instalasinya
onInstallationUpdateRemove
Mendaftarkan pendengar saat bot dihapus instalannya dalam unit organisasi.
Jenis aktivitas lain yang diterima
onUnrecognizedActivityType
Mendaftarkan pendengar saat handler untuk jenis aktivitas tertentu tidak ditentukan.
Penanganan aktivitas telah selesai
onDialog
Dipanggil setelah handler yang berlaku selesai.
Panggil fungsi kelanjutan next dari setiap handler untuk memungkinkan pemrosesan berlanjut. Jika next tidak dipanggil, pemrosesan aktivitas berakhir.
Logika bot utama didefinisikan dalam kode bot. Untuk mengimplementasikan bot sebagai penanganan aktivitas, dapatkan kelas bot Anda dari ActivityHandler, yang mengimplementasikan Bot antarmuka. ActivityHandler mendefinisikan berbagai handler untuk berbagai jenis aktivitas, seperti onMessageActivity, dan onMembersAdded. 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
onTurn
Memanggil salah satu penangan lainnya, berdasarkan jenis aktivitas yang diterima.
Aktivitas pesan diterima
onMessageActivity
Ambil alih ini untuk menangani message aktivitas.
Aktivitas pembaruan percakapan diterima
onConversationUpdateActivity
conversationUpdate Pada aktivitas, memanggil handler jika anggota selain bot bergabung atau meninggalkan percakapan.
Anggota non-bot bergabung dalam percakapan
onMembersAdded
Ambil alih ini untuk menangani anggota yang bergabung dalam percakapan.
Anggota non-bot meninggalkan percakapan
onMembersRemoved
Ambil alih ini untuk menangani anggota yang meninggalkan percakapan.
Aktivitas peristiwa diterima
onEventActivity
event Pada aktivitas, memanggil handler khusus untuk jenis peristiwa.
Aktivitas peristiwa respons token diterima
onTokenResponseEvent
Ambil alih ini untuk menangani peristiwa respons token.
Aktivitas peristiwa non-token-response diterima
onEvent
Ambil alih ini untuk menangani jenis peristiwa lainnya.
Aktivitas reaksi pesan diterima
onMessageReactionActivity
messageReaction Pada aktivitas, memanggil handler jika satu atau beberapa reaksi ditambahkan atau dihapus dari pesan.
Reaksi pesan ditambahkan ke pesan
onReactionsAdded
Ambil alih ini untuk menangani reaksi yang ditambahkan ke pesan.
Reaksi pesan dihapus dari pesan
onReactionsRemoved
Ambil alih ini untuk menangani reaksi yang dihapus dari pesan.
Aktivitas pembaruan penginstalan diterima
onInstallationUpdate
installationUpdate Pada aktivitas, memanggil handler berdasarkan apakah bot diinstal atau dihapus instalasinya.
Bot terpasang
onInstallationUpdateAdd
Ambil alih ini untuk menambahkan logika saat bot diinstal dalam unit organisasi.
Bot dihapus instalasinya
onInstallationUpdateRemove
Ambil alih ini untuk menambahkan logika saat bot dihapus instalasinya dalam unit organisasi.
Jenis aktivitas lain yang diterima
onUnrecognizedActivityType
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, onMessageActivity akan selalu ditangani, dan umumnya adalah yang paling umum.
Ada juga opsi untuk menerapkan metode onTurnpublik . 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 onTurnkustom , itu masih merupakan opsi.
Penting
Jika Anda mengambil alih onTurn metode , Anda harus memanggil super.onTurn untuk mendapatkan implementasi dasar untuk memanggil semua handler lain on<activity> atau memanggil handler tersebut sendiri. Jika tidak, handler tersebut tidak akan dipanggil dan kode tersebut tidak akan dijalankan.
Logika bot utama didefinisikan dalam kode bot. Untuk menerapkan bot sebagai penanganan aktivitas, dapatkan kelas bot Anda dari ActivityHandler, yang pada gilirannya berasal dari kelas abstrak Bot . ActivityHandler mendefinisikan berbagai handler untuk berbagai jenis aktivitas, seperti on_message_activity dan on_members_added. 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
on_turn
Memanggil salah satu penangan lainnya, berdasarkan jenis aktivitas yang diterima.
Aktivitas pesan diterima
on_message_activity
Ambil alih ini untuk menangani message aktivitas.
Aktivitas pembaruan percakapan diterima
on_conversation_update_activity
conversationUpdate Pada aktivitas, memanggil handler jika anggota selain bot bergabung atau meninggalkan percakapan.
Anggota non-bot bergabung dalam percakapan
on_members_added_activity
Ambil alih ini untuk menangani anggota yang bergabung dalam percakapan.
Anggota non-bot meninggalkan percakapan
on_members_removed_activity
Ambil alih ini untuk menangani anggota yang meninggalkan percakapan.
Aktivitas peristiwa diterima
on_event_activity
event Pada aktivitas, memanggil handler khusus untuk jenis peristiwa.
Aktivitas peristiwa respons token diterima
on_token_response_event
Ambil alih ini untuk menangani peristiwa respons token.
Aktivitas peristiwa non-token-response diterima
on_event_activity
Ambil alih ini untuk menangani jenis peristiwa lainnya.
Aktivitas reaksi pesan diterima
on_message_reaction_activity
messageReaction Pada aktivitas, memanggil handler jika satu atau beberapa reaksi ditambahkan atau dihapus dari pesan.
Reaksi pesan ditambahkan ke pesan
on_reactions_added
Ambil alih ini untuk menangani reaksi yang ditambahkan ke pesan.
Reaksi pesan dihapus dari pesan
on_reactions_removed
Ambil alih ini untuk menangani reaksi yang dihapus dari pesan.
Aktivitas pembaruan penginstalan diterima
on_installation_update
installationUpdate Pada aktivitas, memanggil handler berdasarkan apakah bot diinstal atau dihapus instalasinya.
Bot terpasang
on_installation_update_add
Ambil alih ini untuk menambahkan logika saat bot diinstal dalam unit organisasi.
Bot dihapus instalasinya
on_installation_update_remove
Ambil alih ini untuk menambahkan logika saat bot dihapus instalasinya dalam unit organisasi.
Jenis aktivitas lain yang diterima
on_unrecognized_activity_type
Ambil alih ini untuk menangani jenis aktivitas apa pun jika tidak ditangani.
Handler yang berbeda ini memiliki turn_context 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, on_message_activity 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 on_turnpublik . 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 on_turnkustom , itu masih merupakan opsi.
Penting
Jika Anda mengambil alih on_turn metode , Anda harus memanggil super().on_turn untuk mendapatkan implementasi dasar untuk memanggil semua handler lain on_<activity> 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);
}
}
}
}
class EchoBot extends ActivityHandler {
constructor() {
super();
// See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
this.onMessage(async (context, next) => {
const replyText = `Echo: ${ context.activity.text }`;
await context.sendActivity(MessageFactory.text(replyText, replyText));
// By calling next() you ensure that the next BotHandler is run.
await next();
});
this.onMembersAdded(async (context, next) => {
const membersAdded = context.activity.membersAdded;
const welcomeText = 'Hello and welcome!';
for (let cnt = 0; cnt < membersAdded.length; ++cnt) {
if (membersAdded[cnt].id !== context.activity.recipient.id) {
await context.sendActivity(MessageFactory.text(welcomeText, welcomeText));
}
}
// By calling next() you ensure that the next BotHandler is run.
await next();
});
}
}
class EchoBot(ActivityHandler):
async def on_members_added_activity(
self, members_added: [ChannelAccount], turn_context: TurnContext
):
for member in members_added:
if member.id != turn_context.activity.recipient.id:
await turn_context.send_activity("Hello and welcome!")
async def on_message_activity(self, turn_context: TurnContext):
return await turn_context.send_activity(
MessageFactory.text(f"Echo: {turn_context.activity.text}")
)
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.