Запись данных напрямую в хранилищеWrite directly to storage

применимо к: Пакет SDK v4APPLIES TO: SDK v4

Вы можете выполнять операции записи и чтения непосредственно в объекте хранилища, не используя ПО промежуточного слоя или объект контекста.You can read and write directly to your storage object without using middleware or context object. Это может требоваться для данных, которые бот использует для сохранения беседы, или данных, которые поступают из источника за пределами потока общения бота.This can be appropriate for data your bot uses to preserve a conversation, or data that comes from a source outside your bot's conversation flow. В рамках этой модели хранилища данные считываются непосредственно из хранилища без использования диспетчера состояний.In this data storage model, data is read in directly from storage instead of using a state manager. в примерах кода в этой статье показано, как выполнять чтение и запись данных в хранилище с помощью памяти, Cosmos DB, большого двоичного объекта azure и хранилища записей blob-объектов azure .The code examples in this article show you how to read and write data to storage using memory, Cosmos DB, Azure Blob, and Azure Blob transcript storage.

Предварительные требованияPrerequisites

Примечание

Пакет VSIX включает версии .net Core 2,1 и .net Core 3,1 шаблонов C#.The VSIX package includes both .NET Core 2.1 and .NET Core 3.1 versions of the C# templates. При создании ботов в Visual Studio 2019 следует использовать шаблоны .NET Core 3.1.When creating new bots in Visual Studio 2019, you should use the .NET Core 3.1 templates. В текущих примерах ботов используются шаблоны .NET Core 3.1.The current bot samples use .NET Core 3.1 templates. Примеры, использующие шаблоны .NET Core 2.1, можно найти в ветви 4.7-archive репозитория BotBuilder-Samples.You can find the samples that use .NET Core 2.1 templates in the 4.7-archive branch of the BotBuilder-Samples repository. Сведения о развертывании .NET Core 3,1 программы-роботы в Azure см. в статье развертывание программы Bot в Azure.For information about deploying .NET Core 3.1 bots to Azure, see how to deploy your bot to Azure.

Об этом примереAbout this sample

Пример кода в этой статье определяет структуру базового эхо-бота. Добавив дополнительный код (см. ниже), вы сможете расширить функции этого бота.The sample code in this article begins with the structure of a basic echo bot, then extends that bot's functionality by adding additional code (provided below). Этот расширенный код создает список для хранения вводимых пользователем данных по мере получения.This extended code creates a list to preserve user inputs as they are received. Каждый ход, полный список входных данных пользователя, сохраненный в памяти, возвращается пользователю.Each turn, the full list of user inputs, saved to memory, is echoed back to the user. Структура данных, содержащая этот список входов, затем изменяется для сохранения в хранилище.The data structure containing this list of inputs is then modified to save to storage. Различные типы хранилища рассматриваются по мере добавления дополнительных функциональных возможностей в этот пример кода.Various types of storage are explored as additional functionality is added to this sample code.

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

Пакет SDK Bot Framework позволяет хранить вводимые пользователем данные с помощью размещенного в памяти хранилища.The Bot Framework SDK allows you to store user inputs using in-memory storage. Поскольку хранилище в памяти удаляется при каждом перезапуске программы-робота, оно лучше всего подходит для тестирования и не предназначено для использования в рабочей среде.Since in-memory storage is cleared each time the bot is restarted, it is best suited for testing purposes and is not intended for production use. Постоянные хранилища, такие как хранилище базы данных, лучше всего подходят для ботов в рабочей среде.Persistent storage types, such as database storage, are best for production bots.

Создание базового ботаBuild a basic bot

Остальная часть этой статьи описывает использование эхо-бота.The rest of this topic builds off of an Echo bot. Пример кода для программы Echo Bot можно создать локально, следуя инструкциям краткого руководства по созданию робота.The Echo bot sample code can be locally built by following the quickstart instructions to Create a bot.

Замените код в ечобот. CS следующим кодом:Replace the code in EchoBot.cs with the following code:

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

Запуск ботаStart your bot

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

Запуск эмулятора и подключение к ботуStart the Emulator and connect your bot

установите платформу Bot Emulator далее, запустите Emulator и подключитесь к роботу в Emulator:Install the Bot Framework Emulator Next, start the Emulator and then connect to your bot in the Emulator:

  1. щелкните ссылку создать конфигурацию bot на вкладке приветствие Emulator.Select the Create new bot configuration link in the Emulator Welcome tab.
  2. Заполните поля для подключения к боту, используя сведения на веб-странице, отображаемой при запуске бота.Fill in fields to connect to your bot, given the information on the webpage displayed when you started your bot.

Взаимодействие с ботомInteract with your bot

Отправьте сообщение боту.Send a message to your bot. Он отобразит список полученных сообщений.The bot will list the messages it has received.

Окно Bot Framework Emulator

В оставшейся части этой статьи будет показано, как сохранить данные в постоянное хранилище вместо внутренней памяти Bot.The remainder of this article will demonstrate how to save to persistent storage instead of the bot's internal memory.

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

Важно!

Класс хранилища Cosmos DB является устаревшим.The Cosmos DB storage class has been deprecated. Контейнеры, изначально созданные с помощью Космосдбстораже, не имели набора ключей секций и получили ключ раздела по умолчанию _ / partitionKey.Containers originally created with CosmosDbStorage had no partition key set, and were given the default partition key of _/partitionKey.

контейнеры, созданные с помощью хранилища Cosmos DB , можно использовать с Cosmos DB секционированного хранилища.Containers created with Cosmos DB storage can be used with Cosmos DB partitioned storage. См. сведения о секционировании в Azure Cosmos DB.Read Partitioning in Azure Cosmos DB for more information.

также обратите внимание, что, в отличие от устаревшего Cosmos DB хранения, Cosmos DB секционированного хранилища не создает базу данных в учетной записи Cosmos DB автоматически.Also note that, unlike the legacy Cosmos DB storage, the Cosmos DB partitioned storage does not automatically create a database within your Cosmos DB account. Необходимо создать новую базу данных вручную, но пропустить создание контейнера вручную, так как космосдбпартитионедстораже создаст контейнер.You need to create a new database manually, but skip manually creating a container since CosmosDbPartitionedStorage will create the container for you.

Начав использовать хранилище в памяти, мы изменим код, чтобы начать работу с Azure Cosmos DB.Now that you've used memory storage, we'll update the code to use Azure Cosmos DB. Cosmos DB — это глобально распределенная многомодельная база данных Майкрософт.Cosmos DB is Microsoft's globally distributed, multi-model database. Azure Cosmos DB позволяет гибко и независимо масштабировать пропускную способность и ресурсы хранилища в любом количестве регионов Azure.Azure Cosmos DB enables you to elastically and independently scale throughput and storage across any number of Azure's geographic regions. Она гарантирует пропускную способность, задержку, доступность и согласованность в соответствии с комплексными Соглашениями об уровне обслуживания (SLA).It offers throughput, latency, availability, and consistency guarantees with comprehensive service level agreements (SLAs).

настройка Cosmos DB ресурсаSet up a Cosmos DB resource

Чтобы использовать в боте Cosmos DB, необходимо создать ресурс базы данных, прежде чем приступать к написанию кода.To use Cosmos DB in your bot, you'll need to create a database resource before getting into the code. подробное описание Cosmos DB базы данных и создания приложений см. в кратком руководстве по .net, Node.js или Python.For an in-depth description of Cosmos DB database and app creation, see the quickstart for .Net, Node.js or Python.

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

  1. Создайте учетную запись для базы данных Azure Cosmos DB, перейдя на портал Azure.Go to the Azure portal to create an Azure Cosmos DB account. Найдите в поиске и выберите Azure Cosmos DBSearch for and select Azure Cosmos DB.

  2. на странице Azure Cosmos DB выберите создать , чтобы открыть страницу создание учетной записи Azure Cosmos DB .In the Azure Cosmos DB page, select New to bring up the the Create Azure Cosmos DB Account page.

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

  3. Укажите значения для следующих полей:Provide values for the following fields:

    1. Подписка.Subscription. Выберите подписку Azure, которую нужно использовать для этой учетной записи Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    2. Группа ресурсов.Resource group. Выберите существующую группу ресурсов или щелкните создать и введите имя для новой группы ресурсов.Select an existing resource group or select Create new, and enter a name for a new resource group.
    3. Имя учетной записи.Account name. Введите имя для идентификации учетной записи Azure Cosmos.Enter a name to identify your Azure Cosmos account. Так как элемент documents.azure.com добавляется к указанному вами имени для создания URI, используйте уникальное имя.Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name. Придерживайтесь приведенных ниже рекомендаций:Note the following guidelines:
      • Это имя должно быть уникальным в пределах Azure.The name must be unique across Azure.
      • Длина имени должна составлять от 3 до 31 символов.The name must be between three and 31 characters long.
      • Имя может содержать только строчные буквы, цифры и символ дефиса (-).The name can include only lowercase letters, numbers, and the hyphen (-) character.
    4. API.API. Выбор ядра (SQL)Select Core(SQL)
    5. Расположение.Location. выберите ближайшее к пользователям расположение, чтобы предоставить им самый быстрый доступ к данным.select a location that is closest to your users to give them the fastest access to the data.
  4. Выберите Review + Create (Просмотреть и создать).Select Review + Create.

  5. После проверки выберите создать.Once validated, select Create.

Создание учетной записи займет несколько минут.The account creation takes a few minutes. Дождитесь, пока на портале откроется страница с сообщением Congratulations! Your Azure Cosmos DB account was created (Поздравляем! Ваша учетная запись Azure Cosmos DB создана).Wait for the portal to display the Congratulations! Your Azure Cosmos DB account was created page.

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

Примечание

Не следует создавать контейнер самостоятельно.You should not create the container yourself. Ваш бот создаст его одновременно с внутренним клиентом Cosmos DB и правильно настроит для сохранения состояния бота.Your bot will create it for you when creating its internal Cosmos DB client, ensuring it is configured correctly for storing bot state.

  1. перейдите на обозреватель данных страницу в созданной учетной записи Cosmos DB, а затем выберите пункт создать базу данных в раскрывающемся списке новый контейнер .Navigate to the Data Explorer page within your newly created Cosmos DB account, then choose New Database from the New Container drop-down. В правой части окна откроется панель, где можно указать сведения о новой базе данных.A panel will then open on the right hand side of the window, where you can enter the details for the new database.

    создание образа ресурса базы данных Cosmos DB

  2. Введите идентификатор для новой базы данных и, при необходимости, задайте пропускную способность (это можно будет изменить позже), а затем нажмите кнопку ОК , чтобы создать базу данных.Enter an ID for your new database and, optionally, set the throughput (you can change this later) and finally select OK to create your database. Запишите идентификатор базы данных, чтобы использовать его позже для настройки бота.Make a note of this database ID for use later on when configuring your bot.

  3. Завершив создание учетной записи Cosmos DB и базы данных, скопируйте некоторые значения для интеграции новой базы данных в бота.Now that you have created a Cosmos DB account and a database, you need to copy over some of the values for integrating your new database into your bot. Чтобы получить их, перейдите на вкладку Ключи в разделе параметров базы данных, которую вы создали в учетной записи Cosmos DB.To retrieve these, navigate to the Keys tab within the database settings section of your Cosmos DB account. на этой странице вам потребуется URI (Cosmos DB конечной точки) и первичный ключ (ключ авторизации).From this page you will need your URI (Cosmos DB endpoint) and your PRIMARY KEY (authorization key).

    Ключи Cosmos DB

теперь у вас должна быть учетная запись Cosmos DB с базой данных и следующие значения, готовые к использованию в параметрах программы bot.You should now have a Cosmos DB account with a database and the following values ready to use in your bot settings.

  • URIURI
  • Первичный ключPrimary Key
  • Идентификатор базы данныхDatabase ID

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

Используйте ранее сохраненные сведения, чтобы задать конечную точку, ключ авторизации и идентификатор базы данных.Use the details you made a note of in the previous part of this article to set your endpoint, authorization key and database ID. Наконец, выберите подходящее имя для контейнера, который будет создан в базе данных для хранения состояния бота.Finally, you should choose an appropriate name for the container that will be created within your database to store your bot state. в примере ниже созданный контейнер Cosmos DB будет называться «bot-storage».In the example below the Cosmos DB container that is created will be named "bot-storage".

Добавьте следующие сведения в файл конфигурации.Add the following information to your configuration file.

appsettings.jsonappsettings.json

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

установка пакетов Cosmos DBInstalling Cosmos DB packages

Убедитесь, что вы установили пакеты, необходимые для работы с Cosmos DB.Make sure you have the packages necessary for Cosmos DB.

установите пакет Microsoft. Bot. Builder. Azure NuGet.Install the Microsoft.Bot.Builder.Azure NuGet package. дополнительные сведения об использовании NuGet см. в разделе установка пакетов и управление ими в Visual Studio с помощью диспетчер пакетов NuGet .For more information on using NuGet, see Install and manage packages in Visual Studio using the NuGet Package Manager .

Cosmos Реализация базы данныхCosmos DB implementation

Примечание

В версии 4.6 появился новый поставщик хранилища Cosmos DB — класс секционированного хранилища Cosmos DB класса. Исходный класс хранилища Cosmos DB является устаревшим.Version 4.6 introduced a new Cosmos DB storage provider, the Cosmos DB partitioned storage class, and the original Cosmos DB storage class is deprecated. контейнеры, созданные с помощью хранилища Cosmos DB , можно использовать с Cosmos DB секционированного хранилища.Containers created with Cosmos DB storage can be used with Cosmos DB partitioned storage. См. сведения о секционировании в Azure Cosmos DB.Read Partitioning in Azure Cosmos DB for more information.

также обратите внимание, что, в отличие от устаревшего Cosmos DB хранения, Cosmos DB секционированного хранилища не создает базу данных в учетной записи Cosmos DB автоматически.Also note that, unlike the legacy Cosmos DB storage, the Cosmos DB partitioned storage does not automatically create a database within your Cosmos DB account. Необходимо создать новую базу данных вручную, но пропустить создание контейнера вручную, так как космосдбпартитионедстораже создаст контейнер.You need to create a new database manually, but skip manually creating a container since CosmosDbPartitionedStorage will create the container for you.

Следующий пример кода выполняется с использованием того же кода Bot, что и в приведенном выше примере хранилища памяти , за исключением перечисленных здесь исключений.The following sample code runs using the same bot code as the memory storage sample provided above, with the exceptions listed here. фрагменты кода ниже демонстрируют реализацию хранилища Cosmos DB для "myStorage", которое заменяет хранилище локальной памяти.The code snippets below show an implementation of Cosmos DB storage for 'myStorage' that replaces local Memory storage.

Сначала необходимо обновить Startup. CS для ссылки на библиотеку Azure Builder :You first need to update Startup.cs to reference the bot builder Azure library:

using Microsoft.Bot.Builder.Azure;

Затем в ConfigureServices методе в Startup. CS создайте CosmosDbPartitionedStorage объект.Next, in the ConfigureServices method in Startup.cs, create the CosmosDbPartitionedStorage object. Он передается в EchoBot конструктор посредством внедрения зависимостей.This will be passed into the EchoBot constructor through dependency injection.

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

В ечобот. CS измените _myStorage объявление переменной private static readonly MemoryStorage _myStorage = new MemoryStorage(); следующим образом:In EchoBot.cs change the _myStorage variable declaration private static readonly MemoryStorage _myStorage = new MemoryStorage(); to the following:

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

Затем передайте IStorage объект в EchoBot конструктор:Then pass in the IStorage object to the EchoBot constructor:

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

запуск Cosmos DB botStart your Cosmos DB bot

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

тестирование Cosmos DB bot с Bot Framework EmulatorTest your Cosmos DB bot with Bot Framework Emulator

теперь запустите Bot Framework Emulator и подключитесь к роботу:Now start the Bot Framework Emulator and connect to your bot:

  1. на вкладке приветствия Emulator выберите ссылку создать новую конфигурацию bot .Select the create a new bot configuration link in the Emulator Welcome tab.
  2. Заполните поля для подключения к боту, используя сведения на веб-странице, отображаемой при запуске бота.Fill in fields to connect to your bot, given the information on the webpage displayed when you started your bot.

взаимодействие с Cosmos DB botInteract with your Cosmos DB bot

Отправьте сообщение боту, и он отобразит список полученных сообщений.Send a message to your bot, and the bot will list the messages it received. Работающий эмуляторEmulator running

просмотр данных Cosmos DBView your Cosmos DB data

Если вы запустили бот и сохранили информацию, ее можно просмотреть на портале Azure на вкладке Обозреватель данных.After you have run your bot and saved your information, we can view the data stored in the Azure portal under the Data Explorer tab.

Пример Data Explorer

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

Хранилище BLOB-объектов Azure — это решение корпорации Майкрософт для хранения объектов в облаке.Azure Blob storage is Microsoft's object storage solution for the cloud. Хранилище BLOB-объектов оптимизировано для хранения больших объемов неструктурированных данных, например текстовых или двоичных данных.Blob storage is optimized for storing massive amounts of unstructured data, such as text or binary data. В этом разделе объясняется, как создать учетную запись хранилища BLOB-объектов Azure и контейнер, а затем как ссылаться на контейнер хранилища BLOB-объектов из программы-робота.This section explains how to create an Azure blob storage account and container, then how to reference your blob storage container from your bot.

дополнительные сведения о служба хранилища больших двоичных объектов см. в статье что такое хранилище blob-объектов Azure?For additional information on Blob Storage, see What is Azure Blob storage?

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

Для использования хранилища BLOB-объектов в боте необходимо выполнить некоторые настройки, прежде чем приступать к написанию кода.To use Blob storage in your bot, you'll need to get a few things set up before getting into the code.

  1. На портале Azure выберите Все службы.In the Azure portal, select All services.

  2. в разделе основные материалы страницы все службы выберите служба хранилища учетные записи.In the Featured section of the All services page, select Storage accounts.

  3. на странице учетные записи служба хранилища выберите * * New * * * *.In the Storage accounts page, select **New****.

    Страница создания учетной записи хранения большого двоичного объекта

  4. В поле Подписка выберите подписку, в которой будет создана учетная запись хранения.In the Subscription field, select the subscription in which to create the storage account.

  5. В поле Группа ресурсов выберите имеющуюся группу ресурсов или выберите Создать и введите имя новой группы ресурсов.In the Resource group field, select an existing resource group or select Create new, and enter a name for the new resource group.

  6. В поле Имя учетной записи хранения введите имя учетной записи.In the Storage account name field, enter a name for the account. Придерживайтесь приведенных ниже рекомендаций:Note the following guidelines:

    • Это имя должно быть уникальным в пределах Azure.The name must be unique across Azure.
    • Количество символов в имени должно быть от 3 до 24.The name must be between three and 24 characters long.
    • Имя может содержать только цифры и строчные буквы.The name can include only numbers and lowercase letters.
  7. В поле Расположение выберите расположение для учетной записи хранения или используйте расположение по умолчанию.In the Location field, select a location for the storage account, or use the default location.

  8. Настройте остальные параметры установки:For the rest of the settings, configure the following:

  9. в разделе сведения о Project на странице создание учетной записи хранения выберите нужные значения для подписки и группы ресурсов.In the Project details section of the Create storage account page, select the desired values for subscription and Resource group.

  10. в разделе сведения об экземпляре страницы создание учетной записи хранения введите служба хранилища имя учетной записи , а затем выберите значения для параметров расположение, тип учетной записи и репликация.In the Instance details section of the Create storage account page, enter the Storage account name then select values for Location, Account kind and Replication.

  11. Чтобы проверить параметры учетной записи хранения, выберите Проверить и создать.Select Review + create to review the storage account settings.

  12. После проверки выберите создать.Once validated, select Create.

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

После создания учетной записи хранилища BLOB-объектов откройте ее, а затем:Once your Blob storage account is created, open it, then:

  1. выберите Обозреватель службы хранилища (предварительная версия).Select Storage Explorer (Preview).

  2. Затем щелкните правой кнопкой мыши контейнеры больших двоичных объектовThen right-click on BLOB CONTAINERS

  3. В раскрывающемся списке выберите создать контейнер BLOB-объектов .Select Create blob container from the drop-down list.

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

  4. Введите имя в форму новый контейнер .Enter a name in the New container form. Это имя будет использоваться в качестве значения "BLOB-хранилище-контейнер-имя", чтобы предоставить доступ к учетной записи хранилища больших двоичных объектов.You will use this name for the value of your "blob-storage-container-name" to provide access to your Blob storage account. Придерживайтесь приведенных ниже рекомендаций:Note the following guidelines:

    • Это имя может содержать только строчные буквы, цифры и дефисы.This name may only contain lowercase letters, numbers, and hyphens.
    • Это имя должно начинаться с буквы или цифры.This name must begin with a letter or a number.
    • Перед каждым дефисом должен быть указан допустимый символ, отличный от дефиса.Each hyphen must be preceded and followed by a valid non-hyphen character.
    • Длина имени должна составлять от 3 до 63 символов.The name must be between three and 63 characters long.

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

Найдите ключи хранилища BLOB-объектов, необходимые для настройки хранилища BLOB-объектов для программы Bot, как показано выше:Find the Blob storage keys you need to configure Blob storage for your bot as shown above:

  1. в портал Azure откройте учетную запись хранилища Blob-объектов и выберите ключи доступа в разделе Параметры .In the Azure portal, open your Blob storage account and select Access keys in the Settings section.

    Поиск ключей хранилища BLOB-объектов

Используйте строку подключения в качестве значения для строки подключения, чтобы предоставить доступ к учетной записи хранилища BLOB-объектов.Use Connection string as the value for your "connection-string" to provide access to your Blob storage account.

Добавьте следующие сведения в файл конфигурации.Add the following information to your configuration file.

appsettings.jsonappsettings.json

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

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

Установите следующие пакеты, если они не были установлены ранее.If not previously installed, install the following packages.

установите пакет NuGet Microsoft. Bot. Builder. Azure. blobs .Install the Microsoft.Bot.Builder.Azure.Blobs NuGet package. дополнительные сведения об использовании NuGet см. в разделе установка пакетов и управление ими в Visual Studio с помощью диспетчер пакетов NuGet.For more information on using NuGet, see Install and manage packages in Visual Studio using the NuGet Package Manager.

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

Хранилище BLOB-объектов используется для хранения состояния Bot.Blob storage is used to store bot state.

Примечание

Начиная с версии 4,10, Microsoft.Bot.Builder.Azure.AzureBlobStorage является устаревшим.As of version 4.10, Microsoft.Bot.Builder.Azure.AzureBlobStorage is deprecated. Используйте новый Microsoft.Bot.Builder.Azure.Blobs.BlobsStorage в своем месте.Use the new Microsoft.Bot.Builder.Azure.Blobs.BlobsStorage in its place.

Следующий пример кода выполняется с использованием того же кода Bot, что и в приведенном выше примере хранилища памяти , за исключением перечисленных здесь исключений.The following sample code runs using the same bot code as the memory storage sample provided above, with the exceptions listed here.

В приведенных ниже фрагментах кода показана реализация хранилища BLOB-объектов для "myStorage", которая заменяет хранилище локальной памяти.The code snippets below show an implementation of Blob storage for 'myStorage' that replaces local Memory storage.

Сначала необходимо обновить Startup. CS , чтобы он ссылался на библиотеку больших двоичных объектов Azure для Bot Builder :You first need to update Startup.cs to reference the bot builder Azure blobs library:

Startup.csStartup.cs

using Microsoft.Bot.Builder.Azure.Blobs;

Затем в ConfigureServices методе в Startup. CS создайте BlobsStorage объект, передав значения из appsettings.json .Next, in the ConfigureServices method in Startup.cs, create the BlobsStorage object, passing in the values from appsettings.json. Он передается в EchoBot конструктор посредством внедрения зависимостей.This will be passed into the EchoBot constructor through dependency injection.

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

Теперь сначала необходимо обновить ечобот. CS , чтобы он ссылался на библиотеку больших двоичных объектов Azure для Bot Builder :Now you first need to update EchoBot.cs to reference the bot builder Azure blobs library:

EchoBot.csEchoBot.cs

using Microsoft.Bot.Builder.Azure.Blobs;

затем удалите или закомментируйте строку кода, которая создает переменную мемористораже "private static readonly мемористораже _myStorage = new мемористораже ();", и создайте новую переменную, которая будет использоваться для сохранения вводимых пользователем данных в служба хранилища больших двоичных объектов.Next, remove or comment out the line of code that creates the MemoryStorage variable 'private static readonly MemoryStorage _myStorage = new MemoryStorage();', and create a new variable that will be used to save user input to the Blob Storage.

EchoBot.csEchoBot.cs

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

Затем передайте IStorage объект в EchoBot конструктор:Then pass in the IStorage object to the EchoBot constructor:

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

после того как хранилище настроено на учетную запись служба хранилища больших двоичных объектов, код программы-робота теперь будет хранить и получать данные из хранилища blob-объектов.Once your storage is set to point to your Blob Storage account, your bot code will now store and retrieve data from Blob storage.

после того как хранилище настроено на учетную запись служба хранилища больших двоичных объектов, код программы-робота теперь будет хранить и получать данные из хранилища blob-объектов.Once your storage is set to point to your Blob Storage account, your bot code will now store and retrieve data from Blob storage.

Запуск ленты для хранилища BLOB-объектовStart your Blob storage bot

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

запуск Emulator и подключение ленты хранилища Blob-объектовStart the Emulator and connect your Blob storage bot

затем запустите Emulator, а затем подключитесь к роботу в Emulator:Next, start the Emulator and then connect to your bot in the Emulator:

  1. щелкните ссылку создать конфигурацию bot на вкладке Emulator "добро пожаловать!".Select the Create new bot configuration link in the Emulator "Welcome" tab.
  2. Заполните поля для подключения к боту, используя сведения на веб-странице, отображаемой при запуске бота.Fill in fields to connect to your bot, given the information on the webpage displayed when you started your bot.

Взаимодействие с программой-роботом хранилища BLOB-объектовInteract with your Blob storage bot

Отправьте сообщение боту, и он отобразит список полученных сообщений.Send a message to your bot, and the bot will list the messages it receives.

Окно Bot Framework Emulator

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

Если вы запустили бот и сохранили информацию, ее можно просмотреть на портале Azure на вкладке Обозреватель службы хранилища.After you have run your bot and saved your information, we can view it in under the Storage Explorer tab in the Azure portal.

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

Хранилище расшифровок в BLOB-объектах Azure — это специализированное хранилище, которое позволяет легко сохранять и получать разговоры пользователей в виде записей расшифровок.Azure blob transcript storage provides a specialized storage option that allows you to easily save and retrieve user conversations in the form of a recorded transcript. Использовать хранилище расшифровок разговоров в больших двоичных объектах Azure особенно удобно для автоматической записи данных, вводимых пользователями, и дальнейшего их анализа при отладке бота.Azure blob transcript storage is particularly useful for automatically capturing user inputs to examine while debugging your bot's performance.

Примечание

В настоящее время Python не поддерживает хранилище для записи BLOB-объектов Azure.Python does not currently support Azure Blob transcript storage. Хотя JavaScript поддерживает хранилище для записи BLOB-объектов, следующие направления предназначены только для C#.While JavaScript supports Blob transcript storage, the following directions are for C# only.

Настройка контейнера хранилища для записи BLOB-объектовSet up a Blob transcript storage container

Хранилище расшифровок разговоров в BLOB-объектах Azure использует ту же учетную запись хранилища BLOB-объектов, которая описана в разделах Создание учетной записи хранилища BLOB-объектов и Добавление сведений о конфигурации выше.Azure blob transcript storage can use the same blob storage account created following the steps detailed in sections "Create your blob storage account" and "Add configuration information" above. Теперь добавьте контейнер для хранения расшифровок.We now add a container to hold our transcripts

Создание контейнера для расшифровок

  1. Откройте учетную запись хранилища BLOB-объектов AzureOpen your Azure blob storage account.
  2. выберите Обозреватель службы хранилища.Select Storage Explorer.
  3. Щелкните правой кнопкой мыши Контейнеры больших двоичных объектов и выберите Создать контейнер BLOB-объектов.Right click on BLOB CONTAINERS and select create blob container.
  4. Введите имя для контейнера транскрипции и нажмите кнопку ОК.Enter a name for your transcript container and then select OK. (Мы указали миботтранскриптс)(We entered mybottranscripts)

Реализация хранилища для записи большого двоичного объектаBlob transcript storage implementation

В коде ниже указатель на хранилище расшифровок _myTranscripts подключается к новой учетной записи хранилища BLOB-объектов с расшифровками.The following code connects transcript storage pointer _myTranscripts to your new Azure blob transcript storage account. Чтобы создать эту ссылку с новым именем контейнера, <your-blob-transcript-container-name> создает новый контейнер в хранилище BLOB-объектов для хранения файлов с транскрипциями.To create this link with a new container name, <your-blob-transcript-container-name>, creates a new container within Blob storage to hold your transcript files.

Хранилище для расшифровки BLOB-объектов предназначено для хранения записей роботов.Blob transcript storage is designed to store bot transcripts.

Примечание

Начиная с версии 4,10, Microsoft.Bot.Builder.Azure.AzureBlobTranscriptStore является устаревшим.As of version 4.10, Microsoft.Bot.Builder.Azure.AzureBlobTranscriptStore is deprecated. Используйте новый Microsoft.Bot.Builder.Azure.Blobs.BlobsTranscriptStore в своем месте.Use the new Microsoft.Bot.Builder.Azure.Blobs.BlobsTranscriptStore in its place.

echoBot.csechoBot.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-объектов AzureStore user conversations in azure blob transcripts

Создав контейнер 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 interact with your bot. каждый Emulator перезапуск диалога инициирует создание нового списка разговора.Each Emulator Restart conversation initiates the creation of a new transcript conversation list. Следующий код сохраняет диалог с пользователем в сохраненном файле с расшифровками.The following code preserves user conversation inputs within a stored transcript file.

  • Текущая расшифровка сохраняется с использованием LogActivityAsync.The current transcript is saved using LogActivityAsync.
  • Сохраненные расшифровки можно получить с использованием ListTranscriptsAsync.Saved transcripts are retrieved using ListTranscriptsAsync. В этом примере кода идентификатор каждой сохраненной расшифровки включается в список storedTranscripts.In this sample code the Id of each stored transcript is saved into a list named "storedTranscripts". Позже этот список используется для управления количеством расшифровок, хранимых в больших двоичных объектах.This list is later used to manage the number of stored blob transcripts we retain.

echoBot.csechoBot.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 stored blob transcripts

Хотя хранимые расшифровки можно использовать как средство отладки, со временем их количество превышает возможности хранилища.While stored transcripts can be used as a debugging tool, over time the number of stored transcripts can grow larger than you care to preserve. Дополнительный код ниже использует DeleteTranscriptAsync для удаления из хранилища BLOB-объектов всех извлеченных элементов расшифровок, кроме последних трех.The additional code included below uses DeleteTranscriptAsync to remove all but the last three retrieved transcript items from your blob transcript store.

echoBot.csechoBot.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 .See Azure Blob Transcript Storage for more information about the class.

Дополнительные сведенияAdditional Information

Управление параллелизмом с помощью тегов eTagManage concurrency using eTags

В нашем примере кода бота мы установили свойство eTag каждого экземпляра IStoreItem равным *.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.

Во-первых, создайте класс, который реализует IStoreItem.First, create a class that implements IStoreItem.

EchoBot.csEchoBot.cs

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

Затем создайте начальную заметку, создав объект хранилища и добавив объект в это хранилище.Next, create an initial note by creating a storage object, and add the object to your store.

EchoBot.csEchoBot.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, прочитанное из хранилища.Then, access and update the note later, keeping its eTag that you read from the store.

EchoBot.csEchoBot.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 возникнет исключение.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.

Дальнейшие действияNext steps

Теперь, когда вы знаете, как напрямую считывать данные из хранилища и записывать данные в хранилища, посмотрим, как сделать это с помощью диспетчера состояний.Now that you know how to read read and write directly from storage, lets take a look at how you can use the state manager to do that for you.