Konverzace řízené událostmi pomocí obslužné rutiny aktivity

Článek
10/27/2023

PLATÍ PRO: SDK v4

Obslužná rutina aktivity je způsob uspořádání konverzační logiky robota řízený událostmi. Každý jiný typ nebo podtyp aktivity představuje jiný typ konverzační události. V rámci krytu obslužná rutina otáčení robota volá obslužnou rutinu jednotlivých aktivit pro jakýkoli typ aktivity, kterou přijal.

Pokud například robot obdrží aktivitu zprávy, obslužná rutina otáčení uvidí, že příchozí aktivita a odešle ji obslužné rutině aktivity zprávy. Při sestavování robota bude logika robota pro zpracování zpráv a odpovídání na zprávy v této obslužné rutině aktivity zprávy. Logika pro zpracování členů přidaných do konverzace bude ve vaší obslužné rutině přidané členy, která se volá při každém přidání člena do konverzace.

Další způsoby uspořádání logiky robota najdete v části logiky robota v tom, jak roboti fungují.

Poznámka:

Sady SDK služby Bot Framework JavaScript, C# a Python budou nadále podporovány, ale sada Java SDK se vyřazuje s konečnou dlouhodobou podporou končící v listopadu 2023.

Stávající roboti sestavení pomocí sady Java SDK budou i nadále fungovat.

Pro nové vytváření robotů zvažte použití Power Virtual Agents a přečtěte si o výběru správného řešení chatovacího robota.

Další informace najdete v tématu Budoucnost vytváření robotů.

Pokud chcete implementovat logiku pro tyto obslužné rutiny, přepíšete tyto metody v robotovi, například v části obslužné rutiny ukázkové aktivity níže. Pro každý z těchto obslužných rutin neexistuje žádná základní implementace, takže stačí do přepsání přidat logiku, kterou chcete použít.

Existují určité situace, kdy budete chtít přepsat obslužnou rutinu základního turnu, například uložit stav na konci turnu. Při tom nezapomeňte nejprve zavolat await base.OnTurnAsync(turnContext, cancellationToken); , aby se před dalším kódem spustila základní implementace OnTurnAsync . Tato základní implementace je mimo jiné zodpovědná za volání ostatních obslužných rutin aktivit, jako OnMessageActivityAsyncje .

JavaScript ActivityHandler používá model emiteru a naslouchacího procesu události. Můžete například použít metodu onMessage k registraci naslouchacího procesu událostí pro aktivity zpráv. Můžete zaregistrovat více než jeden naslouchací proces. Když robot obdrží aktivitu zpráv, obslužná rutina aktivity uvidí, že příchozí aktivita a odešle ji každému onMessage naslouchacímu procesu aktivity v pořadí, v jakém byly zaregistrovány.

Při sestavování robota se logika robota pro zpracování zpráv a odpovídání na zprávy přesune do naslouchacích onMessage procesů. Stejně tak logika pro zpracování členů přidaných do konverzace přejde do onMembersAdded vašich naslouchacích procesů, které se volají při každém přidání člena do konverzace. Pokud chcete přidat tyto naslouchací procesy, zaregistrujete je ve svém robotovi, jak je vidět v následující části logiky robota . Pro každý naslouchací proces zahrňte logiku robota a pak nezapomeňte volat next() na konci. Voláním next()zajistíte spuštění dalšího naslouchacího procesu.

Před koncem turnu nezapomeňte uložit stav . Můžete to provést přepsáním metody obslužné rutiny run aktivity a uložením stavu po dokončení nadřazené run metody.

Neexistují žádné běžné situace, kdy budete chtít přepsat základní obslužnou rutinu otáčení, proto buďte opatrní, pokud se to pokusíte provést. Existuje speciální obslužná rutina s názvem onDialog. Obslužná rutina onDialog se spustí na konci po spuštění zbývajících obslužných rutin a není svázaná s určitým typem aktivity. Stejně jako u všech výše uvedených obslužných rutin nezapomeňte volat next() , aby se zbytek procesu zabalil.

Pokud chcete implementovat logiku pro tyto obslužné rutiny, přepíšete tyto metody v robotovi, například v části obslužné rutiny ukázkové aktivity níže. Pro každý z těchto obslužných rutin neexistuje žádná základní implementace, proto do přepsání přidejte logiku, kterou chcete použít.

Existují určité situace, kdy budete chtít přepsat obslužnou rutinu základního turnu, například uložit stav na konci turnu. Při tom nezapomeňte nejprve zavolat super.onTurn(turnContext); , aby se před dalším kódem spustila základní implementace onTurn . Tato základní implementace je mimo jiné zodpovědná za volání ostatních obslužných rutin aktivit, jako onMessageActivityje .

Při sestavování robota bude logika robota pro zpracování zpráv a odpovídání na zprávy v této on_message_activity obslužné rutině. Stejně tak logika pro zpracování členů přidaných do konverzace přejde do obslužné on_members_added rutiny, která se volá při každém přidání člena do konverzace.

Pokud například robot obdrží aktivitu zprávy, obslužná rutina otáčení uvidí, že příchozí aktivita a odešle ji obslužné rutině on_message_activity aktivity.

Existují určité situace, kdy budete chtít přepsat obslužnou rutinu základního turnu, například uložit stav na konci turnu. Při tom nezapomeňte nejprve zavolat await super().on_turn(turnContext); , aby se před dalším kódem spustila základní implementace on_turn . Tato základní implementace je mimo jiné zodpovědná za volání ostatních obslužných rutin aktivit, jako on_message_activityje .

Zpracování aktivit

Logika robota zpracovává příchozí aktivity z jednoho nebo více kanálů a generuje odchozí aktivity v reakci.

Hlavní logika robota je definovaná v kódu robota. Chcete-li implementovat robota jako obslužnou rutinu aktivity, odvodit třídu robota z ActivityHandler, která implementuje IBot rozhraní. ActivityHandler definuje různé obslužné rutiny pro různé typy aktivit, například OnMessageActivityAsync, a OnMembersAddedAsync. Tyto metody jsou chráněné, ale lze je přepsat, protože pocházíme z ActivityHandler.

Obslužné rutiny definované v ActivityHandler :

Událost	Obslužná rutina	Popis
Všechny přijaté typy aktivit	`OnTurnAsync`	Zavolá jeden z dalších obslužných rutin na základě typu přijaté aktivity.
Přijatá aktivita zprávy	`OnMessageActivityAsync`	Tuto možnost přepište, aby se zpracovávala `message` aktivita.
Přijatá aktivita aktualizace konverzace	`OnConversationUpdateActivityAsync`	Při aktivitě `conversationUpdate` volá obslužnou rutinu, pokud se členové kromě robota připojili nebo opustili konverzaci.
Členové, kteří nejsou roboti, se připojili ke konverzaci	`OnMembersAddedAsync`	Přepište ho, aby se členové připojili ke konverzaci.
Členové, kteří nejsou roboti, opustili konverzaci.	`OnMembersRemovedAsync`	Přepište to tak, aby členové opustili konverzaci.
Přijatá aktivita události	`OnEventActivityAsync`	Při aktivitě `event` volá obslužnou rutinu specifickou pro typ události.
Přijatá aktivita události odpovědi tokenu	`OnTokenResponseEventAsync`	Přepište ho, aby se zpracovávaly události odezvy tokenu.
Přijatá aktivita události bez tokenu odpovědi	`OnEventAsync`	Přepište ho tak, aby zpracovával jiné typy událostí.
Přijatá aktivita reakce na zprávu	`OnMessageReactionActivityAsync`	Při aktivitě `messageReaction` volá obslužnou rutinu, pokud byla přidána nebo odebrána jedna nebo více reakcí ze zprávy.
Reakce na zprávu přidané do zprávy	`OnReactionsAddedAsync`	Přepište ho tak, aby zpracovával reakce přidané do zprávy.
Reakce na zprávy odebrané ze zprávy	`OnReactionsRemovedAsync`	Přepište ho tak, aby zpracovával reakce odebrané ze zprávy.
Přijatá aktivita aktualizace instalace	`OnInstallationUpdateActivityAsync`	Při aktivitě `installationUpdate` volá obslužnou rutinu na základě toho, jestli byl robot nainstalován nebo odinstalován.
Nainstalovaný robot	`OnInstallationUpdateAddAsync`	Tuto možnost přepište, pokud chcete přidat logiku, když je robot nainstalovaný v organizační jednotce.
Odinstalovaný robot	`OnInstallationUpdateRemoveAsync`	Tuto možnost přepište, pokud chcete přidat logiku, když je robot odinstalován v rámci organizační jednotky.
Byl přijat jiný typ aktivity.	`OnUnrecognizedActivityTypeAsync`	Přepište ho tak, aby zpracovával jakýkoli typ aktivity, jinak neošetřený.

Tyto různé obslužné rutiny mají turnContext informace o příchozí aktivitě, která odpovídá příchozímu požadavku HTTP. Aktivity mohou být různých typů, takže každá obslužná rutina poskytuje aktivitu silného typu v kontextu parametru. ve většině případů OnMessageActivityAsync se bude vždy zpracovávat a obvykle se jedná o nejběžnější.

Stejně jako v předchozích verzích 4.x této architektury existuje také možnost implementovat veřejnou metodu OnTurnAsync. Základní implementace této metody v současné době zpracovává kontrolu chyb a potom volá všechny konkrétní obslužné rutiny (podobně jako ty dva, které definujeme v této ukázce) v závislosti na typu příchozí aktivity. Ve většině případů můžete tuto metodu ponechat samostatně a používat jednotlivé obslužné rutiny, ale pokud vaše situace vyžaduje vlastní implementaci OnTurnAsync, je to stále možnost.

Důležité

Pokud přepíšete metodu OnTurnAsync , budete muset zavolat base.OnTurnAsync základní implementaci, aby volala všechny ostatní On<activity>Async obslužné rutiny nebo volala tyto obslužné rutiny sami. Jinak se tyto obslužné rutiny nevolají a tento kód se nespustí.

Hlavní logika robota je definovaná v kódu robota. Chcete-li implementovat robota jako obslužnou rutinu aktivity, rozšíření ActivityHandler. ActivityHandler definuje různé události pro různé typy aktivit a chování robota můžete upravit registrací naslouchacích procesů událostí, například s onMessage a onConversationUpdate.

Pomocí těchto metod zaregistrujte naslouchací procesy pro každý typ události:

Událost	Metoda registrace	Popis
Všechny přijaté typy aktivit	`onTurn`	Zaregistruje naslouchací proces pro přijetí jakékoli aktivity.
Přijatá aktivita zprávy	`onMessage`	Zaregistruje naslouchací proces pro přijetí `message` aktivity.
Přijatá aktivita aktualizace konverzace	`onConversationUpdate`	Zaregistruje naslouchací proces pro přijetí jakékoli `conversationUpdate` aktivity.
Členové se připojili ke konverzaci	`onMembersAdded`	Zaregistruje naslouchací proces, když se členové připojili ke konverzaci, včetně robota.
Členové opustili konverzaci.	`onMembersRemoved`	Zaregistruje naslouchací proces, kdy členové opustili konverzaci, včetně robota.
Přijatá aktivita reakce na zprávu	`onMessageReaction`	Zaregistruje naslouchací proces pro přijetí jakékoli `messageReaction` aktivity.
Reakce na zprávu přidané do zprávy	`onReactionsAdded`	Zaregistruje naslouchací proces při přidání reakcí do zprávy.
Reakce na zprávy odebrané ze zprávy	`onReactionsRemoved`	Zaregistruje naslouchací proces, pokud se reakce ze zprávy odeberou.
Přijatá aktivita události	`onEvent`	Zaregistruje naslouchací proces pro přijetí jakékoli `event` aktivity.
Přijatá aktivita události odpovědi tokenu	`onTokenResponseEvent`	Zaregistruje naslouchací proces pro přijetí `tokens/response` události.
Přijatá aktivita aktualizace instalace	`onInstallationUpdate`	Zaregistruje naslouchací proces pro přijetí jakékoli `installationUpdate` aktivity.
Nainstalovaný robot	`onInstallationUpdateAdd`	Zaregistruje naslouchací proces, když je robot nainstalovaný v organizační jednotce.
Odinstalovaný robot	`onInstallationUpdateRemove`	Zaregistruje naslouchací proces při odinstalaci robota v rámci organizační jednotky.
Byl přijat jiný typ aktivity.	`onUnrecognizedActivityType`	Zaregistruje naslouchací proces, pokud není definována obslužná rutina pro konkrétní typ aktivity.
Obslužné rutiny aktivit byly dokončeny.	`onDialog`	Volané po dokončení všech použitelných obslužných rutin.

next Voláním funkce pokračování z každé obslužné rutiny povolte zpracování pokračovat. Pokud next není volána, zpracování aktivity skončí.

Hlavní logika robota je definovaná v kódu robota. Chcete-li implementovat robota jako obslužnou rutinu aktivity, odvodit třídu robota z ActivityHandler, která implementuje Bot rozhraní. ActivityHandler definuje různé obslužné rutiny pro různé typy aktivit, například onMessageActivity, a onMembersAdded. Tyto metody jsou chráněné, ale lze je přepsat, protože pocházíme z ActivityHandler.

Obslužné rutiny definované v ActivityHandler :

Událost	Obslužná rutina	Popis
Všechny přijaté typy aktivit	`onTurn`	Zavolá jeden z dalších obslužných rutin na základě typu přijaté aktivity.
Přijatá aktivita zprávy	`onMessageActivity`	Tuto možnost přepište, aby se zpracovávala `message` aktivita.
Přijatá aktivita aktualizace konverzace	`onConversationUpdateActivity`	Při aktivitě `conversationUpdate` volá obslužnou rutinu, pokud se členové kromě robota připojili nebo opustili konverzaci.
Členové, kteří nejsou roboti, se připojili ke konverzaci	`onMembersAdded`	Přepište ho, aby se členové připojili ke konverzaci.
Členové, kteří nejsou roboti, opustili konverzaci.	`onMembersRemoved`	Přepište to tak, aby členové opustili konverzaci.
Přijatá aktivita události	`onEventActivity`	Při aktivitě `event` volá obslužnou rutinu specifickou pro typ události.
Přijatá aktivita události odpovědi tokenu	`onTokenResponseEvent`	Přepište ho, aby se zpracovávaly události odezvy tokenu.
Přijatá aktivita události bez tokenu odpovědi	`onEvent`	Přepište ho tak, aby zpracovával jiné typy událostí.
Přijatá aktivita reakce na zprávu	`onMessageReactionActivity`	Při aktivitě `messageReaction` volá obslužnou rutinu, pokud byla přidána nebo odebrána jedna nebo více reakcí ze zprávy.
Reakce na zprávu přidané do zprávy	`onReactionsAdded`	Přepište ho tak, aby zpracovával reakce přidané do zprávy.
Reakce na zprávy odebrané ze zprávy	`onReactionsRemoved`	Přepište ho tak, aby zpracovával reakce odebrané ze zprávy.
Přijatá aktivita aktualizace instalace	`onInstallationUpdate`	Při aktivitě `installationUpdate` volá obslužnou rutinu na základě toho, jestli byl robot nainstalován nebo odinstalován.
Nainstalovaný robot	`onInstallationUpdateAdd`	Tuto možnost přepište, pokud chcete přidat logiku, když je robot nainstalovaný v organizační jednotce.
Odinstalovaný robot	`onInstallationUpdateRemove`	Tuto možnost přepište, pokud chcete přidat logiku, když je robot odinstalován v rámci organizační jednotky.
Byl přijat jiný typ aktivity.	`onUnrecognizedActivityType`	Přepište ho tak, aby zpracovával jakýkoli typ aktivity, jinak neošetřený.

Tyto různé obslužné rutiny mají turnContext informace o příchozí aktivitě, která odpovídá příchozímu požadavku HTTP. Aktivity mohou být různých typů, takže každá obslužná rutina poskytuje aktivitu silného typu v kontextu parametru. ve většině případů onMessageActivity se bude vždy zpracovávat a obvykle se jedná o nejběžnější.

K dispozici je také možnost implementovat veřejnou metodu onTurn. Základní implementace této metody v současné době zpracovává kontrolu chyb a potom volá všechny konkrétní obslužné rutiny (podobně jako ty dva, které definujeme v této ukázce) v závislosti na typu příchozí aktivity. Ve většině případů můžete tuto metodu ponechat samostatně a používat jednotlivé obslužné rutiny, ale pokud vaše situace vyžaduje vlastní implementaci onTurn, je to stále možnost.

Důležité

Pokud přepíšete metodu onTurn , budete muset zavolat super.onTurn základní implementaci, aby volala všechny ostatní on<activity> obslužné rutiny nebo volala tyto obslužné rutiny sami. Jinak se tyto obslužné rutiny nevolají a tento kód se nespustí.

Hlavní logika robota je definovaná v kódu robota. Chcete-li implementovat robota jako obslužnou rutinu aktivity, odvozujte třídu robota z ActivityHandler, která se zase odvozuje z abstraktní Bot třídy. ActivityHandler definuje různé obslužné rutiny pro různé typy aktivit, například on_message_activity a on_members_added. Tyto metody jsou chráněné, ale lze je přepsat, protože pocházíme z ActivityHandler.

Obslužné rutiny definované v ActivityHandler :

Událost	Obslužná rutina	Popis
Všechny přijaté typy aktivit	`on_turn`	Zavolá jeden z dalších obslužných rutin na základě typu přijaté aktivity.
Přijatá aktivita zprávy	`on_message_activity`	Tuto možnost přepište, aby se zpracovávala `message` aktivita.
Přijatá aktivita aktualizace konverzace	`on_conversation_update_activity`	Při aktivitě `conversationUpdate` volá obslužnou rutinu, pokud se členové kromě robota připojili nebo opustili konverzaci.
Členové, kteří nejsou roboti, se připojili ke konverzaci	`on_members_added_activity`	Přepište ho, aby se členové připojili ke konverzaci.
Členové, kteří nejsou roboti, opustili konverzaci.	`on_members_removed_activity`	Přepište to tak, aby členové opustili konverzaci.
Přijatá aktivita události	`on_event_activity`	Při aktivitě `event` volá obslužnou rutinu specifickou pro typ události.
Přijatá aktivita události odpovědi tokenu	`on_token_response_event`	Přepište ho, aby se zpracovávaly události odezvy tokenu.
Přijatá aktivita události bez tokenu odpovědi	`on_event_activity`	Přepište ho tak, aby zpracovával jiné typy událostí.
Přijatá aktivita reakce na zprávu	`on_message_reaction_activity`	Při aktivitě `messageReaction` volá obslužnou rutinu, pokud byla přidána nebo odebrána jedna nebo více reakcí ze zprávy.
Reakce na zprávu přidané do zprávy	`on_reactions_added`	Přepište ho tak, aby zpracovával reakce přidané do zprávy.
Reakce na zprávy odebrané ze zprávy	`on_reactions_removed`	Přepište ho tak, aby zpracovával reakce odebrané ze zprávy.
Přijatá aktivita aktualizace instalace	`on_installation_update`	Při aktivitě `installationUpdate` volá obslužnou rutinu na základě toho, jestli byl robot nainstalován nebo odinstalován.
Nainstalovaný robot	`on_installation_update_add`	Tuto možnost přepište, pokud chcete přidat logiku, když je robot nainstalovaný v organizační jednotce.
Odinstalovaný robot	`on_installation_update_remove`	Tuto možnost přepište, pokud chcete přidat logiku, když je robot odinstalován v rámci organizační jednotky.
Byl přijat jiný typ aktivity.	`on_unrecognized_activity_type`	Přepište ho tak, aby zpracovával jakýkoli typ aktivity, jinak neošetřený.

Tyto různé obslužné rutiny mají turn_context informace o příchozí aktivitě, která odpovídá příchozímu požadavku HTTP. Aktivity mohou být různých typů, takže každá obslužná rutina poskytuje aktivitu silného typu v kontextu parametru. ve většině případů on_message_activity se bude vždy zpracovávat a obvykle se jedná o nejběžnější.

Stejně jako v předchozích verzích 4.x této architektury existuje také možnost implementovat veřejnou metodu on_turn. Základní implementace této metody v současné době zpracovává kontrolu chyb a potom volá všechny konkrétní obslužné rutiny (podobně jako ty dva, které definujeme v této ukázce) v závislosti na typu příchozí aktivity. Ve většině případů můžete tuto metodu ponechat samostatně a používat jednotlivé obslužné rutiny, ale pokud vaše situace vyžaduje vlastní implementaci on_turn, je to stále možnost.

Důležité

Pokud přepíšete metodu on_turn , budete muset zavolat super().on_turn základní implementaci, aby volala všechny ostatní on_<activity> obslužné rutiny nebo volala tyto obslužné rutiny sami. Jinak se tyto obslužné rutiny nevolají a tento kód se nespustí.

Obslužná rutina ukázkové aktivity

Můžete například zpracovat členy přidané pro vítání uživatelů v konverzaci a zpracovat zprávu , která vrací zprávy, které odesílají robotovi.

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();
        });
    }
}

public class EchoBot extends ActivityHandler {

    @Override
    protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
        return turnContext.sendActivity(
            MessageFactory.text("Echo: " + turnContext.getActivity().getText())
        ).thenApply(sendResult -> null);
    }

    @Override
    protected CompletableFuture<Void> onMembersAdded(
        List<ChannelAccount> membersAdded,
        TurnContext turnContext
    ) {
        String welcomeText = "Hello and welcome!";
        return membersAdded.stream()
            .filter(
                member -> !StringUtils
                    .equals(member.getId(), turnContext.getActivity().getRecipient().getId())
            ).map(channel -> turnContext.sendActivity(MessageFactory.text(welcomeText, welcomeText, null)))
            .collect(CompletableFutures.toFutureList()).thenApply(resourceResponses -> null);
    }
}

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}")
        )

Další kroky

Kanál Microsoft Teams představuje některé aktivity specifické pro Teams, které robot bude muset podporovat, aby správně fungoval s Teams. Vysvětlení klíčových konceptů vývoje robotů pro Microsoft Teams najdete v tématu Jak fungují roboti Microsoft Teams.
Obslužná rutina aktivity je dobrým způsobem, jak navrhnout robota, který nemusí sledovat konverzační stav mezi otočeními. Knihovna dialogových oken poskytuje způsoby správy dlouhotrvající konverzace s uživatelem.

Konverzace řízené událostmi pomocí obslužné rutiny aktivity

Zpracování aktivit

Obslužná rutina ukázkové aktivity

Další kroky

Další materiály