この記事の内容

ストレージに直接書き込むWrite directly to storage

この記事の内容

注意

このトピックは、最新リリースの SDK (v4) を対象としています。This topic is for the latest release of the SDK (v4).前のバージョンの SDK (v3) のコンテンツは、こちらにあります。You can find content for the older version of the SDK (v3) here.

ミドルウェアまたはコンテキスト オブジェクトを使用せずに、ストレージ オブジェクトに対して直接読み取りや書き込みを行うことができます。You can read and write directly to your storage object without using middleware or context object.ボットの会話フローの外にあるソースからのデータをボットが使用する場合は、この方法が適切な可能性があります。This can be appropriate to data that your bot uses, that comes from a source outside your bot's conversation flow.たとえば、ユーザーが天気予報を尋ねるボットで、外部データベースからの読み取りによって指定日の天気予報を取得するとします。For example, let's say your bot allows the user to ask for the weather report, and your bot retrieves the weather report for a specified date, by reading it from an external database.天気データベースの内容はユーザーの情報または会話のコンテキストに依存しないため、状態マネージャーを使用する代わりに、単純にストレージから予報を直接読み取ることができます。The content of the weather database isn't dependent on user information or the conversation context, so you could just read it directly from storage instead of using the state manager.この記事のコード例では、メモリ ストレージ、Cosmos DB、Blob Storage、および Azure Blob Transcript Store を使用してストレージに対するデータの読み取りや書き込みを行う方法を示します。The code examples in this article show you how to read and write data to storage using Memory Storage, Cosmos DB, Blob Storage, and Azure Blob Transcript Store.

前提条件Prerequisites

Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。If you don't have an Azure subscription, create a free account before you begin.

メモリ ストレージMemory storage

メモリ ストレージに対するデータの読み取りや書き込みを行うボットを最初に作成します。We will first create a bot that will read and write data to Memory Storage.メモリ ストレージはテストにのみ使用され、実稼働を目的としたものではありません。Memory storage is used for testing purposes only and is not intended for production use.ボットを発行する前に、ストレージを Cosmos DB または Blob Storage に設定してください。Be sure to set storage to Cosmos DB or Blob Storage before publishing your bot.

基本のボットを作成するBuild a basic bot

このトピックの残りの部分では、エコー ボットについては取り上げません。The rest of this topic builds off of a Echo bot.C# または JS でボットを作成できます。You can create one in either C# or JS.Bot Framework Emulator を使用して、ボットへの接続、対話、およびテストが可能です。You can use the Bot Framework Emulator to connect to, converse with, and test your bot.次のサンプルでは、ユーザーからのすべてのメッセージをリストに追加します。The following sample adds every message from the user to a list.リストを含むデータ構造はストレージに保存されます。The data structure containing the list is saved to your storage.

アカウントの作成には数分かかります。The account creation takes a few minutes.ポータルに "Wait for the portal to display the Congratulations!Azure Cosmos DB アカウントが作成されました" ページが表示されるまで待機します。Your Azure Cosmos DB account was created page.

コレクションの追加Add a collection

[設定]、[新しいコレクション] の順にクリックします。Click Settings > New Collection.[コレクションの追加] 領域が右端に表示されます。表示するには、右にスクロールする必要がある場合があります。The Add Collection area is displayed on the far right, you may need to scroll right to see it.

新しいデータベース コレクションは "bot-cosmos-sql-db" です。コレクション ID は "bot-storage" になります。Your new database collection, "bot-cosmos-sql-db" with a collection id of "bot-storage."これらの値は、以降に示すコード例で使用します。We will use these values in our coding example that follows below.

データベース設定の [キー] タブで、エンドポイント URI とキーが利用可能になります。The endpoint URI and key are available within the Keys tab of your database settings.これらの値は、この記事の後半のコードの構成で必要になります。These values will be needed to configure your code further down in this article.

構成情報の追加Add configuration information

Cosmos DB ストレージを追加するための構成データは短くシンプルなものであり、ボットがより複雑になった場合でも、同じ方法を使用して構成設定を追加できます。Our configuration data to add Cosmos DB storage is short and simple, you can add additional configuration settings using these same methods as your bot gets more complex.この例では、上記の例の Cosmos DB データベースとコレクションの名前を使用します。This example uses the Cosmos DB database and collection names from the example above.

プロジェクトを作成したディレクトリにある .bot ファイルを選択します。Select the .bot file located in the directory where you created the project.

ボットでのやり取りInteract with your bot

メッセージをボットに送信します。ボットは受信したメッセージを表示します。Send a message to your bot, and the bot will list the messages it received.

データの表示View your data

ボットを実行して情報を保存したら、Azure portal の [データ エクスプローラー] タブの下にその情報を表示できます。After you have run your bot and saved your information, we can view it in the Azure portal under the Data Explorer tab.

eTag を使用してコンカレンシーを管理するManage concurrency using eTags

ボット コード例では、各 IStoreItem の eTag プロパティを * に設定します。In our bot code example we set the eTag property of each IStoreItem to *.ストア オブジェクトの eTag (エンティティ タグ) メンバーは、コンカレンシーを管理するために Cosmos DB 内で使用されます。The eTag (entity tag) member of your store object is used within Cosmos DB to manage concurrency.eTag は、自分のボットが書き込んでいる同じストレージ内のオブジェクトをボットの別のインスタンスが変更した場合の対処方法をデータベースに通知します。The eTag tells your database what to do if another instance of the bot has changed the object in the same storage that your bot is writing to.

最後の書き込みが有効 - 上書きを許可するLast write wins - allow overwrites

eTag プロパティの値にアスタリスク (*) を指定すると、最後の書き込みが有効であることを示します。An eTag property value of asterisk (*) indicates that the last writer wins.新しいデータ ストアを作成するときは、プロパティの eTag を * に設定して、以前に保存したことのないデータを書き込んでいること、または以前に保存されたすべてのプロパティを最後の書き込みで上書きすることを示します。When creating a new data store, you can set eTag of a property to * to indicate that you have not previously saved the data that you are writing, or that you want the last writer to overwrite any previously saved property.コンカレンシーがボットにとって問題にならない場合は、書き込んでいるすべてのデータについて eTag プロパティを * に設定して上書きを許可します。If concurrency is not an issue for your bot, setting the eTag property to * for any data that you are writing enables overwrites.

コンカレンシーを維持して上書きを禁止するMaintain concurrency and prevent overwrites

データを Cosmos DB に保存する際に、プロパティへの同時アクセスを禁止し、変更をボットの別のインスタンスによって上書きされないようにする場合は、* 以外の値を eTag に使います。When storing your data into Cosmos DB, use a value other than * for the eTag if you want to prevent concurrent access to a property and avoid overwriting changes from another instance of the bot.ボットが状態データを保存しようとして、eTag がストレージ内の eTag と同じ値でない場合、ボットは etag conflict key= というメッセージのエラー応答を受け取ります。The bot receives an error response with the message etag conflict key= when it attempts to save state data and the eTag is not the same value as the eTag in storage.

既定では、Cosmos DB ストアはボットがストレージ オブジェクトを書き込むたびにその項目の eTag プロパティが等しいかどうかを確認し、各書き込みの後で新しい一意の値に更新します。By default, the Cosmos DB store checks the eTag property of a storage object for equality every time a bot writes to that item, and then updates it to a new unique value after each write.書き込みの eTag プロパティがストレージの eTag と一致しない場合は、別のボットまたはスレッドがデータを変更したことを意味します。If the eTag property on write doesn't match the eTag in storage, it means another bot or thread changed the data.

たとえば、保存されたメモをボットで編集しますが、ボットの別のインスタンスが行った変更を上書きしないようにする必要があるものとします。For example, let's say you want your bot to edit a saved note, but you don't want your bot to overwrite changes that another instance of the bot has done.ボットの別のインスタンスが編集を行った場合は、ユーザーに最新の更新でバージョンを編集させます。If another instance of the bot has made edits, you want the user to edit the version with the latest updates.

変更を書き込む前にストアのメモが更新されていた場合、write の呼び出しでは例外がスローされます。If the note was updated in the store before you write your changes, the call to write will throw an exception.

コンカレンシーを維持するには、常にストレージからプロパティを読み取った後、読み取ったプロパティを変更して、eTag が維持されるようにします。To maintain concurrency, always read a property from storage, then modify the property you read, so that the eTag is maintained.ストアからユーザー データを読み取る場合、応答には eTag プロパティが含まれます。If you read user data from the store, the response will contain the eTag property.データを変更して更新後のデータをストアに書き込む場合、要求に含まれる eTag プロパティでは、前に読み取ったのと同じ値が指定されている必要があります。If you change the data and write updated data to the store, your request should include the eTag property that specifies the same value as you read earlier.ただし、eTag を * に設定してオブジェクトを書き込むと、書き込みで他の変更を上書きできます。However, writing an object with its eTag set to * will allow the write to overwrite any other changes.

BLOB コンテナーでトランスクリプトを保存できるようになったら、ボットとユーザーの会話の保持を開始できます。After a blob container is available to store transcripts you can begin to preserve your users' conversations with your bot.このような会話を後からデバッグ ツールとして使用しすると、ユーザーがボットとどのようにやり取りするかを確認できます。These conversations can later be used as a debugging tool to see how users are interacting with your bot.次のコードは、activity.text が入力メッセージ !history を受け取ったときにユーザー会話の入力を保持します。The following code preserves user conversation inputs when activity.text receives the input message !history.

保存したデータの内容を確認するために、次のコードを使用して、保存したすべてのトランスクリプトの "ConversationID" をプログラムによって検索できます。To see what data you have stored, you can use the following code to programmatically find the "ConversationIDs" for all transcripts that you have stored.ボット エミュレーターを使用してコードをテストする場合に "やり直す" を選択すると、新しいトランスクリプトが新しい "ConversationID" で開始します。When using the bot emulator to test your code, selecting "Start Over" begins a new transcript with a new "ConversationID."

ボット対話のトランスクリプトが Azure Blob Transcript Store に保存されたら、それらをプログラムによって取得し、AzureBlobTranscriptStorage メソッドである "GetTranscriptActivities" を使用してテストまたはデバッグできます。Once bot interaction transcripts have been stored into your Azure blob transcript store, you can programmatically retrieve them for testing or debugging using the AzureBlobTranscriptStorage method, "GetTranscriptActivities".次のコード スニペットでは、保存された各トランスクリプトから過去 24 時間以内に受信して保存されたユーザー入力のトランスクリプトをすべて取得します。The following code snippet retrieves all user inputs transcripts that were received and stored within the previous 24 hours from each stored transcript.