Ladění robota pomocí middlewaru kontroly

PLATÍ PRO: SDK v4

Tento článek popisuje, jak ladit robota pomocí kontrolního middlewaru. Tato funkce umožňuje bot Framework Emulatoru ladit provoz do robota a z robota a zobrazit aktuální stav robota. Pomocí zprávy trasování můžete odeslat data do emulátoru a pak zkontrolovat stav robota v libovolném časovém rámci konverzace.

Používáme místně sestavený EchoBot pomocí bot Frameworku v4 v rychlém startu Vytvořit robota, abychom ukázali, jak ladit a kontrolovat stav zpráv robota. Robota můžete také ladit pomocí integrovaného vývojového prostředí nebo ladění pomocí bot Framework Emulatoru, ale pokud chcete ladit stav, musíte do robota přidat kontrolní middleware. Ukázky kontrolních robotů jsou k dispozici pro C#, JavaScript, Javu a Python.

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.

Při vytváření nových robotů zvažte použití aplikace Microsoft Copilot Studio a přečtěte si o výběru správného řešení copilotu.

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

Požadavky

• Znalost middlewaru robota a správy stavu
• Znalost ladění robota první sady SDK a testování a ladění pomocí emulátoru
• Instalace bot Framework Emulatoru
• Instalace Dev Tunnelu (pokud chcete ladit robota nakonfigurovaného v Azure tak, aby používal jiné kanály)
• Kopie ukázky kontrolního robota pro C#, JavaScript, Javu nebo Python

Aktualizace emulátoru na nejnovější verzi

Před použitím middlewaru kontroly robota k ladění robota aktualizujte emulátor na verzi 4.15 nebo novější. Zkontrolujte nejnovější verzi aktualizací.

Pokud chcete zkontrolovat verzi emulátoru, vyberte Nápověda a potom v nabídce o aplikaci. Zobrazí se aktuální verze emulátoru.

Aktualizace kódu robota

C#

Kontrolní stav a middleware kontroly se konfigurují v Startup.cs souboru a pak ho adaptér používá.

Startup.cs

});

services.AddSingleton<ConversationState>();

// Create the Bot Framework Authentication to be used with the Bot Adapter.

AdapterWithInspection.cs

{
    public class AdapterWithInspection : CloudAdapter
    {
        public AdapterWithInspection(BotFrameworkAuthentication auth, IConfiguration configuration, InspectionState inspectionState, UserState userState, ConversationState conversationState, ILogger<IBotFrameworkHttpAdapter> logger)
            : base(auth, logger)
        {
            // Inspection needs credentials because it will be sending the Activities and User and Conversation State to the emulator
            var credentials = new MicrosoftAppCredentials(configuration["MicrosoftAppId"], configuration["MicrosoftAppPassword"]);

            Use(new InspectionMiddleware(inspectionState, userState, conversationState, credentials));

            OnTurnError = async (turnContext, exception) =>
            {
                // Log any leaked exception from the application.
                logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

                // Send a message to the user
                await turnContext.SendActivityAsync("The bot encountered an error or bug.");
                await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

                // Send a trace activity, which will be displayed in the Bot Framework Emulator
                await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
            };
        }

Aktualizujte třídu robota v souboru EchoBot.cs .

EchoBot.cs

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var conversationStateProp = _conversationState.CreateProperty<CustomState>("customState");
    var convProp = await conversationStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    var userStateProp = _userState.CreateProperty<CustomState>("customState");
    var userProp = await userStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text} conversation state: {convProp.Value} user state: {userProp.Value}"), cancellationToken);

    convProp.Value++;
    userProp.Value++;
}

JavaScript

Před aktualizací kódu robota aktualizujte jeho balíčky na nejnovější verze spuštěním následujícího příkazu v terminálu:

npm install --save botbuilder@latest

Pak musíte následujícím způsobem aktualizovat kód vašeho javascriptového robota. Další informace najdete tady: Aktualizujte kód robota nebo si projděte ukázku middlewaru Kontroly na GitHubu.

index.js

Nastavte stav kontroly a přidejte do adaptéru v index.js souboru middleware kontroly.

// Import required bot services.
// See https://aka.ms/bot-services to learn more about the different parts of a bot.
const {
    CloudAdapter,
    ConversationState,
    InspectionMiddleware,
    InspectionState,
    MemoryStorage,
    UserState,
    ConfigurationBotFrameworkAuthentication
} = require('botbuilder');

const { MicrosoftAppCredentials } = require('botframework-connector');

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);

// Create adapter.
// See https://aka.ms/about-bot-adapter to learn more about how bots work.
const adapter = new CloudAdapter(botFrameworkAuthentication);

// Create the Storage provider and the various types of BotState.
const memoryStorage = new MemoryStorage();
const inspectionState = new InspectionState(memoryStorage);
const userState = new UserState(memoryStorage);
const conversationState = new ConversationState(memoryStorage);

// Create and add the InspectionMiddleware to the adapter.
adapter.use(new InspectionMiddleware(inspectionState, userState, conversationState, new MicrosoftAppCredentials(process.env.MicrosoftAppId, process.env.MicrosoftAppPassword)));

// Catch-all for errors.
adapter.onTurnError = async (context, error) => {
    // This check writes out errors to console log .vs. app insights.
    // NOTE: In production environment, you should consider logging this to Azure
    //       application insights. See https://aka.ms/bottelemetry for telemetry
    //       configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

bot.js

Aktualizujte třídu robota v souboru bot.js .

this.onMessage(async (context, next) => {
    // get the state objects
    const testConversationState = await this.conversationStateAccessor.get(context, { count: 0 });
    const testUserState = await this.userStateAccessor.get(context, { count: 0 });

    // print the current state to the reply to show we are incrementing it
    await context.sendActivity(`You said '${ context.activity.text }' conversation-state: ${ testConversationState.count } user-state: ${ testUserState.count }`);

    // do the actual increment
    testConversationState.count++;
    testUserState.count++;

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Java

Nastavte stav kontroly a přidejte do adaptéru v Application.java souboru middleware kontroly. Stav kontroly je nastaven tak, že poskytuje novou Spring @Bean pro zadání botFrameworkHttpAdapter, který je nastaven tak @Primary , aby přepsal výchozí BotFrameworkHttpAdapter poskytovaný základní třídou BotDependencyConfiguration. Podívejte se na následující aktualizaci kódu nebo se podívejte na ukázku middlewaru Kontroly na GitHubu.

Application.java

/**
 * Create an adapter with InspectionMiddleware.
 *
 * <p>
 * NOTE: This is marked as @Primary to override the default Bean.
 * </p>
 *
 * @param configuration     The configuration.
 *                          {@link BotDependencyConfiguration#getConfiguration()}
 * @param inspectionState   The InspectionState.
 *                          {@link BotDependencyConfiguration#getInspectionState(Storage)}
 * @param userState         The UserState.
 *                          {@link BotDependencyConfiguration#getUserState(Storage)}
 * @param conversationState The ConversationState.
 *                          {@link BotDependencyConfiguration#getConversationState(Storage)}
 * @return An AdapterWithInspection object.
 */
@Bean
@Primary
public BotFrameworkHttpAdapter getInspectionBotFrameworkHttpAdapter(
    Configuration configuration,
    InspectionState inspectionState,
    UserState userState,
    ConversationState conversationState
) {
    return new AdapterWithInspection(
        configuration,
        inspectionState,
        userState,
        conversationState
    );
}

AdapterWithInspection se implementuje jako součást balíčku com.microsoft.bot.integration a je možné ho zkontrolovat ze zdrojového kódu sady Java SDK.

Aktualizujte třídu robota v souboru EchoBot.java .

EchoBot.java

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    // Get state data from ConversationState.
    StatePropertyAccessor<CustomState> dataAccessor =
        conversationState.createProperty("customState");
    CompletableFuture<CustomState> convStateFuture =
        dataAccessor.get(turnContext, CustomState::new);

    // Get profile from UserState.
    StatePropertyAccessor<CustomState> profileAccessor =
        userState.createProperty("customState");
    CompletableFuture<CustomState> userStateFuture =
        profileAccessor.get(turnContext, CustomState::new);

    return convStateFuture.thenCombine(userStateFuture, (convProp, userProp) -> {
        convProp.setValue(convProp.getValue() + 1);
        userProp.setValue(userProp.getValue() + 1);

        return turnContext.sendActivity(
            MessageFactory.text(
                String.format(
                    "Echo: %s conversation state %d user state %d",
                    turnContext.getActivity().getText(), convProp.getValue(),
                    userProp.getValue()
                )
            )
        );
    }).thenApply(resourceResponse -> null);
}

Python

Před aktualizací kódu robota nainstalujte potřebné balíčky PyPI spuštěním následujících příkazů v terminálu:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Nastavte stav kontroly v souboru app.py přidáním middlewaru do adaptéru.

app.py

from botbuilder.core import (
    ConversationState,
    MemoryStorage,
    TurnContext,
    UserState,
)
from botbuilder.core.inspection import InspectionMiddleware, InspectionState
from botbuilder.core.integration import aiohttp_error_middleware
from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication
from botbuilder.schema import Activity, ActivityTypes
from botframework.connector.auth import MicrosoftAppCredentials

# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
ADAPTER = CloudAdapter(ConfigurationBotFrameworkAuthentication(CONFIG))

# Catch-all for errors.
USER_STATE = UserState(MEMORY)
CONVERSATION_STATE = ConversationState(MEMORY)

# Create InspectionMiddleware
INSPECTION_MIDDLEWARE = InspectionMiddleware(
    inspection_state=InspectionState(MEMORY),
    user_state=USER_STATE,
    conversation_state=CONVERSATION_STATE,
    credentials=MicrosoftAppCredentials(
        app_id=CONFIG.APP_ID, password=CONFIG.APP_PASSWORD
    ),
)
ADAPTER.use(INSPECTION_MIDDLEWARE)

# Create Bot
BOT = EchoBot(CONVERSATION_STATE, USER_STATE)

Aktualizujte třídu robota v souboru echo_bot.py .

roboti/echo_bot.py

async def on_message_activity(self, turn_context: TurnContext):
    # Get the state properties from the turn context.
    user_data = await self.user_state_accessor.get(turn_context, CustomState)
    conversation_data = await self.conversation_state_accessor.get(
        turn_context, CustomState
    )

    await turn_context.send_activity(
        MessageFactory.text(
            f"Echo: {turn_context.activity.text}, "
            f"conversation state: {conversation_data.value}, "
            f"user state: {user_data.value}"
        )
    )

    user_data.value = user_data.value + 1
    conversation_data.value = conversation_data.value + 1

Místní testování robota

Po aktualizaci kódu můžete spustit robota místně a otestovat funkci ladění pomocí dvou emulátorů: jedné pro odesílání a příjem zpráv a druhý pro kontrolu stavu zpráv v režimu ladění. Místní testování robota:

1. Přejděte do adresáře robota v terminálu a spuštěním následujícího příkazu spusťte robota místně:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

   mvn package
   java -jar .\target\bot-inspection-sample.jar 
   

   Python

   python app.py
   

2. Otevřete emulátor. Vyberte Otevřít robota. Do adresy URL robota zadejte http://localhost:3978/api/messages hodnoty MicrosoftAppId a MicrosoftAppPassword. Pokud máte javascriptového robota, můžete tyto hodnoty najít v souboru .env vašeho robota. Pokud máte robota v jazyce C#, můžete tyto hodnoty najít v souboru appsettings.json . V případě robota v Javě najdete tyto hodnoty v souboru application.properties . Vyberte Připojit.

3. Teď otevřete další okno emulátoru. Toto druhé okno emulátoru bude fungovat jako ladicí program. Postupujte podle pokynů popsaných v předchozím kroku. Zaškrtněte políčko Otevřít v režimu ladění a pak vyberte Připojit.

4. V tomto okamžiku uvidíte příkaz s jedinečným identifikátorem (/INSPECT attach <identifier>) v emulátoru ladění. Zkopírujte celý příkaz s identifikátorem z emulátoru ladění a vložte ho do chatovacího pole prvního emulátoru.

   Poznámka:

   Jedinečný identifikátor se vygeneruje při každém spuštění emulátoru v režimu ladění po přidání kontrolního middlewaru do kódu robota.

5. Teď můžete posílat zprávy v chatovacím poli svého prvního emulátoru a kontrolovat zprávy v emulátoru ladění. Pokud chcete zkontrolovat stav zpráv, vyberte stav robota v emulátoru ladění a rozbalte hodnoty v pravém okně JSON . Stav robota uvidíte v emulátoru ladění:

   

Kontrola stavu robota nakonfigurovaného v Azure

Pokud chcete zkontrolovat stav robota nakonfigurovaného v Azure a připojit se k kanálům (jako je Teams), budete muset nainstalovat a spustit Dev Tunnels.

Spuštění devtunnelu

V tuto chvíli jste aktualizovali emulátor na nejnovější verzi a přidali do kódu robota kontrolní middleware. Dalším krokem je spuštění devtunnelu a konfigurace místního robota. Před spuštěním devtunnelu musíte spustit robota místně.

Místní spuštění robota:

1. Přejděte do složky robota v terminálu a nastavte registraci npm tak, aby používala nejnovější buildy.

2. Spusťte robota místně. Uvidíte, že robot zveřejní číslo portu, jako je 3978.

3. Otevřete další příkazový řádek a přejděte do složky projektu robota. Spusťte následující příkaz:

   devtunnel host -a -p 3978
   

4. Devtunnel je teď připojený k místně běžícímu robotovi. Zkopírujte veřejnou adresu URL zabezpečeného protokolu (HTTPS).

   

Aktualizace prostředku robota

Teď, když je místní robot připojený k devtunnelu, můžete prostředek robota v Azure nakonfigurovat tak, aby používal adresu URL devtunnelu.

1. Přejděte k prostředku robota v Azure. V nabídce vlevo v části Nastavení vyberte Konfigurace.

   1. Nastavte koncový bod zasílání zpráv na adresu URL devtunnelu, kterou jste zkopírovali. V případě potřeby za IP adresu přidejte /api/messages . Například https://0qg12llz-3978.usw2.devtunnels.ms/api/messages.

   2. Vyberte Povolit koncový bod streamování.

      

   3. Výběrem možnosti Použít změny uložte.

      Tip

      Pokud možnost Použít není povolená, můžete zrušit zaškrtnutí políčka Povolit koncový bod streamování a vybrat Použít, pak zaškrtněte políčko Povolit koncový bod streamování a znovu vyberte Použít. Musíte se ujistit, že je zaškrtnuté políčko Povolit koncový bod streamování a že se uloží konfigurace koncového bodu.

2. Přejděte do skupiny prostředků vašeho robota.

   1. Vyberte Nasazení a pak vyberte prostředek robota, který se dříve úspěšně nasadil. V nabídce vlevo vyberte šablonu a získejte MicrosoftAppId a MicrosoftAppPassword pro webovou aplikaci přidruženou k robotovi.

      

   2. Aktualizujte konfigurační soubor robota (appsettings.json pro C# nebo .env pro JavaScript) pomocí MicrosoftAppId a MicrosoftAppPassword.

3. Spusťte emulátor, vyberte Otevřít robota a zadejte http://localhost:3978/api/messages adresu URL robota. Vyplňte ID aplikace Microsoft a heslo aplikace Microsoftu stejným kódem MicrosoftAppId a MicrosoftAppPassword , které jste přidali do konfiguračního souboru našeho robota. Pak vyberte Připojit.

4. Spuštěný robot je teď připojený k vašemu prostředku robota v Azure. Pokud chcete robota otestovat v Azure v Webový chat, přejděte k prostředkům robota, vyberte test v Webový chat a odešlete do robota zprávy.

Povolení režimu ladění

1. V emulátoru vyberte Ladit a spusťte ladění.

2. Zadejte adresu URL devtunnelu (nezapomeňte přidat /api/messages) pro adresu URL robota (napříkladhttps://4jj51x75-51865.usw2.devtunnels.ms/api/messages).

   1. Jako ID aplikace Microsoftu zadejte ID aplikace vašeho robota.
   2. Jako heslo aplikace Microsoftu zadejte tajný kód aplikace vašeho robota.
   3. Zkontrolujte také, že je zaškrtnuté políčko Otevřít v režimu ladění.
   4. Vyberte Připojit.

3. Když je režim ladění povolený, emulátor vygeneruje UUID. UUID je jedinečné ID vygenerované při každém spuštění režimu ladění v emulátoru.

4. Zkopírujte a vložte UUID do pole Test v Webový chat chatu pro chatovací pole kanálu. V chatovacím poli se zobrazí zpráva "Připojeno k relaci, veškerý provoz se replikuje pro kontrolu".

Ladění robota můžete zahájit odesláním zpráv v chatovacím poli nakonfigurovaného kanálu. Místní emulátor automaticky aktualizuje zprávy o všech podrobnostech pro ladění. Pokud chcete zkontrolovat stav zpráv robota, vyberte Stav robota a rozbalte hodnoty v pravém okně JSON.

Další kroky

• Naučte se ladit robota pomocí souborů přepisu.
• Naučte se ladit dovednost nebo příjemce dovedností.