直接寫入記憶體

發行項
08/10/2024

適用於： SDK v4

您可以直接讀取和寫入記憶體物件，而不需使用中間件或內容物件。這適用於 Bot 用來保留交談的數據，或來自 Bot 交談流程外部來源的數據。在此數據記憶體模型中，數據會直接從記憶體讀取，而不是使用狀態管理員。本文中的程式代碼範例示範如何使用記憶體、Cosmos DB、Azure Blob 和 Azure Blob 文字記錄記憶體，將數據讀取和寫入記憶體。

注意

Bot Framework JavaScript、C# 和 Python SDK 將會繼續受到支援，不過，Java SDK 即將淘汰，最終長期支援將於 2023 年 11 月結束。

使用 Java SDK 建置的現有 Bot 將繼續運作。

針對新的 Bot 建置，請考慮使用 Microsoft Copilot Studio ，並閱讀選擇正確的 Copilot 解決方案。

如需詳細資訊，請參閱 Bot 建置的未來。

必要條件

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
熟悉在本機建立 Bot 。
適用於 Visual Studio 的 Bot Framework SDK v4 範本（C#）、 Node.js或 Yeoman。

注意

您可以從 Visual Studio 內安裝範本。

在功能表中，選取 [擴充功能]，然後選取 [管理擴充功能]。
在 [ 管理延伸模組 ] 對話框中，搜尋並安裝 適用於Visual Studio的 Bot Framework v4 SDK 範本。

如需將 .NET Bot 部署至 Azure 的相關信息，請參閱如何布建和發佈 Bot。

關於此範例

本文中的範例程式代碼從基本回應 Bot 的結構開始，然後藉由新增其他程式代碼來擴充 Bot 的功能（如下所示）。此擴充程式代碼會建立清單，以在收到使用者輸入時保留使用者輸入。每個回合，儲存至記憶體的使用者輸入完整清單都會回顯給使用者。然後修改包含此輸入清單的數據結構，以儲存至記憶體。隨著將其他功能新增至此範例程式代碼，會探索各種類型的記憶體。

記憶體記憶體

Bot Framework SDK 可讓您使用記憶體內部記憶體來儲存使用者輸入。由於每次重新啟動 Bot 時都會清除記憶體內部記憶體，因此最適合用於測試目的，且不適合用於生產環境。持續性記憶體類型，例如資料庫記憶體，最適合生產 Bot。

建置基本 Bot

本主題的其餘部分會建置回 Echo Bot。您可以遵循建立 Bot 的快速入門指示，在本機建置 Echo Bot 範例程式代碼。

以下列程式代碼取代 EchoBot.cs 中的程式代碼：

using System;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;
using System.Collections.Generic;
using System.Linq;
using System.Threading;

// Represents a bot saves and echoes back user input.
public class EchoBot : ActivityHandler
{
   // Create local Memory Storage.
   private static readonly MemoryStorage _myStorage = new MemoryStorage();

   // Create cancellation token (used by Async Write operation).
   public CancellationToken cancellationToken { get; private set; }

   // Class for storing a log of utterances (text of messages) as a list.
   public class UtteranceLog : IStoreItem
   {
      // A list of things that users have said to the bot
      public List<string> UtteranceList { get; } = new List<string>();

      // The number of conversational turns that have occurred
      public int TurnNumber { get; set; } = 0;

      // Create concurrency control where this is used.
      public string ETag { get; set; } = "*";
   }

   // Echo back user input.
   protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
   {
      // preserve user input.
      var utterance = turnContext.Activity.Text;

      // Make empty local log-items list.
      UtteranceLog logItems = null;

      // See if there are previous messages saved in storage.
      try
      {
         string[] utteranceList = { "UtteranceLog" };
         logItems = _myStorage.ReadAsync<UtteranceLog>(utteranceList).Result?.FirstOrDefault().Value;
      }
      catch
      {
         // Inform the user an error occurred.
         await turnContext.SendActivityAsync("Sorry, something went wrong reading your stored messages!");
      }

      // If no stored messages were found, create and store a new entry.
      if (logItems is null)
      {
         // Add the current utterance to a new object.
         logItems = new UtteranceLog();
         logItems.UtteranceList.Add(utterance);

         // Set initial turn counter to 1.
         logItems.TurnNumber++;

         // Show user new user message.
         await turnContext.SendActivityAsync($"{logItems.TurnNumber}: The list is now: {string.Join(", ", logItems.UtteranceList)}");

         // Create dictionary object to hold received user messages.
         var changes = new Dictionary<string, object>();
         {
            changes.Add("UtteranceLog", logItems);
         }
         try
         {
            // Save the user message to your Storage.
            await _myStorage.WriteAsync(changes, cancellationToken);
         }
         catch
         {
            // Inform the user an error occurred.
            await turnContext.SendActivityAsync("Sorry, something went wrong storing your message!");
         }
      }
      // Else, our storage already contained saved user messages, add new one to the list.
      else
      {
         // add new message to list of messages to display.
         logItems.UtteranceList.Add(utterance);
         // increment turn counter.
         logItems.TurnNumber++;

         // show user new list of saved messages.
         await turnContext.SendActivityAsync($"{logItems.TurnNumber}: The list is now: {string.Join(", ", logItems.UtteranceList)}");

         // Create Dictionary object to hold new list of messages.
         var changes = new Dictionary<string, object>();
         {
            changes.Add("UtteranceLog", logItems);
         };

         try
         {
            // Save new list to your Storage.
            await _myStorage.WriteAsync(changes,cancellationToken);
         }
         catch
         {
            // Inform the user an error occurred.
            await turnContext.SendActivityAsync("Sorry, something went wrong storing your message!");
         }
      }
   }
}

若要使用 .env 組態檔，您的 Bot 需要包含額外的套件。如果尚未安裝，請從 npm 取得 .NET 套件：

npm install --save dotenv

修改index.js中建立主要對話框的程序代碼。建立主要對話框的現有程式代碼行是 const myBot = new EchoBot();，它需要更新才能將記憶體對象傳遞至 EchoBot 建構函式，以便您將使用者的輸入儲存至 Bot 的內部記憶體：

首先，您必須在中新增的MemoryStoragebotbuilder參考：

const { MemoryStorage } = require('botbuilder');

然後建立記憶體記憶體物件，並將它傳遞至建 EchoBot 構函式：

const myStorage = new MemoryStorage();
const myBot = new EchoBot(myStorage);

這會將 MemoryStorage 對象傳入建 EchoBot 構函式。您稍後將變更為傳遞 Cosmos DB 或 Blob 記憶體 物件。

接下來，將 bot.js 中的程式代碼取代為下列程式代碼：

const { ActivityHandler, MemoryStorage } = require('botbuilder');
const restify = require('restify');

// Process incoming requests - adds storage for messages.
class EchoBot extends ActivityHandler {
    constructor(myStorage) {
        super();
        this.storage = myStorage;
        // See https://learn.microsoft.com/azure/bot-service/bot-builder-basics to learn more about the message and other activity types.
        this.onMessage(async turnContext => { console.log('this gets called (message)');
        await turnContext.sendActivity(`You said '${ turnContext.activity.text }'`);
        // Save updated utterance inputs.
        await logMessageText(this.storage, turnContext);
    });
        this.onConversationUpdate(async turnContext => { console.log('this gets called (conversation update)');
        await turnContext.sendActivity('Welcome, enter an item to save to your list.'); });
    }
}

// This function stores new user messages. Creates new utterance log if none exists.
async function logMessageText(storage, turnContext) {
    let utterance = turnContext.activity.text;
    // debugger;
    try {
        // Read from the storage.
        let storeItems = await storage.read(["UtteranceLogJS"])
        // Check the result.
        var UtteranceLogJS = storeItems["UtteranceLogJS"];
        if (typeof (UtteranceLogJS) != 'undefined') {
            // The log exists so we can write to it.
            storeItems["UtteranceLogJS"].turnNumber++;
            storeItems["UtteranceLogJS"].UtteranceList.push(utterance);
            // Gather info for user message.
            var storedString = storeItems.UtteranceLogJS.UtteranceList.toString();
            var numStored = storeItems.UtteranceLogJS.turnNumber;

            try {
                await storage.write(storeItems)
                await turnContext.sendActivity(`${numStored}: The list is now: ${storedString}`);
            } catch (err) {
                await turnContext.sendActivity(`Write failed of UtteranceLogJS: ${err}`);
            }
        }
        else{
            await turnContext.sendActivity(`Creating and saving new utterance log`);
            var turnNumber = 1;
            storeItems["UtteranceLogJS"] = { UtteranceList: [`${utterance}`], "eTag": "*", turnNumber }
            // Gather info for user message.
            var storedString = storeItems.UtteranceLogJS.UtteranceList.toString();
            var numStored = storeItems.UtteranceLogJS.turnNumber;

            try {
                await storage.write(storeItems)
                await turnContext.sendActivity(`${numStored}: The list is now: ${storedString}`);
            } catch (err) {
                await turnContext.sendActivity(`Write failed: ${err}`);
            }
        }
    }
    catch (err){
        await turnContext.sendActivity(`Read rejected. ${err}`);
    }
}

module.exports.EchoBot = EchoBot;

將 echo_bot.py 中的程式代碼取代為下列程式代碼：

from botbuilder.core import ActivityHandler, TurnContext, StoreItem, MemoryStorage


class UtteranceLog(StoreItem):
    """
    Class for storing a log of utterances (text of messages) as a list.
    """

    def __init__(self):
        super(UtteranceLog, self).__init__()
        self.utterance_list = []
        self.turn_number = 0
        self.e_tag = "*"


class EchoBot(ActivityHandler):
    """
    Represents a bot saves and echoes back user input.
    """

    def __init__(self):
        self.storage = MemoryStorage()

    async def on_message_activity(self, turn_context: TurnContext):
        utterance = turn_context.activity.text

        # read the state object
        store_items = await self.storage.read(["UtteranceLog"])

        if "UtteranceLog" not in store_items:
            # add the utterance to a new state object.
            utterance_log = UtteranceLog()
            utterance_log.utterance_list.append(utterance)
            utterance_log.turn_number = 1
        else:
            # add new message to list of messages existing state object.
            utterance_log: UtteranceLog = store_items["UtteranceLog"]
            utterance_log.utterance_list.append(utterance)
            utterance_log.turn_number = utterance_log.turn_number + 1

        # Show user list of utterances.
        await turn_context.send_activity(f"{utterance_log.turn_number}: "
                                         f"The list is now: {','.join(utterance_log.utterance_list)}")

        try:
            # Save the user message to your Storage.
            changes = {"UtteranceLog": utterance_log}
            await self.storage.write(changes)
        except Exception as exception:
            # Inform the user an error occurred.
            await turn_context.send_activity("Sorry, something went wrong storing your message!")

啟動 Bot

在本機執行 Bot。

啟動模擬器並連線 Bot

安裝 Bot Framework Emulator Next、啟動模擬器，然後在模擬器中連線到您的 Bot：

在 [模擬器歡迎使用] 索引標籤中選取 [建立新的 Bot 組態] 連結。
填入欄位以連線到您的 Bot，指定您啟動 Bot 時所顯示網頁上的資訊。

與您的 Bot 互動

將訊息傳送至 Bot。 Bot 會列出已接收的訊息。

與 Bot 的交談，其中顯示 Bot 會保留來自使用者的訊息清單。

本文的其餘部分將示範如何儲存至持續性記憶體，而不是 Bot 的內部記憶體。

使用 Cosmos DB

重要

Cosmos DB 記憶體類別已被取代。原本使用 CosmosDbStorage 建立的容器沒有分割區索引鍵集，而且已獲得 _/partitionKey 的預設分割區索引鍵。

使用 Cosmos DB 記憶體 建立的容器可以搭配 Cosmos DB 分割記憶體使用。如需詳細資訊，請參閱 Azure Cosmos DB 中的數據分割。

另請注意，與舊版 Cosmos DB 記憶體不同，Cosmos DB 分割記憶體不會自動在您的 Cosmos DB 帳戶內建立資料庫。您必須手動建立新的資料庫，但請略過手動建立容器，因為 CosmosDbPartitionedStorage 會為您建立容器。

現在您已使用記憶體記憶體記憶體，我們將更新程式代碼以使用 Azure Cosmos DB。 Cosmos DB 是Microsoft全域散發的多模型資料庫。 Azure Cosmos DB 可讓您彈性且獨立地跨任意數目的 Azure 地理區域調整輸送量和記憶體。它提供輸送量、延遲、可用性和一致性保證，並提供完整的服務等級協定（SLA）。

設定 Cosmos DB 資源

若要在 Bot 中使用 Cosmos DB，您必須先建立資料庫資源，才能進入程式代碼。如需 Cosmos DB 資料庫和應用程式建立的深入描述，請參閱 .NET、Node.js 或 Python 的快速入門。

建立資料庫帳戶

移至 Azure 入口網站以建立 Azure Cosmos DB 帳戶。搜尋並選取 [Azure Cosmos DB]。
在 [ Azure Cosmos DB ] 頁面中，選取 [ 新增 ] 以顯示 [ 建立 Azure Cosmos DB 帳戶 ] 頁面。
提供下列欄位的值︰
1. 訂用帳戶。選取要用於此 Azure Cosmos 帳戶的 Azure 訂用帳戶。
2. 資源群組。選取現有的資源群組或選取 [新建]，然後輸入新資源群組的名稱。
3. 帳戶名稱。輸入名稱來識別您的 Azure Cosmos 帳戶。因為 documents.azure.com 會附加到您所提供的名稱以建立 URI，請使用唯一名稱。請注意下列指導方針：
  - 名稱在整個 Azure 中必須是唯一的。
  - 名稱長度必須介於 3 到 31 個字元之間。
  - 名稱只能包含小寫字母、數位和連字元（-）字元。
4. API。選取 Core（SQL）
5. 位置。選取最接近使用者的位置，讓他們能夠快速存取數據。
選取 [檢閱 + 建立] 。
驗證後，選取 [建立]。

建立帳戶需要幾分鐘。等候入口網站顯示 [恭喜!已建立您的 Azure Cosmos DB 帳戶] 頁面。

加入資料庫

注意

請勿自行建立容器。 Bot 會在建立其內部 Cosmos DB 用戶端時為您建立它，確保其已正確設定以儲存 Bot 狀態。

流覽至新建立 Cosmos DB 帳戶內的 [數據總管] 頁面，然後從 [新增容器] 下拉式清單中選擇 [新增資料庫]。然後，面板會在視窗右側開啟，您可以在其中輸入新資料庫的詳細數據。
輸入新資料庫的標識碼，並選擇性地設定輸送量（您稍後可以變更此標識符），最後選取 [ 確定 ] 以建立資料庫。請記下此資料庫標識碼，以供稍後在設定 Bot 時使用。
既然您已建立 Cosmos DB 帳戶和資料庫，您必須複製一些值，以將新資料庫整合到 Bot 中。若要擷取這些專案，請流覽至 Cosmos DB 帳戶資料庫設定區段中的 [金鑰 ] 索引標籤。從此頁面，您將需要您的 URI（Cosmos DB 端點）和 PRIMARY KEY（授權金鑰）。

您現在應該會有具有資料庫的 Cosmos DB 帳戶，且下列值已準備好在 Bot 設定中使用。

URI
主索引鍵
資料庫識別碼

新增 Cosmos DB 組態資訊

使用您在本文上一個部分中記下的詳細數據，來設定您的端點、授權密鑰和資料庫識別碼。最後，您應該為將在資料庫內建立的容器選擇適當的名稱，以儲存 Bot 狀態。在下列範例中，所建立的 Cosmos DB 容器將會命名為 “bot-storage”。

將下列資訊新增至組態檔。

appsettings.json

"CosmosDbEndpoint": "<your-CosmosDb-URI>",
"CosmosDbAuthKey": "<your-primary-key>",
"CosmosDbDatabaseId": "<your-database-id>",
"CosmosDbContainerId": "bot-storage"

將下列資訊新增至 . env 檔案。

.env

CosmosDbEndpoint="<your-CosmosDb-URI>"
CosmosDbAuthKey="<your-primary-key>"
CosmosDbDatabaseId="<your-database-id>"
CosmosDbContainerId="bot-storage"

將下列資訊新增至組態檔。

config.py

COSMOS_DB_URI="<your-CosmosDb-URI>"
COSMOS_DB_PRIMARY_KEY="your-primary-key"
COSMOS_DB_DATABASE_ID="<your-database-id>"
COSMOS_DB_CONTAINER_ID="bot-storage"

安裝 Cosmos DB 套件

請確定您有 Cosmos DB 所需的套件。

安裝 Microsoft.Bot.Builder.Azure NuGet 套件。如需使用 NuGet 的詳細資訊，請參閱使用 NuGet 封裝管理員在 Visual Studio 中安裝和管理套件。

使用 npm 新增 botbuilder-azure 的參考。

npm install --save botbuilder-azure

如果尚未安裝，請從 npm 取得 .NET 套件，以存取您的 .env 檔案設定。

npm install --save dotenv

您可以透過 pip 在專案中新增 botbuilder-azure 的參考。

pip install botbuilder-azure

Cosmos DB 實作

注意

4.6 版引進了新的 Cosmos DB 記憶體提供者、 Cosmos DB 分割記憶體 類別，以及原始 Cosmos DB 儲存 類別已被取代。使用 Cosmos DB 記憶體 建立的容器可以搭配 Cosmos DB 分割記憶體使用。如需詳細資訊，請參閱 Azure Cosmos DB 中的數據分割。

不同於舊版 Cosmos DB 記憶體，Cosmos DB 分割記憶體不會自動在 Cosmos DB 帳戶內建立資料庫。您必須手動建立新的資料庫，但請略過手動建立容器，因為 CosmosDbPartitionedStorage 會為您建立容器。

下列範例程式代碼會使用與上述記憶體記憶體範例相同的 Bot 程式代碼來執行，但此處所列的例外狀況除外。下列代碼段顯示『myStorage』的 Cosmos DB 記憶體實作，以取代本機記憶體記憶體記憶體。

您必須先更新Startup.cs以參考 Bot 建立器 Azure 連結庫：

using Microsoft.Bot.Builder.Azure;

接下來，在 ConfigureServices Startup.cs 的方法中，建立 CosmosDbPartitionedStorage 物件。這會透過相依性插入傳遞至建 EchoBot 構函式。

// Use partitioned CosmosDB for storage, instead of in-memory storage.
services.AddSingleton<IStorage>(
    new CosmosDbPartitionedStorage(
        new CosmosDbPartitionedStorageOptions
        {
            CosmosDbEndpoint = Configuration.GetValue<string>("CosmosDbEndpoint"),
            AuthKey = Configuration.GetValue<string>("CosmosDbAuthKey"),
            DatabaseId = Configuration.GetValue<string>("CosmosDbDatabaseId"),
            ContainerId = Configuration.GetValue<string>("CosmosDbContainerId"),
            CompatibilityMode = false,
        }));

在 EchoBot.cs 將 _myStorage 變數宣告 private static readonly MemoryStorage _myStorage = new MemoryStorage(); 變更為下列專案：

// variable used to save user input to CosmosDb Storage.
private readonly IStorage _myStorage;

然後將物件傳入 IStorage 建 EchoBot 構函式：

public EchoBot(IStorage storage)
{
    if (storage is null) throw new ArgumentNullException();
    _myStorage = storage;
}

首先，將程式代碼新增至 您的index.js 檔案，讓您能夠存取 您先前輸入的 .env 檔案中的值：

// initialized to access values in .env file.
const ENV_FILE = path.join(__dirname, '.env');
require('dotenv').config({ path: ENV_FILE });

接下來，您必須變更 index.js ，以使用 Cosmos DB 分割記憶體，而不是 Bot Framework 內部記憶體。本節中的所有程式代碼變更都是在 index.js 進行。

首先，在 index.js 中新增 botbuilder-azure 的參考。這可讓您存取類別 CosmosDbPartitionedStorage 。

const { CosmosDbPartitionedStorage } = require('botbuilder-azure');

接下來，建立新的 CosmosDbPartitionedStorage 物件。

const myStorage = new CosmosDbPartitionedStorage({
    cosmosDbEndpoint: process.env.CosmosDbEndpoint,
    authKey: process.env.CosmosDbAuthKey,
    databaseId: process.env.CosmosDbDatabaseId,
    containerId: process.env.CosmosDbContainerId,
    compatibilityMode: false
});

您現在可以將先前新增的 myStorage const 宣告批注化或移除，因為您不再將使用者輸入儲存至 Bot Framework 內部記憶體，而是改為儲存至 Cosmos DB：

//const myStorage = new MemoryStorage();
const myBot = new EchoBot(myStorage);

下列範例程式代碼會使用與上述記憶體記憶體範例相同的 Bot 程式代碼來執行，但此處所列的例外狀況除外。

建立 CosmosDbPartitionedStorage CosmosDBStorage 物件需要和 CosmosDbPartitionedConfig 來源 botbuilder-azure 。

echo_bot.py

from botbuilder.azure import CosmosDbPartitionedStorage, CosmosDbPartitionedConfig

若要存取 config.py 中的設定，您將匯入DefaultConfig，如下所示：

from config import DefaultConfig
CONFIG = DefaultConfig()

將中的 __init__ 記憶體記憶體記憶體批注化，並將取代為 Cosmos DB 的參考。使用 URI（端點）、主鍵（授權金鑰）、資料庫識別碼，以及上面所使用的容器識別碼。

接下來，從 config.py __init__ 移除或批註中的記憶體記憶體記憶體程序代碼，並新增 Cosmos DB 資訊的參考。

下列代碼段顯示『Storage』的 Cosmos DB 實作，以取代本機記憶體記憶體。

echo_bot.py

def __init__(self):
    cosmos_config = CosmosDbPartitionedConfig(
        cosmos_db_endpoint=CONFIG.COSMOS_DB_URI,
        auth_key=CONFIG.COSMOS_DB_PRIMARY_KEY,
        database_id=CONFIG.COSMOS_DB_DATABASE_ID,
        container_id=CONFIG.COSMOS_DB_CONTAINER_ID,
        compatibility_mode = False
    )
    self.storage = CosmosDbPartitionedStorage(cosmos_config)

啟動 Cosmos DB Bot

在本機執行 Bot。

使用 Bot Framework 模擬器測試 Cosmos DB Bot

現在啟動 Bot Framework 模擬器，並連線到您的 Bot：

在 [模擬器歡迎使用] 索引標籤中選取 [建立新的 Bot 組態] 連結。
填入欄位以連線到您的 Bot，指定您啟動 Bot 時所顯示網頁上的資訊。

與您的 Cosmos DB Bot 互動

將訊息傳送至 Bot，Bot 會列出其收到的訊息。

與 Bot 的交談，其中顯示 Bot 會保留來自使用者的訊息清單。

檢視 Cosmos DB 數據

執行 Bot 並儲存資訊之後，您可以在 [資料總管] 索引卷標下檢視儲存在 [Azure 入口網站中的數據。

Azure 入口網站中 [數據總管] 的螢幕快照。

使用 Blob 記憶體

Azure Blob 儲存體是 Microsoft 針對雲端推出的物件儲存體解決方案。 Blob 儲存體已針對儲存大量非結構化資料 (如文字或二進位資料) 進行最佳化。本節說明如何建立 Azure Blob 記憶體帳戶和容器，以及如何從 Bot 參考 Blob 記憶體容器。

如需 Blob 記憶體的詳細資訊，請參閱什麼是 Azure Blob 記憶體？

建立 Blob 記憶體帳戶

若要在 Bot 中使用 Blob 記憶體，您需要先設定一些專案，才能進入程式代碼。

在 Azure 入口網站中，選取 [所有服務]。
在 [所有服務] 頁面的 [精選] 區段中，選取 [儲存體帳戶]。
在 [ 記憶體帳戶] 頁面中，選取 [ 新增]。
在 [訂用帳戶] 欄位中，選取要在其中建立儲存體帳戶的訂用帳戶。
在 [ 資源群組] 字段中，選取現有的資源群組 或選取 [新建]，然後輸入新資源群組的名稱。
在 [儲存體帳戶名稱] 欄位中，輸入帳戶的名稱。請注意下列指導方針：
- 名稱在整個 Azure 中必須是唯一的。
- 名稱長度必須介於 3 到 24 個字元之間。
- 名稱只能包含數字和小寫字母。
在 [位置] 欄位中，選取儲存體帳戶的位置，或使用預設位置。
針對其餘的設定，請設定下列各項：
- 效能：標準。深入瞭解效能。
- 帳戶種類：BlobStorage。深入瞭解記憶體帳戶。
- 複寫：保留預設設定。深入瞭解備援。
在 [建立記憶體帳戶] 頁面的 [專案詳細數據] 區段中，選取訂用帳戶和資源群組所需的值。
在 [建立記憶體帳戶] 頁面的 [實例詳細數據] 區段中，輸入記憶體帳戶名稱，然後選取 [位置]、[帳戶種類] 和 [複寫] 的值。
選取 [檢閱 + 建立] 以檢閱儲存體帳戶設定。
驗證後，選取 [建立]。

建立 Blob 記憶體容器

建立 Blob 記憶體帳戶之後，請開啟它，然後：

選擇[儲存體總管[預覽] 。
然後以滑鼠右鍵按兩下 [BLOB 容器]
從下拉式清單中選取 [建立 Blob 容器 ]。
在 [新增容器] 表單中輸入名稱。您將使用此名稱做為「Blob 容器名稱」的值，以提供 Blob 記憶體帳戶的存取權。請注意下列指導方針：
- 此名稱只能包含小寫字母、數位和連字元。
- 此名稱的開頭必須是字母或數位。
- 每個連字元前面必須加上，後面接著有效的非連字元字元。
- 名稱長度必須為 3 到 63 個字元。

新增 Blob 記憶體組態資訊

尋找您需要為 Bot 設定 Blob 記憶體所需的 Blob 記憶體密鑰，如下所示：

在 Azure 入口網站中，開啟您的 Blob 記憶體帳戶，然後在 [設定] 區段中選取 [存取密鑰]。
若要將 Bot 設定為存取 Blob 記憶體帳戶，請使用連接字串作為 blob 連接字串的值。

將下列資訊新增至組態檔。

appsettings.json

"BlobConnectionString": "<your-blob-connection-string>",
"BlobContainerName": "<your-blob-container-name>",

將下列資訊新增至 . env 檔案。

.env

BlobConnectionString="<your-blob-connection-string>"
BlobContainerName="<your-blob-container-name>"

將下列資訊新增至組態檔。使用建立 Blob 記憶體容器時所使用的相同容器名稱和連接字串。

config.py

BLOB_CONNECTION_STRING="<your-blob-connection-string>"
BLOB_CONTAINER_NAME="<your-blob-container-name>"

安裝 Blob 記憶體套件

如果先前未安裝，請安裝下列套件。

安裝 Microsoft.Bot.Builder.Azure.Blobs NuGet 套件。如需使用 NuGet 的詳細資訊，請參閱使用 NuGet 封裝管理員在 Visual Studio 中安裝和管理套件。

透過 npm 在專案中新增的 botbuilder-azure-blobs 參考。

注意

此 npm 套件依賴在開發計算機上現有的 Python 安裝。如果您先前尚未安裝 Python，您可以在 Python.org 找到計算機的安裝資源

npm install --save botbuilder-azure-blobs

如果尚未安裝，請從 npm 取得 .NET 套件，以存取您的 .env 檔案設定。

npm install --save dotenv

您可以透過 pip 在專案中新增 botbuilder-azure 的參考。

pip install botbuilder-azure

Blob 記憶體實作

Blob 記憶體 是用來儲存 Bot 狀態。

注意

自 4.10 版起， Microsoft.Bot.Builder.Azure.AzureBlobStorage 已被取代。在位置使用新的 Microsoft.Bot.Builder.Azure.Blobs.BlobsStorage 。

下列範例程式代碼會使用與上述記憶體記憶體範例相同的 Bot 程式代碼來執行，但此處所列的例外狀況除外。

下列代碼段顯示『myStorage』的 Blob 記憶體實作，以取代本機記憶體記憶體記憶體。

您必須先更新Startup.cs以參考 Bot 建立器 Azure Blob 連結庫：

Startup.cs

using Microsoft.Bot.Builder.Azure.Blobs;

接下來，在 ConfigureServices Startup.cs 的方法中，建立 BlobsStorage 對象，傳入來自appsettings.json的值。這會透過相依性插入傳遞至建 EchoBot 構函式。

//Use Azure Blob storage, instead of in-memory storage.
services.AddSingleton<IStorage>(
    new BlobsStorage(
        Configuration.GetValue<string>("BlobConnectionString"),
        Configuration.GetValue<string>("BlobContainerName")
        ));

現在，您必須先更新EchoBot.cs以參考 Bot 建立器 Azure Blob 連結庫：

EchoBot.cs

using Microsoft.Bot.Builder.Azure.Blobs;

接下來，請移除或批注化建立 MemoryStorage 變數 'private static readonly MemoryStorage _myStorage = new MemoryStorage（）：' 的程式代碼行，並建立將用來將使用者輸入儲存至 Blob 記憶體的新變數。

EchoBot.cs

// variable used to save user input to CosmosDb Storage.
private readonly IStorage _myStorage;

然後將物件傳入 IStorage 建 EchoBot 構函式：

public EchoBot(IStorage storage)
{
    if (storage is null) throw new ArgumentNullException();
    _myStorage = storage;
}

一旦記憶體設定為指向 Blob 記憶體帳戶，Bot 程式代碼現在將會儲存及擷取 Blob 記憶體中的數據。

本節中的所有程式代碼變更都是在 index.js 進行。

首先，新增程式代碼，讓您能夠從 先前輸入的 .env 檔案存取值：

// initialized to access values in .env file.
const ENV_FILE = path.join(__dirname, '.env');
require('dotenv').config({ path: ENV_FILE });

接下來，您必須進行變更，使用 Blob 記憶體，而不是 Bot Framework 內部記憶體。

接下來，新增對的 botbuilder-azure-blobs參考。這可讓您存取 Blob 記憶體 API：

const { BlobsStorage } = require("botbuilder-azure-blobs");

若要修改程式代碼以使用 BlobsStorage 類別，請修改宣告 myStorage ，如下所示：

const myStorage = new BlobsStorage(
    process.env.BlobConnectionString,
    process.env.BlobContainerName
);

一旦記憶體設定為指向 Blob 記憶體帳戶，Bot 程式代碼現在將會儲存及擷取 Blob 記憶體中的數據。

下列範例程式代碼會使用與上述記憶體記憶體範例相同的 Bot 程式代碼來執行，但此處所列的例外狀況除外。

這會需要 BlobStorage 與 BlobStorageSettings 來自 botbuilder-azure。

echo_bot.py

from botbuilder.azure import BlobStorage, BlobStorageSettings

若要存取 config.py 中的設定，您將匯入DefaultConfig，如下所示：

from config import DefaultConfig
CONFIG = DefaultConfig()

接下來，從 config.py __init__ 移除或批註中的記憶體記憶體程式代碼，並新增 Blob 記憶體資訊的參考。

下列代碼段顯示取代本機記憶體記憶體的 Blob 記憶體實作。

echo_bot.py

def __init__(self):
    blob_settings = BlobStorageSettings(
        connection_string=CONFIG.BLOB_CONNECTION_STRING,
        container_name=CONFIG.BLOB_CONTAINER_NAME
    )
    self.storage = BlobStorage(blob_settings)

一旦記憶體設定為指向 Blob 記憶體帳戶，Bot 程式代碼現在將會儲存及擷取 Blob 記憶體中的數據。

啟動 Blob 記憶體 Bot

在本機執行 Bot。

啟動模擬器並連線 Blob 記憶體 Bot

接下來，啟動模擬器，然後在模擬器中聯機到您的 Bot：

選取模擬器 [歡迎使用] 索引標籤中的 [ 建立新的 Bot 組態 ] 連結。
填入欄位以連線到您的 Bot，指定您啟動 Bot 時所顯示網頁上的資訊。

與您的 Blob 記憶體 Bot 互動

將訊息傳送至 Bot，Bot 會列出其收到的訊息。

與 Bot 的交談，其中顯示 Bot 會保留來自使用者的訊息清單。

檢視 Blob 記憶體數據

執行 Bot 並儲存資訊之後，我們可以在 Azure 入口網站的 [儲存體總管] 索引標籤下檢視它。

Blob 文字記錄記憶體

Azure Blob 文字記錄記憶體提供特殊的記憶體選項，可讓您輕鬆地以錄製文字記錄的形式儲存和擷取使用者交談。 Azure Blob 文字記錄記憶體很適合用來自動擷取使用者輸入，以在對 Bot 效能進行偵錯時進行檢查。

注意

Python 目前 不支援 Azure Blob 文字記錄記憶體。雖然 JavaScript 支援 Blob 文字記錄記憶體，但下列指示僅適用於 C#。

設定 Blob 文字記錄記憶體容器

Azure Blob 文字記錄記憶體可以使用遵循上述<建立 Blob 儲存器帳戶>和<新增組態資訊>一節中詳述的步驟所建立的相同 Blob 記憶體帳戶。我們現在新增容器來保存我們的文字記錄

建立 Blob 容器作為文字記錄存放區的螢幕快照。

開啟您的 Azure Blob 記憶體帳戶。
選取 [儲存體總管]。
以滑鼠右鍵按兩下 [BLOB 容器 ]，然後選取 [ 建立 Blob 容器]。
輸入文字記錄容器的名稱，然後選取 [ 確定]。（我們輸入 mybottranscripts）

Blob 文字記錄記憶體實作

下列程式代碼會將文字記錄記憶體指標 _myTranscripts 連線到新的 Azure Blob 文字記錄記憶體帳戶。若要使用新的容器名稱 <your-blob-transcript-container-name> 建立此連結，它會在 Blob 記憶體中建立新的容器來保存您的文字記錄檔。

Blob 文字記錄記憶體 是設計來儲存 Bot 文字記錄。

注意

自 4.10 版起， Microsoft.Bot.Builder.Azure.AzureBlobTranscriptStore 已被取代。在位置使用新的 Microsoft.Bot.Builder.Azure.Blobs.BlobsTranscriptStore 。

echoBot.cs

using Microsoft.Bot.Builder.Azure.Blobs;

public class EchoBot : ActivityHandler
{
   ...

   private readonly BlobsTranscriptStore _myTranscripts = new BlobsTranscriptStore("<your-azure-storage-connection-string>", "<your-blob-transcript-container-name>");

   ...
}

將使用者交談儲存在 Azure Blob 文字記錄中

在 Blob 容器可供儲存文字記錄之後，您可以開始保留使用者與 Bot 的交談。這些交談稍後可用來作為偵錯工具，以查看使用者如何與您的 Bot 互動。每個模擬器 重新啟動交談 都會起始新文字記錄交談清單的建立。下列程式代碼會在預存的文字記錄檔中保留使用者交談輸入。

目前的文字記錄會使用 LogActivityAsync儲存。
已儲存的文字記錄是使用 ListTranscriptsAsync來擷取。在此範例程式代碼中，每個預存文字記錄的標識符都會儲存到名為「storedTranscripts」的清單。此清單稍後會用來管理我們保留的預存 Blob 文字記錄數目。

echoBot.cs


protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    await _myTranscripts.LogActivityAsync(turnContext.Activity);

    List<string> storedTranscripts = new List<string>();
    PagedResult<Microsoft.Bot.Builder.TranscriptInfo> pagedResult = null;
    var pageSize = 0;
    do
    {
       pagedResult = await _myTranscripts.ListTranscriptsAsync("emulator", pagedResult?.ContinuationToken);
       pageSize = pagedResult.Items.Count();

       // transcript item contains ChannelId, Created, Id.
       // save the channelIds found by "ListTranscriptsAsync" to a local list.
       foreach (var item in pagedResult.Items)
       {
          storedTranscripts.Add(item.Id);
       }
    } while (pagedResult.ContinuationToken != null);

    ...
}

管理儲存的 Blob 文字記錄

雖然預存的文字記錄可作為偵錯工具，但隨著時間推移，儲存的文字記錄數目可能會比您關心的要保留還要大。下面包含的其他程式代碼會使用 DeleteTranscriptAsync 從 Blob 文字記錄存放區移除最後三個擷取的文字記錄專案。

echoBot.cs


protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    await _myTranscripts.LogActivityAsync(turnContext.Activity);

    List<string> storedTranscripts = new List<string>();
    PagedResult<Microsoft.Bot.Builder.TranscriptInfo> pagedResult = null;
    var pageSize = 0;
    do
    {
       pagedResult = await _myTranscripts.ListTranscriptsAsync("emulator", pagedResult?.ContinuationToken);
       pageSize = pagedResult.Items.Count();

       // transcript item contains ChannelId, Created, Id.
       // save the channelIds found by "ListTranscriptsAsync" to a local list.
       foreach (var item in pagedResult.Items)
       {
          storedTranscripts.Add(item.Id);
       }
    } while (pagedResult.ContinuationToken != null);

    // Manage the size of your transcript storage.
    for (int i = 0; i < pageSize; i++)
    {
       // Remove older stored transcripts, save just the last three.
       if (i < pageSize - 3)
       {
          string thisTranscriptId = storedTranscripts[i];
          try
          {
             await _myTranscripts.DeleteTranscriptAsync("emulator", thisTranscriptId);
           }
           catch (System.Exception ex)
           {
              await turnContext.SendActivityAsync("Debug Out: DeleteTranscriptAsync had a problem!");
              await turnContext.SendActivityAsync("exception: " + ex.Message);
           }
       }
    }
    ...
}

如需類別的詳細資訊，請參閱 Azure Blob 文字記錄記憶體。

其他資訊

使用 eTag 管理並行

在我們的 Bot 程式代碼範例中，我們會將每個 IStoreItem 的屬性設定eTag為 *。 eTag 存放區物件的（實體卷標）成員會在 Cosmos DB 內用來管理並行。 eTag會告知您的資料庫，如果 Bot 的另一個實例已變更 Bot 所寫入之相同記憶體中的物件，該怎麼做。

上次寫入獲勝 - 允許覆寫

星號的屬性值（*）表示最後一個eTag寫入器獲勝。建立新的資料存放區時，您可以設定 eTag 屬性來 * 指出您先前尚未儲存要寫入的數據，或您想要最後一個寫入器覆寫任何先前儲存的屬性。如果 Bot 的並行存取不是問題，請針對您正在撰寫的任何資料將屬性*設定eTag為，以啟用覆寫。

維護並行並防止覆寫

將數據儲存至 Cosmos DB 時，如果您想要防止對屬性的並行存取，並避免覆寫來自另一個 Bot 實例的變更，請使用以外的值*eTag。 Bot 會在嘗試儲存狀態數據，且 eTag 與記憶體中的值不同eTag時，收到訊息etag conflict key=的錯誤回應。

根據預設，Cosmos DB 存放區會在每次 Bot 寫入該專案時檢查 eTag 記憶體物件的屬性是否相等，然後在每次寫入之後，將其更新為新的唯一值。 eTag如果寫入上的屬性不符合eTag記憶體中的，表示另一個 Bot 或線程已變更數據。

例如，假設您想要讓 Bot 編輯已儲存的附註，但不希望 Bot 覆寫另一個 Bot 實例所做的變更。如果 Bot 的另一個實體已進行編輯，您希望使用者以最新的更新來編輯版本。

首先，建立實作的 IStoreItem類別。

EchoBot.cs

public class Note : IStoreItem
{
    public string Name { get; set; }
    public string Contents { get; set; }
    public string ETag { get; set; }
}

接下來，建立記憶體物件來建立初始附注，並將物件新增至您的存放區。

EchoBot.cs

// create a note for the first time, with a non-null, non-* ETag.
var note = new Note { Name = "Shopping List", Contents = "eggs", ETag = "x" };

var changes = Dictionary<string, object>();
{
    changes.Add("Note", note);
};
await NoteStore.WriteAsync(changes, cancellationToken);

然後，稍後存取並更新附註，並 eTag 保留您從市集讀取的附註。

EchoBot.cs

var note = NoteStore.ReadAsync<Note>("Note").Result?.FirstOrDefault().Value;

if (note != null)
{
    note.Contents += ", bread";
    var changes = new Dictionary<string, object>();
    {
         changes.Add("Note1", note);
    };
    await NoteStore.WriteAsync(changes, cancellationToken);
}

如果您在撰寫變更之前已在存放區中更新附註，呼叫 Write 將會擲回例外狀況。

將協助程式函式新增至 Bot 結尾，以將範例附註寫入資料存放區。第一個建立 myNoteData 物件。

bot.js

// Helper function for writing a sample note to a data store
async function createSampleNote(storage, context) {
    var myNoteData = {
        name: "Shopping List",
        contents: "eggs",
        // If any Note file is already stored, the eTag field
        // must be set to "*" in order to allow writing without first reading the stored eTag
        // otherwise you'll likely get an exception indicating an eTag conflict.
        eTag: "*"
    }
}

在協助程式函式中createSampleNote，初始化 changes 物件，並將筆記新增至其中，然後將它寫入記憶體。

bot.js

// Write the note data to the "Note" key
var changes = {};
changes["Note"] = myNoteData;
// Creates a file named Note, if it doesn't already exist.
// specifying eTag= "*" will overwrite any existing contents.
// The act of writing to the file automatically updates the eTag property
// The first time you write to Note, the eTag is changed from *, and file contents will become:
//    {"name":"Shopping List","contents":"eggs","eTag":"1"}
try {
     await storage.write(changes);
     var list = changes["Note"].contents;
     await context.sendActivity(`Successful created a note: ${list}`);
} catch (err) {
     await context.sendActivity(`Could not create note: ${err}`);
}

藉由新增下列呼叫，即可從 Bot 邏輯中存取協助程式函式：

bot.js

// Save a note with etag.
await createSampleNote(storage, turnContext);

建立之後，若要稍後擷取並更新附注，我們會建立另一個協助程式函式，可在使用者輸入「更新附注」時存取。

bot.js

async function updateSampleNote(storage, context) {
    try {
        // Read in a note
        var note = await storage.read(["Note"]);
        console.log(`note.eTag=${note["Note"].eTag}\n note=${JSON.stringify(note)}`);
        // update the note that we just read
        note["Note"].contents += ", bread";
        console.log(`Updated note=${JSON.stringify(note)}`);

        try {
             await storage.write(note); // Write the changes back to storage
             var list = note["Note"].contents;
             await context.sendActivity(`Successfully updated note: ${list}`);
        } catch (err) {
             console.log(`Write failed: ${err}`);
        }
    }
    catch (err) {
        await context.sendActivity(`Unable to read the Note: ${err}`);
    }
}

藉由新增下列呼叫，即可從 Bot 邏輯中存取此協助程式函式：

bot.js

// Update a note with etag.
await updateSampleNote(storage, turnContext);

如果在嘗試回寫變更之前，另一位使用者在存放區中更新了附註，則 eTag 值將不再相符，而的呼叫 write 將會擲回例外狀況。

首先，建立實作的 StoreItem類別。

echo_bot.py

class Note(StoreItem):
    def __init__(self, name: str, contents: str, e_tag="*"):
        super(Note, self).__init__()
        self.name = name
        self.contents = contents
        self.e_tag = e_tag

接下來，建立記憶體物件來建立初始附注，並將物件新增至您的存放區。

echo_bot.py

# create a note for the first time, with a non-null, non-* ETag.
changes = {"Note": Note(name="Shopping List", contents="eggs", e_tag="x")}

await self.storage.write(changes)

然後，稍後存取並更新附註，並 eTag 保留您從市集讀取的附註。

echo_bot.py

store_items = await self.storage.read(["Note"])
    note = store_items["Note"]
    note.contents = note.contents + ", bread"

    changes = {"Note": note}
    await self.storage.write(changes)

如果您在撰寫變更之前已在存放區中更新附註，呼叫 write 將會擲回例外狀況。

若要維護並行，請一律從記憶體讀取屬性，然後修改您讀取的屬性，以便 eTag 維護。如果您從存放區讀取用戶數據，回應會包含 eTag 屬性。如果您變更數據並將更新的數據寫入至存放區，您的要求應該包含 eTag 屬性，指定與先前讀取相同的值。不過，將物件設定 eTag 為 * 來寫入，將允許寫入覆寫任何其他變更。

下一步

既然您已瞭解如何直接從記憶體讀取和寫入，讓我們看看如何使用狀態管理員為您執行此作業。

使用交談和使用者屬性儲存狀態

共用方式為

直接寫入記憶體

必要條件

關於此範例

記憶體記憶體

建置基本 Bot

啟動 Bot

啟動模擬器並連線 Bot

與您的 Bot 互動

使用 Cosmos DB

設定 Cosmos DB 資源

建立資料庫帳戶

加入資料庫

新增 Cosmos DB 組態資訊

安裝 Cosmos DB 套件

Cosmos DB 實作

啟動 Cosmos DB Bot

使用 Bot Framework 模擬器測試 Cosmos DB Bot

與您的 Cosmos DB Bot 互動

檢視 Cosmos DB 數據

使用 Blob 記憶體

建立 Blob 記憶體帳戶

建立 Blob 記憶體容器

新增 Blob 記憶體組態資訊

安裝 Blob 記憶體套件

Blob 記憶體實作

啟動 Blob 記憶體 Bot

啟動模擬器並連線 Blob 記憶體 Bot

與您的 Blob 記憶體 Bot 互動

檢視 Blob 記憶體數據

Blob 文字記錄記憶體

設定 Blob 文字記錄記憶體容器

Blob 文字記錄記憶體實作

將使用者交談儲存在 Azure Blob 文字記錄中

管理儲存的 Blob 文字記錄

其他資訊

使用 eTag 管理並行

上次寫入獲勝 - 允許覆寫

維護並行並防止覆寫

下一步

其他資源