Debugowanie bota za pomocą oprogramowania pośredniczącego inspekcji

DOTYCZY: ZESTAW SDK w wersji 4

W tym artykule opisano sposób debugowania bota przy użyciu oprogramowania pośredniczącego inspekcji. Ta funkcja umożliwia emulatorowi platformy Bot Framework debugowanie ruchu do i z bota oraz wyświetlanie bieżącego stanu bota. Możesz użyć komunikatu śledzenia, aby wysłać dane do emulatora, a następnie sprawdzić stan bota w dowolnym momencie konwersacji.

Używamy narzędzia EchoBot utworzonego lokalnie przy użyciu platformy Bot Framework w wersji 4 w przewodniku Szybki start Tworzenie bota, aby pokazać, jak debugować i sprawdzać stan komunikatu bota. Możesz również debugować bota przy użyciu środowiska IDE lub debugowania za pomocą emulatora platformy Bot Framework, ale aby debugować stan, musisz dodać oprogramowanie pośredniczące inspekcji do bota. Przykłady botów inspekcji są dostępne dla języków C#, JavaScript, Java i Python.

Uwaga

Zestawy SDK języka JavaScript, C# i Python platformy Bot Framework będą nadal obsługiwane, jednak zestaw SDK języka Java jest wycofywany z ostatecznym długoterminowym wsparciem kończącym się w listopadzie 2023 r.

Istniejące boty utworzone za pomocą zestawu JAVA SDK będą nadal działać.

W przypadku tworzenia nowego bota rozważ użycie agentów usługi Power Virtual Agents i przeczytaj o wyborze odpowiedniego rozwiązania czatbota.

Aby uzyskać więcej informacji, zobacz Przyszłość tworzenia botów.

Wymagania wstępne

• Znajomość oprogramowania pośredniczącego bota i zarządzania stanem
• Znajomość debugowania bota opartego na zestawie SDK oraz testowania i debugowania za pomocą emulatora
• Instalacja emulatora platformy Bot Framework
• Instalacja narzędzia ngrok (jeśli chcesz debugować bota skonfigurowanego na platformie Azure do korzystania z innych kanałów)
• Kopia przykładowego bota inspekcji dla języka C#, JavaScript, Java lub Python

Aktualizowanie emulatora do najnowszej wersji

Przed użyciem oprogramowania pośredniczącego inspekcji bota w celu debugowania bota zaktualizuj emulator do wersji 4.5 lub nowszej. Sprawdź najnowszą wersję aktualizacji.

Aby sprawdzić wersję emulatora, wybierz pozycję Pomoc, a następnie pozycję Informacje w menu. Zobaczysz bieżącą wersję emulatora.

Aktualizowanie kodu bota

C#

Stan inspekcji i oprogramowanie pośredniczące inspekcji są konfigurowane w pliku Startup.cs , a następnie używane przez adapter.

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

Zaktualizuj klasę bota w pliku 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

Przed zaktualizowaniem kodu bota zaktualizuj jego pakiety do najnowszych wersji, wykonując następujące polecenie w terminalu:

npm install --save botbuilder@latest

Następnie należy zaktualizować kod bota JavaScript w następujący sposób. Więcej informacji można znaleźć tutaj: Zaktualizuj kod bota lub zapoznaj się z przykładem oprogramowania pośredniczącego Inspekcja w witrynie GitHub.

index.js

Skonfiguruj stan inspekcji i dodaj oprogramowanie pośredniczące inspekcji do karty w pliku index.js .

// 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

Zaktualizuj klasę bota w pliku 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

Skonfiguruj stan inspekcji i dodaj oprogramowanie pośredniczące inspekcji do adaptera w pliku Application.java . Stan inspekcji jest ustawiany przez udostępnienie nowej platformy Spring @Bean do dostarczenia elementu BotFrameworkHttpAdapter ustawionego na @Primary wartość , aby zastąpić domyślną klasę BotFrameworkHttpAdapter dostarczoną przez klasę bazową BotDependencyConfiguration. Zapoznaj się z poniższą aktualizacją kodu lub zapoznaj się z przykładem oprogramowania pośredniczącego Inspekcja w witrynie GitHub.

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 jest implementowany w ramach pakietu com.microsoft.bot.integration i można go przejrzeć za pomocą kodu źródłowego zestawu Java SDK.

Zaktualizuj klasę bota w pliku 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

Przed zaktualizowaniem kodu bota zainstaluj niezbędne pakiety PyPI, uruchamiając następujące polecenia w terminalu:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Skonfiguruj stan inspekcji w pliku app.py przez dodanie oprogramowania pośredniczącego do karty.

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)

Zaktualizuj klasę bota w pliku echo_bot.py .

boty/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

Lokalne testowanie bota

Po zaktualizowaniu kodu możesz uruchomić bota lokalnie i przetestować funkcję debugowania przy użyciu dwóch emulatorów: jeden do wysyłania i odbierania komunikatów, a drugi do sprawdzania stanu komunikatów w trybie debugowania. Aby przetestować bota lokalnie:

1. Przejdź do katalogu bota w terminalu i wykonaj następujące polecenie, aby uruchomić bota lokalnie:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

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

   Python

   python app.py
   

2. Otwórz emulator. Wybierz pozycję Otwórz bota. Wypełnij pola Adres URL bota wartościami http://localhost:3978/api/messages MicrosoftAppId i MicrosoftAppPassword. Jeśli masz bota JavaScript, możesz znaleźć te wartości w pliku env bota. Jeśli masz bota języka C#, te wartości można znaleźć w pliku appsettings.json . W przypadku bota Java można znaleźć te wartości w pliku application.properties . Wybierz pozycję Połącz.

3. Teraz otwórz kolejne okno emulatora. To drugie okno emulatora będzie działać jako debuger. Postępuj zgodnie z instrukcjami opisanymi w poprzednim kroku. Zaznacz pozycję Otwórz w trybie debugowania, a następnie wybierz pozycję Połączenie.

4. W tym momencie zobaczysz polecenie z unikatowym identyfikatorem (/INSPECT attach <identifier>) w emulatorze debugowania. Skopiuj całe polecenie z identyfikatorem z emulatora debugowania i wklej je w polu czatu pierwszego emulatora.

   Uwaga

   Unikatowy identyfikator jest generowany za każdym razem, gdy emulator jest uruchamiany w trybie debugowania po dodaniu oprogramowania pośredniczącego inspekcji w kodzie bota.

5. Teraz możesz wysyłać wiadomości w polu czatu pierwszego emulatora i sprawdzać komunikaty w emulatorze debugowania. Aby sprawdzić stan komunikatów, wybierz pozycję Stan bota w emulatorze debugowania i rozwiń wartości w prawym oknie JSON. Stan bota zostanie wyświetlony w emulatorze debugowania:

   

Sprawdzanie stanu bota skonfigurowanego na platformie Azure

Jeśli chcesz sprawdzić stan bota skonfigurowanego na platformie Azure i połączyć się z kanałami (takimi jak Teams), musisz zainstalować i uruchomić narzędzie ngrok.

Uruchamianie narzędzia ngrok

Na tym etapie zaktualizowano emulator do najnowszej wersji i dodano oprogramowanie pośredniczące inspekcji w kodzie bota. Następnym krokiem jest uruchomienie narzędzia ngrok i skonfigurowanie lokalnego bota. Przed uruchomieniem narzędzia ngrok należy uruchomić bota lokalnie.

Aby uruchomić bota lokalnie:

1. Przejdź do folderu bota w terminalu i ustaw rejestrację npm, aby używać najnowszych kompilacji

2. Uruchom bota lokalnie. Zobaczysz, że bot uwidacznia numer portu, taki jak 3978.

3. Otwórz kolejny wiersz polecenia i przejdź do folderu projektu bota. Uruchom następujące polecenie:

   ngrok http 3978
   

4. Aplikacja ngrok jest teraz połączona z lokalnym uruchomionym botem. Skopiuj bezpieczny publiczny adres IP (HTTPS).

   

Aktualizowanie zasobu bota

Teraz, gdy lokalny bot jest połączony z serwerem ngrok, możesz skonfigurować zasób bota na platformie Azure tak, aby używał adresu URL narzędzia ngrok.

1. Przejdź do zasobu bota na platformie Azure. W menu po lewej stronie w obszarze Ustawienia wybierz pozycję Konfiguracja.

   1. Ustaw punkt końcowy obsługi komunikatów na skopiowany adres IP ngrok. W razie potrzeby dodaj /api/messages po adresie IP. Na przykład https://e58549b6.ngrok.io/api/messages.

   2. Wybierz pozycję Włącz punkt końcowy przesyłania strumieniowego.

      

   3. Wybierz pozycję Zastosuj, aby zapisać zmiany.

      Napiwek

      Jeśli opcja Zastosuj nie jest włączona, możesz usunąć zaznaczenie pola wyboru Włącz punkt końcowy przesyłania strumieniowego i wybrać pozycję Zastosuj, a następnie zaznaczyć pozycję Włącz punkt końcowy przesyłania strumieniowego i ponownie wybrać pozycję Zastosuj . Upewnij się, że opcja Włącz punkt końcowy przesyłania strumieniowego jest zaznaczona, a konfiguracja punktu końcowego jest zapisywana.

2. Przejdź do grupy zasobów bota.

   1. Wybierz pozycję Wdrożenie, a następnie wybierz zasób bota, który został wcześniej wdrożony pomyślnie. Wybierz pozycję Szablon z menu po lewej stronie, aby pobrać identyfikatory MicrosoftAppId i MicrosoftAppPassword dla aplikacji internetowej skojarzonej z botem.

      

   2. Zaktualizuj plik konfiguracji bota (appsettings.json dla języka C# lub env for JavaScript) przy użyciu wartości MicrosoftAppId i MicrosoftAppPassword.

3. Uruchom emulator, wybierz pozycję Otwórz bota i wprowadź http://localhost:3978/api/messages adres URL bota. Wypełnij pola Identyfikator aplikacji firmy Microsoft i hasło aplikacji firmy Microsoft przy użyciu tych samych identyfikatorów MicrosoftAppId i MicrosoftAppPassword dodanych do pliku konfiguracji bota. Następnie wybierz pozycję Połączenie.

4. Uruchomiony bot jest teraz połączony z zasobem bota na platformie Azure. Aby przetestować bota na platformie Azure w usłudze czat internetowy, przejdź do zasobów bota, wybierz pozycję Testuj w czat internetowy i wyślij komunikaty do bota.

Włączanie trybu debugowania

1. W emulatorze wybierz pozycję Debuguj, a następnie rozpocznij debugowanie.

2. Wprowadź adres IP narzędzia ngrok (nie zapomnij dodać /api/messages) dla adresu URL bota (na przykład https://e58549b6.ngrok.io/api/messages).

   1. W polu Identyfikator aplikacji firmy Microsoft wprowadź identyfikator aplikacji bota.
   2. W polu Hasło aplikacji firmy Microsoft wprowadź wpis tajny aplikacji bota.
   3. Upewnij się, że opcja Otwórz w trybie debugowania jest również zaznaczona.
   4. Wybierz pozycję Połącz.

3. Po włączeniu trybu debugowania emulator generuje identyfikator UUID. Identyfikator UUID jest unikatowym identyfikatorem generowanym za każdym razem, gdy uruchamiasz tryb debugowania w emulatorze.

4. Skopiuj i wklej identyfikator UUID do pola Testuj w czat internetowy czatu w polu czatu kanału. W polu czatu zostanie wyświetlony komunikat "Dołączony do sesji, cały ruch jest replikowany do inspekcji".

Możesz rozpocząć debugowanie bota, wysyłając wiadomości w polu czatu skonfigurowanego kanału. Lokalny emulator automatycznie zaktualizuje komunikaty ze wszystkimi szczegółami dotyczącymi debugowania. Aby sprawdzić stan komunikatów bota, wybierz pozycję Stan bota i rozwiń wartości w odpowiednim oknie JSON.

Następne kroki

• Dowiedz się, jak debugować bota przy użyciu plików transkrypcji.
• Dowiedz się, jak debugować umiejętności lub umiejętności konsumenta.