Nyomkövetési tevékenységek hozzáadása a robothoz

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

A nyomkövetési tevékenység olyan tevékenység, amelyet a robot elküldhet a Bot Framework Emulatornak. A nyomkövetési tevékenységek segítségével interaktívan hibakeresést végezhet egy roboton, mivel ezek lehetővé teszik a robot adatainak megtekintését a helyi futtatás során.

A nyomkövetési tevékenységek csak az Emulátornak lesznek elküldve, más ügyfélnek vagy csatornának nem. Az Emulátor megjeleníti őket a naplóban, a fő csevegési panelen azonban nem.

• A turn környezeten keresztül küldött nyomkövetési tevékenységeket a turn kontextusban regisztrált küldési tevékenységkezelők küldik el.
• A turn környezeten keresztül küldött nyomkövetési tevékenységek a bejövő tevékenységhez vannak társítva a beszélgetési hivatkozás alkalmazásával, ha volt ilyen. Proaktív üzenet esetén az azonosítóra adott válasz egy új GUID lesz.
• Függetlenül attól, hogy a rendszer hogyan küldi el, a nyomkövetési tevékenység soha nem állítja be a válaszjelzőt .

Feljegyzés

A Bot Framework JavaScript, C# és Python SDK-k továbbra is támogatottak lesznek, a Java SDK-t azonban 2023 novemberében végső hosszú távú támogatással kivonják.

A Java SDK-val létrehozott meglévő robotok továbbra is működni fognak.

Az új robotépítéshez fontolja meg a Microsoft Copilot Studio használatát, és olvassa el a megfelelő copilot-megoldás kiválasztását.

További információ: A robotépítés jövője.

Nyomkövetési tevékenység használata

Ahhoz, hogy nyomkövetési tevékenységet láthasson az Emulatorban, olyan forgatókönyvre van szüksége, amelyben a robot nyomkövetési tevékenységet küld, például kivételt küld, és nyomkövetési tevékenységet küld az adapter bekapcsolt hibakezelőjéből.

Nyomkövetési tevékenység küldése a robotból:

1. Hozzon létre egy új tevékenységet.
   • Állítsa be a szükséges típustulajdonságot "trace" értékre .
   • Igény szerint állítsa be a nevét, a címkét, az értéket és az értéktípus tulajdonságait a nyomkövetésnek megfelelően.
2. A nyomkövetési tevékenység elküldéséhez használja a turn context object send activity metódusát.
   • Ez a metódus a bejövő tevékenység alapján hozzáadja a tevékenység fennmaradó szükséges tulajdonságaihoz tartozó értékeket. Ezek a tulajdonságok közé tartozik a csatornaazonosító, a szolgáltatás URL-címe, a feladó és a címzett tulajdonságai.

Nyomkövetési tevékenység megtekintése az Emulátorban:

1. Futtassa a robotot helyileg a gépen.
2. Tesztelje az Emulator használatával.
   • Lépjen kapcsolatba a robottal, és használja a forgatókönyv lépéseit a nyomkövetési tevékenység létrehozásához.
   • Amikor a robot kibocsátja a nyomkövetési tevékenységet, a nyomkövetési tevékenység megjelenik az Emulator-naplóban.

Az alábbi nyomkövetési tevékenységből megtudhatja, hogy futtatta-e a Core robotot anélkül, hogy először beállította volna a QnAMaker tudásbázis, amelyekre a robot támaszkodik.

Nyomkövetési tevékenység hozzáadása az adapter hibakezelőhöz

Az adapter bekapcsolt hibakezelője észleli a robottól a fordulás során kidobott, egyébként nem tapasztalt kivételeket. A hibakezelő jó hely a nyomkövetési tevékenységekhez, mivel felhasználóbarát üzenetet küldhet a felhasználónak, és hibakeresési információkat küldhet a kivételről az Emulátornak.

Ez a példakód a Core Bot-mintából származik. Tekintse meg a teljes mintát c#, JavaScript, Python vagy Java nyelven.

C#

Az adapter OnTurnError kezelője létrehozza a nyomkövetési tevékenységet, amely tartalmazza a kivételadatokat, és elküldi azokat az Emulátornak.

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

Az adapter onTurnError kezelője létrehozza a nyomkövetési tevékenységet, amely tartalmazza a kivételadatokat, és elküldi azokat az Emulátornak.

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

A Java SDK-ban egy AdapterWithErrorHandler osztály szerepel a com.microsoft.bot.integration csomag SDK-jának részeként. Az adapter onTurnError kezelője létrehozza a nyomkövetési tevékenységet, amely tartalmazza a kivételadatokat, és elküldi azokat az Emulátornak. Az alapértelmezett adapter forráskódja alább látható.

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

Az adapter on_error kezelője létrehozza a nyomkövetési tevékenységet, amely tartalmazza a kivételadatokat, és elküldi azokat az Emulátornak.

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)

Következő lépések

• A felügyeleti köztes szoftverrel rendelkező robot hibakeresése azt ismerteti, hogyan adhat hozzá nyomkövetési tevékenységeket kibocsátó köztes szoftvereket.
• Az üzembe helyezett robot hibakereséséhez használhatja az Application Insightst. További információ: Telemetriai adatok hozzáadása a robothoz.
• Az egyes tevékenységtípusokra vonatkozó részletes információkért tekintse meg a Bot Framework tevékenységséma című témakört.