Непосредственная запись в хранилище

Статья
10/27/2023

ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ SDK версии 4

Вы можете выполнять операции записи и чтения непосредственно в объекте хранилища, не используя ПО промежуточного слоя или объект контекста. Это может требоваться для данных, которые бот использует для сохранения беседы, или данных, которые поступают из источника за пределами потока общения бота. В рамках этой модели хранилища данные считываются непосредственно из хранилища без использования диспетчера состояний. В примерах кода в этой статье показано, как считывать и записывать данные в хранилище с помощью памяти, Cosmos DB, BLOB-объектов Azure и хранилища расшифровки BLOB-объектов Azure.

Примечание.

Пакеты SDK для JavaScript, C# и Python для Bot Framework по-прежнему будут поддерживаться, однако пакет SDK java отменяется с окончательной долгосрочной поддержкой, заканчивающейся в ноябре 2023 года.

Существующие боты, созданные с помощью пакета SDK для Java, будут продолжать функционировать.

Для создания нового бота рекомендуется использовать Power Virtual Agent и ознакомиться с выбором подходящего решения чат-бота.

Дополнительные сведения см. в статье "Будущее создания бота".

Необходимые компоненты

Если у вас нет подписки Azure, создайте бесплатную учетную запись, прежде чем приступить к работе.
Знакомство с созданием бота локально.
Шаблоны пакета SDK Bot Framework версии 4 для Visual Studio (C#), Node.js или Yeoman.

Примечание.

Вы можете установить шаблоны из Visual Studio.

В меню выберите "Расширения" и "Управление расширениями".
В диалоговом окне "Управление расширениями" найдите и установите шаблоны SDK Bot Framework версии 4 для Visual Studio.

Сведения о развертывании ботов .NET в Azure см. в статье о подготовке и публикации бота.

Об этом примере

Пример кода в этой статье определяет структуру базового эхо-бота. Добавив дополнительный код (см. ниже), вы сможете расширить функции этого бота. Этот расширенный код создает список для сохранения входных данных пользователей по мере их получения. Каждый поворот, полный список входных данных пользователя, сохраненный в памяти, повторяется пользователю. Структура данных, содержащая этот список входных данных, затем изменяется для сохранения в хранилище. В этот пример кода добавляются различные типы хранилища.

Хранилище в памяти

Пакет SDK Bot Framework позволяет хранить вводимые пользователем данные с помощью размещенного в памяти хранилища. Так как хранилище в памяти очищается при каждом перезапуске бота, оно лучше всего подходит для тестирования и не предназначено для использования в рабочей среде. Постоянные хранилища, такие как хранилище базы данных, лучше всего подходят для ботов в рабочей среде.

Создание базового бота

Остальная часть этой статьи описывает использование эхо-бота. Пример кода бота Echo можно создать локально, следуя инструкциям краткого руководства по созданию бота.

Замените код в 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 , боту требуется дополнительный пакет. Если он еще не установлен, получите пакет .NET из npm:

npm install --save dotenv

Измените код в index.js , создающего основное диалоговое окно. Существующая строка кода для создания основного диалогового окна const myBot = new EchoBot();— это необходимо обновить, чтобы включить передачу объекта EchoBot хранилища конструктору, чтобы вы могли хранить входные данные пользователя во внутреннюю память бота:

Сначала необходимо добавить ссылку MemoryStorage на botbuilder:

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 Framework Далее, запустите эмулятор и подключитесь к боту в эмуляторе:

Выберите ссылку "Создать бота" на вкладке приветствия эмулятора.
Заполните поля для подключения к боту, используя сведения на веб-странице, отображаемой при запуске бота.

Взаимодействие с ботом

Отправьте сообщение боту. Он отобразит список полученных сообщений.

Беседа с ботом, показывая боту список сообщений от пользователя.

Оставшаяся часть этой статьи демонстрирует сохранение в постоянном хранилище вместо внутренней памяти бота.

Использование Cosmos DB

Внимание

Класс хранилища Cosmos DB является устаревшим. Контейнеры, изначально созданные с помощью CosmosDb служба хранилища не имели набора ключей секций и были предоставлены ключ секции по умолчанию _/partitionKey.

Контейнеры, созданные с помощью хранилища Cosmos DB, можно использовать с секционированным хранилищем Cosmos DB. См. сведения о секционировании в Azure Cosmos DB.

Кроме того, обратите внимание, что в отличие от устаревшего хранилища Cosmos DB секционированные хранилища Cosmos DB не создают базу данных в учетной записи Cosmos DB. Необходимо вручную создать новую базу данных, но пропустить создание контейнера вручную, так как CosmosDbPartitioned служба хранилища создаст для вас контейнер.

Начав использовать хранилище в памяти, мы изменим код, чтобы начать работу с Azure Cosmos DB. Cosmos DB — это глобально распределенная многомодельная база данных Майкрософт. Azure Cosmos DB позволяет гибко и независимо масштабировать пропускную способность и ресурсы хранилища в любом количестве регионов Azure. Она гарантирует пропускную способность, задержку, доступность и согласованность в соответствии с комплексными Соглашениями об уровне обслуживания (SLA).

Настройка ресурса Cosmos DB

Чтобы использовать в боте Cosmos DB, необходимо создать ресурс базы данных, прежде чем приступать к написанию кода. Подробное описание создания базы данных и приложений Cosmos DB см. в кратком руководстве по .NET, Node.js или Python.

Создание учетной записи базы данных

Создайте учетную запись для базы данных Azure Cosmos DB, перейдя на портал Azure. Найдите и выберите Azure Cosmos DB.
На странице Azure Cosmos DB выберите "Создать", чтобы открыть страницу "Создать учетную запись Azure Cosmos DB".
Введите значения для следующих полей:
1. Подписка. Выберите подписку Azure, которую нужно использовать для этой учетной записи Azure Cosmos.
2. Группа ресурсов. Выберите существующую группу ресурсов или нажмите кнопку "Создать" и введите имя новой группы ресурсов.
3. Имя учетной записи Введите имя для идентификации учетной записи Azure Cosmos. Так как элемент documents.azure.com добавляется к указанному вами имени для создания URI, используйте уникальное имя. Обратите внимание на следующие рекомендации.
  - Это имя должно быть уникальным в пределах Azure.
  - Имя должно иметь длину от 3 до 31 символов.
  - Имя может содержать только строчные буквы, цифры и символ дефиса (-).
4. API. Выбор Core(SQL)
5. Location. Выберите расположение, ближайшее к пользователям, чтобы предоставить им самый быстрый доступ к данным.
Выберите Review + Create (Просмотреть и создать).
После проверки нажмите кнопку "Создать".

Создание учетной записи занимает несколько минут. Подождите, пока на портале откроется страница с сообщением Поздравляем! Учетная запись Azure Cosmos DB создана.

Добавление базы данных

Примечание.

Не создавайте контейнер самостоятельно. Бот создаст его для вас при создании внутреннего клиента Cosmos DB, гарантируя правильность настройки состояния бота.

Перейдите на страницу "Данные Обозреватель" в созданной учетной записи Cosmos DB, а затем выберите новую базу данных в раскрывающемся списке "Создать контейнер". Затем панель откроется справа от окна, где можно ввести сведения о новой базе данных.
Введите идентификатор новой базы данных и, при необходимости, задайте пропускную способность (можно изменить ее позже) и нажмите кнопку "ОК ", чтобы создать базу данных. Запишите идентификатор базы данных, чтобы использовать его позже для настройки бота.
Теперь, когда вы создали учетную запись Cosmos DB и базу данных, необходимо скопировать некоторые значения для интеграции новой базы данных в бот. Чтобы получить их, перейдите на вкладку Ключи в разделе параметров базы данных, которую вы создали в учетной записи Cosmos DB. На этой странице вам потребуется URI (конечная точка Cosmos DB) и первичный ключ (ключ авторизации).

Теперь у вас должна быть учетная запись Cosmos DB с базой данных и следующие значения, готовые к использованию в параметрах бота.

URI-адрес
Первичный ключ
Идентификатор базы данных

Добавление сведений о конфигурации Cosmos DB

Используйте сведения, которые вы записали в предыдущей части этой статьи, чтобы задать конечную точку, ключ авторизации и идентификатор базы данных. Наконец, выберите подходящее имя для контейнера, который будет создан в базе данных для хранения состояния бота. В приведенном ниже примере созданный контейнер 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.

Установите пакет NuGet Microsoft.Bot.Builder.Azure. Дополнительные сведения об использовании NuGet см. в статье "Установка пакетов и управление ими в Visual Studio с помощью диспетчер пакетов NuGet".

Добавьте ссылку на botbuilder-azure с помощью npm.

npm install --save botbuilder-azure

Если он еще не установлен, получите пакет .NET из npm, чтобы получить доступ к параметрам env-файла .

npm install --save dotenv

Вы можете добавить ссылку на botbuilder-azure в проекте с помощью pip.

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. Необходимо вручную создать новую базу данных, но пропустить создание контейнера вручную, так как CosmosDbPartitioned служба хранилища создаст для вас контейнер.

В следующем примере кода используется тот же код бота, что и пример хранилища памяти , приведенный выше, с исключениями, перечисленными здесь. В фрагментах кода ниже показана реализация хранилища Cosmos DB для my служба хранилища, которая заменяет локальное хранилище памяти.

Сначала необходимо обновить Startup.cs для ссылки на библиотеку 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 измените объявление private static readonly MemoryStorage _myStorage = new MemoryStorage(); переменной _myStorage следующим образом:

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

Затем передайте объект конструктору IStorageEchoBot :

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 Frameworks. Все изменения кода в этом разделе вносятся в index.js.

Сначала добавьте ссылку на botbuilder-azure в index.js. Это даст вам доступ к классу 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 Frameworks, а вместо Cosmos DB:

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

В следующем примере кода используется тот же код бота, что и пример хранилища памяти , приведенный выше, с исключениями, перечисленными здесь.

Оба CosmosDbPartitionedStorage и CosmosDbPartitionedConfig из botbuilder-azure них необходимы для создания объекта CosmosDB служба хранилища.

echo_bot.py

from botbuilder.azure import CosmosDbPartitionedStorage, CosmosDbPartitionedConfig

Чтобы получить доступ к параметрам в config.py, импортируется DefaultConfig , как показано ниже:

from config import DefaultConfig
CONFIG = DefaultConfig()

Закомментируйте хранилище в памяти в __init__, заменив ссылкой на Cosmos DB. Используйте URI (конечная точка), первичный ключ (ключ авторизации), идентификатор базы данных и идентификатор контейнера, используемый выше.

Затем удалите или закомментируйте код __init__ служба хранилища памяти и добавьте ссылку на сведения Cosmos DB из config.py.

В приведенном ниже фрагменте кода показана реализация 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

Запустите бот на локальном компьютере.

Тестирование бота Cosmos DB с помощью эмулятора Bot Framework

Теперь запустите эмулятор Bot Framework и подключитесь к боту:

Выберите ссылку на создание новой конфигурации бота на вкладке приветствия эмулятора.
Заполните поля для подключения к боту, используя сведения на веб-странице, отображаемой при запуске бота.

Взаимодействие с ботом Cosmos DB

Отправьте сообщение боту, и он отобразит список полученных сообщений.

Беседа с ботом, показывая боту список сообщений от пользователя.

Просмотр данных Cosmos DB

После запуска бота и сохранения сведений можно просмотреть данные, хранящиеся в портал Azure на вкладке "Данные Обозреватель".

Снимок экрана: Обозреватель данных в портал Azure.

Использование хранилища BLOB-объектов

Хранилище BLOB-объектов Azure — это решение корпорации Майкрософт для хранения объектов в облаке. Хранилище BLOB-объектов оптимизировано для хранения огромных объемов неструктурированных данных, таких как текстовые или двоичные данные. В этом разделе объясняется, как создать учетную запись хранения BLOB-объектов Azure и контейнер, а затем как ссылаться на контейнер хранилища BLOB-объектов из бота.

Дополнительные сведения о служба хранилища BLOB-объектов см. в статье "Что такое хранилище BLOB-объектов Azure"?

Создание учетной записи хранилища BLOB-объектов

Для использования хранилища BLOB-объектов в боте необходимо выполнить некоторые настройки, прежде чем приступать к написанию кода.

На портале Azure выберите Все службы.
В разделе "Избранные" страницы "Все службы" выберите служба хранилища учетные записи.
На странице служба хранилища учетных записей нажмите кнопку "Создать".
В поле Подписка выберите подписку, в которой будет создана учетная запись хранения.
В поле Группа ресурсов выберите имеющуюся группу ресурсов или выберите Создать и введите имя новой группы ресурсов.
В поле Имя учетной записи хранения введите имя учетной записи. Придерживайтесь приведенных ниже рекомендаций:
- Это имя должно быть уникальным в пределах Azure.
- Количество символов в имени должно быть от 3 до 24.
- Имя может содержать только цифры и строчные буквы.
В поле Расположение выберите расположение для учетной записи хранения или используйте расположение по умолчанию.
Настройте остальные параметры установки:
- Производительность: стандартная. Дополнительные сведения о производительности.
- Тип учетной записи: BLOB-объект служба хранилища. Дополнительные сведения о учетных записях хранения.
- Репликация. Оставьте параметр по умолчанию. Узнайте больше о избыточности.
В разделе "Сведения о проекте" на странице "Создание учетной записи хранения" выберите нужные значения для подписки и группы ресурсов.
В разделе сведений об экземпляре на странице "Создание учетной записи хранения" введите имя учетной записи служба хранилища, а затем выберите значения расположения, типа учетной записи и репликации.
Чтобы проверить параметры учетной записи хранения, выберите Проверить и создать.
После проверки нажмите кнопку "Создать".

Создание контейнера хранилища BLOB-объектов

После создания учетной записи хранения BLOB-объектов откройте ее, а затем:

Выберите Обозреватель службы хранилища (предварительная версия).
Затем щелкните правой кнопкой мыши контейнеры BLOB-объектов
Выберите " Создать контейнер BLOB-объектов" из раскрывающегося списка.
Введите имя в форме нового контейнера . Это имя будет использоваться для значения имени контейнера BLOB-объектов, чтобы предоставить доступ к учетной записи хранения BLOB-объектов. Придерживайтесь приведенных ниже рекомендаций:
- Это имя может содержать только строчные буквы, цифры и дефисы.
- Это имя должно начинаться с буквы или числа.
- Перед каждым дефисом следует следовать допустимый символ, отличный от дефиса.
- Имя должно иметь длину от 3 до 63 символов.

Добавление сведений о конфигурации хранилища BLOB-объектов

Найдите ключи хранилища BLOB-объектов, необходимые для настройки хранилища BLOB-объектов для бота, как показано выше:

В портал Azure откройте учетную запись хранения BLOB-объектов и выберите ключи доступа в разделе Параметры.
Чтобы настроить бот для доступа к учетной записи хранения BLOB-объектов, используйте строку Подключение ion в качестве значения для строка подключения 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-объектов

Если ранее не установлено, установите следующие пакеты.

Установите пакет NuGet Microsoft.Bot.Builder.Azure.Blobs. Дополнительные сведения об использовании NuGet см. в статье "Установка пакетов и управление ими в Visual Studio с помощью диспетчер пакетов NuGet".

Добавьте ссылки botbuilder-azure-blobs на проект через npm.

Примечание.

Этот пакет npm использует установку Python, существующую на компьютере разработки. Если вы ранее не установили Python, вы можете найти ресурсы установки для компьютера на Python.org

npm install --save botbuilder-azure-blobs

Если он еще не установлен, получите пакет .NET из npm, чтобы получить доступ к параметрам env-файла .

npm install --save dotenv

Вы можете добавить ссылку на botbuilder-azure в проекте с помощью pip.

pip install botbuilder-azure

Реализация хранилища BLOB-объектов

Хранилище BLOB-объектов используется для хранения состояния бота.

Примечание.

По состоянию на версию 4.10 Microsoft.Bot.Builder.Azure.AzureBlobStorage не рекомендуется. Используйте новое Microsoft.Bot.Builder.Azure.Blobs.BlobsStorage в своем месте.

В фрагментах кода ниже показана реализация хранилища BLOB-объектов для my служба хранилища, которая заменяет локальное хранилище памяти.

Сначала необходимо обновить Startup.cs , чтобы ссылаться на библиотеку BLOB-объектов Azure построителя ботов:

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 , чтобы ссылаться на библиотеку BLOB-объектов Azure построителя ботов:

EchoBot.cs

using Microsoft.Bot.Builder.Azure.Blobs;

Затем удалите или закомментируйте строку кода, которая создает переменную Memory служба хранилища "частная статтическая память чтения служба хранилища _my служба хранилища = новая память служба хранилища();" и создайте новую переменную, которая будет использоваться для сохранения входных данных пользователя в служба хранилища BLOB-объекта.

EchoBot.cs

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

Затем передайте объект конструктору IStorageEchoBot :

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

После того как хранилище будет указано на учетную запись служба хранилища BLOB-объектов, код бота будет хранить и извлекать данные из хранилища 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 Frameworks.

Затем добавьте ссылку на botbuilder-azure-blobs. Это даст вам доступ к API служба хранилища BLOB-объектов:

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

Чтобы изменить код для использования BlobsStorage класса, измените myStorage объявление следующим образом:

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

Для этого потребуется BlobStorage и BlobStorageSettings из botbuilder-azure.

echo_bot.py

from botbuilder.azure import BlobStorage, BlobStorageSettings

Чтобы получить доступ к параметрам в config.py, импортируется DefaultConfig , как показано ниже:

from config import DefaultConfig
CONFIG = DefaultConfig()

Затем удалите или закомментируйте код __init__ служба хранилища памяти и добавьте ссылку на сведения о хранилище BLOB-объектов из config.py.

В приведенном ниже фрагменте кода показана реализация служба хранилища 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-объектов

Запустите бот на локальном компьютере.

Запустите эмулятор и подключите бот хранилища BLOB-объектов

Затем запустите эмулятор и подключитесь к боту в эмуляторе:

Выберите ссылку "Создать бота" на вкладке "Приветствие" эмулятора.
Заполните поля для подключения к боту, используя сведения на веб-странице, отображаемой при запуске бота.

Взаимодействие с ботом хранилища BLOB-объектов

Отправьте сообщение боту, и он отобразит список полученных сообщений.

Беседа с ботом, показывая боту список сообщений от пользователя.

Просмотр данных хранилища BLOB-объектов

После запуска бота и сохранения сведений его можно просмотреть на вкладке Обозреватель службы хранилища на портал Azure.

Хранилище расшифровок разговоров в BLOB-объектах

Хранилище расшифровок в BLOB-объектах Azure — это специализированное хранилище, которое позволяет легко сохранять и получать разговоры пользователей в виде записей расшифровок. Хранилище расшифровки BLOB-объектов Azure полезно для автоматического записи входных данных пользователей для проверки производительности бота.

Примечание.

В настоящее время Python не поддерживает хранилище расшифровок BLOB-объектов Azure. Хотя JavaScript поддерживает хранилище расшифровок BLOB-объектов, следующие указания предназначены только для C#.

Настройка контейнера хранилища расшифровки BLOB-объектов

Хранилище расшифровок разговоров в BLOB-объектах Azure использует ту же учетную запись хранилища BLOB-объектов, которая описана в разделах Создание учетной записи хранилища BLOB-объектов и Добавление сведений о конфигурации выше. Теперь добавьте контейнер для хранения расшифровок.

Снимок экрана: создание контейнера BLOB-объектов для использования в качестве хранилища транскрибирования.

Откройте учетную запись хранилища BLOB-объектов Azure
Выберите Обозреватель службы хранилища.
Щелкните правой кнопкой мыши Контейнеры больших двоичных объектов и выберите Создать контейнер BLOB-объектов.
Введите имя контейнера расшифровки и нажмите кнопку "ОК". (Мы ввели mybottranscripts)

Реализация хранилища расшифровки BLOB-объектов

В коде ниже указатель на хранилище расшифровок _myTranscripts подключается к новой учетной записи хранилища BLOB-объектов с расшифровками. Чтобы создать эту ссылку с новым именем контейнера, <your-blob-transcript-container-name>, он создает новый контейнер в хранилище BLOB-объектов для хранения файлов расшифровки.

Хранилище расшифровок BLOB-объектов предназначено для хранения расшифровок бота.

Примечание.

По состоянию на версию 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>");

   ...
}

Хранение бесед пользователей в расшифровках BLOB-объектов Azure

После того как контейнер BLOB-объектов доступен для хранения расшифровок, вы можете начать сохранять беседы пользователей с ботом. Эти диалоги можно позже использовать для отладки, чтобы проанализировать взаимодействие пользователей с ботом. Каждый диалог перезапуска эмулятора инициирует создание нового списка бесед расшифровки. Следующий код сохраняет диалог с пользователем в сохраненном файле с расшифровками.

Текущая расшифровка сохраняется с использованием LogActivityAsync.
Сохраненные расшифровки можно получить с использованием ListTranscriptsAsync. В этом примере кода идентификатор каждого сохраненного транскрибирования сохраняется в списке с именем storedTranscripts. Позже этот список используется для управления количеством расшифровок, хранимых в больших двоичных объектах.

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

    ...
}

Управление расшифровками, хранимыми в больших двоичных объектах

Хотя хранимые расшифровки можно использовать как средство отладки, со временем их количество превышает возможности хранилища. Дополнительный код ниже использует 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);
           }
       }
    }
    ...
}

Дополнительные сведения о классе см. в служба хранилища расшифровки BLOB-объектов Azure.

Дополнительная информация

Управление параллелизмом с помощью тегов eTag

В примере кода бота мы задали свойству eTag каждого из них IStoreItem*значение . Член eTag (тег сущности) объекта хранилища используется в Cosmos DB для управления параллелизмом. eTag указывает базе данных, что делать, если другой экземпляр бота изменил объект в том же хранилище, в которое записывает данные ваш бот.

Приоритет последней записи — разрешить перезапись

Если указать звездочку (*) в качестве значения свойства eTag, это означает, то приоритет принадлежит последнему боту, который выполняет запись. При создании нового хранилища данных можно задать eTag свойство, чтобы * указать, что вы ранее не сохранили данные, которые вы записываете, или хотите, чтобы последний модуль записи перезаписал любое ранее сохраненное свойство. Если параллелизм не является проблемой для бота, присвойте eTag свойству * значение для любых данных, которые вы записываете, включает перезаписи.

Поддержание параллелизма и предотвращение перезаписи

Если нужно предотвратить параллельный доступ к свойству и избежать перезаписи данных другим экземпляром бота, при сохранении данных в Cosmos DB используйте другое значение свойства eTag, отличное от *. Бот получает ответ на ошибку с сообщением etag conflict key= при попытке сохранить данные о состоянии и eTag не совпадает со значением eTag в хранилище.

По умолчанию хранилище Cosmos DB проверяет равенство свойства eTag в объекте хранилища каждый раз, когда бот записывает данные в этот элемент, а затем включает в это свойство новое уникальное значение после каждой операции записи. Если значение свойства eTag во время записи не соответствует значению свойства eTag в хранилище, это означает, что другой бот или поток изменили данные.

Например, предположим, что ваш бот должен изменять сохраненные заметки, но вы не хотите, чтобы он перезаписывал изменения, выполненные другим экземпляром бота. Если другой экземпляр бота внес изменения, пользователь должен изменять последнюю версию со всеми внесенными изменениями.

Во-первых, создайте класс, который реализует 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 возникнет исключение.

Добавьте в конец кода бота вспомогательную функцию, которая будет записывать пример заметки в хранилище данных. Сначала создайте объект 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: "*"
    }
}

В вспомогательной createSampleNotechanges функции инициализируйте объект и добавьте в него заметки , а затем запишите его в хранилище.

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.js

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

Для последующего получения и обновления созданной заметки мы создадим другую вспомогательную функцию. Она вызывается, когда пользователь вводит команду update note.

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.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, имеющим значение *, будет разрешена перезапись любых других изменений.

Следующие шаги

Теперь, когда вы знаете, как читать и записывать непосредственно из хранилища, можно посмотреть, как можно использовать диспетчер состояний для этого.

Сохранение состояния с помощью свойств conversation и user

Непосредственная запись в хранилище

Необходимые компоненты

Об этом примере

Хранилище в памяти

Создание базового бота

Запуск бота

Запуск эмулятора и подключение к боту

Взаимодействие с ботом

Использование Cosmos DB

Настройка ресурса Cosmos DB

Создание учетной записи базы данных

Добавление базы данных

Добавление сведений о конфигурации Cosmos DB

Установка пакетов Cosmos DB

Реализация Cosmos DB

Запуск бота Cosmos DB

Тестирование бота Cosmos DB с помощью эмулятора Bot Framework

Взаимодействие с ботом Cosmos DB

Просмотр данных Cosmos DB

Использование хранилища BLOB-объектов

Создание учетной записи хранилища BLOB-объектов

Создание контейнера хранилища BLOB-объектов

Добавление сведений о конфигурации хранилища BLOB-объектов

Установка пакетов хранилища BLOB-объектов

Реализация хранилища BLOB-объектов

Запуск бота хранилища BLOB-объектов

Запустите эмулятор и подключите бот хранилища BLOB-объектов

Взаимодействие с ботом хранилища BLOB-объектов

Просмотр данных хранилища BLOB-объектов

Хранилище расшифровок разговоров в BLOB-объектах

Настройка контейнера хранилища расшифровки BLOB-объектов

Реализация хранилища расшифровки BLOB-объектов

Хранение бесед пользователей в расшифровках BLOB-объектов Azure

Управление расшифровками, хранимыми в больших двоичных объектах

Дополнительная информация

Управление параллелизмом с помощью тегов eTag

Приоритет последней записи — разрешить перезапись

Поддержание параллелизма и предотвращение перезаписи

Следующие шаги

Дополнительные ресурсы