Megosztás a következőn keresztül:


Felhasználói és beszélgetésadatok mentése

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

A robot természeténél fogva állapot nélküli. A robot üzembe helyezése után előfordulhat, hogy nem ugyanabban a folyamatban vagy ugyanazon a gépen fut egyikről a másikra. Előfordulhat azonban, hogy a robotnak nyomon kell követnie egy beszélgetés kontextusát, hogy kezelni tudja a viselkedését, és emlékezzen a korábbi kérdésekre adott válaszokra. A Bot Framework SDK állapot- és tárolási funkciói lehetővé teszik az állapot hozzáadását a robothoz. A robotok állapotkezelési és tárolási objektumokat használnak az állapot kezeléséhez és megőrzéséhez. Az állapotkezelő egy absztrakciós réteget biztosít, amely lehetővé teszi az állapottulajdonságok elérését az alapul szolgáló tároló típusától független tulajdonságkiegészítők használatával.

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.

Előfeltételek

  • Ismerni kell a robot alapjait és azt, hogy a robotok hogyan kezelik az állapotot.
  • A cikkben szereplő kód az Állapotkezelési robot mintáján alapul. Szüksége lesz a minta másolatára c#, JavaScript, Java vagy Python nyelven.

A minta ismertetése

A felhasználói bemenet fogadásakor ez a minta ellenőrzi a tárolt beszélgetés állapotát, hogy a rendszer kéri-e korábban a felhasználó nevét. Ha nem, a rendszer kéri a felhasználó nevét, és a bemenetet a rendszer felhasználói állapotban tárolja. Ha igen, a rendszer a felhasználói állapotban tárolt nevet használja a felhasználóval való konververáláshoz, és a bemeneti adatok, valamint a kapott idő és a bemeneti csatorna azonosítója vissza lesz adva a felhasználónak. A rendszer lekéri az idő- és csatornaazonosító-értékeket a felhasználói beszélgetés adataiból, majd menti a beszélgetési állapotba. Az alábbi ábra a robot, a felhasználói profil és a beszélgetési adatosztályok közötti kapcsolatot mutatja be.

Osztályok definiálása

Az állapotkezelés beállításának első lépése a felhasználói és beszélgetési állapotban kezelendő információkat tartalmazó osztályok meghatározása. A cikkben használt példa a következő osztályokat határozza meg:

  • A UserProfile.cs meghatároz egy osztályt UserProfile a robot által gyűjtött felhasználói adatokhoz.
  • A ConversationData.cs meghatároz egy osztályt ConversationData , amely a felhasználói adatok összegyűjtése közben szabályozza a beszélgetés állapotát.

Az alábbi példakódok az osztályok és ConversationData az osztályok definícióit UserProfile mutatják be.

UserProfile.cs

public class UserProfile
{
    public string Name { get; set; }
}

ConversationData.cs

public class ConversationData
{
    // The time-stamp of the most recent incoming message.
    public string Timestamp { get; set; }

    // The ID of the user's channel.
    public string ChannelId { get; set; }

    // Track whether we have already asked the user's name
    public bool PromptedUserForName { get; set; } = false;
}

Beszélgetési és felhasználói állapotobjektumok létrehozása

Ezután regisztrálja MemoryStorage a létrehozáshoz UserState és ConversationState az objektumokhoz használt regisztrációt. A felhasználó- és beszélgetésállapot-objektumok a robotkonstruktorban Startup jönnek létre, és függőséget injektálnak. A regisztrált robotok további szolgáltatásai a következők: hitelesítőadat-szolgáltató, adapter és robot implementációja.

Startup.cs

// {
//     TypeNameHandling = TypeNameHandling.All,
// var storage = new BlobsStorage("<blob-storage-connection-string>", "bot-state");

// With a custom JSON SERIALIZER, use this instead.
// var storage = new BlobsStorage("<blob-storage-connection-string>", "bot-state", jsonSerializer);

/* END AZURE BLOB STORAGE */

Robotok/StateManagementBot.cs

private BotState _conversationState;
private BotState _userState;

public StateManagementBot(ConversationState conversationState, UserState userState)
{
    _conversationState = conversationState;
    _userState = userState;
}

Állapottulajdonság-tartozék hozzáadása

Most hozzon létre tulajdonságkiegészítőket azzal a CreateProperty metódussal, amely egy fogópontot biztosít az BotState objektum számára. Minden állapottulajdonság-tartozék lehetővé teszi a társított állapottulajdonság értékének lekérését vagy beállítását. Az állapottulajdonságok használata előtt az egyes tartozékokkal töltse be a tulajdonságot a tárolóból, és szerezze be az állapotgyorsítótárból. Az állapottulajdonsághoz tartozó megfelelő hatókörű kulcs lekéréséhez hívja meg a metódust GetAsync .

Robotok/StateManagementBot.cs

var conversationStateAccessors = _conversationState.CreateProperty<ConversationData>(nameof(ConversationData));
var userStateAccessors = _userState.CreateProperty<UserProfile>(nameof(UserProfile));

Hozzáférési állapot a robotból

Az előző szakasz ismerteti az inicializálási idő lépéseit, hogy állapottulajdonság-kiegészítőket adjon hozzá a robothoz. Ezeket a tartozékokat futtatáskor használhatja állapotinformációk olvasására és írására. Az alábbi mintakód a következő logikai folyamatot használja:

  • Ha userProfile.Name üres, és conversationData.PromptedUserForName igaz, lekéri a megadott felhasználónevet, és ezt felhasználói állapotban tárolja.
  • Ha userProfile.Name üres, és conversationData.PromptedUserForName hamis, a felhasználó nevét kell megadnia.
  • Ha userProfile.Name korábban tárolták, lekéri az üzenet idejét és csatornaazonosítóját a felhasználói bemenetből, visszakéri az összes adatot a felhasználónak, és a lekért adatokat beszélgetési állapotban tárolja.

Robotok/StateManagementBot.cs

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Get the state properties from the turn context.

    var conversationStateAccessors = _conversationState.CreateProperty<ConversationData>(nameof(ConversationData));
    var conversationData = await conversationStateAccessors.GetAsync(turnContext, () => new ConversationData());

    var userStateAccessors = _userState.CreateProperty<UserProfile>(nameof(UserProfile));
    var userProfile = await userStateAccessors.GetAsync(turnContext, () => new UserProfile());

    if (string.IsNullOrEmpty(userProfile.Name))
    {
        // First time around this is set to false, so we will prompt user for name.
        if (conversationData.PromptedUserForName)
        {
            // Set the name to what the user provided.
            userProfile.Name = turnContext.Activity.Text?.Trim();

            // Acknowledge that we got their name.
            await turnContext.SendActivityAsync($"Thanks {userProfile.Name}. To see conversation data, type anything.");

            // Reset the flag to allow the bot to go through the cycle again.
            conversationData.PromptedUserForName = false;
        }
        else
        {
            // Prompt the user for their name.
            await turnContext.SendActivityAsync($"What is your name?");

            // Set the flag to true, so we don't prompt in the next turn.
            conversationData.PromptedUserForName = true;
        }
    }
    else
    {
        // Add message details to the conversation data.
        // Convert saved Timestamp to local DateTimeOffset, then to string for display.
        var messageTimeOffset = (DateTimeOffset)turnContext.Activity.Timestamp;
        var localMessageTime = messageTimeOffset.ToLocalTime();
        conversationData.Timestamp = localMessageTime.ToString();
        conversationData.ChannelId = turnContext.Activity.ChannelId.ToString();

        // Display state data.
        await turnContext.SendActivityAsync($"{userProfile.Name} sent: {turnContext.Activity.Text}");
        await turnContext.SendActivityAsync($"Message received at: {conversationData.Timestamp}");
        await turnContext.SendActivityAsync($"Message received from: {conversationData.ChannelId}");
    }
}

Mielőtt kilép a turn handlerből, az állapotkezelési objektumok SaveChangesAsync() metódusával minden állapotváltozást visszaírhat a tárolóba.

Robotok/StateManagementBot.cs

public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))
{
    await base.OnTurnAsync(turnContext, cancellationToken);

    // Save any state changes that might have occurred during the turn.
    await _conversationState.SaveChangesAsync(turnContext, false, cancellationToken);
    await _userState.SaveChangesAsync(turnContext, false, cancellationToken);
}

A robot tesztelése

  1. Töltse le és telepítse a legújabb Bot Framework Emulatort
  2. Futtassa a mintát helyileg a számítógépen. Ha útmutatásra van szüksége, tekintse meg a README for C#, JavaScript, Java vagy Python használatát.
  3. Az Emulator használatával tesztelheti a mintarobotot.

További információk

Ez a cikk azt ismertette, hogyan adhat állapotot a robothoz. A kapcsolódó témakörökről az alábbi táblázatban talál további információt.

Téma Jegyzetek
Adatvédelem Ha a felhasználó személyes adatait kívánja tárolni, győződjön meg arról, hogy megfelel az általános adatvédelmi rendeletnek.
Állapotkezelés Az összes állapotkezelési hívás aszinkron, és alapértelmezés szerint az utolsó író nyer. A gyakorlatban az állapotot a lehető legközelebb kell megkapnia, beállítania és mentenie a robotban. Az optimista zárolás implementálásának módjáról a robot egyéni tárolójának implementálása című témakörben olvashat.
Kritikus üzleti adatok A robotállapot használatával tárolhatja a beállításokat, a felhasználónevet vagy az utolsó megrendelt dolgot, de ne használja a kritikus fontosságú üzleti adatok tárolására. Kritikus adatokhoz hozzon létre saját tárolóösszetevőket, vagy írjon közvetlenül a tárolóba.
Recognizer-Text A minta a Microsoft/Recognizers-Text kódtárak használatával elemzi és ellenőrzi a felhasználói bemenetet. További információkért tekintse meg az áttekintési oldalt.

Következő lépések

Megtudhatja, hogyan tehet fel kérdéseket a felhasználónak, hogyan ellenőrizheti a válaszait, és hogyan mentheti a bemenetét.