Skriva direkt till lagring

GÄLLER FÖR: SDK v4

Du kan läsa och skriva direkt till lagringsobjektet utan att använda mellanprogram eller kontextobjekt. Detta kan vara lämpligt för data som roboten använder för att bevara en konversation eller data som kommer från en källa utanför robotens konversationsflöde. I den här datalagringsmodellen läss data in direkt från lagring i stället för att använda en tillståndshanterare. Kodexemplen i den här artikeln visar hur du läser och skriver data till lagring med hjälp av minne, Cosmos DB, Azure Blob och Azure Blob-transkriptionslagring.

Kommentar

Bot Framework JavaScript-, C#- och Python-SDK:erna fortsätter att stödjas, men Java SDK dras tillbaka med slutligt långsiktigt stöd som slutar i november 2023.

Befintliga robotar som skapats med Java SDK fortsätter att fungera.

Om du vill skapa en ny robot bör du överväga att använda Power Virtual Agents och läsa om hur du väljer rätt chattrobotlösning.

Mer information finns i Framtiden för robotbygge.

Förutsättningar

• Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.
• Kunskaper om att skapa en robot lokalt.
• Bot Framework SDK v4-mallar för Visual Studio (C#), Node.js eller Yeoman.

Kommentar

Du kan installera mallarna från Visual Studio.

1. På menyn väljer du Tillägg och sedan Hantera tillägg.
2. I dialogrutan Hantera tillägg söker du efter och installerar Bot Framework v4 SDK-mallar för Visual Studio.

Information om hur du distribuerar .NET-robotar till Azure finns i hur du etablerar och publicerar en robot.

Om det här exemplet

Exempelkoden i den här artikeln börjar med strukturen för en grundläggande ekorobot och utökar sedan robotens funktioner genom att lägga till ytterligare kod (se nedan). Den här utökade koden skapar en lista för att bevara användarindata när de tas emot. Varje tur, den fullständiga listan över användarindata som sparats i minnet, skickas tillbaka till användaren. Datastrukturen som innehåller den här listan med indata ändras sedan för att spara till lagring. Olika typer av lagring utforskas när ytterligare funktioner läggs till i den här exempelkoden.

Minneslagring

Med Bot Framework SDK kan du lagra användarindata med minnesintern lagring. Eftersom minnesintern lagring rensas varje gång roboten startas om är den bäst lämpad för testning och är inte avsedd för produktionsanvändning. Beständiga lagringstyper, till exempel databaslagring, passar bäst för produktionsrobotar.

Skapa en grundläggande robot

Resten av det här avsnittet bygger på en Echo-robot. Exempelkoden för Echo-roboten kan skapas lokalt genom att följa snabbstartsinstruktionerna för att skapa en robot.

C#

Ersätt koden i EchoBot.cs med följande kod:

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

JavaScript

Om du vill använda konfigurationsfilen .env behöver roboten ett extra paket. Om det inte redan är installerat hämtar du .NET-paketet från npm:

npm install --save dotenv

Ändra koden i index.js som skapar huvuddialogrutan. Den befintliga kodraden för att skapa huvuddialogrutan är const myBot = new EchoBot();. Den behöver uppdateras för att kunna skicka ett lagringsobjekt till EchoBot konstruktorn så att du kan lagra användarens indata i robotens interna minne:

Först måste du lägga till en referens MemoryStorage i i botbuilder:

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

Skapa sedan minneslagringsobjektet och skicka det till EchoBot konstruktorn:

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

Detta skickar ett MemoryStorage objekt till EchoBot konstruktorn. Du ändrar det senare för att skicka ett Cosmos DB - eller Blob Storage-objekt .

Ersätt sedan koden i bot.js med följande kod:

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

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

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

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

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

module.exports.EchoBot = EchoBot;

Python

Ersätt koden i echo_bot.py med följande kod:

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


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

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


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

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

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

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

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

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

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

Starta roboten

Kör roboten lokalt.

Starta emulatorn och anslut din robot

Installera Bot Framework-emulatorn Nästa, starta emulatorn och anslut sedan till roboten i emulatorn:

1. Välj länken Skapa ny robotkonfiguration på fliken Välkommen till emulatorn.
2. Fyll i fält för att ansluta till roboten med hjälp av informationen på webbsidan som visades när du startade roboten.

Interagera med din robot

Skicka ett meddelande till roboten. Roboten visar de meddelanden som den har tagit emot.

Resten av den här artikeln visar hur du sparar till beständig lagring i stället för robotens interna minne.

Använda Cosmos DB

Viktigt!

Cosmos DB-lagringsklassen har blivit inaktuell. Containrar som ursprungligen skapades med CosmosDbStorage hade ingen partitionsnyckeluppsättning och fick standardpartitionsnyckeln _/partitionKey.

Containrar som skapats med Cosmos DB-lagring kan användas med Cosmos DB-partitionerad lagring. Mer information finns i Partitionering i Azure Cosmos DB .

Observera också att den cosmos DB-partitionerade lagringen, till skillnad från den äldre Cosmos DB-lagringen, inte automatiskt skapar en databas i ditt Cosmos DB-konto. Du måste skapa en ny databas manuellt, men hoppa över att manuellt skapa en container eftersom CosmosDbPartitionedStorage skapar containern åt dig.

Nu när du har använt minneslagring uppdaterar vi koden så att den använder Azure Cosmos DB. Cosmos DB är Microsofts globalt distribuerade databas med flera modeller. Med Azure Cosmos DB kan du elastiskt och oberoende skala dataflöde och lagring i valfritt antal av Azures geografiska regioner. Den erbjuder garantier för dataflöde, svarstid, tillgänglighet och konsekvens med omfattande serviceavtal (SLA).

Konfigurera en Cosmos DB-resurs

Om du vill använda Cosmos DB i roboten måste du skapa en databasresurs innan du kommer in i koden. En detaljerad beskrivning av hur du skapar Cosmos DB-databaser och appar finns i snabbstarten för .NET, Node.js eller Python.

Skapa ett databaskonto

1. Gå till Microsoft Azure-portalen för att skapa ett Azure Cosmos DB-konto. Sök efter och välj Azure Cosmos DB.

2. På sidan Azure Cosmos DB väljer du Ny för att visa sidan Skapa Azure Cosmos DB-konto .

   

3. Ange värden för följande fält:

   1. Prenumeration. Välj den Azure-prenumeration som ska användas för det här Azure Cosmos-kontot.
   2. Resursgrupp. Välj en befintlig resursgrupp eller välj Skapa ny och ange ett namn för en ny resursgrupp.
   3. Kontonamn. Ange ett namn som identifierar ditt Azure Cosmos-konto. Eftersomdocuments.azure.com läggs till det namn du anger för att skapa din URI måste du använda ett unikt namn. Observera följande riktlinjer:
      • Namnet måste vara unikt i Hela Azure.
      • Namnet måste vara mellan 3 och 31 tecken långt.
      • Namnet kan bara innehålla gemener, siffror och bindestreck (-).
   4. API. Välj Core(SQL)
   5. Plats. välj en plats som är närmast dina användare för att ge dem den snabbaste åtkomsten till data.

4. Välj Granska + skapa.

5. När du har verifierat väljer du Skapa.

Det tar några minuter att skapa kontot. Vänta tills portalen visar Grattis! Azure Cosmos DB-kontot skapades .

Lägga till en databas

Kommentar

Skapa inte containern själv. Roboten skapar den åt dig när den skapar sin interna Cosmos DB-klient, vilket säkerställer att den är korrekt konfigurerad för lagring av robottillstånd.

1. Gå till sidan Datautforskaren i ditt nyligen skapade Cosmos DB-konto och välj sedan Ny databas i listrutan Ny container . En panel öppnas sedan till höger i fönstret, där du kan ange information för den nya databasen.

   

2. Ange ett ID för den nya databasen och ange dataflödet (du kan ändra det senare) och välj slutligen OK för att skapa databasen. Anteckna det här databas-ID:t för användning senare när du konfigurerar roboten.

3. Nu när du har skapat ett Cosmos DB-konto och en databas måste du kopiera över några av värdena för att integrera din nya databas i roboten. Om du vill hämta dessa går du till fliken Nycklar i avsnittet databasinställningar för ditt Cosmos DB-konto. Från den här sidan behöver du din URI (Cosmos DB-slutpunkt) och din PRIMÄRNYCKEL (auktoriseringsnyckel).

Nu bör du ha ett Cosmos DB-konto med en databas och följande värden som är redo att användas i robotinställningarna.

• URI
• Primärnyckel
• Databas-ID

Lägga till Cosmos DB-konfigurationsinformation

Använd informationen som du antecknade i föregående del av den här artikeln för att ange din slutpunkt, auktoriseringsnyckel och databas-ID. Slutligen bör du välja ett lämpligt namn för containern som ska skapas i databasen för att lagra robottillståndet. I exemplet nedan får Cosmos DB-containern som skapas namnet "bot-storage".

C#

Lägg till följande information i konfigurationsfilen.

appsettings.json

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

JavaScript

Lägg till följande information i .env-filen .

.Env

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

Python

Lägg till följande information i konfigurationsfilen.

config.py

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

Installera Cosmos DB-paket

Kontrollera att du har de paket som krävs för Cosmos DB.

C#

Installera NuGet-paketet Microsoft.Bot.Builder.Azure. Mer information om hur du använder NuGet finns i Installera och hantera paket i Visual Studio med Hjälp av NuGet Package Manager .

JavaScript

Lägg till en referens till botbuilder-azure med npm.

npm install --save botbuilder-azure

Om det inte redan är installerat hämtar du .NET-paketet från npm för att få åtkomst till filinställningarna för .env .

npm install --save dotenv

Python

Du kan lägga till en referens till botbuilder-azure i projektet via pip.

pip install botbuilder-azure

Cosmos DB-implementering

Kommentar

Version 4.6 introducerade en ny Cosmos DB-lagringsprovider, cosmos DB-partitionerad lagringsklass och den ursprungliga Cosmos DB-lagringsklassen är inaktuell. Containrar som skapats med Cosmos DB-lagring kan användas med Cosmos DB-partitionerad lagring. Mer information finns i Partitionering i Azure Cosmos DB .

Till skillnad från den äldre Cosmos DB-lagringen skapar cosmos DB-partitionerad lagring inte automatiskt en databas i ditt Cosmos DB-konto. Du måste skapa en ny databas manuellt, men hoppa över att manuellt skapa en container eftersom CosmosDbPartitionedStorage skapar containern åt dig.

C#

Följande exempelkod körs med samma robotkod som exemplet på minneslagring som anges ovan, med undantagen som anges här. Kodfragmenten nedan visar en implementering av Cosmos DB-lagring för "myStorage" som ersätter lokal minneslagring.

Du måste först uppdatera Startup.cs för att referera till Bot Builder Azure-biblioteket :

using Microsoft.Bot.Builder.Azure;

I metoden i ConfigureServicesStartup.cs skapar CosmosDbPartitionedStorage du sedan objektet. Detta skickas till EchoBot konstruktorn via beroendeinmatning.

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

I EchoBot.cs ändra variabeldeklarationen _myStorageprivate static readonly MemoryStorage _myStorage = new MemoryStorage(); till följande:

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

Skicka sedan objektet IStorage till EchoBot konstruktorn:

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

JavaScript

Lägg först till kod i index.js-filen så att du kan komma åt värdena från din .env-fil som du angav tidigare:

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

Därefter måste du göra ändringar i index.js för att använda Cosmos DB-partitionerad lagring i stället för den interna Bot Frameworks-lagringen. Alla kodändringar i det här avsnittet görs i index.js.

Lägg först till en referens till botbuilder-azure i index.js. Detta ger dig åtkomst till CosmosDbPartitionedStorage klassen.

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

Skapa sedan ett nytt CosmosDbPartitionedStorage objekt.

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

Nu kan du kommentera ut eller ta bort den myStorage const-deklaration som du tidigare har lagt till, eftersom du inte längre sparar användarindata till Bot Frameworks interna lagring, utan i stället till Cosmos DB:

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

Python

Följande exempelkod körs med samma robotkod som exemplet på minneslagring som anges ovan, med undantagen som anges här.

Både CosmosDbPartitionedStorage och CosmosDbPartitionedConfig från botbuilder-azure krävs för att skapa CosmosDBStorage-objektet.

echo_bot.py

from botbuilder.azure import CosmosDbPartitionedStorage, CosmosDbPartitionedConfig

För att få åtkomst till inställningarna i config.py importerar DefaultConfig du enligt nedan:

from config import DefaultConfig
CONFIG = DefaultConfig()

Kommentera ut Minneslagring i __init__ och ersätt med referens till Cosmos DB. Använd den URI (slutpunkt), primärnyckel (auktoriseringsnyckel), databas-ID och container-ID som används ovan.

Ta sedan bort eller kommentera ut minneslagringskoden i __init__ och lägg till en referens till Cosmos DB-informationen från config.py.

Kodfragmentet nedan visar en implementering av Cosmos DB för "Storage" som ersätter lokal minneslagring.

echo_bot.py

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

Starta cosmos DB-roboten

Kör roboten lokalt.

Testa din Cosmos DB-robot med Bot Framework-emulatorn

Starta nu Bot Framework-emulatorn och anslut till din robot:

1. Välj länken skapa en ny robotkonfiguration på fliken Välkommen till emulatorn.
2. Fyll i fält för att ansluta till roboten med hjälp av informationen på webbsidan som visades när du startade roboten.

Interagera med din Cosmos DB-robot

Skicka ett meddelande till roboten så visar roboten de meddelanden som den har tagit emot.

Visa dina Cosmos DB-data

När du har kört roboten och sparat informationen kan du visa data som lagras i Azure-portalen under fliken Datautforskaren .

Använda Blob Storage

Azure Blob Storage är Microsofts objektlagringslösning för molnet. Blob Storage är optimerat för att lagra stora mängder ostrukturerade data, exempelvis text eller binära data. I det här avsnittet beskrivs hur du skapar ett Azure Blob Storage-konto och en container och hur du refererar till din bloblagringscontainer från din robot.

Mer information om Blob Storage finns i Vad är Azure Blob Storage?

Skapa ditt Blob Storage-konto

Om du vill använda Blob Storage i din robot måste du konfigurera några saker innan du går in i koden.

1. I Azure-portalen, väljer du Alla tjänster.

2. I avsnittet Aktuell påsidan Alla tjänster väljer du Lagringskonton.

3. På sidan Lagringskonton väljer du Ny.

   

4. I fältet Prenumeration väljer du den prenumeration där lagringskontot ska skapas.

5. I fältet Resursgrupp väljer du en befintlig resursgrupp eller väljer Skapa ny och anger ett namn för den nya resursgruppen.

6. I fältet Lagringskontonamn anger du ett namn för kontot. Observera följande riktlinjer:

   • Namnet måste vara unikt i Hela Azure.
   • Namnet måste vara mellan 3 och 24 tecken långt.
   • Namnet kan bara innehålla siffror och gemener.

7. I fältet Plats väljer du en plats för lagringskontot eller använder standardplatsen.

8. För resten av inställningarna konfigurerar du följande:

   • Prestanda: Standard. Läs mer om prestanda.
   • Kontotyp: BlobStorage. Läs mer om lagringskonton.
   • Replikering: Lämna standardinställningen. Läs mer om redundans.

9. I avsnittet Projektinformation på sidan Skapa lagringskonto väljer du önskade värden för prenumeration och resursgrupp.

10. I avsnittet Instansinformation på sidan Skapa lagringskonto anger du namnet på lagringskontot och väljer sedan värden för Plats, Kontotyp och Replikering.

11. Välj Granska + skapa för att granska lagringskontoinställningarna.

12. När du har verifierat väljer du Skapa.

Skapa bloblagringscontainer

När ditt Blob Storage-konto har skapats öppnar du det och sedan:

1. Välj Storage Explorer (förhandsversion).

2. Högerklicka sedan på BLOBCONTAINRAR

3. Välj Skapa blobcontainer i listrutan.

   

4. Ange ett namn i formuläret Ny container . Du använder det här namnet för värdet för ditt "blobcontainernamn" för att ge åtkomst till ditt Blob Storage-konto. Observera följande riktlinjer:

   • Det här namnet får endast innehålla gemener, siffror och bindestreck.
   • Det här namnet måste börja med en bokstav eller ett tal.
   • Varje bindestreck måste föregås och följas av ett giltigt tecken som inte är bindestreck.
   • Namnet måste vara mellan 3 och 63 tecken långt.

Lägga till konfigurationsinformation för Blob Storage

Hitta de Blob Storage-nycklar som du behöver för att konfigurera Blob Storage för din robot enligt ovan:

1. Öppna ditt Blob Storage-konto i Azure-portalen och välj Åtkomstnycklar i avsnittet Inställningar.
2. Om du vill konfigurera roboten för åtkomst till ditt Blob Storage-konto använder du Anslut ionssträng som värde för blob-anslutningssträng.

C#

Lägg till följande information i konfigurationsfilen.

appsettings.json

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

JavaScript

Lägg till följande information i .env-filen .

.Env

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

Python

Lägg till följande information i konfigurationsfilen. Använd samma containernamn och anslutningssträng som används när du skapar bloblagringscontainern.

config.py

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

Installera Blob Storage-paket

Installera följande paket om de inte har installerats tidigare.

C#

Installera NuGet-paketet Microsoft.Bot.Builder.Azure.Blobs. Mer information om hur du använder NuGet finns i Installera och hantera paket i Visual Studio med Hjälp av NuGet Package Manager.

JavaScript

Lägg till referenser till botbuilder-azure-blobs i projektet via npm.

Kommentar

Det här npm-paketet förlitar sig på en installation av Python som finns på utvecklingsdatorn. Om du inte tidigare har installerat Python kan du hitta installationsresurser för datorn på Python.org

npm install --save botbuilder-azure-blobs

Om det inte redan är installerat hämtar du .NET-paketet från npm för att få åtkomst till filinställningarna för .env .

npm install --save dotenv

Python

du kan lägga till en referens till botbuilder-azure i projektet via pip.

pip install botbuilder-azure

Implementering av bloblagring

Blob Storage används för att lagra robottillstånd.

C#

Kommentar

Från och med version 4.10 Microsoft.Bot.Builder.Azure.AzureBlobStorage är inaktuell. Använd det nya Microsoft.Bot.Builder.Azure.Blobs.BlobsStorage i dess ställe.

Följande exempelkod körs med samma robotkod som exemplet på minneslagring som anges ovan, med undantagen som anges här.

Kodfragmenten nedan visar en implementering av Blob Storage för "myStorage" som ersätter lokal minneslagring.

Du måste först uppdatera Startup.cs för att referera till Azure Blobs-biblioteket för robotverktyget:

Startup.cs

using Microsoft.Bot.Builder.Azure.Blobs;

I metoden i ConfigureServicesStartup.cs skapar BlobsStorage du objektet och skickar sedan värdena från appsettings.json. Detta skickas till EchoBot konstruktorn via beroendeinmatning.

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

Nu måste du först uppdatera EchoBot.cs för att referera till robotverktygets Azure Blobs-bibliotek :

EchoBot.cs

using Microsoft.Bot.Builder.Azure.Blobs;

Ta sedan bort eller kommentera bort kodraden som skapar memorystorage-variabeln "private static readonly MemoryStorage _myStorage = new MemoryStorage();", och skapa en ny variabel som ska användas för att spara användarindata till Blob Storage.

EchoBot.cs

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

Skicka sedan objektet IStorage till EchoBot konstruktorn:

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

När lagringen är inställd på att peka på ditt Blob Storage-konto kommer robotkoden nu att lagra och hämta data från Blob Storage.

JavaScript

Alla kodändringar i det här avsnittet görs i index.js.

Lägg först till kod så att du kan komma åt värdena från din .env-fil som du angav tidigare:

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

Därefter måste du göra ändringar med Blob Storage i stället för Bot Frameworks interna lagring.

Lägg sedan till en referens till botbuilder-azure-blobs. Detta ger dig åtkomst till Blob Storage-API:et:

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

Om du vill ändra koden så att den BlobsStorage använder klassen ändrar du myStorage deklarationen på följande sätt:

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

När lagringen är inställd på att peka på ditt Blob Storage-konto kommer robotkoden nu att lagra och hämta data från Blob Storage.

Python

Följande exempelkod körs med samma robotkod som exemplet på minneslagring som anges ovan, med undantagen som anges här.

Detta kräver BlobStorage och BlobStorageSettings från botbuilder-azure.

echo_bot.py

from botbuilder.azure import BlobStorage, BlobStorageSettings

För att få åtkomst till inställningarna i config.py importerar DefaultConfig du enligt nedan:

from config import DefaultConfig
CONFIG = DefaultConfig()

Ta sedan bort eller kommentera ut minneslagringskoden i __init__ och lägg till en referens till bloblagringsinformationen från config.py.

Kodfragmentet nedan visar en implementering av Blob Storage som ersätter den lokala minneslagringen.

echo_bot.py

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

När lagringen är inställd på att peka på ditt Blob Storage-konto kommer robotkoden nu att lagra och hämta data från Blob Storage.

Starta bloblagringsroboten

Kör roboten lokalt.

Starta emulatorn och anslut bloblagringsroboten

Starta sedan emulatorn och anslut sedan till roboten i emulatorn:

1. Välj länken Skapa ny robotkonfiguration på fliken Emulator "Välkommen".
2. Fyll i fält för att ansluta till roboten med hjälp av informationen på webbsidan som visades när du startade roboten.

Interagera med din Blob Storage-robot

Skicka ett meddelande till roboten så visar roboten de meddelanden den tar emot.

Visa dina Blob Storage-data

När du har kört roboten och sparat din information kan vi visa den på fliken Storage Explorer i Azure-portalen.

Blobutskriftslagring

Azure Blob Transcript Storage är ett specialiserat lagringsalternativ som gör att du enkelt kan spara och hämta användarkonversationer i form av en inspelad avskrift. Azure Blob Transcript Storage är användbart för att automatiskt samla in användarindata för att undersöka när du felsöker robotens prestanda.

Kommentar

Python stöder för närvarande inte Azure Blob-avskriftslagring. JavaScript stöder blobavskriftslagring, men följande anvisningar gäller endast för C#.

Konfigurera en blobavskriftslagringscontainer

Azure Blob Transcript Storage kan använda samma bloblagringskonto som skapats enligt stegen i avsnitten "Skapa ditt bloblagringskonto" och "Lägg till konfigurationsinformation" ovan. Nu lägger vi till en container för att lagra våra avskrifter

1. Öppna ditt Azure Blob Storage-konto.
2. Välj Storage Explorer.
3. Högerklicka på BLOBCONTAINRAR och välj skapa blobcontainer.
4. Ange ett namn för din transkriptionscontainer och välj sedan OK. (Vi gick in i mybottranscripts)

Implementering av blobavskriftslagring

Följande kod ansluter transkriptionslagringspekaren _myTranscripts till ditt nya Lagringskonto för Azure Blob-avskrift. Om du vill skapa den här länken med ett nytt containernamn, <ditt-blob-transcript-container-name>, skapar den en ny container i Blob Storage för att lagra dina transkriptionsfiler.

Blobutskriftslagring är utformad för att lagra robotavskrifter.

Kommentar

Från och med version 4.10 Microsoft.Bot.Builder.Azure.AzureBlobTranscriptStore är inaktuell. Använd det nya Microsoft.Bot.Builder.Azure.Blobs.BlobsTranscriptStore i dess ställe.

echoBot.cs

using Microsoft.Bot.Builder.Azure.Blobs;

public class EchoBot : ActivityHandler
{
   ...

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

   ...
}

Lagra användarkonversationer i Azure Blob-avskrifter

När en blobcontainer är tillgänglig för att lagra avskrifter kan du börja bevara användarnas konversationer med roboten. Dessa konversationer kan senare användas som ett felsökningsverktyg för att se hur användare interagerar med din robot. Varje Emulator Starta om konversation initierar skapandet av en ny transkriptionskonversationlista. Följande kod bevarar indata för användarkonversationer i en lagrad avskriftsfil.

• Den aktuella avskriften sparas med .LogActivityAsync
• Sparade avskrifter hämtas med .ListTranscriptsAsync I den här exempelkoden sparas ID:t för varje lagrad avskrift i en lista med namnet "storedTranscripts". Den här listan används senare för att hantera antalet lagrade blobavskrifter som vi behåller.

echoBot.cs

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

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

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

    ...
}

Hantera lagrade blobavskrifter

Lagrade avskrifter kan användas som ett felsökningsverktyg, men med tiden kan antalet lagrade avskrifter bli större än vad du vill bevara. Den ytterligare kod som ingår nedan används DeleteTranscriptAsync för att ta bort alla utom de tre senaste hämtade avskriftsobjekten från blobavskriftsarkivet.

echoBot.cs

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

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

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

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

Mer information om klassen finns i Azure Blob Transcript Storage.

Ytterligare Information

Hantera samtidighet med eTags

I vårt robotkodexempel anger eTag vi egenskapen för var och en IStoreItem till *. ( eTag entitetstagg)-medlemmen i ditt butiksobjekt används i Cosmos DB för att hantera samtidighet. eTag Talar om för databasen vad du ska göra om en annan instans av roboten har ändrat objektet i samma lagring som roboten skriver till.

Senaste skrivvinster – tillåt överskrivningar

Ett eTag egenskapsvärde för asterisk (*) anger att den senaste skrivaren vinner. När du skapar ett nytt datalager kan du ange eTag en egenskap som * anger att du inte tidigare har sparat data som du skriver, eller att du vill att den sista skrivaren ska skriva över en tidigare sparad egenskap. Om samtidighet inte är ett problem för din robot kan eTag du skriva över eventuella data som du skriver om egenskapen * .

Upprätthålla samtidighet och förhindra överskrivningar

När du lagrar dina data i Cosmos DB använder du ett annat värde än * för eTag om du vill förhindra samtidig åtkomst till en egenskap och undvika att skriva över ändringar från en annan instans av roboten. Roboten får ett felmeddelande med meddelandet etag conflict key= när den försöker spara tillståndsdata och eTag är inte samma värde som i lagringen eTag .

Som standard kontrollerar Cosmos DB-arkivet eTag egenskapen för ett lagringsobjekt för likhet varje gång en robot skriver till objektet och uppdaterar den sedan till ett nytt unikt värde efter varje skrivning. Om egenskapen vid eTag skrivning inte matchar i lagringen eTag innebär det att en annan robot eller tråd har ändrat data.

Anta till exempel att du vill att roboten ska redigera en sparad anteckning, men du vill inte att roboten ska skriva över ändringar som en annan instans av roboten har gjort. Om en annan instans av roboten har gjort ändringar vill du att användaren ska redigera versionen med de senaste uppdateringarna.

C#

Skapa först en klass som implementerar IStoreItem.

EchoBot.cs

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

Skapa sedan en första anteckning genom att skapa ett lagringsobjekt och lägga till objektet i ditt lager.

EchoBot.cs

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

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

Gå sedan till och uppdatera anteckningen senare och behåll den eTag som du läser från arkivet.

EchoBot.cs

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

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

Om anteckningen uppdaterades i arkivet innan du skriver ändringarna utlöser anropet till Write ett undantag.

JavaScript

Lägg till en hjälpfunktion i slutet av roboten som skriver en exempelanteckning till ett datalager. myNoteData Skapa först objekt.

bot.js

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

createSampleNote I hjälpfunktionen initierar du ett changes objekt och lägger till anteckningarna i det och skriver det sedan till lagring.

bot.js

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

Hjälpfunktionen nås inifrån robotens logik genom att lägga till följande anrop:

bot.js

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

När du har skapat den skapar vi en annan hjälpfunktion som kan nås när användaren skriver i "update note" för att senare hämta och uppdatera anteckningen.

bot.js

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

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

Den här hjälpfunktionen nås inifrån robotens logik genom att lägga till följande anrop:

bot.js

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

Om anteckningen uppdaterades i arkivet av en annan användare innan du försökte skriva tillbaka ändringarna eTag matchar inte längre värdet och anropet till write utlöser ett undantag.

Python

Skapa först en klass som implementerar StoreItem.

echo_bot.py

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

Skapa sedan en första anteckning genom att skapa ett lagringsobjekt och lägga till objektet i ditt lager.

echo_bot.py

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

await self.storage.write(changes)

Gå sedan till och uppdatera anteckningen senare och behåll den eTag som du läser från arkivet.

echo_bot.py

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

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

Om anteckningen uppdaterades i arkivet innan du skriver ändringarna utlöser anropet till write ett undantag.

För att upprätthålla samtidighet läser du alltid en egenskap från lagringen och ändrar sedan den egenskap som du läser så att den eTag underhålls. Om du läser användardata från arkivet innehåller svaret egenskapen eTag. Om du ändrar data och skriver uppdaterade data till arkivet bör din begäran innehålla egenskapen eTag som anger samma värde som du läste tidigare. Men om du skriver ett objekt med dess eTag inställd * på kan skrivning skriva över eventuella andra ändringar.

Nästa steg

Nu när du vet hur du läser och skriver direkt från lagringen kan du ta en titt på hur du kan använda tillståndshanteraren för att göra det åt dig.

Spara tillstånd med hjälp av konversations- och användaregenskaper