Gebeurtenisgestuurde gesprekken met behulp van een activiteitshandler
Artikel
VAN TOEPASSING OP: SDK v4
Een activiteitshandler is een gebeurtenisgestuurde manier om de gesprekslogica voor uw bot te organiseren.
Elk ander type of subtype van activiteit vertegenwoordigt een ander type gespreksevenement.
Onder de covers roept de turn-handler van de bot de afzonderlijke activiteitshandler aan voor welk type activiteit de bot ook heeft ontvangen.
Als de bot bijvoorbeeld een berichtactiviteit ontvangt, ziet de draaihandler die binnenkomende activiteit en verzendt deze naar de handler voor berichtactiviteit . Bij het bouwen van uw bot gaat uw botlogica voor het verwerken en reageren op berichten hierin op de handler voor berichtactiviteiten . Op dezelfde manier gaat uw logica voor het verwerken van leden die aan het gesprek worden toegevoegd, in uw aan leden toegevoegde handler, die wordt aangeroepen wanneer een lid wordt toegevoegd aan het gesprek.
De Sdk's voor Bot Framework JavaScript, C# en Python blijven ondersteund, maar de Java SDK wordt buiten gebruik gesteld met definitieve langetermijnondersteuning die eindigt op november 2023.
Bestaande bots die zijn gebouwd met de Java SDK blijven functioneren.
Als u uw logica voor deze handlers wilt implementeren, overschrijft u deze methoden in uw bot, zoals in de onderstaande sectie voor de handler voor voorbeeldactiviteiten. Voor elk van deze handlers is er geen basis-implementatie, dus voeg gewoon de logica toe die u wilt gebruiken in uw onderdrukking.
Er zijn bepaalde situaties waarin u de basisdraaihandler wilt overschrijven, zoals het opslaan van de status aan het einde van een draai. Als u dit doet, moet u eerst aanroepen await base.OnTurnAsync(turnContext, cancellationToken); om ervoor te zorgen dat de basis-implementatie van OnTurnAsync wordt uitgevoerd voordat uw aanvullende code wordt uitgevoerd. Deze basis-implementatie is onder andere verantwoordelijk voor het aanroepen van de rest van de activiteitshandlers zoals OnMessageActivityAsync.
JavaScript ActivityHandler maakt gebruik van een gebeurtenis-emitter- en listenerpatroon.
Gebruik bijvoorbeeld de onMessage methode om een gebeurtenislistener te registreren voor berichtactiviteiten. U kunt meer dan één listener registreren. Wanneer de bot een berichtactiviteit ontvangt, ziet de activiteitshandler die binnenkomende activiteit en verzendt deze elke activiteitlisteners onMessage , in de volgorde waarin ze zijn geregistreerd.
Bij het bouwen van uw bot gaat uw botlogica voor het verwerken en reageren op berichten in de onMessage listeners. Op dezelfde manier gaat uw logica voor het verwerken van leden die aan het gesprek worden toegevoegd, in uw onMembersAdded listeners, die worden aangeroepen wanneer een lid wordt toegevoegd aan het gesprek.
Als u deze listeners wilt toevoegen, registreert u deze in uw bot, zoals te zien is in de sectie Botlogica hieronder. Neem voor elke listener uw botlogica op en zorg ervoor dat u aan het einde aanroeptnext(). Door aan te roepen next(), zorgt u ervoor dat de volgende listener wordt uitgevoerd.
Zorg ervoor dat u de status opslaat voordat de draai eindigt. U kunt dit doen door de methode activiteitshandler run te overschrijven en de status op te slaan nadat de methode van run het bovenliggende item is voltooid.
Er zijn geen veelvoorkomende situaties waarin u de basisdraaihandler wilt overschrijven, dus wees voorzichtig als u dit probeert te doen.
Er is een speciale handler genaamd onDialog. De onDialog handler wordt aan het einde uitgevoerd, nadat de rest van de handlers zijn uitgevoerd en niet is gekoppeld aan een bepaald activiteitstype. Net als bij alle bovenstaande handlers moet u ervoor zorgen dat next() de rest van het proces wordt verpakt.
Als u uw logica voor deze handlers wilt implementeren, overschrijft u deze methoden in uw bot, zoals in de onderstaande sectie voor de handler voor voorbeeldactiviteiten. Er is geen basis-implementatie voor elk van deze handlers, dus voeg de gewenste logica toe in uw onderdrukking.
Er zijn bepaalde situaties waarin u de basisdraaihandler wilt overschrijven, zoals het opslaan van de status aan het einde van een draai. Als u dit doet, moet u eerst aanroepen super.onTurn(turnContext); om ervoor te zorgen dat de basis-implementatie van onTurn wordt uitgevoerd voordat uw aanvullende code wordt uitgevoerd. Deze basis-implementatie is onder andere verantwoordelijk voor het aanroepen van de rest van de activiteitshandlers zoals onMessageActivity.
Bij het bouwen van uw bot gaat uw botlogica voor het verwerken en reageren op berichten in deze on_message_activity handler. Op dezelfde manier gaat uw logica voor het verwerken van leden die aan het gesprek worden toegevoegd in uw on_members_added handler, die wordt aangeroepen wanneer een lid wordt toegevoegd aan het gesprek.
Als de bot bijvoorbeeld een berichtactiviteit ontvangt, ziet de draaihandler die binnenkomende activiteit en verzendt deze naar de on_message_activity activiteitshandler.
Als u uw logica voor deze handlers wilt implementeren, overschrijft u deze methoden in uw bot, zoals in de onderstaande sectie voor de handler voor voorbeeldactiviteiten. Voor elk van deze handlers is er geen basis-implementatie, dus voeg gewoon de logica toe die u wilt gebruiken in uw onderdrukking.
Er zijn bepaalde situaties waarin u de basisdraaihandler wilt overschrijven, zoals het opslaan van de status aan het einde van een draai. Als u dit doet, moet u eerst aanroepen await super().on_turn(turnContext); om ervoor te zorgen dat de basis-implementatie van on_turn wordt uitgevoerd voordat uw aanvullende code wordt uitgevoerd. Deze basis-implementatie is onder andere verantwoordelijk voor het aanroepen van de rest van de activiteitshandlers zoals on_message_activity.
Activiteitsafhandeling
De botlogica verwerkt binnenkomende activiteiten van een of meer kanalen en genereert uitgaande activiteiten als reactie.
De belangrijkste botlogica wordt gedefinieerd in de botcode. Als u een bot wilt implementeren als een activiteitshandler, moet u uw botklasse afleiden van ActivityHandler, waarmee de IBot interface wordt geïmplementeerd. ActivityHandler definieert verschillende handlers voor verschillende soorten activiteiten, zoals OnMessageActivityAsync, en OnMembersAddedAsync. Deze methoden zijn beveiligd, maar kunnen worden overschreven, omdat we hiervan ActivityHandlerafhalen.
De handlers die zijn gedefinieerd in ActivityHandler zijn:
Gebeurtenis
Handler
Beschrijving
Elk activiteitstype dat is ontvangen
OnTurnAsync
Roept een van de andere handlers aan op basis van het type activiteit dat is ontvangen.
Berichtactiviteit ontvangen
OnMessageActivityAsync
Overschrijf dit om een message activiteit af te handelen.
Ontvangen activiteit voor gespreksupdate
OnConversationUpdateActivityAsync
In een conversationUpdate activiteit roept u een handler aan als andere leden dan de bot deelnemen aan of het gesprek verlaten.
Niet-botleden zijn lid geworden van het gesprek
OnMembersAddedAsync
Overschrijf dit om leden die deelnemen aan een gesprek af te handelen.
Niet-botleden hebben het gesprek verlaten
OnMembersRemovedAsync
Overschrijf dit om leden af te handelen die een gesprek verlaten.
Gebeurtenisactiviteit ontvangen
OnEventActivityAsync
Bij een event activiteit roept u een handler aan die specifiek is voor het gebeurtenistype.
Activiteit van tokenresponsgebeurtenis ontvangen
OnTokenResponseEventAsync
Overschrijf dit om reactiegebeurtenissen van tokens af te handelen.
Gebeurtenisactiviteit voor niet-tokenantwoord ontvangen
OnEventAsync
Overschrijf dit om andere typen gebeurtenissen te verwerken.
Berichtreactieactiviteit ontvangen
OnMessageReactionActivityAsync
Bij een messageReaction activiteit roept u een handler aan als een of meer reacties zijn toegevoegd aan of verwijderd uit een bericht.
Berichtreacties toegevoegd aan een bericht
OnReactionsAddedAsync
Overschrijf dit om reacties af te handelen die zijn toegevoegd aan een bericht.
Berichtreacties verwijderd uit een bericht
OnReactionsRemovedAsync
Overschrijf dit om reacties af te handelen die zijn verwijderd uit een bericht.
Ontvangen installatie-updateactiviteit
OnInstallationUpdateActivityAsync
Bij een installationUpdate activiteit roept u een handler aan op basis van of de bot is geïnstalleerd of verwijderd.
Bot geïnstalleerd
OnInstallationUpdateAddAsync
Overschrijf dit om logica toe te voegen voor wanneer de bot in een organisatie-eenheid is geïnstalleerd.
Bot verwijderd
OnInstallationUpdateRemoveAsync
Overschrijf dit om logica toe te voegen voor wanneer de bot wordt verwijderd in een organisatie-eenheid.
Ander activiteitstype ontvangen
OnUnrecognizedActivityTypeAsync
Overschrijf dit om elk activiteitstype af te handelen, anders niet verwerkt.
Deze verschillende handlers bevatten informatie turnContext over de binnenkomende activiteit, die overeenkomt met de inkomende HTTP-aanvraag. Activiteiten kunnen van verschillende typen zijn, dus elke handler biedt een sterk getypte activiteit in de contextparameter van zijn beurt; in de meeste gevallen OnMessageActivityAsync wordt altijd afgehandeld en is over het algemeen de meest voorkomende.
Net als in vorige 4.x-versies van dit framework, is er ook de optie om de openbare methode OnTurnAsyncte implementeren. Momenteel verwerkt de basis-implementatie van deze methode foutcontrole en roept vervolgens elk van de specifieke handlers aan (zoals de twee die we in dit voorbeeld definiëren) afhankelijk van het type binnenkomende activiteit. In de meeste gevallen kunt u die methode alleen laten en de afzonderlijke handlers gebruiken, maar als voor uw situatie een aangepaste implementatie OnTurnAsyncis vereist, is dit nog steeds een optie.
Belangrijk
Als u de OnTurnAsync methode overschrijft, moet u de basis-implementatie aanroepen base.OnTurnAsync om alle andere On<activity>Async handlers aan te roepen of deze handlers zelf aan te roepen. Anders worden deze handlers niet aangeroepen en wordt die code niet uitgevoerd.
De belangrijkste botlogica wordt gedefinieerd in de botcode. Als u een bot wilt implementeren als een activiteitshandler, kunt u uitbreiden ActivityHandler. ActivityHandler definieert verschillende gebeurtenissen voor verschillende soorten activiteiten en u kunt het gedrag van uw bot wijzigen door gebeurtenislisteners te registreren, zoals bij onMessage en onConversationUpdate.
Gebruik deze methoden om listeners te registreren voor elk type gebeurtenis:
Gebeurtenis
Registratiemethode
Beschrijving
Elk activiteitstype dat is ontvangen
onTurn
Registreert een listener voor wanneer een activiteit wordt ontvangen.
Berichtactiviteit ontvangen
onMessage
Registreert een listener voor wanneer een message activiteit wordt ontvangen.
Ontvangen activiteit voor gespreksupdate
onConversationUpdate
Registreert een listener voor wanneer een conversationUpdate activiteit wordt ontvangen.
Leden zijn lid geworden van het gesprek
onMembersAdded
Registreert een listener voor wanneer leden deelnemen aan het gesprek, inclusief de bot.
Leden hebben het gesprek verlaten
onMembersRemoved
Registreert een listener voor wanneer leden het gesprek hebben verlaten, inclusief de bot.
Berichtreactieactiviteit ontvangen
onMessageReaction
Registreert een listener voor wanneer een messageReaction activiteit wordt ontvangen.
Berichtreacties toegevoegd aan een bericht
onReactionsAdded
Registreert een listener voor wanneer reacties worden toegevoegd aan een bericht.
Berichtreacties verwijderd uit een bericht
onReactionsRemoved
Registreert een listener voor wanneer reacties uit een bericht worden verwijderd.
Gebeurtenisactiviteit ontvangen
onEvent
Registreert een listener voor wanneer een event activiteit wordt ontvangen.
Activiteit van tokenresponsgebeurtenis ontvangen
onTokenResponseEvent
Registreert een listener voor wanneer een tokens/response gebeurtenis wordt ontvangen.
Ontvangen installatie-updateactiviteit
onInstallationUpdate
Registreert een listener voor wanneer een installationUpdate activiteit wordt ontvangen.
Bot geïnstalleerd
onInstallationUpdateAdd
Registreert een listener voor wanneer de bot in een organisatie-eenheid is geïnstalleerd.
Bot verwijderd
onInstallationUpdateRemove
Registreert een listener voor wanneer de bot wordt verwijderd binnen een organisatie-eenheid.
Ander activiteitstype ontvangen
onUnrecognizedActivityType
Registreert een listener voor wanneer een handler voor het specifieke type activiteit niet is gedefinieerd.
Activiteitshandlers zijn voltooid
onDialog
Aangeroepen nadat alle toepasselijke handlers zijn voltooid.
Roep de next vervolgfunctie van elke handler aan om de verwerking door te laten gaan. Als next dit niet wordt aangeroepen, eindigt de verwerking van de activiteit.
De belangrijkste botlogica wordt gedefinieerd in de botcode. Als u een bot wilt implementeren als een activiteitshandler, moet u uw botklasse afleiden van ActivityHandler, waarmee de Bot interface wordt geïmplementeerd. ActivityHandler definieert verschillende handlers voor verschillende soorten activiteiten, zoals onMessageActivity, en onMembersAdded. Deze methoden zijn beveiligd, maar kunnen worden overschreven, omdat we hiervan ActivityHandlerafhalen.
De handlers die zijn gedefinieerd in ActivityHandler zijn:
Gebeurtenis
Handler
Beschrijving
Elk activiteitstype dat is ontvangen
onTurn
Roept een van de andere handlers aan op basis van het type activiteit dat is ontvangen.
Berichtactiviteit ontvangen
onMessageActivity
Overschrijf dit om een message activiteit af te handelen.
Ontvangen activiteit voor gespreksupdate
onConversationUpdateActivity
In een conversationUpdate activiteit roept u een handler aan als andere leden dan de bot deelnemen aan of het gesprek verlaten.
Niet-botleden zijn lid geworden van het gesprek
onMembersAdded
Overschrijf dit om leden die deelnemen aan een gesprek af te handelen.
Niet-botleden hebben het gesprek verlaten
onMembersRemoved
Overschrijf dit om leden af te handelen die een gesprek verlaten.
Gebeurtenisactiviteit ontvangen
onEventActivity
Bij een event activiteit roept u een handler aan die specifiek is voor het gebeurtenistype.
Activiteit van tokenresponsgebeurtenis ontvangen
onTokenResponseEvent
Overschrijf dit om reactiegebeurtenissen van tokens af te handelen.
Gebeurtenisactiviteit voor niet-tokenantwoord ontvangen
onEvent
Overschrijf dit om andere typen gebeurtenissen te verwerken.
Berichtreactieactiviteit ontvangen
onMessageReactionActivity
Bij een messageReaction activiteit roept u een handler aan als een of meer reacties zijn toegevoegd aan of verwijderd uit een bericht.
Berichtreacties toegevoegd aan een bericht
onReactionsAdded
Overschrijf dit om reacties af te handelen die zijn toegevoegd aan een bericht.
Berichtreacties verwijderd uit een bericht
onReactionsRemoved
Overschrijf dit om reacties af te handelen die zijn verwijderd uit een bericht.
Ontvangen installatie-updateactiviteit
onInstallationUpdate
Bij een installationUpdate activiteit roept u een handler aan op basis van of de bot is geïnstalleerd of verwijderd.
Bot geïnstalleerd
onInstallationUpdateAdd
Overschrijf dit om logica toe te voegen voor wanneer de bot in een organisatie-eenheid is geïnstalleerd.
Bot verwijderd
onInstallationUpdateRemove
Overschrijf dit om logica toe te voegen voor wanneer de bot wordt verwijderd in een organisatie-eenheid.
Ander activiteitstype ontvangen
onUnrecognizedActivityType
Overschrijf dit om elk activiteitstype af te handelen, anders niet verwerkt.
Deze verschillende handlers bevatten informatie turnContext over de binnenkomende activiteit, die overeenkomt met de inkomende HTTP-aanvraag. Activiteiten kunnen van verschillende typen zijn, dus elke handler biedt een sterk getypte activiteit in de contextparameter van zijn beurt; in de meeste gevallen onMessageActivity wordt altijd afgehandeld en is over het algemeen de meest voorkomende.
Er is ook de optie om de openbare methode onTurnte implementeren. Momenteel verwerkt de basis-implementatie van deze methode foutcontrole en roept vervolgens elk van de specifieke handlers aan (zoals de twee die we in dit voorbeeld definiëren) afhankelijk van het type binnenkomende activiteit. In de meeste gevallen kunt u die methode alleen laten en de afzonderlijke handlers gebruiken, maar als voor uw situatie een aangepaste implementatie onTurnis vereist, is dit nog steeds een optie.
Belangrijk
Als u de onTurn methode overschrijft, moet u de basis-implementatie aanroepen super.onTurn om alle andere on<activity> handlers aan te roepen of deze handlers zelf aan te roepen. Anders worden deze handlers niet aangeroepen en wordt die code niet uitgevoerd.
De belangrijkste botlogica wordt gedefinieerd in de botcode. Als u een bot wilt implementeren als een activiteitshandler, moet u de botklasse afleiden van ActivityHandler, die op zijn beurt is afgeleid van de abstracte Bot klasse. ActivityHandler definieert verschillende handlers voor verschillende soorten activiteiten, zoals on_message_activity en on_members_added. Deze methoden zijn beveiligd, maar kunnen worden overschreven, omdat we hiervan ActivityHandlerafhalen.
De handlers die zijn gedefinieerd in ActivityHandler zijn:
Gebeurtenis
Handler
Beschrijving
Elk activiteitstype dat is ontvangen
on_turn
Roept een van de andere handlers aan op basis van het type activiteit dat is ontvangen.
Berichtactiviteit ontvangen
on_message_activity
Overschrijf dit om een message activiteit af te handelen.
Ontvangen activiteit voor gespreksupdate
on_conversation_update_activity
In een conversationUpdate activiteit roept u een handler aan als andere leden dan de bot deelnemen aan of het gesprek verlaten.
Niet-botleden zijn lid geworden van het gesprek
on_members_added_activity
Overschrijf dit om leden die deelnemen aan een gesprek af te handelen.
Niet-botleden hebben het gesprek verlaten
on_members_removed_activity
Overschrijf dit om leden af te handelen die een gesprek verlaten.
Gebeurtenisactiviteit ontvangen
on_event_activity
Bij een event activiteit roept u een handler aan die specifiek is voor het gebeurtenistype.
Activiteit van tokenresponsgebeurtenis ontvangen
on_token_response_event
Overschrijf dit om reactiegebeurtenissen van tokens af te handelen.
Gebeurtenisactiviteit voor niet-tokenantwoord ontvangen
on_event_activity
Overschrijf dit om andere typen gebeurtenissen te verwerken.
Berichtreactieactiviteit ontvangen
on_message_reaction_activity
Bij een messageReaction activiteit roept u een handler aan als een of meer reacties zijn toegevoegd aan of verwijderd uit een bericht.
Berichtreacties toegevoegd aan een bericht
on_reactions_added
Overschrijf dit om reacties af te handelen die zijn toegevoegd aan een bericht.
Berichtreacties verwijderd uit een bericht
on_reactions_removed
Overschrijf dit om reacties af te handelen die zijn verwijderd uit een bericht.
Ontvangen installatie-updateactiviteit
on_installation_update
Bij een installationUpdate activiteit roept u een handler aan op basis van of de bot is geïnstalleerd of verwijderd.
Bot geïnstalleerd
on_installation_update_add
Overschrijf dit om logica toe te voegen voor wanneer de bot in een organisatie-eenheid is geïnstalleerd.
Bot verwijderd
on_installation_update_remove
Overschrijf dit om logica toe te voegen voor wanneer de bot wordt verwijderd in een organisatie-eenheid.
Ander activiteitstype ontvangen
on_unrecognized_activity_type
Overschrijf dit om elk activiteitstype af te handelen, anders niet verwerkt.
Deze verschillende handlers bevatten informatie turn_context over de binnenkomende activiteit, die overeenkomt met de inkomende HTTP-aanvraag. Activiteiten kunnen van verschillende typen zijn, dus elke handler biedt een sterk getypte activiteit in de contextparameter van zijn beurt; in de meeste gevallen on_message_activity wordt altijd afgehandeld en is over het algemeen de meest voorkomende.
Net als in vorige 4.x-versies van dit framework, is er ook de optie om de openbare methode on_turnte implementeren. Momenteel verwerkt de basis-implementatie van deze methode foutcontrole en roept vervolgens elk van de specifieke handlers aan (zoals de twee die we in dit voorbeeld definiëren) afhankelijk van het type binnenkomende activiteit. In de meeste gevallen kunt u die methode alleen laten en de afzonderlijke handlers gebruiken, maar als voor uw situatie een aangepaste implementatie on_turnis vereist, is dit nog steeds een optie.
Belangrijk
Als u de on_turn methode overschrijft, moet u de basis-implementatie aanroepen super().on_turn om alle andere on_<activity> handlers aan te roepen of deze handlers zelf aan te roepen. Anders worden deze handlers niet aangeroepen en wordt die code niet uitgevoerd.
Voorbeeldactiviteitshandler
U kunt bijvoorbeeld afhandelen op leden die zijn toegevoegd om gebruikers te verwelkomen bij een gesprek en om berichten af te handelen om terug te sturen naar de 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();
});
}
}
Een activiteitshandler is een goede manier om een bot te ontwerpen die de gespreksstatus tussen bochten niet hoeft bij te houden. De dialoogvensterbibliotheek biedt manieren om een langlopend gesprek met de gebruiker te beheren.