Přidání aktivit trasování do robota

PLATÍ PRO: SDK v4

Aktivita trasování je aktivita, kterou robot může odeslat do bot Framework Emulatoru. Aktivity trasování můžete použít k interaktivnímu ladění robota, protože umožňují zobrazit informace o robotovi, když běží místně.

Aktivity trasování se odesílají pouze do emulátoru a ne do žádného jiného klienta nebo kanálu. Emulátor je zobrazí v protokolu, ale ne v hlavním panelu chatu.

• Trasování aktivit odesílaných přes kontext turn se odesílají prostřednictvím obslužných rutin aktivity pro odesílání zaregistrovaných v kontextu turnu.
• Trasování aktivit odesílaných přes kontext turn jsou přidružené k příchozí aktivitě použitím odkazu na konverzaci, pokud existuje. V případě proaktivní zprávy bude odpověď na ID novým identifikátorem GUID.
• Bez ohledu na to, jak se odesílá, aktivita trasování nikdy nenastaví příznak odpovědi .

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ů.

Použití aktivity trasování

Abyste viděli aktivitu trasování v emulátoru, potřebujete scénář, ve kterém robot odešle aktivitu trasování, například vyvolání výjimky a odeslání aktivity trasování z obslužné rutiny chyby adaptéru.

Odeslání aktivity trasování z robota:

1. Vytvořte novou aktivitu.
   • Nastavte jeho požadovanou vlastnost typu na "trace".
   • Volitelně můžete nastavit jeho název, popisek, hodnotu a vlastnosti typu hodnoty podle potřeby pro trasování.
2. K odeslání aktivity trasování použijte metodu aktivity odeslání kontextového objektu turn.
   • Tato metoda přidá hodnoty pro zbývající požadované vlastnosti aktivity na základě příchozí aktivity. Mezi tyto vlastnosti patří ID kanálu, adresa URL služby, z a vlastnosti příjemce.

Zobrazení aktivity trasování v emulátoru:

1. Spusťte robota místně na svém počítači.
2. Otestujte ho pomocí emulátoru.
   • Komunikujte s robotem a pomocí kroků ve vašem scénáři vygenerujte aktivitu trasování.
   • Když robot vygeneruje aktivitu trasování, aktivita trasování se zobrazí v protokolu emulátoru.

Tady je aktivita trasování, která se může zobrazit, pokud jste spustili robota Core, aniž byste nejprve nastavili QnAMaker znalostní báze, na které robot spoléhá.

Přidání aktivity trasování do obslužné rutiny při chybě adaptéru

Obslužná rutina chyby zapnutí adaptéru zachytí všechny jinak nezachycené výjimky vyvolané robotem během otáčení. Obslužná rutina chyby je vhodným místem pro aktivitu trasování, protože uživateli můžete odeslat uživatelsky přívětivou zprávu a odeslat informace o ladění o výjimce emulátoru.

Tento ukázkový kód pochází z ukázky core bota . Podívejte se na úplnou ukázku v jazyce C#, JavaScript, Python nebo Java.

C#

Obslužná rutina OnTurnError adaptéru vytvoří aktivitu trasování, která zahrne informace o výjimce a odešle ji do emulátoru.

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

Obslužná rutina onTurnError adaptéru vytvoří aktivitu trasování, která zahrne informace o výjimce a odešle ji do emulátoru.

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

V sadě Java SDK AdapterWithErrorHandler je třída součástí sady SDK v balíčku com.microsoft.bot.integration . Obslužná rutina onTurnError adaptéru vytvoří aktivitu trasování, která zahrne informace o výjimce a odešle ji do emulátoru. Zdrojový kód výchozího adaptéru je uvedený níže.

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

Obslužná rutina on_error adaptéru vytvoří aktivitu trasování, která zahrne informace o výjimce a odešle ji do emulátoru.

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)

Další kroky

• Postup ladění robota pomocí middlewaru kontroly popisuje, jak přidat middleware, který generuje aktivity trasování.
• K ladění nasazeného robota můžete použít Přehledy aplikace. Další informace najdete v tématu Přidání telemetrie do robota.
• Podrobné informace o jednotlivých typech aktivit najdete ve schématu aktivity služby Bot Framework.