Écrire directement dans le stockageWrite directly to storage

s’applique à : SDK v4APPLIES TO: SDK v4

Vous pouvez lire et écrire directement dans votre objet de stockage sans utiliser d’intergiciel ou d’objet de contexte.You can read and write directly to your storage object without using middleware or context object. Cela peut convenir pour les données que votre bot utilise afin de préserver une conversation, ou les données provenant d'une source située en dehors du flux de conversation de votre 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. Dans ce modèle de stockage de données, plutôt que d'utiliser un gestionnaire d'états, les données sont lues directement à partir du stockage.In this data storage model, data is read in directly from storage instead of using a state manager. Les exemples de code de cet article vous montrent comment lire et écrire des données dans le stockage à l’aide de la mémoire, Cosmos DB, un objet BLOB Azure et le stockage de transcription d’objets 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.

PrérequisPrerequisites

Notes

Le package VSIX comprend à la fois les versions .net Core 2,1 et .net Core 3,1 des modèles C#.The VSIX package includes both .NET Core 2.1 and .NET Core 3.1 versions of the C# templates. Quand vous créez de nouveaux bots dans Visual Studio 2019, vous devez utiliser les modèles .NET Core 3.1.When creating new bots in Visual Studio 2019, you should use the .NET Core 3.1 templates. Les exemples de bot actuels utilisent des modèles .NET Core 3.1.The current bot samples use .NET Core 3.1 templates. Vous trouverez les exemples qui utilisent les modèles .NET Core 2.1 dans la branche 4.7-archive du dépôt 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. Pour plus d’informations sur le déploiement de robots .NET Core 3,1 sur Azure, consultez Comment déployer votre robot sur Azure.For information about deploying .NET Core 3.1 bots to Azure, see how to deploy your bot to Azure.

À propos de cet exempleAbout this sample

L’exemple de code de cet article commence par la structure d’un bot d’écho de base, puis étend les fonctionnalités de ce bot par ajout de code (ci-dessous).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). Ce code étendu crée une liste pour conserver les entrées utilisateur au fur et à mesure qu’elles sont reçues.This extended code creates a list to preserve user inputs as they are received. À chaque tour, la liste complète des entrées utilisateur est répercutée vers l’utilisateur.Each turn, the full list of user inputs is echoed back to the user. La structure de données contenant cette liste d’entrées est ensuite enregistrée dans le stockage à la fin du tour.The data structure containing this list of inputs is then saved to storage at the end of that turn. Divers types de stockage sont explorés à mesure que des fonctionnalités supplémentaires sont ajoutées à cet exemple de code.Various types of storage are explored as additional functionality is added to this sample code.

Stockage mémoireMemory storage

Le kit SDK Bot Framework permet de stocker les entrées utilisateur en utilisant un stockage en mémoire.The Bot Framework SDK allows you to store user inputs using in-memory storage. Le stockage mémoire est utilisé uniquement à des fins de test et n’est pas destiné à une utilisation en production.Memory storage is used for testing purposes only and is not intended for production use. Le stockage en mémoire est volatile et temporaire puisque les données sont effacées à chaque redémarrage du bot.In-memory storage is volatile and temporary since the data is cleared each time the bot is restarted. Les types de stockage persistant, tels que le stockage de base de données, sont plus adaptés aux bots de production.Persistent storage types, such as database storage, are best for production bots. Veillez à définir le stockage sur Cosmos DB, Stockage Blob ou Stockage de table Azure avant de publier votre bot.Be sure to set storage to Cosmos DB, Blob Storage, or Azure Table storage before publishing your bot.

Créer un bot de baseBuild a basic bot

Le reste de cette rubrique s’appuie sur un bot Echo.The rest of this topic builds off of an Echo bot. Vous pouvez générer localement l’exemple de code de bot d’écho en suivant les instructions du guide de démarrage rapide pour la génération d’un EchoBot en C#, d’un EchoBot en JS ou d’un EchoBot en Python.The Echo bot sample code can be locally built by following the Quickstart instructions for building either a C# EchoBot, JS EchoBot or Python EchoBot.

EchoBot.csEchoBot.cs

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Démarrer votre robotStart your bot

Exécutez votre bot en local.Run your bot locally.

Démarrer l’émulateur et connecter votre robotStart the Emulator and connect your bot

Installer l' émulateur de l’infrastructure bot ensuite, démarrez l’émulateur, puis connectez-vous à votre bot dans l’émulateur :Install the Bot Framework Emulator Next, start the Emulator and then connect to your bot in the Emulator:

  1. Cliquez sur le lien créer une nouvelle configuration de bot sous l’onglet « Bienvenue » de l’émulateur.Click the Create new bot configuration link in the Emulator "Welcome" tab.
  2. Renseignez les champs pour vous connecter à votre bot en utilisant les informations figurant dans la page web affichée lorsque vous avez démarré votre bot.Fill in fields to connect to your bot, given the information on the webpage displayed when you started your bot.

Interagir avec votre botInteract with your bot

Envoyez un message à votre bot.Send a message to your bot. Le bot liste les messages qu’il a reçus.The bot will list the messages it has received.

Bot de stockage de test d’émulateur

Utilisation de Cosmos DBUsing Cosmos DB

Important

La classe de stockage Cosmos DB est dépréciée.The Cosmos DB storage class has been deprecated. Les conteneurs créés à l’origine avec CosmosDbStorage n’ont pas de clé de partition définie, et ont la clé de partition par défaut _ / partitionKey.Containers originally created with CosmosDbStorage had no partition key set, and were given the default partition key of _/partitionKey.

Les conteneurs créés avec un stockage Cosmos DB peuvent être utilisés avec Cosmos DB le stockage partitionné.Containers created with Cosmos DB storage can be used with Cosmos DB partitioned storage. Pour plus d’informations, consultez Partitionnement dans Azure Cosmos DB.Read Partitioning in Azure Cosmos DB for more information.

Notez également que, contrairement au stockage Cosmos DB hérité, le stockage partitionné Cosmos DB ne crée pas automatiquement une base de données dans votre compte 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. Vous devez créer une nouvelle base de données manuellement, mais ignorer la création manuelle d’un conteneur, car CosmosDbPartitionedStorage crée le conteneur pour vous.You need to create a new database manually, but skip manually creating a container since CosmosDbPartitionedStorage will create the container for you.

Maintenant que vous avez utilisé le stockage mémoire, nous allons mettre à jour le code pour utiliser Azure Cosmos DB.Now that you've used memory storage, we'll update the code to use Azure Cosmos DB. Cosmos DB est un service de base de données multimodèle mondialement distribué de Microsoft.Cosmos DB is Microsoft's globally distributed, multi-model database. Azure Cosmos DB vous permet de faire évoluer en toute flexibilité et de façon indépendante le débit et le stockage sur n’importe quel nombre de régions géographiques Azure.Azure Cosmos DB enables you to elastically and independently scale throughput and storage across any number of Azure's geographic regions. Il offre des garanties en termes de débit, de latence, de disponibilité et de cohérence avec des contrats SLA complets.It offers throughput, latency, availability, and consistency guarantees with comprehensive service level agreements (SLAs).

Configurer une ressource Cosmos DBSet up a Cosmos DB resource

Pour utiliser Cosmos DB dans votre bot, vous devez créer une ressource de base de données avant d’aborder le code.To use Cosmos DB in your bot, you'll need to create a database resource before getting into the code. Pour une description approfondie de la création de base de données et d’application par Cosmos DB, accédez ici à la documentation pour Cosmos DB dotnet ou Cosmos DB nodejs.For an in-depth description of Cosmos DB database and app creation access the documentation here for Cosmos DB dotnet or Cosmos DB nodejs.

Créer votre compte de base de donnéesCreate your database account

  1. Dans une nouvelle fenêtre du navigateur, connectez-vous au portail Azure.In a new browser window, sign in to the Azure portal.

    Créer un compte de base de données Cosmos DB

  2. Cliquez sur Créer une ressource > Bases de données > Azure Cosmos DBClick Create a resource > Databases > Azure Cosmos DB

    Nouvelle page de compte Cosmos DB

  3. Dans la page Nouveau compte, spécifiez les informations Abonnement et Groupe de ressources.On the New account page, provide Subscription, Resource group information. Créez un nom unique pour votre champ Nom du compte. Il figurera finalement dans votre nom d’URL d’accès aux données.Create a unique name for your Account Name field - this eventually becomes part of your data access URL name. Pour API, sélectionnez Core(SQL) et fournissez un emplacement proche pour réduire le temps d’accès aux données.For API, select Core(SQL), and provide a nearby Location to improve data access times.

  4. Ensuite, cliquez sur Vérifier + créer.Then click Review + Create.

  5. Une fois la validation réussie, cliquez sur Créer.Once validation has been successful, click Create.

La création du compte prend quelques minutes.The account creation takes a few minutes. Attendez que le portail affiche la page Congratulations!Wait for the portal to display the Congratulations! Your Azure Cosmos DB account was created (Félicitations ! Votre compte Azure Cosmos DB a été créé).Your Azure Cosmos DB account was created page.

Ajouter une base de donnéesAdd a database

Important

Contrairement au stockage Cosmos DB hérité, qui est désormais déconseillé, le cosmos DB le stockage partitionné ne crée pas automatiquement une base de données au sein de votre compte Cosmos DB.Unlike the legacy Cosmos DB storage, which has now been deprecated, the Cosmos DB partitioned storage does not automatically create a database within your Cosmos DB account.

  1. Accédez à la page Explorateur de données de votre compte Cosmos DB nouvellement créé, puis choisissez Créer une base de données dans la zone de liste déroulante en regard du bouton Créer un conteneur.Navigate to the Data Explorer page within your newly created Cosmos DB account, then choose Create Database from the drop-down box next to the Create Container button. Un panneau s’ouvre sur le côté droit de la fenêtre, où vous pouvez entrer les détails de la nouvelle base de données.A panel will then open on the right hand side of the window, where you can enter the details for the new database.

    Créer une image de ressource cosmosdb base

  2. Attribuez un ID à votre nouvelle base de données et, si vous le souhaitez, définissez le débit (vous pouvez le modifier pas la suite), puis cliquez sur OK pour créer votre base de données.Enter an ID for your new database and, optionally, set the throughput (you can change this later) and finally click OK to create your database. Notez cet ID de base de données, vous en aurez besoin par la suite pour configurer votre bot.Make a note of this database ID for use later on when configuring your bot.

    Image de détails de ressource de base de données Cosmos cosmosdb

  3. Maintenant que vous avez créé un compte et une base de données Cosmos DB, vous devez copier certaines des valeurs pour intégrer la nouvelle base de données dans votre 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. Pour les récupérer, accédez à l’onglet Clés dans les paramètres de base de données de votre compte Cosmos DB.To retrieve these, navigate to the Keys tab within the database settings section of your Cosmos DB account. Dans cette page, vous aurez besoin de votre point de terminaison Cosmos DB (URI) et de votre clé d’autorisation (CLÉ PRIMAIRE).From this page you will need your Cosmos DB endpoint (URI) and your authorization key (PRIMARY KEY).

    Clés Cosmos DB

Vous devez maintenant disposer d’un compte Cosmos DB contenant une base de données ainsi que des détails ci-dessous pour configurer votre bot.You should now have a Cosmos DB account, containing a database and have the following details ready to configure your bot.

  • Point de terminaison Cosmos DBCosmos DB Endpoint
  • Clé d’autorisationAuthorization Key
  • ID de base de donnéesDatabase ID

Ajouter des informations de configuration Cosmos DBAdd Cosmos DB configuration information

Les données de configuration permettant d’ajouter un stockage Cosmos DB sont succinctes et simples.Our configuration data to add Cosmos DB storage is short and simple. Utilisez les détails que vous avez notés dans la section précédente de cet article pour définir votre point de terminaison, la clé d’autorisation et l’ID de base de données.Use the details you made a note of in the previous part of this article to set your endpoint, authorization key and database ID. Enfin, vous devez attribuer un nom approprié au conteneur qui sera créé dans votre base de données pour stocker l’état de votre bot.Finally, you should choose an appropriate name for the container that will be created within your database to store your bot state. Dans l’exemple ci-dessous, le conteneur est appelé « bot-storage ».In the example below the container will be called "bot-storage".

Notes

Vous ne devez pas créer vous-même le conteneur.You should not create the container yourself. Votre bot le créera à votre place, en même temps que son client Cosmos DB, tout en veillant à ce qu’il soit correctement configuré pour le stockage de l’état du bot.Your bot will create it for you when creating its internal Cosmos DB client, ensuring it is configured correctly for storing bot state.

Ajoutez les informations suivantes à votre fichier de configuration.Add the following information to your configuration file.

appsettings.jsonappsettings.json

"CosmosDbEndpoint": "<your-cosmosdb-uri>",
"CosmosDbAuthKey": "<your-authorization-key>",
"CosmosDbDatabaseId": "<your-database-id>",
"CosmosDbContainerId": "<your-container-id>"

Installation des packages Cosmos DBInstalling Cosmos DB packages

Veillez à disposer des packages nécessaires pour Cosmos DB.Make sure you have the packages necessary for Cosmos DB.

Install-Package Microsoft.Bot.Builder.Azure

Implémentation de Cosmos DBCosmos DB implementation

Notes

La version 4.6 a introduit un nouveau fournisseur de stockage Cosmos DB, la classe de stockage partitionné Cosmos DB, tandis que la classe de stockage Cosmos DB d’origine est dépréciée.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. Les conteneurs créés avec un stockage Cosmos DB peuvent être utilisés avec Cosmos DB le stockage partitionné.Containers created with Cosmos DB storage can be used with Cosmos DB partitioned storage. Pour plus d’informations, consultez Partitionnement dans Azure Cosmos DB.Read Partitioning in Azure Cosmos DB for more information.

Notez également que, contrairement au stockage Cosmos DB hérité, le stockage partitionné Cosmos DB ne crée pas automatiquement une base de données dans votre compte 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. Vous devez créer une nouvelle base de données manuellement, mais ignorer la création manuelle d’un conteneur, car CosmosDbPartitionedStorage crée le conteneur pour vous.You need to create a new database manually, but skip manually creating a container since CosmosDbPartitionedStorage will create the container for you.

L’exemple de code suivant s’exécute avec le même code de bot que l’exemple de stockage mémoire fourni ci-dessus.The following sample code runs using the same bot code as the memory storage sample provided above. L’extrait de code ci-dessous illustre une implémentation de stockage Cosmos DB pour « myStorage » qui remplace le stockage mémoire local.The code snippet below shows an implementation of Cosmos DB storage for 'myStorage' that replaces local Memory storage. Le stockage de mémoire est mis en commentaires et remplacé par une référence à Cosmos DB.Memory Storage is commented out and replaced with a reference to Cosmos DB.

Startup.csStartup.cs

using Microsoft.Bot.Builder.Azure;

Dans ConfigureServices, créez l’instance de stockage pour le stockage partitionné CosmosDB.Within ConfigureServices, create the storage instance for CosmosDB partitioned storage.

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

Démarrez votre robot Cosmos DBStart your Cosmos DB bot

Exécutez votre bot en local.Run your bot locally.

Tester votre robot Cosmos DB avec bot Framework EmulatorTest your Cosmos DB bot with bot framework Emulator

À présent, démarrez votre émulateur bot Framework et connectez-vous à votre bot :Now start your bot framework Emulator and connect to your bot:

  1. Cliquez sur le lien créer une nouvelle configuration de bot sous l’onglet « Bienvenue » de l’émulateur.Click the Create new bot configuration link in the Emulator "Welcome" tab.
  2. Renseignez les champs pour vous connecter à votre bot en utilisant les informations figurant dans la page web affichée lorsque vous avez démarré votre bot.Fill in fields to connect to your bot, given the information on the webpage displayed when you started your bot.

Interagissez avec votre robot Cosmos DBInteract with your Cosmos DB bot

Envoyez un message à votre bot, et le bot va répertorier les messages qu’il reçoit.Send a message to your bot, and the bot will list the messages it received. Émulateur en cours d’exécutionEmulator running

Afficher vos données de Cosmos DBView your Cosmos DB data

Une fois que vous avez exécuté votre bot et enregistré vos informations, nous pouvons visualiser les données stockées dans le portail Azure, sous l’onglet Explorateur de données.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.

Exemple de l’Explorateur de données

Utilisation du stockage BlobUsing Blob storage

Le stockage Blob Azure est la solution de stockage d’objet de Microsoft pour le cloud.Azure Blob storage is Microsoft's object storage solution for the cloud. Le stockage Blob est optimisé pour stocker de grandes quantités de données non structurées, telles que des données texte ou binaires.Blob storage is optimized for storing massive amounts of unstructured data, such as text or binary data.

Créer votre compte de stockage BlobCreate your Blob storage account

Pour utiliser le stockage Blob dans votre bot, vous devez configurer certaines choses avant d’aborder le code.To use Blob storage in your bot, you'll need to get a few things set up before getting into the code.

  1. Dans une nouvelle fenêtre du navigateur, connectez-vous au portail Azure.In a new browser window, sign in to the Azure portal.

    Créer un stockage Blob

  2. Cliquez sur Créer une ressource > Stockage > Compte de stockage - blob, fichier, table, file d’attenteClick Create a resource > Storage > Storage account - blob, file, table, queue

    Page Nouveau compte de stockage d’objets blob

  3. Sur la page Nouveau compte, tapez le nom du compte de stockage, sélectionnez Stockage d’objets blob pour Type de compte, puis fournissez les informations relatives aux champs Emplacement, Groupe de ressources et Abonnement.In the New account page, enter Name for the storage account, select Blob storage for Account kind, provide Location, Resource group and Subscription information.

  4. Ensuite, cliquez sur Vérifier + créer.Then click Review + Create.

  5. Une fois la validation réussie, cliquez sur Créer.Once validation has been successful, click Create.

Créer un conteneur de stockage d’objets blobCreate Blob storage container

Une fois que votre compte de stockage d’objets blob a été créé, ouvrez ce compte en effectuant les opérations suivantes :Once your Blob storage account is created, open this account by

  1. Sélectionnez la ressource.Selecting the resource.

  2. Ouvrez à l’aide de l’Explorateur Stockage (préversion).Now "Open" using Storage Explorer (preview)

    Créer un conteneur de stockage d’objets blob

  3. Cliquez avec le bouton droit sur BLOB CONTAINERS et sélectionnez Créer un conteneur d'objets blob .Right click BLOB CONTAINERS, select Create blob container.

  4. Ajoutez un nom.Add a name. Vous utiliserez ce nom pour la valeur « your-blob-storage-container-name » afin de permettre l’accès à votre compte de stockage d’objets blob.You will use this name for the value "your-blob-storage-container-name" to provide access to your Blob Storage account.

Ajouter des informations de configuration du stockage BLOBAdd Blob storage configuration information

Recherchez les clés de Stockage Blob dont vous avez besoin pour configurer le Stockage Blob de votre bot, comme indiqué ci-dessus :Find the Blob Storage keys you need to configure Blob Storage for your bot as shown above:

  1. Dans le Portail Azure, ouvrez votre compte Stockage Blob et sélectionnez Paramètres > Clés d’accès.In the Azure portal, open your Blob Storage account and select Settings > Access keys.

    Rechercher des clés de Stockage Blob

Vous utiliserez la chaîne de connexion key1 comme valeur « your-blob-storage-container-name » pour permettre l’accès à votre compte de stockage d’objets blob.We will use key1 Connection string as the value "your-blob-storage-account-string" to provide access to your Blob Storage account.

Installation des packages de stockage d’objets BLOBInstalling Blob storage packages

Si ce n’est déjà fait, installez les packages suivants.If not previously installed, install the following packages.

Install-Package Microsoft.Bot.Builder.Azure.Blobs

Implémentation du stockage d’objets BLOBBlob storage implementation

Le stockage d’objets BLOB est conçu pour stocker l’état du bot.Blob storage is designed to store bot state.

Notes

À partir de la version 4,10, Microsoft.Bot.Builder.Azure.AzureBlobStorage est déconseillé.As of version 4.10, Microsoft.Bot.Builder.Azure.AzureBlobStorage is deprecated. Utilisez le nouveau Microsoft.Bot.Builder.Azure.Blobs.BlobsStorage à la place.Use the new Microsoft.Bot.Builder.Azure.Blobs.BlobsStorage in its place.

EchoBot.csEchoBot.cs

using Microsoft.Bot.Builder.Azure.Blobs;

Mettez à jour la ligne de code qui pointe « myStorage » vers votre compte Stockage Blob existant.Update the line of code that points "myStorage" to your existing Blob Storage account.

EchoBot.csEchoBot.cs

private static readonly BlobsStorage _myStorage = new BlobsStorage("<your-azure-storage-connection-string>", "<your-blob-storage-container-name>");

Une fois que votre stockage est défini pour pointer sur votre compte de stockage d’objets blob, le code de votre bot va maintenant stocker et récupérer des données depuis le stockage d’objets 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.

Démarrer votre robot de stockage d’objets BLOBStart your Blob storage bot

Exécutez votre bot en local.Run your bot locally.

Démarrer l’émulateur et connecter votre robot de stockage d’objets BLOBStart the Emulator and connect your Blob storage bot

Ensuite, démarrez l’émulateur, puis connectez-vous à votre bot dans l’émulateur :Next, start the Emulator and then connect to your bot in the Emulator:

  1. Cliquez sur le lien créer une nouvelle configuration de bot sous l’onglet « Bienvenue » de l’émulateur.Click the Create new bot configuration link in the Emulator "Welcome" tab.
  2. Renseignez les champs pour vous connecter à votre bot en utilisant les informations figurant dans la page web affichée lorsque vous avez démarré votre bot.Fill in fields to connect to your bot, given the information on the webpage displayed when you started your bot.

Interagissez avec votre robot de stockage d’objets BLOBInteract with your Blob storage bot

Envoyez un message à votre bot, suite à quoi le bot listera les messages qu’il reçoit.Send a message to your bot, and the bot will list the messages it receives.

Bot de stockage de test d’émulateur

Afficher vos données de stockage d’objets BLOBView your Blob storage data

Une fois que vous avez exécuté votre bot et enregistré vos informations, nous pouvons les afficher sous l’onglet Explorateur de données du Portail 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.

Stockage de transcriptions d’objets blobBlob transcript storage

Le stockage de transcriptions d’objets blob Azure fournit une option de stockage spécialisée qui vous permet d’enregistrer et de récupérer facilement des conversations d’utilisateur sous la forme d’une transcription enregistrée.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. Le stockage de transcriptions d’objets blob Azure est particulièrement utile pour capturer automatiquement les entrées utilisateur à examiner lors du débogage des performances de votre bot.Azure blob transcript storage is particularly useful for automatically capturing user inputs to examine while debugging your bot's performance.

Notes

Python ne prend pas actuellement en charge le stockage de transcription d’objets BLOB Azure.Python does not currently support Azure Blob transcript storage. Bien que JavaScript prenne en charge le stockage de transcription d’objets BLOB, les instructions suivantes sont destinées à C# uniquement.While JavaScript supports Blob transcript storage, the following directions are for C# only.

Configurer un conteneur de stockage de transcription d’objet BLOBSet up a Blob transcript storage container

Le stockage de transcriptions d’objets blob Azure peut utiliser le même compte de stockage Blob créé en suivant les étapes détaillées dans les sections « Créer votre compte de stockage Blob » et « Ajouter des informations de configuration ».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. Un conteneur est maintenant ajouté pour stocker vos transcriptions.We now add a container to hold our transcripts

Créer un conteneur de transcriptions

  1. Ouvrez votre compte de stockage d’objets blob Azure.Open your Azure blob storage account.
  2. Cliquez sur Explorateur Stockage.Click on Storage Explorer.
  3. Cliquez avec le bouton droit sur BLOB CONTAINERS et sélectionnez Créer un conteneur d’objets blob.Right click on BLOB CONTAINERS and select create blob container.
  4. Entrez un nom pour votre conteneur de transcriptions, puis sélectionnez OK.enter a name for your transcript container and then select OK. (Nous avons saisi mybottranscripts.)(We entered mybottranscripts)

Implémentation du stockage de transcription d’objets BLOBBlob transcript storage implementation

Le code suivant connecte le pointeur de stockage de transcriptions _myTranscripts à votre nouveau compte de stockage de transcriptions d’objets blob Azure.The following code connects transcript storage pointer _myTranscripts to your new Azure blob transcript storage account. Pour créer ce lien avec un nouveau nom de conteneur, <your-blob-transcript-container-name> , crée un conteneur dans le stockage d’objets BLOB pour stocker vos fichiers de transcription.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.

Le stockage de transcription d’objets BLOB est conçu pour stocker les transcriptions des robots.Blob transcript storage is designed to store bot transcripts.

Notes

À partir de la version 4,10, Microsoft.Bot.Builder.Azure.AzureBlobTranscriptStore est déconseillé.As of version 4.10, Microsoft.Bot.Builder.Azure.AzureBlobTranscriptStore is deprecated. Utilisez le nouveau Microsoft.Bot.Builder.Azure.Blobs.BlobsTranscriptStore à la place.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>");

   ...
}

Stocker les conversations utilisateur dans les transcriptions d’objets blob AzureStore user conversations in azure blob transcripts

Une fois qu’un conteneur d’objets blob est disponible pour stocker les transcriptions, vous pouvez commencer à conserver les conversations de vos utilisateurs avec votre bot.After a blob container is available to store transcripts you can begin to preserve your users' conversations with your bot. Ces conversations peuvent être utilisées plus tard en tant qu’outil de débogage pour observer la façon dont les utilisateurs interagissent avec votre bot.These conversations can later be used as a debugging tool to see how users interact with your bot. Chaque conversation de redémarrage de l’émulateur lance la création d’une nouvelle liste de conversations de transcription.Each Emulator Restart conversation initiates the creation of a new transcript conversation list. Le code suivant conserve les entrées de conversation utilisateur dans un fichier de transcription stocké.The following code preserves user conversation inputs within a stored transcript file.

  • La transcription actuelle est enregistrée à l’aide de LogActivityAsync.The current transcript is saved using LogActivityAsync.
  • Les transcriptions enregistrées sont récupérées à l’aide de ListTranscriptsAsync.Saved transcripts are retrieved using ListTranscriptsAsync. Dans cet exemple de code, l’ID de chaque transcription stockée est enregistrée dans une liste nommée « storedTranscripts ».In this sample code the Id of each stored transcript is saved into a list named "storedTranscripts". Cette liste est utilisée ultérieurement pour gérer le nombre de transcriptions d’objet blob stockées que nous conservons.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);

    ...
}

Gérer les transcriptions d’objet blob stockéesManage stored blob transcripts

Les transcriptions stockées peuvent être utilisées comme outil de débogage, mais, au fil du temps, le nombre de transcriptions stockées peut dépasser le nombre que vous voulez conserver.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. Le code supplémentaire inclus ci-dessous utilise DeleteTranscriptAsync pour supprimer tous les éléments de transcription récupérés de votre magasin de transcriptions d’objet blob, sauf les trois derniers.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);
           }
       }
    }
    ...
}

Le lien suivant fournit plus d’informations sur le stockage de transcriptions d’objet blob AzureThe following link provides more information concerning Azure Blob Transcript Storage

Informations supplémentairesAdditional Information

Gérer la concurrence à l’aide des étiquettes d’entitéManage concurrency using eTags

Dans notre exemple de code de bot, nous définissons la propriété eTag de chaque IStoreItem sur *.In our bot code example we set the eTag property of each IStoreItem to *. L’élément eTag (étiquette d’entité) de votre objet de stockage est utilisé au sein de Cosmos DB pour gérer la concurrence.The eTag (entity tag) member of your store object is used within Cosmos DB to manage concurrency. L’élément eTag indique à votre base de données ce qu’il faut faire si une autre instance du bot modifie l’objet de stockage sur lequel votre bot écrit.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 dernière écriture prévaut : autorise les remplacementsLast write wins - allow overwrites

Une valeur de propriété eTag de l’astérisque (*) indique que celui qui prévaut est le dernier qui écrit.An eTag property value of asterisk (*) indicates that the last writer wins. Lorsque vous créez une nouvelle banque de données, vous pouvez définir l’élément eTag d’une propriété à * pour indiquer que vous n’avez pas précédemment enregistré les données que vous écrivez, ou que vous voulez que le dernier auteur remplace toutes les propriétés précédemment enregistrées.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 concurrence ne constitue pas un problème pour votre bot, le remplacement est autorisé si vous définissez la propriété eTag sur * pour toutes les données que vous écrivez.If concurrency is not an issue for your bot, setting the eTag property to * for any data that you are writing enables overwrites.

Gérer la concurrence et empêcher les remplacementsMaintain concurrency and prevent overwrites

Lorsque vous stockez vos données dans Cosmos DB, utilisez une valeur autre que * pour l’élément eTag si vous souhaitez empêcher l’accès simultané à une propriété et éviter de remplacer les modifications apportées par une autre instance du 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. Le bot reçoit une réponse d’erreur avec le message etag conflict key= quand il tente d’enregistrer des données d’état et que la valeur de l’élément eTag est différente de celle de l’élément eTag qui se trouve dans le stockage.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.

Par défaut, le magasin Cosmos DB vérifie que la propriété eTag d’un objet de stockage reste la même chaque fois qu’un bot écrit dessus, puis la met à jour avec une nouvelle valeur unique après chaque écriture.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 propriété eTag d’écriture ne correspond pas à la propriété eTag de stockage, un autre robot ou thread a donc modifié les données.If the eTag property on write doesn't match the eTag in storage, it means another bot or thread changed the data.

Par exemple, si vous souhaitez que votre robot modifie une note enregistrée, mais que vous ne voulez pas qu’il remplace les modifications apportées par une autre instance du robot.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 une autre instance du robot a apporté des modifications, vous souhaitez que l’utilisateur modifie la version avec les dernières mises à jour.If another instance of the bot has made edits, you want the user to edit the version with the latest updates.

Commencez par créer une classe qui implémente 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; }
}

Créez ensuite une première note avec un nouvel objet de stockage que vous a ajoutez à la banque.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);

Accédez à la note et actualisez-la ultérieurement, en gardant le eTag que vous lisez dans la banque.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 la note a été actualisée dans la banque avant que vous n’écriviez vos modifications, l’appel à Write lance une exception.If the note was updated in the store before you write your changes, the call to Write will throw an exception.

Pour gérer la concurrence, lisez toujours une propriété à partir du stockage, puis modifiez la propriété que vous lisez afin de conserver eTag.To maintain concurrency, always read a property from storage, then modify the property you read, so that the eTag is maintained. Si vous lisez les données de l’utilisateur dans la banque, la réponse contient la propriété de l’étiquette d’entité.If you read user data from the store, the response will contain the eTag property. Si vous modifiez les données et que vous enregistrez les nouvelles données dans la banque, votre requête doit inclure la propriété de l’étiquette d’entité qui indique la même valeur que celle que vous avez lue précédemment.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. Lorsque l’élément eTag d’un objet est défini à *, il est toutefois possible de l’enregistrer en remplaçant les autres modifications.However, writing an object with its eTag set to * will allow the write to overwrite any other changes.

Étapes suivantesNext steps

Maintenant que vous savez comment lire et écrire directement dans le stockage, voyons comment effectuer ces opérations à l’aide du gestionnaire d’état.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.