Escritura directa en el almacenamientoWrite directly to storage

se aplica a: SDK V4APPLIES TO: SDK v4

Puede leer y escribir directamente en el objeto de almacenamiento sin usar middleware ni un objeto de contexto.You can read and write directly to your storage object without using middleware or context object. Esto puede ser adecuado para los datos que el bot usa para conservar una conversación o los que provienen de un origen externo al flujo de conversación del bot.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. En este modelo de almacenamiento de datos, los datos se leen directamente desde el almacenamiento en lugar de usar un administrador de estados.In this data storage model, data is read in directly from storage instead of using a state manager. Los ejemplos de código de este artículo muestran cómo leer y escribir datos en el almacenamiento mediante el almacenamiento de memoria , Cosmos DB, Blob de Azure y almacenamiento de transcripciones de blobs de 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.

Requisitos previosPrerequisites

Nota

El paquete VSIX incluye las versiones .net Core 2,1 y .net Core 3,1 de las plantillas de C#.The VSIX package includes both .NET Core 2.1 and .NET Core 3.1 versions of the C# templates. Al crear nuevos bots en Visual Studio 2019, debe usar las plantillas de .NET Core 3.1.When creating new bots in Visual Studio 2019, you should use the .NET Core 3.1 templates. Los ejemplos de bot actuales usan plantillas de .NET Core 3.1.The current bot samples use .NET Core 3.1 templates. Encontrará los ejemplos que usan las plantillas de .NET Core 2.1 en la rama 4.7-archive del repositorio 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. Para obtener información sobre la implementación de bots de .NET Core 3,1 en Azure, consulte implementación de un bot en Azure.For information about deploying .NET Core 3.1 bots to Azure, see how to deploy your bot to Azure.

Acerca de este ejemploAbout this sample

El código de ejemplo de este artículo comienza con la estructura de un bot de eco básico y luego se amplía la funcionalidad de ese bot mediante la incorporación de código adicional (que se proporciona a continuación).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). Este código ampliado permite crear una lista para conservar las entradas del usuario tal como se reciben.This extended code creates a list to preserve user inputs as they are received. Cada turno, la lista completa de entradas del usuario, guardadas en memoria, se vuelve a hacer eco al usuario.Each turn, the full list of user inputs, saved to memory, is echoed back to the user. La estructura de datos que contiene esta lista de entradas se modifica para guardarla en el almacenamiento.The data structure containing this list of inputs is then modified to save to storage. Se exploran varios tipos de almacenamiento a medida que se agrega funcionalidad adicional a este código de ejemplo.Various types of storage are explored as additional functionality is added to this sample code.

Almacenamiento en memoriaMemory storage

Bot Framework SDK le permite almacenar las entradas del usuario mediante el almacenamiento en memoria.The Bot Framework SDK allows you to store user inputs using in-memory storage. Puesto que el almacenamiento en memoria se borra cada vez que se reinicia el bot, es más adecuado para fines de prueba y no está diseñado para su uso en producción.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. Los tipos de almacenamiento persistente, como el almacenamiento de base de datos, son los más adecuados para los bots de producción.Persistent storage types, such as database storage, are best for production bots.

Creación de un bot básicoBuild a basic bot

El resto de este tema se basa en un bot de eco.The rest of this topic builds off of an Echo bot. El código de ejemplo del bot de eco se puede compilar localmente siguiendo las instrucciones de inicio rápido para compilar el EchoBot en C#, JavaScript o Python.The Echo bot sample code can be locally built by following the Quickstart instructions for building the EchoBot in either C#, JavaScript or Python.

Reemplace el código de EchoBot.cs por el código siguiente: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!");
         }
      }
   }
}

Inicio del botStart your bot

Ejecute el bot localmente.Run your bot locally.

Inicio del emulador y conexión del botStart the Emulator and connect your bot

Instale el emulador Bot Framework siguiente, inicie el emulador y, a continuación, conéctese al bot en el emulador:Install the Bot Framework Emulator Next, start the Emulator and then connect to your bot in the Emulator:

  1. Seleccione el vínculo Create new bot configuration (Crear nueva configuración del bot) en la pestaña De bienvenida del emulador.Select the Create new bot configuration link in the Emulator Welcome tab.
  2. Rellene los campos para conectarse al bot con la información de la página web que aparece cuando inicia el bot.Fill in fields to connect to your bot, given the information on the webpage displayed when you started your bot.

Interacción con el botInteract with your bot

Envíe un mensaje al bot.Send a message to your bot. El bot mostrará la lista de mensajes que ha recibido.The bot will list the messages it has received.

Bot de almacenamiento de pruebas del emulador

En el resto de este artículo se muestra cómo guardar en el almacenamiento persistente en lugar de en la memoria interna del bot.The remainder of this article will demonstrate how to save to persistent storage instead of the bot's internal memory.

Uso de Cosmos DBUsing Cosmos DB

Importante

La clase almacenamiento de Cosmos DB está en desuso.The Cosmos DB storage class has been deprecated. Los contenedores creados originalmente con CosmosDbStorage no tenían ningún conjunto de claves de partición y se les dio la clave de partición predeterminada de _ / partitionKey.Containers originally created with CosmosDbStorage had no partition key set, and were given the default partition key of _/partitionKey.

Los contenedores creados Cosmos DB almacenamiento se pueden usar con Cosmos DB con particiones.Containers created with Cosmos DB storage can be used with Cosmos DB partitioned storage. Para más información, consulte Creación de particiones en Azure Cosmos DB.Read Partitioning in Azure Cosmos DB for more information.

Tenga en cuenta también que, a diferencia del almacenamiento de Cosmos DB heredado, el Cosmos DB con particiones no crea automáticamente una base de datos dentro de Cosmos DB cuenta.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. Debe crear manualmente una basede datos, pero omitir la creación manual de un contenedor, ya que CosmosDbPartitionedStorage creará el contenedor automáticamente.You need to create a new database manually, but skip manually creating a container since CosmosDbPartitionedStorage will create the container for you.

Ahora que ha usado el almacenamiento en memoria, actualizaremos el código para usar Azure Cosmos DB.Now that you've used memory storage, we'll update the code to use Azure Cosmos DB. Cosmos DB es la base de datos multimodelo de distribución global de Microsoft.Cosmos DB is Microsoft's globally distributed, multi-model database. Azure Cosmos DB permite escalar de forma elástica e individual el rendimiento y el almacenamiento en cualquiera de las regiones geográficas de Azure.Azure Cosmos DB enables you to elastically and independently scale throughput and storage across any number of Azure's geographic regions. Ofrece garantía de rendimiento, latencia, disponibilidad y coherencia con Acuerdos de Nivel de Servicio (SLA) integrales.It offers throughput, latency, availability, and consistency guarantees with comprehensive service level agreements (SLAs).

Configuración de un recurso Cosmos DB personalizadoSet up a Cosmos DB resource

Para utilizar Cosmos DB en el bot, es necesario crear un recurso de base de datos antes de meternos en el código.To use Cosmos DB in your bot, you'll need to create a database resource before getting into the code. Para obtener una descripción detallada de la creación Cosmos DB base de datos y la aplicación, consulte el inicio rápido de .NET, Node.js o Python.For an in-depth description of Cosmos DB database and app creation, see the quickstart for .Net, Node.js or Python.

Crear la cuenta de base de datosCreate your database account

  1. Vaya a Azure Portal para crear una cuenta de Azure Cosmos DB.Go to the Azure portal to create an Azure Cosmos DB account. Busque y seleccione Azure Cosmos DB.Search for and select Azure Cosmos DB.

  2. En la Azure Cosmos DB, seleccione Nuevo para abrir la página Crear Azure Cosmos DB cuenta.In the Azure Cosmos DB page, select New to bring up the the Create Azure Cosmos DB Account page.

    Creación de una cuenta de base de datos de Cosmos DB

  3. Proporcione valores para los campos siguientes:Provide values for the following fields:

    1. Suscripción.Subscription. Seleccione la suscripción de Azure que desea usar para esta cuenta de Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    2. Grupo de recursos.Resource group. Seleccione un grupo de recursos existente o seleccione Crear nuevo y escriba un nombre para un nuevo grupo de recursos.Select an existing resource group or select Create new, and enter a name for a new resource group.
    3. Nombre de cuenta.Account name. Escriba un nombre para identificar la cuenta de Azure Cosmos.Enter a name to identify your Azure Cosmos account. Dado que documents.azure.com se anexa al nombre que se proporciona para crear el identificador URI, debe usar un nombre único.Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name. Tenga en cuenta estas directrices:Note the following guidelines:
      • El nombre debe ser único en Azure.The name must be unique across Azure.
      • El nombre debe tener entre tres y 31 caracteres.The name must be between three and 31 characters long.
      • El nombre solo puede incluir letras minúsculas, números y el carácter de guion (-).The name can include only lowercase letters, numbers, and the hyphen (-) character.
    4. API.API. Seleccione Core(SQL)Select Core(SQL)
    5. Ubicación.Location. seleccione una ubicación más cercana a los usuarios para darles el acceso más rápido a los datos.select a location that is closest to your users to give them the fastest access to the data.
  4. Seleccione Revisar + crear.Select Review + Create.

  5. Una vez validado, seleccione Crear.Once validated, select Create.

La cuenta tarda unos minutos en crearse.The account creation takes a few minutes. Espere a que el portal muestre la página ¡Enhorabuena! Se ha creado su cuenta de Azure Cosmos DB.Wait for the portal to display the Congratulations! Your Azure Cosmos DB account was created page.

Agregar una base de datosAdd a database

Nota

No debe crear el contenedor usted mismo.You should not create the container yourself. El bot lo creará automáticamente al crear su cliente interno de Cosmos DB, asegurándose de que esté configurado correctamente para almacenar el estado del bot.Your bot will create it for you when creating its internal Cosmos DB client, ensuring it is configured correctly for storing bot state.

  1. Vaya a la página Explorador de datos de la cuenta de Cosmos DB recién creada y, a continuación, elija Nueva base de datos en la lista desplegable Nuevo contenedor.Navigate to the Data Explorer page within your newly created Cosmos DB account, then choose New Database from the New Container drop-down. A continuación, se abrirá un panel en el lado derecho de la ventana, donde puede especificar los detalles de la nueva base de datos.A panel will then open on the right hand side of the window, where you can enter the details for the new database.

    Creación de una Cosmos DB de recursos de base de datos

  2. Escriba un identificador para la nueva base de datos y, opcionalmente, establezca el rendimiento (puede cambiarlo más adelante) y, por último, seleccione Aceptar para crear la base de datos.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. Tome nota de este identificador de base de datos para usarlo más adelante al configurar el bot.Make a note of this database ID for use later on when configuring your bot.

  3. Ahora que ha creado una cuenta de Cosmos DB y una base de datos, debe copiar algunos valores para integrar la nueva base de datos en el bot.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. Para recuperarlos, vaya a la pestaña Claves de la sección de configuración de la base de datos de la cuenta de Cosmos DB.To retrieve these, navigate to the Keys tab within the database settings section of your Cosmos DB account. En esta página necesitará el URI (el punto de conexión Cosmos DB) y la CLAVE PRINCIPAL (clave de autorización).From this page you will need your URI (Cosmos DB endpoint) and your PRIMARY KEY (authorization key).

    Claves de Cosmos DB

Ahora debe tener una cuenta de Cosmos DB con una base de datos y los siguientes valores listos para usarse en la configuración del bot.You should now have a Cosmos DB account with a database and the following values ready to use in your bot settings.

  • URIURI
  • Clave principalPrimary Key
  • Identificador de base de datosDatabase ID

Agregar Cosmos DB de configuraciónAdd Cosmos DB configuration information

Use los detalles que anotó en la parte anterior de este artículo para establecer el punto de conexión, la clave de autorización y el identificador de base de datos.Use the details you made a note of in the previous part of this article to set your endpoint, authorization key and database ID. Por último, debe elegir un nombre apropiado para el contenedor que se creará en la base de datos para almacenar el estado de bot.Finally, you should choose an appropriate name for the container that will be created within your database to store your bot state. En el ejemplo siguiente, Cosmos DB contenedor que se crea se denominará "bot-storage".In the example below the Cosmos DB container that is created will be named "bot-storage".

Agregue la siguiente información al archivo de configuración.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"

Instalación de Cosmos DB paquetesInstalling Cosmos DB packages

Asegúrese de que tiene los paquetes necesarios para Cosmos DB.Make sure you have the packages necessary for Cosmos DB.

Instale el paquete NuGet Microsoft.Bot.Builder.Azure.Install the Microsoft.Bot.Builder.Azure NuGet package. Para obtener más información sobre el uso de NuGet, consulte Instalación y administración de paquetes en Visual Studio mediante el Administrador de paquetes NuGet. For more information on using NuGet, see Install and manage packages in Visual Studio using the NuGet Package Manager .

Cosmos DB implementaciónCosmos DB implementation

Nota

La versión 4.6 incorporó un nuevo proveedor de almacenamiento de Cosmos DB, la clase almacenamiento con particiones de Cosmos DB, y la clase almacenamiento de Cosmos DB ha quedado en desuso.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. Los contenedores creados Cosmos DB almacenamiento se pueden usar con Cosmos DB almacenamiento con particiones.Containers created with Cosmos DB storage can be used with Cosmos DB partitioned storage. Para más información, consulte Creación de particiones en Azure Cosmos DB.Read Partitioning in Azure Cosmos DB for more information.

Tenga en cuenta también que, a diferencia del almacenamiento de Cosmos DB heredado, el Cosmos DB con particiones no crea automáticamente una base de datos dentro de la Cosmos DB cuenta.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. Debe crear manualmente una basede datos, pero omitir la creación manual de un contenedor, ya que CosmosDbPartitionedStorage creará el contenedor automáticamente.You need to create a new database manually, but skip manually creating a container since CosmosDbPartitionedStorage will create the container for you.

El código de ejemplo siguiente se ejecuta con el mismo código de bot que el ejemplo de almacenamiento de memoria proporcionado anteriormente, con las excepciones enumeradas aquí.The following sample code runs using the same bot code as the memory storage sample provided above, with the exceptions listed here. Los fragmentos de código siguientes muestran una implementación de Cosmos DB storage para "myStorage" que reemplaza al almacenamiento de memoria local.The code snippets below show an implementation of Cosmos DB storage for 'myStorage' that replaces local Memory storage.

Primero debe actualizar Startup.cs para hacer referencia a la biblioteca de Azure bot builder:You first need to update Startup.cs to reference the bot builder Azure library:

using Microsoft.Bot.Builder.Azure;

A continuación, ConfigureServices en el método de Startup.cs, cree el CosmosDbPartitionedStorage objeto .Next, in the ConfigureServices method in Startup.cs, create the CosmosDbPartitionedStorage object. Esto se pasará al constructor mediante la EchoBot inserción de dependencias.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,
        }));

En EchoBot.cs, cambie la _myStorage declaración de variable a lo private static readonly MemoryStorage _myStorage = new MemoryStorage(); siguiente: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;

A continuación, pase IStorage el objeto al EchoBot constructor:Then pass in the IStorage object to the EchoBot constructor:

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

Inicio del Cosmos DB botStart your Cosmos DB bot

Ejecute el bot localmente.Run your bot locally.

Pruebe el bot Cosmos DB con Bot Framework EmulatorTest your Cosmos DB bot with Bot Framework Emulator

Ahora, inicie el Bot Framework Emulator y conéctese al bot:Now start the Bot Framework Emulator and connect to your bot:

  1. Seleccione el vínculo Create a new bot configuration (Crear una nueva configuración de bot) en la pestaña De bienvenida del emulador.Select the create a new bot configuration link in the Emulator Welcome tab.
  2. Rellene los campos para conectarse al bot con la información de la página web que aparece cuando inicia el bot.Fill in fields to connect to your bot, given the information on the webpage displayed when you started your bot.

Interacción con el Cosmos DB botInteract with your Cosmos DB bot

Envíe un mensaje al bot y este enumerará los mensajes que ha recibido.Send a message to your bot, and the bot will list the messages it received. Emulador en ejecuciónEmulator running

Visualización de los Cosmos DB datosView your Cosmos DB data

Después de ejecutar el bot y guardar la información, podemos ver los datos almacenados en Azure Portal en la pestaña Explorador de datos.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.

Ejemplo del Explorador de datos

Uso de Blob StorageUsing Blob storage

Azure Blob Storage es la solución de almacenamiento de objetos de Microsoft para la nube.Azure Blob storage is Microsoft's object storage solution for the cloud. Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados, como texto o datos binarios.Blob storage is optimized for storing massive amounts of unstructured data, such as text or binary data. En esta sección se explica cómo crear una cuenta y un contenedor de Azure Blob Storage y, a continuación, cómo hacer referencia al contenedor de Blob Storage desde el bot.This section explains how to create an Azure blob storage account and container, then how to reference your blob storage container from your bot.

Para más información sobre Blob Storage, consulte ¿Qué es Azure Blob Storage?For additional information on Blob Storage, see What is Azure Blob storage?

Creación de la cuenta de Blob StorageCreate your Blob storage account

Para utilizar Blob Storage en el bot, es necesario configurar algunas cosas antes de meternos en el código.To use Blob storage in your bot, you'll need to get a few things set up before getting into the code.

  1. En Azure Portal, seleccione Todos los servicios.In the Azure portal, select All services.

  2. En la sección Destacados de la página Todos los servicios, seleccione Cuentas de almacenamiento.In the Featured section of the All services page, select Storage accounts.

  3. En la página Cuentas de almacenamiento, seleccione Nuevo..In the Storage accounts page, select **New****.

    Página Creación de una cuenta de almacenamiento de blobs

  4. Seleccione la suscripción en la que se va a crear la cuenta de almacenamiento en el campo Suscripción.In the Subscription field, select the subscription in which to create the storage account.

  5. En el campo del Grupo de recursos, seleccione un grupo de recursos existente o Crear nuevo y escriba un nombre para el grupo de recursos.In the Resource group field, select an existing resource group or select Create new, and enter a name for the new resource group.

  6. En el campo Nombre de la cuenta de almacenamiento, escriba un nombre para la cuenta.In the Storage account name field, enter a name for the account. Tenga en cuenta estas directrices:Note the following guidelines:

    • El nombre debe ser único en Azure.The name must be unique across Azure.
    • El nombre debe tener entre tres y 24 caracteres.The name must be between three and 24 characters long.
    • El nombre solo puede contener números y letras minúsculas.The name can include only numbers and lowercase letters.
  7. En el campo Ubicación, seleccione una ubicación para la cuenta de almacenamiento o utilice la ubicación predeterminada.In the Location field, select a location for the storage account, or use the default location.

  8. Defina la configuración de los siguientes valores:For the rest of the settings, configure the following:

  9. En la sección Detalles del proyecto de la página Crear cuenta de almacenamiento, seleccione los valores deseados para la suscripción y el grupo de recursos.In the Project details section of the Create storage account page, select the desired values for subscription and Resource group.

  10. En la sección Detalles de instancia de la página Crear cuenta de almacenamiento, escriba el nombre de la cuenta de almacenamiento y, a continuación, seleccione los valores ubicación, tipo de cuenta y replicación.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. Seleccione Revisar y crear para revisar la configuración de la cuenta de almacenamiento.Select Review + create to review the storage account settings.

  12. Una vez validado, seleccione Crear.Once validated, select Create.

Creación de un contenedor de Blob StorageCreate Blob storage container

Una vez creada la cuenta de Blob Storage, ábrala y, a continuación:Once your Blob storage account is created, open it, then:

  1. Seleccione Explorador de Storage (versión preliminar).Select Storage Explorer (Preview).

  2. A continuación, haga clic con el botón derecho en CONTENEDORES DE BLOBS.Then right-click on BLOB CONTAINERS

  3. Seleccione Crear contenedor de blobs en la lista desplegable.Select Create blob container from the drop-down list.

    Creación de un contenedor de Blob Storage

  4. Escriba un nombre en el formulario Nuevo contenedor.Enter a name in the New container form. Usará este nombre para el valor de "blob-storage-container-name" para proporcionar acceso a la cuenta de Blob Storage.You will use this name for the value of your "blob-storage-container-name" to provide access to your Blob storage account. Tenga en cuenta estas directrices:Note the following guidelines:

    • Este nombre solo puede contener letras minúsculas, números y guiones.This name may only contain lowercase letters, numbers, and hyphens.
    • Este nombre debe comenzar por una letra o un número.This name must begin with a letter or a number.
    • Cada guion debe ir precedido y seguido de un carácter no guion válido.Each hyphen must be preceded and followed by a valid non-hyphen character.
    • El nombre debe tener entre tres y 63 caracteres.The name must be between three and 63 characters long.

Adición de información de configuración de Blob StorageAdd Blob storage configuration information

Busque las claves de Blob Storage que necesita para configurar Blob Storage para el bot, como se ha mostrado anteriormente:Find the Blob storage keys you need to configure Blob storage for your bot as shown above:

  1. En la Azure Portal, abra la cuenta de Blob Storage y seleccione Claves de acceso en la sección Configuración.In the Azure portal, open your Blob storage account and select Access keys in the Settings section.

    Buscar claves de Blob Storage

Use Cadena de conexión como valor de " cadena de conexión" para proporcionar acceso a la cuenta de Blob Storage.Use Connection string as the value for your "connection-string" to provide access to your Blob storage account.

Agregue la siguiente información al archivo de configuración.Add the following information to your configuration file.

appsettings.jsonappsettings.json

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

Instalación de paquetes de Blob StorageInstalling Blob storage packages

Si no se ha instalado previamente, instale los siguientes paquetes.If not previously installed, install the following packages.

Instale el paquete NuGet Microsoft.Bot.Builder.Azure.Blobs.Install the Microsoft.Bot.Builder.Azure.Blobs NuGet package. Para obtener más información sobre el uso de NuGet, consulte Instalación y administración de paquetes en Visual Studio mediante el Administrador de paquetes NuGet.For more information on using NuGet, see Install and manage packages in Visual Studio using the NuGet Package Manager.

Implementación de Blob StorageBlob storage implementation

Blob Storage se usa para almacenar el estado del bot.Blob storage is used to store bot state.

Nota

A partir de la versión 4.10, Microsoft.Bot.Builder.Azure.AzureBlobStorage está en desuso.As of version 4.10, Microsoft.Bot.Builder.Azure.AzureBlobStorage is deprecated. Use el nuevo Microsoft.Bot.Builder.Azure.Blobs.BlobsStorage en su lugar.Use the new Microsoft.Bot.Builder.Azure.Blobs.BlobsStorage in its place.

El código de ejemplo siguiente se ejecuta con el mismo código de bot que el ejemplo de almacenamiento de memoria proporcionado anteriormente, con las excepciones enumeradas aquí.The following sample code runs using the same bot code as the memory storage sample provided above, with the exceptions listed here.

Los fragmentos de código siguientes muestran una implementación de Blob Storage para "myStorage" que reemplaza al almacenamiento de memoria local.The code snippets below show an implementation of Blob storage for 'myStorage' that replaces local Memory storage.

Primero debe actualizar Startup.cs para hacer referencia a la biblioteca de blobs de Azure del generador de bots:You first need to update Startup.cs to reference the bot builder Azure blobs library:

Startup.csStartup.cs

using Microsoft.Bot.Builder.Azure.Blobs;

A continuación, ConfigureServices en el método de Startup.cs, cree el BlobsStorage objeto y pase los valores de appsettings.json .Next, in the ConfigureServices method in Startup.cs, create the BlobsStorage object, passing in the values from appsettings.json. Esto se pasará al constructor mediante la EchoBot inserción de dependencias.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")
        ));

Ahora primero debe actualizar EchoBot.cs para hacer referencia a la biblioteca de blobs de Azure del generador de bots: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;

A continuación, quite o comente la línea de código que crea la variable MemoryStorage "private static readonly MemoryStorage _myStorage = new MemoryStorage();" y cree una nueva variable que se usará para guardar la entrada del usuario en el Blob Storage.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;

A continuación, pase IStorage el objeto al EchoBot constructor:Then pass in the IStorage object to the EchoBot constructor:

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

Una vez que el almacenamiento está establecido para que apunte a la cuenta de Blob Storage, el código del bot almacenará y recuperará datos de Blob Storage.Once your storage is set to point to your Blob Storage account, your bot code will now store and retrieve data from Blob storage.

Una vez que el almacenamiento está establecido para que apunte a la cuenta de Blob Storage, el código del bot almacenará y recuperará datos de Blob Storage.Once your storage is set to point to your Blob Storage account, your bot code will now store and retrieve data from Blob storage.

Inicio del bot de Blob StorageStart your Blob storage bot

Ejecute el bot localmente.Run your bot locally.

Iniciar el emulador y conectar el bot de Blob StorageStart the Emulator and connect your Blob storage bot

A continuación, inicie el emulador y conéctese al bot en el emulador:Next, start the Emulator and then connect to your bot in the Emulator:

  1. Seleccione el vínculo Crear nueva configuración del bot en la pestaña "Bienvenida" del emulador.Select the Create new bot configuration link in the Emulator "Welcome" tab.
  2. Rellene los campos para conectarse al bot con la información de la página web que aparece cuando inicia el bot.Fill in fields to connect to your bot, given the information on the webpage displayed when you started your bot.

Interacción con el bot de Blob StorageInteract with your Blob storage bot

Envíe un mensaje al bot y este mostrará una lista de los mensajes que recibe.Send a message to your bot, and the bot will list the messages it receives.

Bot de almacenamiento de pruebas del emulador

Visualización de los datos de Blob StorageView your Blob storage data

Después de ejecutar el bot y guardar la información, lo podemos ver en la pestaña Explorador de Storage de Azure Portal.After you have run your bot and saved your information, we can view it in under the Storage Explorer tab in the Azure portal.

Almacenamiento de transcripciones de blobsBlob transcript storage

El almacenamiento de transcripciones de blobs de Azure ofrece una opción de almacenamiento especializado que le permite guardar y recuperar con facilidad las conversaciones del usuario en forma de una transcripción grabada.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. El almacenamiento de transcripciones de blobs de Azure es especialmente útil para capturar automáticamente las entradas de usuario para examinarlas al tiempo que se depura el rendimiento del bot.Azure blob transcript storage is particularly useful for automatically capturing user inputs to examine while debugging your bot's performance.

Nota

Python no admite actualmente el almacenamiento de transcripciones de blobs de Azure.Python does not currently support Azure Blob transcript storage. Aunque JavaScript admite el almacenamiento de transcripciones de blobs, las instrucciones siguientes son solo para C#.While JavaScript supports Blob transcript storage, the following directions are for C# only.

Configuración de un contenedor de almacenamiento de transcripciones de blobsSet up a Blob transcript storage container

El almacenamiento de transcripciones de blobs de Azure puede usar la misma cuenta de Blob Storage que creó siguiendo los pasos detallados en las secciones "Creación de la cuenta de Blob Storage" y "Adición de la información de configuración" anteriores.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. Ahora se agrega un contenedor para almacenar las transcripcionesWe now add a container to hold our transcripts

Creación de un contenedor de transcripciones

  1. Abra la cuenta de Azure Blob Storage.Open your Azure blob storage account.
  2. Seleccione Explorador de Storage.Select Storage Explorer.
  3. Haga clic con el botón derecho en CONTENEDORES DE BLOB y seleccione Crear contenedor de blobs.Right click on BLOB CONTAINERS and select create blob container.
  4. Escriba un nombre para el contenedor de transcripciones y seleccione Aceptar.Enter a name for your transcript container and then select OK. (Hemos escrito mybottranscripts)(We entered mybottranscripts)

Implementación del almacenamiento de transcripciones de blobsBlob transcript storage implementation

El siguiente código conecta el puntero de almacenamiento de transcripciones _myTranscripts a la nueva cuenta de almacenamiento de transcripciones de blobs de Azure.The following code connects transcript storage pointer _myTranscripts to your new Azure blob transcript storage account. Para crear este vínculo con un nuevo nombre de contenedor, , crea un nuevo contenedor en <your-blob-transcript-container-name> Blob Storage para almacenar los archivos de transcripción.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.

El almacenamiento de transcripciones de blobs está diseñado para almacenar transcripciones de bots.Blob transcript storage is designed to store bot transcripts.

Nota

A partir de la versión 4.10, Microsoft.Bot.Builder.Azure.AzureBlobTranscriptStore está en desuso.As of version 4.10, Microsoft.Bot.Builder.Azure.AzureBlobTranscriptStore is deprecated. Use el nuevo Microsoft.Bot.Builder.Azure.Blobs.BlobsTranscriptStore en su lugar.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>");

   ...
}

Almacenamiento de las conversaciones del usuario en transcripciones de blobs de AzureStore user conversations in azure blob transcripts

Después de tener disponible un contenedor de blobs para almacenar las transcripciones, puede comenzar a conservar las conversaciones de los usuarios con el bot.After a blob container is available to store transcripts you can begin to preserve your users' conversations with your bot. Estas conversaciones se pueden utilizar más adelante como una herramienta de depuración para ver cómo interactúan los usuarios con el bot.These conversations can later be used as a debugging tool to see how users interact with your bot. Cada conversación de reinicio del emulador inicia la creación de una nueva lista de conversaciones de transcripción.Each Emulator Restart conversation initiates the creation of a new transcript conversation list. El siguiente código conserva las entradas de la conversación del usuario en un archivo de transcripciones almacenado.The following code preserves user conversation inputs within a stored transcript file.

  • La transcripción actual se guarda mediante LogActivityAsync.The current transcript is saved using LogActivityAsync.
  • Las transcripciones guardadas se recuperan mediante ListTranscriptsAsync.Saved transcripts are retrieved using ListTranscriptsAsync. En este ejemplo de código, el identificador de cada transcripción almacenada se guarda en una lista llamada "storedTranscripts".In this sample code the Id of each stored transcript is saved into a list named "storedTranscripts". Esta lista se usa más adelante para administrar el número de transcripciones de blobs almacenadas que se conservan.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);

    ...
}

Administración de las transcripciones de blobs almacenadasManage stored blob transcripts

Aunque las transcripciones almacenadas se pueden usar como una herramienta de depuración, con el tiempo, el número de transcripciones almacenadas puede crecer más de lo que desea conservar.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. El código adicional que se incluye a continuación usa DeleteTranscriptAsync para eliminarlas todas excepto los tres últimos elementos de transcripción recuperados del almacén de transcripciones del 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);
           }
       }
    }
    ...
}

Consulte Azure Blob Transcript Storage para obtener más información sobre la clase .See Azure Blob Transcript Storage for more information about the class.

Información adicionalAdditional Information

Administración de la simultaneidad mediante eTagsManage concurrency using eTags

En nuestro ejemplo de código de bot, establecemos la propiedad eTag de cada elemento IStoreItem en *.In our bot code example we set the eTag property of each IStoreItem to *. Cosmos DB utiliza el miembro eTag (etiqueta de entidad) del objeto de almacén para administrar la simultaneidad.The eTag (entity tag) member of your store object is used within Cosmos DB to manage concurrency. La etiqueta eTag indica a la base de datos qué hacer si otra instancia del bot ha cambiado el objeto en el mismo almacenamiento en el que está escribiendo su bot.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.

La última escritura tiene prioridad: permitir la sobrescrituraLast write wins - allow overwrites

Un valor de propiedad eTag de asterisco (*) indica que la última escritura tiene prioridad.An eTag property value of asterisk (*) indicates that the last writer wins. Al crear un nuevo almacén de datos, puede establecer la etiqueta eTag de una propiedad en * para indicar que no ha guardado previamente los datos que está escribiendo, o que desea que el último escritor sobrescriba cualquier propiedad guardada previamente.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. Si la simultaneidad no es un problema para el bot, establezca la propiedad eTag en * para habilitar la sobrescritura para los datos que escriba.If concurrency is not an issue for your bot, setting the eTag property to * for any data that you are writing enables overwrites.

Mantenimiento de la simultaneidad y evitación de la sobrescrituraMaintain concurrency and prevent overwrites

Cuando almacene datos en Cosmos DB, use un valor distinto de * en la propiedad eTag si desea evitar el acceso simultáneo a una propiedad y sobrescribir los cambios de otra instancia del bot.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. El bot recibe una respuesta de error con el mensaje etag conflict key= cuando intenta guardar los datos de estado, y la etiqueta eTag no tiene el mismo valor que eTag en el almacenamiento.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.

De forma predeterminada, el almacén de Cosmos DB comprueba la igualdad de la propiedad eTag de un objeto de almacenamiento cada vez que un bot escribe en ese elemento y, a continuación, lo actualiza a un nuevo valor único después de cada escritura.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. Si la propiedad eTag en la escritura no coincide con la eTag en el almacenamiento, significa que otro subproceso o bot ha cambiado los datos.If the eTag property on write doesn't match the eTag in storage, it means another bot or thread changed the data.

Por ejemplo, supongamos que desea que su bot edite una nota guardada, pero no quiere que sobrescriba los cambios que haya realizado otra instancia del bot.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. Si otra instancia del bot ha realizado modificaciones, lo que quiere es que el usuario edite la versión con las actualizaciones más recientes.If another instance of the bot has made edits, you want the user to edit the version with the latest updates.

Primero, cree una clase que implemente 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; }
}

A continuación, cree una nota inicial mediante la creación de un objeto de almacenamiento y agregue el objeto a su almacén.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);

A continuación, acceda y actualice la nota más adelante, manteniendo su eTag que usted lee desde el almacén.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);
}

Si se ha actualizado la nota en el almacén antes de que haya escrito los cambios, la llamada a Write iniciará una excepción.If the note was updated in the store before you write your changes, the call to Write will throw an exception.

Para mantener la simultaneidad, siempre es necesario leer una propiedad desde el almacenamiento y luego modificar la propiedad que se ha leído, de esta manera eTag se mantiene.To maintain concurrency, always read a property from storage, then modify the property you read, so that the eTag is maintained. Si lee datos de usuario desde el almacén, la respuesta contendrá la propiedad de eTag.If you read user data from the store, the response will contain the eTag property. Si cambia los datos y escribe datos actualizados en el almacén, la solicitud debe incluir la propiedad de eTag que especifica el mismo valor que leyó anteriormente.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. Sin embargo, escribir un objeto con su eTag establecida en * permitirá que la escritura sobrescriba cualquier otro cambio.However, writing an object with its eTag set to * will allow the write to overwrite any other changes.

Pasos siguientesNext steps

Ahora que sabe cómo leer lectura y escritura directamente desde el almacenamiento, eche un vistazo a cómo puede usar el Administrador de estado para que lo haga por usted.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.