Zápis přímo do úložiště

PLATÍ PRO: SDK v4

Do objektu úložiště můžete číst a zapisovat přímo bez použití middlewaru nebo kontextového objektu. To může být vhodné pro data, která robot používá k zachování konverzace nebo dat pocházejících ze zdroje mimo tok konverzace robota. V tomto modelu úložiště dat se data čtou přímo z úložiště místo použití správce stavů. Příklady kódu v tomto článku ukazují, jak číst a zapisovat data do úložiště pomocí paměti, Cosmos DB, objektů blob Azure a úložiště přepisu objektů blob v Azure.

Poznámka:

Sady SDK služby Bot Framework JavaScript, C# a Python budou nadále podporovány, ale sada Java SDK se vyřazuje s konečnou dlouhodobou podporou končící v listopadu 2023. V tomto úložišti budou provedeny pouze kritické opravy zabezpečení a chyb.

Stávající roboti sestavení pomocí sady Java SDK budou i nadále fungovat.

Pro nové vytváření robotů zvažte použití Power Virtual Agents a přečtěte si o výběru správného řešení chatovacího robota.

Další informace najdete v tématu Budoucnost vytváření robotů.

Předpoklady

• Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.
• Znalost místního vytváření robota
• Šablony sady SDK služby Bot Framework v4 pro Visual Studio (C#), Node.js nebo Yeoman.

Poznámka:

Šablony můžete nainstalovat ze sady Visual Studio.

1. V nabídce vyberte Rozšíření a pak Spravovat rozšíření.
2. V dialogovém okně Spravovat rozšíření vyhledejte a nainstalujte šablony sady Bot Framework v4 SDK pro Visual Studio.

Informace o nasazení robotů .NET do Azure najdete v tématu zřízení a publikování robota.

O této ukázce

Vzorový kód v tomto článku začíná strukturou základního robota echo a pak rozšiřuje funkčnost robota přidáním dalšího kódu (viz níže). Tento rozšířený kód vytvoří seznam pro zachování uživatelských vstupů při jejich přijetí. Každý turn, úplný seznam uživatelských vstupů, uložených do paměti, se ozvěna zpět uživateli. Datová struktura obsahující tento seznam vstupů se pak upraví tak, aby se uložila do úložiště. Různé typy úložiště jsou prozkoumány, protože do tohoto ukázkového kódu se přidávají další funkce.

Úložiště paměti

Sada SDK služby Bot Framework umožňuje ukládat vstupy uživatelů pomocí úložiště v paměti. Vzhledem k tomu, že se při každém restartování robota vymaže úložiště v paměti, je nejvhodnější pro účely testování a není určená pro produkční použití. Pro produkční roboty jsou nejvhodnější trvalé typy úložiště, jako je například databázové úložiště.

Vytvoření základního robota

Zbývající část tohoto tématu vychází z robota Echo. Vzorový kód echo robota můžete vytvořit místně podle pokynů pro rychlý start k vytvoření robota.

C#

Nahraďte kód v EchoBot.cs následujícím kódem:

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

Pokud chcete použít konfigurační soubor .env , váš robot potřebuje balíček navíc. Pokud ještě není nainstalovaný, získejte balíček .NET z npm:

npm install --save dotenv

Upravte kód v souboru index.js , který vytvoří hlavní dialog. Stávající řádek kódu pro vytvoření hlavního dialogového okna je const myBot = new EchoBot();potřeba aktualizovat, aby umožnil předání objektu úložiště konstruktoru EchoBot , abyste mohli uložit vstup uživatele do interní paměti robota:

Nejprve budete muset přidat odkaz do MemoryStoragebotbuilder:

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

Pak vytvořte objekt úložiště paměti a předejte ho konstruktoru EchoBot :

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

Tím se předá MemoryStorage objekt konstruktoru EchoBot . Později ho změníte tak, aby předával objekt Cosmos DB nebo Blob Storage .

Dále nahraďte kód v souboru bot.js následujícím kódem:

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

Nahraďte kód v souboru echo_bot.py následujícím kódem:

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

Spuštění robota

Spusťte robota místně.

Spuštění emulátoru a připojení robota

Nainstalujte bot Framework Emulator Next, spusťte emulátor a pak se připojte k robotovi v emulátoru:

1. Na úvodní kartě emulátoru vyberte odkaz Vytvořit novou konfiguraci robota.
2. Vyplňte pole pro připojení k robotovi s informacemi na webové stránce zobrazené při spuštění robota.

Interakce s robotem

Odešlete robotovi zprávu. Robot zobrazí seznam přijatých zpráv.

Zbývající část tohoto článku vám ukáže, jak místo interní paměti robota uložit do trvalého úložiště.

Použití služby Cosmos DB

Důležité

Třída úložiště Cosmos DB je zastaralá. Kontejnery původně vytvořené pomocí služby CosmosDbStorage neměly žádnou sadu klíčů oddílů a byly přiděleny výchozímu klíči oddílu _/partitionKey.

Kontejnery vytvořené s úložištěmCosmos DB je možné použít s děleným úložištěm Cosmos DB. Další informace najdete v článku Dělení ve službě Azure Cosmos DB .

Všimněte si také, že na rozdíl od starší verze úložiště Cosmos DB se dělené úložiště Cosmos DB automaticky nevytvoří databázi v rámci vašeho účtu Cosmos DB. Potřebujete vytvořit novou databázi ručně, ale přeskočit ruční vytvoření kontejneru, protože CosmosDbPartitionedStorage za vás kontejner vytvoří.

Teď, když jste použili úložiště paměti, aktualizujeme kód tak, aby používal Službu Azure Cosmos DB. Cosmos DB je globálně distribuovaná databáze Microsoftu s více modely. Azure Cosmos DB umožňuje elasticky a nezávisle škálovat propustnost a úložiště napříč libovolným počtem geografických oblastí Azure. Nabízí záruky propustnosti, latence, dostupnosti a konzistence s komplexními smlouvami o úrovni služeb (SLA).

Nastavení prostředku Cosmos DB

Pokud chcete ve svém robotovi používat Cosmos DB, musíte před načtením kódu vytvořit databázový prostředek. Podrobný popis vytvoření databáze a aplikace Cosmos DB najdete v rychlém startu pro .NET, Node.js nebo Python.

Vytvoření databázového účtu

1. Přejděte na Azure Portal a vytvořte si účet služby Azure Cosmos DB. Vyhledejte a vyberte Azure Cosmos DB.

2. Na stránce Azure Cosmos DB vyberte Možnost Nový , aby se otevře stránka Vytvořit účet služby Azure Cosmos DB.

   

3. Zadejte hodnoty pro následující pole:

   1. Předplatné Vyberte předplatné Azure, které chcete pro tento účet služby Azure Cosmos použít.
   2. Skupina prostředků. Vyberte existující skupinu prostředků nebo vyberte Vytvořit novou a zadejte název nové skupiny prostředků.
   3. Název účtu Zadejte název identifikující váš účet služby Azure Cosmos. Vzhledem k tomu, že se váš identifikátor URI vytvoří připojením řetězce documents.azure.com k názvu, který zadáte, použijte jedinečný název. Všimněte si následujících pokynů:
      • Název musí být jedinečný v rámci Azure.
      • Název musí mít délku 3 až 31 znaků.
      • Název může obsahovat pouze malá písmena, číslice a znak spojovníku (-).
   4. Rozhraní API. Výběr Core(SQL)
   5. Umístění: vyberte umístění, které je nejblíže vašim uživatelům, abyste jim poskytli nejrychlejší přístup k datům.

4. Vyberte Zkontrolovat a vytvořit.

5. Po ověření vyberte Vytvořit.

Vytvoření účtu trvá několik minut. Počkejte, až se na portálu zobrazí blahopřejeme! Vytvořili jste stránku vašeho účtu služby Azure Cosmos DB.

Přidání databáze

Poznámka:

Nevytvávejte kontejner sami. Robot ho vytvoří za vás při vytváření interního klienta Cosmos DB a zajistí, že je správně nakonfigurovaný pro ukládání stavu robota.

1. V nově vytvořeném účtu Cosmos DB přejděte na stránku Průzkumník dat a v rozevíracím seznamu Nový kontejner zvolte Nová databáze. Na pravé straně okna se otevře panel, kde můžete zadat podrobnosti o nové databázi.

   

2. Zadejte ID nové databáze a volitelně nastavte propustnost (později ji můžete změnit) a nakonec vyberte OK a vytvořte databázi. Poznamenejte si toto ID databáze pro pozdější použití při konfiguraci robota.

3. Teď, když jste vytvořili účet Cosmos DB a databázi, musíte zkopírovat některé hodnoty pro integraci nové databáze do robota. Pokud je chcete načíst, přejděte na kartu Klíče v části Nastavení databáze vašeho účtu Cosmos DB. Na této stránce budete potřebovat identifikátor URI (koncový bod Cosmos DB) a primární klíč (autorizační klíč).

Teď byste měli mít účet Cosmos DB s databází a následující hodnoty připravené k použití v nastavení robota.

• Identifikátor URI
• Primární klíč
• ID databáze

Přidání informací o konfiguraci služby Cosmos DB

Podrobnosti, které jste si poznamenali v předchozí části tohoto článku, použijte k nastavení koncového bodu, autorizačního klíče a ID databáze. Nakonec byste měli zvolit vhodný název kontejneru, který se vytvoří v rámci vaší databáze pro uložení stavu robota. V příkladu pod vytvořeným kontejnerem Cosmos DB se bude jmenovat bot-storage.

C#

Do konfiguračního souboru přidejte následující informace.

appsettings.json

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

JavaScript

Do souboru .env přidejte následující informace.

.Env

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

Python

Do konfiguračního souboru přidejte následující informace.

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"

Instalace balíčků Cosmos DB

Ujistěte se, že máte balíčky potřebné pro Cosmos DB.

C#

Nainstalujte balíček Microsoft.Bot.Builder.Azure NuGet. Další informace o používání NuGetu najdete v tématu Instalace a správa balíčků v sadě Visual Studio pomocí Správce balíčků NuGet .

JavaScript

Přidejte odkaz na botbuilder-azure pomocí npm.

npm install --save botbuilder-azure

Pokud ještě není nainstalovaný, získejte balíček .NET z npm, abyste získali přístup k nastavení souboru .env .

npm install --save dotenv

Python

Pomocí pipu můžete do projektu přidat odkaz na botbuilder-azure.

pip install botbuilder-azure

Implementace cosmos DB

Poznámka:

Verze 4.6 zavedla nového poskytovatele úložiště Cosmos DB, třídu rozděleného úložiště cosmos DB a původní třídu úložiště Cosmos DB je zastaralá. Kontejnery vytvořené s úložištěmCosmos DB je možné použít s děleným úložištěm Cosmos DB. Další informace najdete v článku Dělení ve službě Azure Cosmos DB .

Na rozdíl od starší verze úložiště Cosmos DB se dělené úložiště Cosmos DB automaticky nevytvoří databázi v rámci vašeho účtu Cosmos DB. Potřebujete vytvořit novou databázi ručně, ale přeskočit ruční vytvoření kontejneru, protože CosmosDbPartitionedStorage za vás kontejner vytvoří.

C#

Následující ukázkový kód se spustí pomocí stejného kódu robota jako výše uvedený vzorek úložiště paměti s výjimkami uvedenými zde. Následující fragmenty kódu ukazují implementaci úložiště Cosmos DB pro myStorage, která nahrazuje místní úložiště paměti.

Nejprve je potřeba aktualizovat Startup.cs , aby odkaz na knihovnu Azure v tvůrci robotů:

using Microsoft.Bot.Builder.Azure;

Dále v ConfigureServices metodě startup.cs vytvořte CosmosDbPartitionedStorage objekt. Ten se předá do konstruktoru EchoBot prostřednictvím injektáže závislostí.

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

V EchoBot.cs změňte _myStorage deklaraci private static readonly MemoryStorage _myStorage = new MemoryStorage(); proměnné na následující:

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

Pak předejte IStorage objekt konstruktoru EchoBot :

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

JavaScript

Nejprve přidejte do souboru index.js kód, který vám umožní přístup k hodnotám ze souboru .env , který jste zadali dříve:

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

Dále budete muset provést změny index.js , abyste místo interního úložiště Bot Frameworks používali dělené úložiště Cosmos DB. Všechny změny kódu v této části jsou provedeny v index.js.

Nejprve přidejte odkaz na botbuilder-azure v index.js. Tím získáte přístup ke CosmosDbPartitionedStorage třídě.

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

Dále vytvořte nový CosmosDbPartitionedStorage objekt.

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

Teď můžete zakomentovat nebo odebrat myStorage deklaraci const, kterou jste přidali dříve, protože už neukládajíte uživatelský vstup do interního úložiště Bot Frameworks, ale místo toho do cosmos DB:

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

Python

Následující ukázkový kód se spustí pomocí stejného kódu robota jako výše uvedený vzorek úložiště paměti s výjimkami uvedenými zde.

K vytvoření objektu CosmosDBStorage se vyžaduje obojí CosmosDbPartitionedStorage i CosmosDbPartitionedConfig od botbuilder-azure .

echo_bot.py

from botbuilder.azure import CosmosDbPartitionedStorage, CosmosDbPartitionedConfig

Pokud chcete získat přístup k nastavení v config.py, importujete DefaultConfig ho, jak je znázorněno níže:

from config import DefaultConfig
CONFIG = DefaultConfig()

Zakomentujte úložiště paměti __init__ a nahraďte odkazem na Cosmos DB. Použijte identifikátor URI (koncový bod), primární klíč (autorizační klíč), ID databáze a ID kontejneru použité výše.

Dále odeberte nebo okomentujte kód __init__ úložiště paměti a přidejte odkaz na informace o službě Cosmos DB z config.py.

Následující fragment kódu ukazuje implementaci služby Cosmos DB pro Úložiště, která nahrazuje místní úložiště paměti.

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)

Spuštění robota Cosmos DB

Spusťte robota místně.

Testování robota služby Cosmos DB pomocí bot Framework Emulatoru

Teď spusťte bot Framework Emulator a připojte se k robotovi:

1. Na úvodní kartě emulátoru vyberte odkaz pro vytvoření nové konfigurace robota.
2. Vyplňte pole pro připojení k robotovi s informacemi na webové stránce zobrazené při spuštění robota.

Interakce s robotem Cosmos DB

Odešlete robotovi zprávu a robot zobrazí seznam přijatých zpráv.

Zobrazení dat cosmos DB

Po spuštění robota a uložení informací můžete zobrazit data uložená na webu Azure Portal na kartě Průzkumník dat.

Použití úložiště objektů blob

Azure Blob Storage je řešení úložiště objektů pro cloud od Microsoftu. Blob Storage je optimalizované pro ukládání velkých objemů nestrukturovaných dat, jako jsou textová nebo binární data. Tato část vysvětluje, jak vytvořit účet úložiště objektů blob Azure a kontejner a jak odkazovat na kontejner úložiště objektů blob z robota.

Další informace o službě Blob Storage najdete v tématu Co je Azure Blob Storage?

Vytvoření účtu služby Blob Storage

Pokud chcete ve svém robotovi používat úložiště objektů blob, musíte před vstupem do kódu nastavit několik věcí.

1. Na webu Azure Portal vyberte Všechny služby.

2. V části Doporučené na stránce Všechny služby vyberte Účty úložiště.

3. Na stránce Účty úložiště vyberte Nový.

   

4. V poli Předplatné vyberte předplatné, ve kterém chcete vytvořit účet úložiště.

5. V poli Skupina zdrojů vyberte existující skupinu prostředků nebo vyberte Vytvořit novou a zadejte název nové skupiny prostředků.

6. Do pole Název účtu úložiště zadejte název účtu. Všimněte si následujících pokynů:

   • Název musí být jedinečný v rámci Azure.
   • Název musí mít délku 3 až 24 znaků.
   • Název může obsahovat jenom číslice a malá písmena.

7. V poli Umístění vyberte umístění pro účet úložiště nebo použijte výchozí umístění.

8. Pro zbývající nastavení nakonfigurujte následující:

   • Výkon: Standard. Přečtěte si další informace o výkonu.
   • Druh účtu: BlobStorage. Přečtěte si další informace o účtech úložiště.
   • Replikace: Ponechte výchozí nastavení. Přečtěte si další informace o redundanci.

9. V části Podrobnosti projektu na stránce Vytvořit účet úložiště vyberte požadované hodnoty pro předplatné a skupinu prostředků.

10. V části Podrobnosti instance na stránce Vytvořit účet úložiště zadejte název účtu úložiště a pak vyberte hodnoty pro umístění, druh účtu a replikaci.

11. Výběrem možnosti Zkontrolovat a vytvořit zkontrolujte nastavení účtu úložiště.

12. Po ověření vyberte Vytvořit.

Vytvoření kontejneru úložiště objektů blob

Po vytvoření účtu blob storage ho otevřete a pak:

1. Vyberte Průzkumník služby Storage (Preview).

2. Potom klikněte pravým tlačítkem na kontejnery objektů blob.

3. V rozevíracím seznamu vyberte Vytvořit kontejner objektů blob.

   

4. Do formuláře Nový kontejner zadejte název. Tento název použijete pro hodnotu "název kontejneru objektů blob" a poskytnete tak přístup k vašemu účtu blob storage. Všimněte si následujících pokynů:

   • Tento název může obsahovat jenom malá písmena, číslice a pomlčky.
   • Tento název musí začínat písmenem nebo číslem.
   • Každé pomlce musí předcházet a za ním platný znak spojovníku.
   • Název musí mít délku 3 až 63 znaků.

Přidání informací o konfiguraci úložiště objektů blob

Vyhledejte klíče úložiště objektů blob, které potřebujete ke konfiguraci úložiště objektů blob pro robota, jak je znázorněno výše:

1. Na webu Azure Portal otevřete účet úložiště Blob a v části Nastavení vyberte Přístupové klíče.
2. Pokud chcete nakonfigurovat robota pro přístup k účtu úložiště Blob, použijte jako hodnotu připojovací řetězec objektu blob řetězec Připojení ion.

C#

Do konfiguračního souboru přidejte následující informace.

appsettings.json

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

JavaScript

Do souboru .env přidejte následující informace.

.Env

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

Python

Do konfiguračního souboru přidejte následující informace. Použijte stejný název kontejneru a připojovací řetězec použitý při vytváření kontejneru úložiště objektů blob.

config.py

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

Instalace balíčků úložiště objektů blob

Pokud jste ještě nenainstalovali, nainstalujte následující balíčky.

C#

Nainstalujte balíček NuGet Microsoft.Bot.Builder.Azure.Blobs. Další informace o používání NuGetu najdete v tématu Instalace a správa balíčků v sadě Visual Studio pomocí Správce balíčků NuGet.

JavaScript

Přidejte do projektu odkazy botbuilder-azure-blobs prostřednictvím npm.

Poznámka:

Tento balíček npm spoléhá na instalaci Pythonu existujícího na vašem vývojovém počítači. Pokud jste python ještě nenainstalovali, najdete instalační prostředky pro svůj počítač na Python.org

npm install --save botbuilder-azure-blobs

Pokud ještě není nainstalovaný, získejte balíček .NET z npm, abyste získali přístup k nastavení souboru .env .

npm install --save dotenv

Python

Pomocí pipu můžete do projektu přidat odkaz na botbuilder-azure.

pip install botbuilder-azure

Implementace služby Blob Storage

Úložiště objektů blob se používá k ukládání stavu robota.

C#

Poznámka:

Od verze 4.10 Microsoft.Bot.Builder.Azure.AzureBlobStorage je zastaralé. Použijte nový Microsoft.Bot.Builder.Azure.Blobs.BlobsStorage na svém místě.

Následující ukázkový kód se spustí pomocí stejného kódu robota jako výše uvedený vzorek úložiště paměti s výjimkami uvedenými zde.

Následující fragmenty kódu ukazují implementaci úložiště objektů blob pro myStorage, která nahrazuje místní úložiště paměti.

Nejprve je potřeba aktualizovat Startup.cs , aby odkaz na knihovnu objektů blob Azure v Tvůrci robotů :

Startup.cs

using Microsoft.Bot.Builder.Azure.Blobs;

Dále v ConfigureServices metodě startup.cs vytvořte BlobsStorage objekt, který předává hodnoty z appsettings.json. Ten se předá do konstruktoru EchoBot prostřednictvím injektáže závislostí.

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

Teď musíte nejprve aktualizovat EchoBot.cs tak, aby odkazovat na knihovnu Azure Blobs v Tvůrci robotů :

EchoBot.cs

using Microsoft.Bot.Builder.Azure.Blobs;

Dále odeberte řádek kódu, který vytvoří proměnnou MemoryStorage private static readonly MemoryStorage _myStorage = new MemoryStorage(); a vytvořte novou proměnnou, která se použije k uložení uživatelského vstupu do služby Blob Storage.

EchoBot.cs

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

Pak předejte IStorage objekt konstruktoru EchoBot :

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

Jakmile je vaše úložiště nastavené tak, aby ukazovalo na váš účet Blob Storage, kód robota teď bude ukládat a načítat data z úložiště objektů blob.

JavaScript

Všechny změny kódu v této části jsou provedeny v index.js.

Nejprve přidejte kód, který vám umožní přístup k hodnotám ze souboru .env , který jste zadali dříve:

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

V dalším kroku budete muset místo interního úložiště Bot Frameworks provádět změny v úložišti objektů blob.

Dále přidejte odkaz na botbuilder-azure-blobs. Tím získáte přístup k rozhraní API služby Blob Storage:

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

Chcete-li upravit kód tak, aby používal BlobsStorage třídu, upravte deklaraci myStorage následujícím způsobem:

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

Jakmile je vaše úložiště nastavené tak, aby ukazovalo na váš účet Blob Storage, kód robota teď bude ukládat a načítat data z úložiště objektů blob.

Python

Následující ukázkový kód se spustí pomocí stejného kódu robota jako výše uvedený vzorek úložiště paměti s výjimkami uvedenými zde.

To bude vyžadovat BlobStorage a BlobStorageSettings od botbuilder-azure.

echo_bot.py

from botbuilder.azure import BlobStorage, BlobStorageSettings

Pokud chcete získat přístup k nastavení v config.py, importujete DefaultConfig ho, jak je znázorněno níže:

from config import DefaultConfig
CONFIG = DefaultConfig()

Dále odeberte nebo okomentujte kód __init__ úložiště paměti a přidejte odkaz na informace o úložišti objektů blob z config.py.

Následující fragment kódu ukazuje implementaci služby Blob Storage, která nahrazuje místní úložiště paměti.

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)

Jakmile je vaše úložiště nastavené tak, aby ukazovalo na váš účet Blob Storage, kód robota teď bude ukládat a načítat data z úložiště objektů blob.

Spuštění robota služby Blob Storage

Spusťte robota místně.

Spuštění emulátoru a připojení robota úložiště objektů blob

Potom spusťte emulátor a pak se připojte k robotovi v emulátoru:

1. Na kartě Vítejte v emulátoru vyberte odkaz Vytvořit novou konfiguraci robota.
2. Vyplňte pole pro připojení k robotovi s informacemi na webové stránce zobrazené při spuštění robota.

Interakce s robotem úložiště objektů blob

Pošlete robotovi zprávu a robot zobrazí seznam přijatých zpráv.

Zobrazení dat úložiště objektů blob

Po spuštění robota a uložení informací je můžeme zobrazit na kartě Průzkumník služby Storage na webu Azure Portal.

Úložiště přepisu objektů blob

Úložiště přepisů objektů blob v Azure poskytuje specializovanou možnost úložiště, která umožňuje snadno ukládat a načítat uživatelské konverzace ve formě zaznamenaného přepisu. Úložiště přepisu objektů blob v Azure je užitečné k automatickému zachytávání uživatelských vstupů, aby bylo možné zkoumat při ladění výkonu robota.

Poznámka:

Python v současné době nepodporuje úložiště přepisů objektů blob v Azure. JavaScript sice podporuje úložiště přepisů objektů blob, ale následující pokyny platí jenom pro jazyk C#.

Nastavení kontejneru úložiště přepisu objektů blob

Úložiště přepisu objektů blob v Azure může použít stejný účet úložiště objektů blob vytvořený podle kroků popsaných v částech Vytvoření účtu úložiště objektů blob a Přidání informací o konfiguraci výše. Teď přidáme kontejner pro uchovávání přepisů.

1. Otevřete účet služby Azure Blob Storage.
2. Vyberte Průzkumník služby Storage.
3. Klikněte pravým tlačítkem na KONTEJNERY OBJEKTŮ BLOB a vyberte vytvořit kontejner objektů blob.
4. Zadejte název kontejneru přepisu a pak vyberte OK. (Zadali jsme mybottranscripts)

Implementace úložiště přepisu objektů blob

Následující kód připojí ukazatel úložiště _myTranscripts přepisu k novému účtu úložiště přepisu objektů blob v Azure. Pokud chcete vytvořit tento odkaz s novým názvem kontejneru, <název kontejneru s přepisem objektu blob>, vytvoří nový kontejner v úložišti objektů blob pro uložení souborů přepisu.

Úložiště přepisů objektů blob je navržené tak, aby ukládaly přepisy robota.

Poznámka:

Od verze 4.10 Microsoft.Bot.Builder.Azure.AzureBlobTranscriptStore je zastaralé. Použijte nový Microsoft.Bot.Builder.Azure.Blobs.BlobsTranscriptStore na svém místě.

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

   ...
}

Ukládání uživatelských konverzací v přepisech objektů blob v Azure

Jakmile bude kontejner objektů blob k dispozici pro ukládání přepisů, můžete začít uchovávat konverzace uživatelů s robotem. Tyto konverzace můžete později použít jako nástroj pro ladění, abyste viděli, jak uživatelé komunikují s robotem. Každá konverzace restartování emulátoru zahájí vytvoření nového seznamu konverzací přepisu. Následující kód zachovává vstupy uživatelských konverzací v uloženém souboru přepisu.

• Aktuální přepis se uloží pomocí LogActivityAsync.
• Uložené přepisy se načítají pomocí ListTranscriptsAsync. V tomto ukázkovém kódu se ID každého uloženého přepisu uloží do seznamu s názvem "storedTranscripts". Tento seznam se později používá ke správě počtu uložených přepisů objektů blob, které uchováváme.

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

    ...
}

Správa uložených přepisů objektů blob

I když se uložené přepisy dají použít jako nástroj pro ladění, v průběhu času se počet uložených přepisů může zvětšit, než je potřeba zachovat. Další kód, který je uvedený níže, používá DeleteTranscriptAsync k odebrání všech, ale posledních tří načtených položek přepisu z úložiště přepisů objektů blob.

echoBot.cs

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

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

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

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

Další informace o třídě najdete v tématu Azure Blob Transcript Storage.

Další informace

Správa souběžnosti pomocí značek eTag

V příkladu kódu robota eTag nastavíme vlastnost každého z nich IStoreItem na *hodnotu . Člen eTag (značka entity) objektu úložiště se používá ve službě Cosmos DB ke správě souběžnosti. Informuje eTag vaši databázi, co dělat, pokud jiná instance robota změnila objekt ve stejném úložišti, do kterého robot zapisuje.

Poslední zápis wins – povolit přepsání

Hodnota eTag vlastnosti hvězdičky (*) označuje, že poslední zapisovač vyhraje. Při vytváření nového úložiště dat můžete nastavit eTag vlastnost * , která označuje, že jste dříve neuložili data, která píšete, nebo chcete, aby poslední zapisovač přepsal jakoukoli dříve uloženou vlastnost. Pokud u robota není problém s souběžností, nastavte eTag vlastnost na * všechna data, která píšete, přepsání povolí.

Zachování souběžnosti a zabránění přepsání

Při ukládání dat do služby Cosmos DB použijte jinou hodnotu než * pro eTag případ, že chcete zabránit souběžnému přístupu k vlastnosti a vyhnout se přepsání změn z jiné instance robota. Robot obdrží chybovou odpověď se zprávou etag conflict key= , když se pokusí uložit data o stavu a eTag není stejná hodnota jako v úložišti eTag .

Úložiště Cosmos DB ve výchozím nastavení kontroluje eTag vlastnost objektu úložiště na rovnost při každém zápisu robota do této položky a po každém zápisu ji aktualizuje na novou jedinečnou hodnotu. Pokud vlastnost při zápisu eTageTag neodpovídá vlastnosti v úložišti, znamená to, že data změnil jiný robot nebo vlákno.

Řekněme například, že chcete, aby robot upravil uloženou poznámku, ale nechcete, aby robot přepsal změny, které udělal jiný výskyt robota. Pokud jiná instance robota provedla úpravy, chcete, aby uživatel upravil verzi s nejnovějšími aktualizacemi.

C#

Nejprve vytvořte třídu, která implementuje IStoreItem.

EchoBot.cs

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

Dále vytvořte počáteční poznámku tak, že vytvoříte objekt úložiště a přidáte ho do úložiště.

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

Potom se k poznámce dostanete a později ji aktualizujete a zachováte eTag tak, že si ji přečtete ze storu.

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

Pokud byla poznámka před zápisem změn aktualizována v úložišti, vyvolá volání Write výjimku.

JavaScript

Na konec robota přidejte pomocnou funkci, která do úložiště dat napíše ukázkovou poznámku. Nejprve vytvořte myNoteData 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 V pomocné funkci inicializujete changes objekt a přidáte do něj poznámky a pak ho napíšete do úložiště.

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

Pomocná funkce se přistupuje z logiky robota přidáním následujícího volání:

bot.js

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

Po vytvoření vytvoříme pro pozdější načtení a aktualizaci poznámky vytvoříme další pomocnou funkci, ke které se dostanete, když uživatel zadá "update note".

bot.js

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

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

Tato pomocná funkce se přistupuje z logiky robota přidáním následujícího volání:

bot.js

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

Pokud byla poznámka v úložišti aktualizována jiným uživatelem před pokusem o zápis změn zpět, eTag hodnota se už neshoduje a volání write vyvolá výjimku.

Python

Nejprve vytvořte třídu, která implementuje 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

Dále vytvořte počáteční poznámku tak, že vytvoříte objekt úložiště a přidáte ho do úložiště.

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)

Potom se k poznámce dostanete a později ji aktualizujete a zachováte eTag tak, že si ji přečtete ze storu.

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)

Pokud byla poznámka před zápisem změn aktualizována v úložišti, vyvolá volání write výjimku.

Chcete-li zachovat souběžnost, vždy načtěte vlastnost z úložiště a potom upravte vlastnost, kterou jste přečetli, aby byla zachována eTag . Pokud načtete uživatelská data z úložiště, odpověď bude obsahovat vlastnost eTag. Pokud změníte data a zapíšete aktualizovaná data do úložiště, měla by vaše žádost obsahovat vlastnost eTag, která určuje stejnou hodnotu, jakou jste si přečetli dříve. Zápis objektu s nastavenou eTag sadou * však umožní zápisu přepsat všechny ostatní změny.

Další kroky

Když teď víte, jak číst a zapisovat přímo z úložiště, podívejte se, jak to můžete pomocí správce stavů udělat za vás.

Uložení stavu pomocí konverzačních a uživatelských vlastností