Dodawanie działań śledzenia do bota

DOTYCZY: ZESTAW SDK w wersji 4

Działanie śledzenia to działanie , które bot może wysłać do emulatora bota. Możesz używać działań śledzenia do interaktywnego debugowania bota, ponieważ umożliwiają wyświetlanie informacji o botze podczas jego uruchamiania lokalnie.

Działania śledzenia są wysyłane tylko do emulatora, a nie do żadnego innego klienta lub kanału. Emulator wyświetla je w dzienniku, ale nie w głównym panelu czatu.

• Działania śledzenia wysyłane za pośrednictwem kontekstu kolei są wysyłane za pośrednictwem programów obsługi działań wysyłania zarejestrowanych w kontekście włączania.
• Działania śledzenia wysyłane za pośrednictwem kontekstu kolei są skojarzone z działaniem przychodzącym, stosując odwołanie do konwersacji, jeśli istnieje. W przypadku proaktywnej wiadomości odpowiedź na identyfikator będzie nowym identyfikatorem GUID.
• Niezależnie od sposobu wysyłania działania śledzenia nigdy nie ustawia flagi odpowiedzi .

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.

Aby użyć działania śledzenia

Aby zobaczyć działanie śledzenia w emulatorze, potrzebny jest scenariusz, w którym bot wyśle działanie śledzenia, takie jak zgłoszenie wyjątku i wysłanie działania śledzenia z programu obsługi błędów włączania karty.

Aby wysłać działanie śledzenia z bota:

1. Utwórz nowe działanie.
   • Ustaw wymaganą właściwość typu na "trace".
   • Opcjonalnie ustaw jego nazwę, etykietę, wartość i właściwości typu wartości odpowiednio dla śledzenia.
2. Użyj metody działania wysyłania obiektu kontekstu turn, aby wysłać działanie śledzenia.
   • Ta metoda dodaje wartości dla pozostałych wymaganych właściwości działania na podstawie działania przychodzącego. Te właściwości obejmują identyfikator kanału, adres URL usługi, właściwości z i adresata.

Aby wyświetlić działanie śledzenia w emulatorze:

1. Uruchom bota lokalnie na maszynie.
2. Przetestuj go przy użyciu emulatora.
   • Wchodzenie w interakcję z botem i używanie kroków w scenariuszu w celu wygenerowania działania śledzenia.
   • Gdy bot emituje działanie śledzenia, działanie śledzenia jest wyświetlane w dzienniku emulatora.

Oto działanie śledzenia, które można zobaczyć, jeśli uruchomiono bota Core bez uprzedniego skonfigurowania baza wiedzy QnAMaker, na którym opiera się bot.

Dodawanie działania śledzenia do programu obsługi błędów karty

Program obsługi błędów włączania karty przechwytuje wszelkie nieuchwycone wyjątki zgłaszane przez bota podczas obrotu. Procedura obsługi błędów jest dobrym miejscem dla działania śledzenia, ponieważ można wysłać użytkownikowi przyjazny dla użytkownika komunikat i wysłać informacje debugowania dotyczące wyjątku do emulatora.

Ten przykładowy kod pochodzi z przykładu Core Bot . Zobacz kompletny przykład w języku C#, JavaScript, Python lub Java.

C#

Procedura obsługi OnTurnError adaptera tworzy działanie śledzenia w celu uwzględnienia informacji o wyjątku i wysyła je do emulatora.

AdapterWithErrorHandler.cs

    {
        // Log any leaked exception from the application.
        // NOTE: In production environment, you should consider logging this to
        // Azure Application Insights. Visit https://aka.ms/bottelemetry to see how
        // to add telemetry capture to your bot.
        logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

        // Send a message to the user
        var errorMessageText = "The bot encountered an error or bug.";
        var errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.IgnoringInput);
        await turnContext.SendActivityAsync(errorMessage);

        errorMessageText = "To continue to run this bot, please fix the bot source code.";
        errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.ExpectingInput);
        await turnContext.SendActivityAsync(errorMessage);

        if (conversationState != null)
        {
            try
            {
                // Delete the conversationState for the current conversation to prevent the
                // bot from getting stuck in a error-loop caused by being in a bad state.
                // ConversationState should be thought of as similar to "cookie-state" in a Web pages.
                await conversationState.DeleteAsync(turnContext);
            }
            catch (Exception e)
            {
                logger.LogError(e, $"Exception caught on attempting to Delete ConversationState : {e.Message}");
            }
        }

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

JavaScript

Procedura obsługi onTurnError karty tworzy działanie śledzenia w celu uwzględnienia informacji o wyjątku i wysyła je do emulatora.

index.js

    // Send a trace activity, which will be displayed in Bot Framework Emulator
    await context.sendTraceActivity(
        'OnTurnError Trace',
        `${ error }`,
        'https://www.botframework.com/schemas/error',
        'TurnError'
    );

    // Send a message to the user
    let onTurnErrorMessage = 'The bot encountered an error or bug.';
    await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);
    onTurnErrorMessage = 'To continue to run this bot, please fix the bot source code.';
    await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);
    // Clear out state
    await conversationState.delete(context);
};

// Set the onTurnError for the singleton CloudAdapter.
adapter.onTurnError = onTurnErrorHandler;

// Define a state store for your bot. See https://aka.ms/about-bot-state to learn more about using MemoryStorage.
// A bot requires a state store to persist the dialog and user state between messages.

// For local development, in-memory storage is used.

Java

W zestawie SDK AdapterWithErrorHandler języka Java klasa jest dołączana jako część zestawu SDK w pakiecie com.microsoft.bot.integration . Procedura obsługi onTurnError karty tworzy działanie śledzenia w celu uwzględnienia informacji o wyjątku i wysyła je do emulatora. Poniżej przedstawiono kod źródłowy karty domyślnej.

AdapterWithErrorHandler.java

setOnTurnError((turnContext, exception) -> {
    LoggerFactory.getLogger(AdapterWithErrorHandler.class).error("onTurnError", exception);


    return turnContext.sendActivities(
        MessageFactory.text(ERROR_MSG_ONE), MessageFactory.text(ERROR_MSG_TWO)
    ).thenCompose(resourceResponse -> sendTraceActivity(turnContext, exception))
        .thenCompose(stageResult -> {
            if (withConversationState != null) {
                // Delete the conversationState for the current conversation to prevent the
                // bot from getting stuck in a error-loop caused by being in a bad state.
                // ConversationState should be thought of as similar to "cookie-state" in a
                // Web pages.
                return withConversationState.delete(turnContext)
                    .exceptionally(deleteException -> {
                        LoggerFactory.getLogger(AdapterWithErrorHandler.class)
                            .error("ConversationState.delete", deleteException);
                        return null;
                    });
            }
            return CompletableFuture.completedFuture(null);
        });
});

Python

Program obsługi on_error adaptera tworzy działanie śledzenia w celu uwzględnienia informacji o wyjątku i wysyła je do emulatora.

adapter_with_error_handler.py

# This check writes out errors to console log
# NOTE: In production environment, you should consider logging this to Azure
#       application insights.
print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
traceback.print_exc()

# Send a message to the user
await context.send_activity("The bot encountered an error or bug.")
await context.send_activity(
    "To continue to run this bot, please fix the bot source code."
)
# Send a trace activity if we're talking to the Bot Framework Emulator
if context.activity.channel_id == "emulator":
    # Create a trace activity that contains the error object
    trace_activity = Activity(
        label="TurnError",
        name="on_turn_error Trace",
        timestamp=datetime.utcnow(),
        type=ActivityTypes.trace,
        value=f"{error}",
        value_type="https://www.botframework.com/schemas/error",
    )
    # Send a trace activity, which will be displayed in Bot Framework Emulator
    await context.send_activity(trace_activity)

Następne kroki

• Jak debugować bota za pomocą oprogramowania pośredniczącego inspekcji opisuje sposób dodawania oprogramowania pośredniczącego emitującego działania śledzenia.
• Do debugowania wdrożonego bota można użyć Szczegółowe informacje aplikacji. Aby uzyskać więcej informacji, zobacz Dodawanie telemetrii do bota.
• Aby uzyskać szczegółowe informacje o każdym typie działania, zobacz Schemat działania platformy Bot Framework.