ユーザーおよび会話データを保存する

[アーティクル]
03/08/2023

適用対象: SDK v4

ボットは本質的にステートレスです。いったんご自身のボットがデプロイされると、ターンをまたいで、そのボットを同じプロセスやマシンで実行することはできません。しかし、お使いのボットでは、会話のコンテキストの追跡が必要になることがあります。これにより、自身の動作を管理し、以前の質問に対する回答を記憶できるようになります。 Bot Framework SDK の状態とストレージの機能を使用すると、状態をお使いのボットに追加できます。ボットは状態管理およびストレージオブジェクトを使用して状態を管理維持します。この状態マネージャーは、基になるストレージの種類には関係なく、プロパティアクセサーを使用して状態プロパティにアクセスできる抽象化レイヤーを提供します。

Note

Bot Framework JavaScript と C# SDK は引き続きサポートされますが、Python SDK と Java SDK は廃止され、2023 年 11 月に終了する最終的な長期サポートが終了します。このリポジトリ内の重要なセキュリティとバグの修正のみが行われます。

これらの SDK を使用して構築された既存のボットは引き続き機能します。

新しいボットの構築については、 Power Virtual Agents の使用を検討し、適切なチャットボットソリューションの選択に関する記事を参照してください。

詳細については、「ボット構築の未来」を参照してください。

前提条件

ボットの基本、およびボットによる状態の管理方法に関する知識が必要です。
この記事のコードは、状態管理ボット サンプルをベースにしています。サンプルのコピーは、 C#、 JavaScript、 Java、または Python のいずれかで必要になります。

このサンプルについて

このサンプルでは、ユーザー入力を受け取ったときに、保存済み会話状態を確認して、ユーザーが以前に名前を入力するように求められたかどうかを確かめます。求められていない場合は、ユーザーの名前が要求され、入力した内容はユーザー状態に格納されます。その場合は、ユーザー状態に格納されている名前を使用して、ユーザーとその入力データと、受信した時刻と入力チャネル ID がユーザーに返されます。時刻とチャネル ID の値は、ユーザーの会話データから取得され、会話状態に保存されます。次の図は、ボット、ユーザープロファイル、および会話データクラスの間の関係を示しています。

C# サンプルの構造を示すクラス図。

クラスの定義

状態管理を設定するには、まず、ユーザーと会話状態で管理する情報を含むクラスを定義します。この記事で使用している例では、次のクラスを定義しています。

UserProfile.cs では、ボットがUserProfile収集するユーザー情報のクラスを定義します。
ConversationData.cs では、ユーザー情報のConversationData収集中に会話の状態を制御するクラスを定義します。

次のコード例は、UserProfile と 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;
}

状態管理を設定するには、まず、ユーザーと会話状態で管理する情報を含むクラスを定義します。この記事で使用する例では、次のクラスを定義します。

UserProfile.java では、ボットがUserProfile収集するユーザー情報のクラスを定義します。
ConversationData.java では、ユーザー情報のConversationData収集中に会話の状態を制御するクラスを定義します。

次のコード例は、UserProfile と ConversationData クラスの定義を示しています。

UserProfile.java

public class UserProfile {
    private String name;

    public String getName() {
        return name;
    }

    public void setName(String withName) {
        name = withName;
    }
}

ConversationData.java

public class ConversationData {
    // The time-stamp of the most recent incoming message.
    private String timestamp;
    // The ID of the user's channel.
    private String channelId;
    // Track whether we have already asked the user's name.
    private boolean promptedUserForName = false;

    public String getTimestamp() {
        return timestamp;
    }

    public void setTimestamp(String withTimestamp) {
        timestamp = withTimestamp;
    }

    public String getChannelId() {
        return channelId;
    }

    public void setChannelId(String withChannelId) {
        channelId = withChannelId;
    }

    public boolean getPromptedUserForName() {
        return promptedUserForName;
    }

    public void setPromptedUserForName(boolean withPromptedUserForName) {

user_profile.py には、UserProfileボットによって収集されたユーザー情報を格納するクラスが含まれています。
conversation_data.py には、ユーザー情報のConversationData収集中に会話の状態を制御するクラスが含まれています。

次のコード例は、UserProfile と ConversationData クラスの定義を示しています。

user_profile.py

class UserProfile:
    def __init__(self, name: str = None):
        self.name = name

conversation_data.py

class ConversationData:
    def __init__(
        self,
        timestamp: str = None,
        channel_id: str = None,
        prompted_for_user_name: bool = False,
    ):
        self.timestamp = timestamp
        self.channel_id = channel_id
        self.prompted_for_user_name = prompted_for_user_name

会話およびユーザー状態オブジェクトの作成

次に、オブジェクトと ConversationState オブジェクトの作成UserStateに使用されるを登録MemoryStorageします。ユーザーおよび会話状態オブジェクトは Startup で作成され、依存関係がボットコンストラクターに挿入されます。ボット用のサービスとして他に資格情報プロバイダー、アダプター、およびボット実装が登録されています。

Startup.cs

var storage = new MemoryStorage();

// Create the User state passing in the storage layer.
var userState = new UserState(storage);
services.AddSingleton(userState);

// Create the Conversation state passing in the storage layer.
var conversationState = new ConversationState(storage);
services.AddSingleton(conversationState);

Bots/StateManagementBot.cs

private BotState _conversationState;
private BotState _userState;

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

次に、それを登録MemoryStorageし、オブジェクトと ConversationState オブジェクトを作成UserStateするために使用します。これらは index.js で作成され、ボットの作成時に使用されます。

index.js

const memoryStorage = new MemoryStorage();

// Create conversation and user state with in-memory storage provider.
const conversationState = new ConversationState(memoryStorage);
const userState = new UserState(memoryStorage);

// Create the bot.
const bot = new StateManagementBot(conversationState, userState);

bots/stateManagementBot.js

const CONVERSATION_DATA_PROPERTY = 'conversationData';
const USER_PROFILE_PROPERTY = 'userProfile';

class StateManagementBot extends ActivityHandler {
    constructor(conversationState, userState) {
        super();
        // Create the state property accessors for the conversation data and user profile.
        this.conversationDataAccessor = conversationState.createProperty(CONVERSATION_DATA_PROPERTY);
        this.userProfileAccessor = userState.createProperty(USER_PROFILE_PROPERTY);

        // The state management objects for the conversation and user state.
        this.conversationState = conversationState;
        this.userState = userState;

次に、を StateManagementBot Application.java に登録します。 ConversationState と UserState の両方が既定で BotDependencyConfiguration クラスから提供され、Spring によって getBot メソッドに挿入されます。

Application.java

@Bean
public Bot getBot(
    ConversationState conversationState,
    UserState userState
) {
    return new StateManagementBot(conversationState, userState);
}

次に、オブジェクトと ConversationState オブジェクトの作成UserStateに使用されるを登録MemoryStorageします。これらは app.py で作成され、ボットの作成時に使用されます。

app.py

# Create MemoryStorage and state
MEMORY = MemoryStorage()
USER_STATE = UserState(MEMORY)
CONVERSATION_STATE = ConversationState(MEMORY)

# Create Bot
BOT = StateManagementBot(CONVERSATION_STATE, USER_STATE)

bots/state_management_bot.py

def __init__(self, conversation_state: ConversationState, user_state: UserState):
    if conversation_state is None:
        raise TypeError(
            "[StateManagementBot]: Missing parameter. conversation_state is required but None was given"
        )
    if user_state is None:
        raise TypeError(
            "[StateManagementBot]: Missing parameter. user_state is required but None was given"
        )

    self.conversation_state = conversation_state
    self.user_state = user_state

    self.conversation_data_accessor = self.conversation_state.create_property(
        "ConversationData"
    )
    self.user_profile_accessor = self.user_state.create_property("UserProfile")

状態プロパティアクセサーの追加

次に、オブジェクトへのハンドルを提供するメソッドを CreateProperty 使用して、プロパティアクセサーを BotState 作成します。各状態プロパティアクセサーを使用すると、関連付けられている状態プロパティの値を取得または設定できます。状態プロパティを使用する前に、各アクセサーを使用してストレージからプロパティを読み込み、状態キャッシュから取得します。 state プロパティに関連付けられている適切なスコープのキーを取得するには、メソッドを GetAsync 呼び出します。

Bots/StateManagementBot.cs

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

次に、とのプロパティアクセサーを UserState 作成します ConversationState。各状態プロパティアクセサーを使用すると、関連付けられている状態プロパティの値を取得または設定できます。各アクセサーを使用して、関連付けられたプロパティをストレージから読み込み、キャッシュから現在の状態を取得します。

bots/stateManagementBot.js

// Create the state property accessors for the conversation data and user profile.
this.conversationDataAccessor = conversationState.createProperty(CONVERSATION_DATA_PROPERTY);
this.userProfileAccessor = userState.createProperty(USER_PROFILE_PROPERTY);

次に、メソッドを使用してプロパティアクセサーを createProperty 作成します。各状態プロパティアクセサーを使用すると、関連付けられている状態プロパティの値を取得または設定できます。状態プロパティを使用する前に、各アクセサーを使用してストレージからプロパティを読み込み、状態キャッシュから取得します。 state プロパティに関連付けられている適切なスコープのキーを取得するには、メソッドを get 呼び出します。

StateManagementBot.java

StatePropertyAccessor<ConversationData> dataAccessor =
    conversationState.createProperty("data");
CompletableFuture<ConversationData> dataFuture =
    dataAccessor.get(turnContext, ConversationData::new);

次に、とのプロパティアクセサーを UserProfile 作成します ConversationData。各状態プロパティアクセサーを使用すると、関連付けられている状態プロパティの値を取得または設定できます。各アクセサーを使用して、関連付けられたプロパティをストレージから読み込み、キャッシュから現在の状態を取得します。

bots/state_management_bot.py

self.conversation_data_accessor = self.conversation_state.create_property(
    "ConversationData"
)
self.user_profile_accessor = self.user_state.create_property("UserProfile")

お使いのボットから状態にアクセスする

前のセクションでは、状態プロパティアクセサーをボットに追加するための、初期化時の手順について説明しました。これで、実行時にこれらのアクセサーを使用して、状態情報の読み取りと書き込みを行うことができます。次のサンプルコードでは次のロジックフローを使用します。

が空で conversationData.PromptedUserForNametrue の場合userProfile.Nameは、指定されたユーザー名を取得し、これをユーザー状態に格納します。
が空で conversationData.PromptedUserForNamefalse の場合userProfile.Nameは、ユーザーの名前を要求します。
以前に格納されていた場合 userProfile.Name は、ユーザー入力からメッセージ時間とチャネル ID を取得し、すべてのデータをユーザーにエコーバックし、取得したデータを会話状態に格納します。

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

ターンハンドラーを終了する前に、状態管理オブジェクトの SaveChangesAsync() メソッドを使用して、すべての状態変更をストレージに書き戻します。

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

が空で conversationData.PromptedUserForNametrue の場合userProfile.Nameは、指定されたユーザー名を取得し、これをユーザー状態に格納します。
が空で conversationData.PromptedUserForNamefalse の場合userProfile.Nameは、ユーザーの名前を要求します。
以前に格納されていた場合 userProfile.Name は、ユーザー入力からメッセージ時間とチャネル ID を取得し、すべてのデータをユーザーにエコーバックし、取得したデータを会話状態に格納します。

bots/stateManagementBot.js

this.onMessage(async (turnContext, next) => {
    // Get the state properties from the turn context.
    const userProfile = await this.userProfileAccessor.get(turnContext, {});
    const conversationData = await this.conversationDataAccessor.get(
        turnContext, { promptedForUserName: false });

    if (!userProfile.name) {
        // First time around this is undefined, so we will prompt user for name.
        if (conversationData.promptedForUserName) {
            // Set the name to what the user provided.
            userProfile.name = turnContext.activity.text;

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

            // Reset the flag to allow the bot to go though the cycle again.
            conversationData.promptedForUserName = false;
        } else {
            // Prompt the user for their name.
            await turnContext.sendActivity('What is your name?');

            // Set the flag to true, so we don't prompt in the next turn.
            conversationData.promptedForUserName = true;
        }
    } else {
        // Add message details to the conversation data.
        conversationData.timestamp = turnContext.activity.timestamp.toLocaleString();
        conversationData.channelId = turnContext.activity.channelId;

        // Display state data.
        await turnContext.sendActivity(`${ userProfile.name } sent: ${ turnContext.activity.text }`);
        await turnContext.sendActivity(`Message received at: ${ conversationData.timestamp }`);
        await turnContext.sendActivity(`Message received from: ${ conversationData.channelId }`);
    }

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

各ダイアログターンを終了する前に、状態管理オブジェクトの saveChanges() メソッドを使用して、状態をストレージに書き戻すことによってすべての変更を保持します。

bots/stateManagementBot.js

/**
 * Override the ActivityHandler.run() method to save state changes after the bot logic completes.
 */
async run(context) {
    await super.run(context);

    // Save any state changes. The load happened during the execution of the Dialog.
    await this.conversationState.saveChanges(context, false);
    await this.userState.saveChanges(context, false);
}

が空で conversationData.getPromptedUserForName()true の場合userProfile.getName()は、指定されたユーザー名を取得し、これをユーザー状態に格納します。
が空で conversationData.getPromptedUserForName()false の場合userProfile.getName()は、ユーザーの名前を要求します。
以前に格納されていた場合 userProfile.getName() は、ユーザー入力からメッセージ時間とチャネル ID を取得し、すべてのデータをユーザーにエコーバックし、取得したデータを会話状態に格納します。

StateManagementBot.java

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    // Get state data from ConversationState.
    StatePropertyAccessor<ConversationData> dataAccessor =
        conversationState.createProperty("data");
    CompletableFuture<ConversationData> dataFuture =
        dataAccessor.get(turnContext, ConversationData::new);

    // Get profile from UserState.
    StatePropertyAccessor<UserProfile> profileAccessor = userState.createProperty("profile");
    CompletableFuture<UserProfile> profileFuture =
        profileAccessor.get(turnContext, UserProfile::new);

    return dataFuture.thenCombine(profileFuture, (conversationData, userProfile) -> {
        if (StringUtils.isBlank(userProfile.getName())) {
            // First time around this is set to false, so we will prompt user for name.
            if (conversationData.getPromptedUserForName()) {
                // Reset the flag to allow the bot to go though the cycle again.
                conversationData.setPromptedUserForName(false);

                // Set the name to what the user provided and reply.
                userProfile.setName(turnContext.getActivity().getText());
                // Acknowledge that we got their name.
                return turnContext.sendActivity(
                    MessageFactory.text(
                        "Thanks " + userProfile.getName()
                            + ".  To see conversation data, type anything."
                    )
                );
            } else {
                // Set the flag to true, so we don't prompt in the next turn.
                conversationData.setPromptedUserForName(true);
                // Prompt the user for their name.
                return turnContext.sendActivity(MessageFactory.text("What is your name?"));
            }
        } else {
            OffsetDateTime messageTimeOffset = turnContext.getActivity().getTimestamp();
            LocalDateTime localMessageTime = messageTimeOffset.toLocalDateTime();
            //Displaying current date and time in 12 hour format with AM/PM
            DateTimeFormatter dateTimeAMPMFormat = DateTimeFormatter.ofPattern("MM/dd/yyyy, hh:mm:ss a");
            conversationData.setTimestamp(dateTimeAMPMFormat.format(localMessageTime));
            conversationData.setChannelId(turnContext.getActivity().getChannelId());

            List<Activity> sendToUser = new ArrayList<>();

            sendToUser.add(
                MessageFactory.text(
                    userProfile.getName() + " sent: " + turnContext.getActivity().getText()
                )
            );

            sendToUser.add(
                MessageFactory.text("Message received at: " + conversationData.getTimestamp()
                )
            );

            sendToUser.add(
                MessageFactory.text("Message received from: " + conversationData.getChannelId()
                )
            );

            return turnContext.sendActivities(sendToUser);
        }
    })
        // make the return value happy.
        .thenApply(resourceResponse -> null);
}

ターンハンドラーを終了する前に、状態管理オブジェクトの saveChanges() メソッドを使用して、すべての状態変更をストレージに書き戻します。

StateManagementBot.java

@Override
public CompletableFuture<Void> onTurn(TurnContext turnContext) {
    return super.onTurn(turnContext)
        // Save any state changes that might have occurred during the turn.
        .thenCompose(turnResult -> conversationState.saveChanges(turnContext))
        .thenCompose(saveResult -> userState.saveChanges(turnContext));
}

user_profile.name が空で、conversation_data.prompted_for_user_name が true の場合、ボットは、ユーザーによって指定された名前を取得し、ユーザーの状態内に格納します。
が空で conversation_data.prompted_for_user_namefalse の場合user_profile.name、ボットはユーザーの名前を要求します。
以前に格納されていた場合 user_profile.name 、ボットはユーザー入力からメッセージ時間とチャネル ID を取得し、データをユーザーにエコーバックし、取得したデータを会話状態に格納します。

bots/state_management_bot.py

async def on_message_activity(self, turn_context: TurnContext):
    # Get the state properties from the turn context.
    user_profile = await self.user_profile_accessor.get(turn_context, UserProfile)
    conversation_data = await self.conversation_data_accessor.get(
        turn_context, ConversationData
    )

    if user_profile.name is None:
        # First time around this is undefined, so we will prompt user for name.
        if conversation_data.prompted_for_user_name:
            # Set the name to what the user provided.
            user_profile.name = turn_context.activity.text

            # Acknowledge that we got their name.
            await turn_context.send_activity(
                f"Thanks { user_profile.name }. To see conversation data, type anything."
            )

            # Reset the flag to allow the bot to go though the cycle again.
            conversation_data.prompted_for_user_name = False
        else:
            # Prompt the user for their name.
            await turn_context.send_activity("What is your name?")

            # Set the flag to true, so we don't prompt in the next turn.
            conversation_data.prompted_for_user_name = True
    else:
        # Add message details to the conversation data.
        conversation_data.timestamp = self.__datetime_from_utc_to_local(
            turn_context.activity.timestamp
        )
        conversation_data.channel_id = turn_context.activity.channel_id

        # Display state data.
        await turn_context.send_activity(
            f"{ user_profile.name } sent: { turn_context.activity.text }"
        )
        await turn_context.send_activity(
            f"Message received at: { conversation_data.timestamp }"
        )
        await turn_context.send_activity(
            f"Message received from: { conversation_data.channel_id }"
        )

各ダイアログターンが終了する前に、ボットは状態管理オブジェクトの save_changes メソッドを使用して、ストレージに状態情報を書き込むことですべての変更を保持します。

bots/state_management_bot.py

async def on_turn(self, turn_context: TurnContext):
    await super().on_turn(turn_context)

    await self.conversation_state.save_changes(turn_context)
    await self.user_state.save_changes(turn_context)

ボットをテストする

最新の Bot Framework Emulator をダウンロードしてインストールします
ご自身のマシンを使ってローカルでサンプルを実行します。手順が必要な場合は、 C#、 JavaScript、 Java、または Python の README を参照してください。
エミュレーターを使用してサンプルボットをテストします。

トピック	Notes
プライバシー	ユーザーの個人データを格納する場合は、一般データ保護規則に関するコンプライアンスを確保する必要があります。
状態管理	すべての状態管理呼び出しが非同期で行われます。これらの呼び出しは既定で Last-Writer-Wins です。実際の場面では、状態の取得、設定、および保存は、ご自身のボット内で、できるだけ近いタイミングで行う必要があります。オプティミスティックロックを実装する方法については、「ボットのカスタムストレージを実装する」を参照してください。
重要なビジネスデータ	ボットの状態を使用して、優先順位、ユーザー名、または最後に注文したものを格納しますが、重要なビジネスデータの格納には使用しないでください。重要なデータについては、独自のストレージコンポーネントを作成するか、ストレージに直接書き込んでください。
Recognizer-Text	サンプルでは、ユーザー入力の解析および検証に Microsoft/Recognizers-Text ライブラリが使用されます。詳細については、概要に関するページを参照してください。

次のステップ

ユーザーに一連の質問をし、回答を検証し、入力を保存する方法について説明します。

ユーザー入力を収集するために独自のプロンプトを作成する。

ユーザーおよび会話データを保存する

前提条件

このサンプルについて

クラスの定義

会話およびユーザー状態オブジェクトの作成

状態プロパティアクセサーの追加

お使いのボットから状態にアクセスする

ボットをテストする

関連情報

次のステップ

その他のリソース

その他のリソース

ユーザーおよび会話データを保存する

前提条件

このサンプルについて

クラスの定義

会話およびユーザー状態オブジェクトの作成

状態プロパティ アクセサーの追加

お使いのボットから状態にアクセスする

ボットをテストする

関連情報

次のステップ

その他のリソース

その他のリソース

状態プロパティアクセサーの追加