Bagikan melalui


Menyimpan data pengguna dan percakapan

BERLAKU UNTUK: SDK v4

Bot secara inheren tanpa status. Setelah bot Anda disebarkan, bot mungkin tidak berjalan dalam proses yang sama atau pada komputer yang sama dari satu giliran ke giliran berikutnya. Namun, bot Anda mungkin perlu melacak konteks percakapan sehingga dapat mengelola perilakunya dan mengingat jawaban atas pertanyaan sebelumnya. Fitur status dan penyimpanan Bot Framework SDK memungkinkan Anda menambahkan status ke bot Anda. Bot menggunakan manajemen status dan objek penyimpanan untuk mengelola dan mempertahankan status. Manajer status menyediakan lapisan abstraksi yang memungkinkan Anda mengakses properti status menggunakan aksesor properti, terlepas dari jenis penyimpanan yang mendasar.

Catatan

Bot Framework JavaScript, C#, dan Python SDK akan terus didukung, namun, Java SDK dihentikan dengan dukungan jangka panjang akhir yang berakhir pada November 2023.

Bot yang ada yang dibangun dengan Java SDK akan terus berfungsi.

Untuk pembuatan bot baru, pertimbangkan untuk menggunakan Power Virtual Agents dan baca tentang memilih solusi chatbot yang tepat.

Untuk informasi selengkapnya, lihat Masa depan pembuatan bot.

Prasyarat

Tentang sampel ini

Setelah menerima input pengguna, sampel ini memeriksa status percakapan yang disimpan untuk melihat apakah pengguna ini sebelumnya telah diminta untuk memberikan namanya. Jika tidak, nama pengguna diminta dan input tersebut disimpan dalam status pengguna. Jika demikian, nama yang disimpan dalam status pengguna digunakan untuk berkomunikasi dengan pengguna dan data input mereka, bersama dengan waktu yang diterima dan ID saluran input, dikembalikan kepada pengguna. Nilai ID waktu dan saluran diambil dari data percakapan pengguna lalu disimpan ke status percakapan. Diagram berikut menunjukkan hubungan antara bot, profil pengguna, dan kelas data percakapan.

Menentukan kelas

Langkah pertama dalam menyiapkan manajemen status adalah menentukan kelas yang berisi informasi yang akan dikelola dalam status pengguna dan percakapan. Contoh yang digunakan dalam artikel ini, menentukan kelas berikut:

  • Dalam UserProfile.cs, Anda menentukan UserProfile kelas untuk informasi pengguna yang akan dikumpulkan bot.
  • Dalam ConversationData.cs, Anda menentukan ConversationData kelas untuk mengontrol status percakapan kami saat mengumpulkan informasi pengguna.

Contoh kode berikut menunjukkan definisi untuk UserProfile kelas dan ConversationData .

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

Membuat objek percakapan dan status pengguna

Selanjutnya, Anda mendaftar MemoryStorage yang digunakan untuk membuat UserState objek dan ConversationState . Objek status pengguna dan percakapan dibuat di Startup dan dependensi disuntikkan ke konstruktor bot. Layanan lain untuk bot yang terdaftar adalah: penyedia info masuk, adaptor, dan implementasi bot.

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

Bot/StateManagementBot.cs

private BotState _conversationState;
private BotState _userState;

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

Menambahkan pengaktif properti status

Sekarang Anda membuat aksesor properti menggunakan CreateProperty metode yang menyediakan handel ke BotState objek. Setiap pengaktif properti status memungkinkan Anda mendapatkan atau mengatur nilai properti status terkait. Sebelum Anda menggunakan properti status, gunakan setiap aksesor untuk memuat properti dari penyimpanan dan mendapatkannya dari cache status. Untuk mendapatkan kunci yang tercakup dengan benar yang terkait dengan properti status, Anda memanggil GetAsync metode .

Bot/StateManagementBot.cs

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

Status akses dari bot Anda

Bagian sebelumnya mencakup langkah-langkah waktu inisialisasi untuk menambahkan pengakses properti status ke bot kami. Sekarang, Anda dapat menggunakan aksesor tersebut pada run-time untuk membaca dan menulis informasi status. Kode sampel di bawah ini menggunakan alur logika berikut:

  • Jika userProfile.Name kosong dan conversationData.PromptedUserForName benar, Anda mengambil nama pengguna yang disediakan dan menyimpannya dalam status pengguna.
  • Jika userProfile.Name kosong dan conversationData.PromptedUserForNamesalah, Anda meminta nama pengguna.
  • Jika userProfile.Name sebelumnya disimpan, Anda mengambil waktu pesan dan ID saluran dari input pengguna, menggemakan semua data kembali ke pengguna, dan menyimpan data yang diambil dalam status percakapan.

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

Sebelum Anda keluar dari handler giliran, Anda menggunakan metode SaveChangesAsync() objek manajemen status untuk menulis semua perubahan status kembali ke penyimpanan.

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

Menguji bot

  1. Unduh dan instal Emulator Kerangka Kerja Bot terbaru
  2. Jalankan sampel secara lokal di komputer Anda. Jika Anda memerlukan instruksi, lihat README untuk C#, JavaScript, Java, atau Python.
  3. Gunakan Emulator untuk menguji bot sampel Anda.

Informasi Tambahan

Artikel ini menjelaskan cara menambahkan status ke bot Anda. Lihat tabel berikut ini untuk informasi selengkapnya tentang topik terkait.

Topik Catatan
Privasi Jika Anda ingin menyimpan data pribadi pengguna, Anda harus memastikan kepatuhan terhadap Peraturan Perlindungan Data Umum.
Manajemen Status Semua panggilan manajemen status bersifat asinkron, dan last-writer-wins secara default. Dalam praktiknya, Anda harus mendapatkan, mengatur, dan menyimpan status sedekat mungkin di bot Anda. Untuk diskusi tentang cara menerapkan penguncian optimis, lihat Menerapkan penyimpanan kustom untuk bot Anda.
Data bisnis penting Gunakan status bot untuk menyimpan preferensi, nama pengguna, atau hal terakhir yang mereka pesan, tetapi jangan gunakan untuk menyimpan data bisnis penting. Untuk data penting, buat komponen penyimpanan Anda sendiri atau tulis langsung ke penyimpanan.
Recognizer-Text Sampel menggunakan pustaka Microsoft/Recognizers-Text untuk mengurai dan memvalidasi input pengguna. Untuk informasi selengkapnya, lihat halaman gambaran umum .

Langkah berikutnya

Pelajari cara mengajukan serangkaian pertanyaan kepada pengguna, memvalidasi jawaban mereka, dan menyimpan input mereka.