Zapisywanie bezpośrednio w magazynie

Artykuł
03/08/2023

DOTYCZY: ZESTAW SDK w wersji 4

Możesz odczytywać i zapisywać bezpośrednio w obiekcie magazynu bez użycia oprogramowania pośredniczącego lub obiektu kontekstu. Może to być odpowiednie dla danych używanych przez bota do zachowania konwersacji lub danych pochodzących ze źródła spoza przepływu konwersacji bota. W tym modelu magazynu danych dane są odczytywane bezpośrednio z magazynu zamiast przy użyciu menedżera stanu. Przykłady kodu w tym artykule pokazują, jak odczytywać i zapisywać dane w magazynie przy użyciu pamięci, usługi Cosmos DB, usługi Azure Blob i magazynu transkrypcji obiektów blob platformy Azure.

Uwaga

Zestawy SDK języka JavaScript, C# i Python platformy Bot Framework będą nadal obsługiwane, jednak zestaw SDK języka Java jest wycofywany z ostatecznym długoterminowym wsparciem kończącym się w listopadzie 2023 r. Zostaną podjęte tylko krytyczne poprawki zabezpieczeń i usterek w tym repozytorium.

Istniejące boty utworzone za pomocą zestawu JAVA SDK będą nadal działać.

W przypadku tworzenia nowego bota rozważ użycie agentów usługi Power Virtual Agents i przeczytaj o wyborze odpowiedniego rozwiązania czatbota.

Aby uzyskać więcej informacji, zobacz Przyszłość tworzenia botów.

Wymagania wstępne

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.
Znajomość tworzenia bota lokalnie.
Szablony zestawu Bot Framework SDK w wersji 4 dla programu Visual Studio (C#), Node.js lub Yeoman.

Uwaga

Szablony można zainstalować z poziomu programu Visual Studio.

W menu wybierz pozycję Rozszerzenia, a następnie zarządzaj rozszerzeniami.
W oknie dialogowym Zarządzanie rozszerzeniami wyszukaj i zainstaluj szablony zestawu Bot Framework w wersji 4 zestawu SDK dla programu Visual Studio.

Aby uzyskać informacje na temat wdrażania botów platformy .NET na platformie Azure, zobacz jak aprowizować i publikować bota.

Informacje o tym przykładzie

Przykładowy kod w tym artykule rozpoczyna się od struktury podstawowego bota echa, a następnie rozszerza funkcjonalność tego bota, dodając dodatkowy kod (podany poniżej). Ten rozszerzony kod tworzy listę w celu zachowania danych wejściowych użytkownika w miarę ich odbierania. Każda kolej, pełna lista danych wejściowych użytkownika, zapisana w pamięci, jest zwracana z powrotem do użytkownika. Struktura danych zawierająca tę listę danych wejściowych jest następnie modyfikowana w celu zapisania w magazynie. Różne typy magazynu są eksplorowane jako dodatkowe funkcje dodawane do tego przykładowego kodu.

Magazyn pamięci

Zestaw BOT Framework SDK umożliwia przechowywanie danych wejściowych użytkownika przy użyciu magazynu w pamięci. Ponieważ magazyn w pamięci jest czyszczone za każdym razem, gdy bot jest ponownie uruchamiany, najlepiej nadaje się do celów testowych i nie jest przeznaczony do użytku produkcyjnego. Trwałe typy magazynów, takie jak magazyn bazy danych, są najlepsze dla botów produkcyjnych.

Tworzenie podstawowego bota

W pozostałej części tego tematu jest kompilowane bot echo. Przykładowy kod bota echo można utworzyć lokalnie, wykonując instrukcje z przewodnika Szybki start dotyczące tworzenia bota.

Zastąp kod w pliku EchoBot.cs następującym kodem:

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

Aby użyć pliku konfiguracji env , bot potrzebuje dodatkowego pakietu. Jeśli jeszcze nie zainstalowano, pobierz pakiet .NET z narzędzia npm:

npm install --save dotenv

Zmodyfikuj kod w pliku index.js , który tworzy główne okno dialogowe. Istniejący wiersz kodu do utworzenia głównego okna dialogowego to const myBot = new EchoBot();, musi zostać zaktualizowany, aby umożliwić przekazanie obiektu magazynu do EchoBot konstruktora, aby można było przechowywać dane wejściowe użytkownika w pamięci wewnętrznej bota:

Najpierw należy dodać odwołanie do MemoryStorage elementu w pliku botbuilder:

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

Następnie utwórz obiekt magazynu pamięci i przekaż go do konstruktora EchoBot :

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

MemoryStorage Przekazuje to obiekt do konstruktoraEchoBot. Później zmienisz to, aby przekazać obiekt usługi Cosmos DB lub blob Storage .

Następnie zastąp kod w pliku bot.js następującym kodem:

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;

Zastąp kod w pliku echo_bot.py następującym kodem:

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

Uruchamianie bota

Uruchom bota lokalnie.

Uruchom emulator i połącz bota

Zainstaluj emulator platformy Bot Framework Dalej, uruchom emulator, a następnie połącz się z botem w emulatorze:

Wybierz link Utwórz nową konfigurację bota na karcie Powitanie emulatora.
Wypełnij pola, aby nawiązać połączenie z botem, biorąc pod uwagę informacje na stronie internetowej wyświetlanej podczas uruchamiania bota.

Interakcja z botem

Wyślij wiadomość do bota. Bot wyświetli listę odebranych komunikatów.

A conversation with the bot that shows the bot keeping a list of messages from the user.

W pozostałej części tego artykułu przedstawiono sposób zapisywania w magazynie trwałym zamiast pamięci wewnętrznej bota.

Korzystanie z usługi Cosmos DB

Ważne

Klasa magazynu usługi Cosmos DB jest przestarzała. Kontenery pierwotnie utworzone za pomocą usługi CosmosDbStorage nie miały ustawionego klucza partycji i otrzymały domyślny klucz partycji _/partitionKey.

Kontenery utworzone za pomocą magazynu usługi Cosmos DB mogą być używane z magazynem podzielonym na partycje usługi Cosmos DB. Aby uzyskać więcej informacji, przeczytaj artykuł Partitioning in Azure Cosmos DB (Partycjonowanie w usłudze Azure Cosmos DB ).

Należy również pamiętać, że w przeciwieństwie do starszego magazynu usługi Cosmos DB magazyn podzielony na partycje usługi Cosmos DB nie tworzy automatycznie bazy danych na koncie usługi Cosmos DB. Musisz ręcznie utworzyć nową bazę danych, ale pomiń ręcznie tworzenie kontenera, ponieważ usługa CosmosDbPartitionedStorage utworzy kontener.

Teraz, gdy już używasz magazynu pamięci, zaktualizujemy kod, aby używał usługi Azure Cosmos DB. Cosmos DB to globalnie rozproszona, wielomodelowa baza danych firmy Microsoft. Usługa Azure Cosmos DB umożliwia elastyczne i niezależne skalowanie przepływności i magazynu w dowolnej liczbie regionów geograficznych platformy Azure. Oferuje ona gwarancje przepływności, opóźnienia, dostępności i spójności z kompleksowymi umowami dotyczącymi poziomu usług (SLA).

Konfigurowanie zasobu usługi Cosmos DB

Aby używać usługi Cosmos DB w botze, należy utworzyć zasób bazy danych przed przejściem do kodu. Szczegółowy opis tworzenia bazy danych i aplikacji usługi Cosmos DB można znaleźć w przewodniku Szybki start dla platformy .NET, Node.js lub Python.

Tworzenie konta bazy danych

Przejdź do witryny Azure Portal, aby utworzyć konto usługi Azure Cosmos DB. Wyszukaj i wybierz pozycję Azure Cosmos DB.
Na stronie Azure Cosmos DB wybierz pozycję Nowy, aby wyświetlić stronę Tworzenie konta usługi Azure Cosmos DB.
Podaj wartości dla następujących pól:
1. Subskrypcja. Wybierz subskrypcję platformy Azure, której chcesz użyć dla tego konta usługi Azure Cosmos.
2. Grupa zasobów. Wybierz istniejącą grupę zasobów lub wybierz pozycję Utwórz nową, a następnie wprowadź nazwę nowej grupy zasobów.
3. Nazwa konta. Wprowadź nazwę, która będzie identyfikować konto usługi Azure Cosmos. Ponieważ adres documents.azure.com jest dołączany do podanej nazwy w celu utworzenia identyfikatora URI, użyj unikatowej nazwy. Zwróć uwagę na następujące wskazówki:
  - Nazwa musi być unikatowa na platformie Azure.
  - Nazwa musi mieć długość od 3 do 31 znaków.
  - Nazwa może zawierać tylko małe litery, cyfry i znak łącznika (-).
4. Interfejs API. Wybierz pozycję Core(SQL)
5. Lokalizacja. wybierz lokalizację znajdującą się najbliżej użytkowników, aby zapewnić im najszybszy dostęp do danych.
Wybierz pozycję Przejrzyj i utwórz.
Po zweryfikowaniu wybierz pozycję Utwórz.

Tworzenie konta potrwa kilka minut. Poczekaj, aż portal wyświetli gratulacje ! Konto usługi Azure Cosmos DB zostało utworzone na stronie.

Dodawanie bazy danych

Uwaga

Nie twórz kontenera samodzielnie. Bot utworzy go podczas tworzenia wewnętrznego klienta usługi Cosmos DB, upewniając się, że jest poprawnie skonfigurowany do przechowywania stanu bota.

Przejdź do strony Eksplorator danych na nowo utworzonym koncie usługi Cosmos DB, a następnie wybierz pozycję Nowa baza danych z listy rozwijanej Nowy kontener . Następnie panel zostanie otwarty po prawej stronie okna, w którym można wprowadzić szczegóły nowej bazy danych.
Wprowadź identyfikator nowej bazy danych i opcjonalnie ustaw przepływność (możesz zmienić tę wartość później), a na koniec wybierz przycisk OK , aby utworzyć bazę danych. Zanotuj ten identyfikator bazy danych do późniejszego użycia podczas konfigurowania bota.
Po utworzeniu konta usługi Cosmos DB i bazy danych należy skopiować niektóre wartości umożliwiające zintegrowanie nowej bazy danych z botem. Aby je pobrać, przejdź do karty Klucze w sekcji ustawienia bazy danych konta usługi Cosmos DB. Na tej stronie będziesz potrzebować identyfikatora URI (punktu końcowego usługi Cosmos DB) i klucza PODSTAWOWEgo (klucza autoryzacji).

Teraz powinno istnieć konto usługi Cosmos DB z bazą danych i następujące wartości gotowe do użycia w ustawieniach bota.

Identyfikator URI
Klucz podstawowy
Identyfikator bazy danych

Dodawanie informacji o konfiguracji usługi Cosmos DB

Użyj szczegółów zanotuj w poprzedniej części tego artykułu, aby ustawić punkt końcowy, klucz autoryzacji i identyfikator bazy danych. Na koniec należy wybrać odpowiednią nazwę kontenera, który zostanie utworzony w bazie danych w celu przechowywania stanu bota. W poniższym przykładzie utworzony kontener usługi Cosmos DB będzie miał nazwę "bot-storage".

Dodaj następujące informacje do pliku konfiguracji.

appsettings.json

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

Dodaj następujące informacje do pliku env .

.Env

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

Dodaj następujące informacje do pliku konfiguracji.

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"

Instalowanie pakietów usługi Cosmos DB

Upewnij się, że masz pakiety niezbędne dla usługi Cosmos DB.

Zainstaluj pakiet NuGet Microsoft.Bot.Builder.Azure. Aby uzyskać więcej informacji na temat korzystania z pakietu NuGet, zobacz Instalowanie pakietów i zarządzanie nimi w programie Visual Studio przy użyciu Menedżer pakietów NuGet.

Dodaj odwołanie do botbuilder-azure przy użyciu narzędzia npm.

npm install --save botbuilder-azure

Jeśli jeszcze nie zainstalowano, pobierz pakiet .NET z narzędzia npm, aby uzyskać dostęp do ustawień pliku env .

npm install --save dotenv

Możesz dodać odwołanie do botbuilder-azure w projekcie za pośrednictwem narzędzia pip.

pip install botbuilder-azure

Implementacja usługi Cosmos DB

Uwaga

W wersji 4.6 wprowadzono nowego dostawcę magazynu usługi Cosmos DB, klasę magazynu podzielonego na partycje usługi Cosmos DB, a oryginalna klasa magazynu usługi Cosmos DB jest przestarzała. Kontenery utworzone za pomocą magazynu usługi Cosmos DB mogą być używane z magazynem podzielonym na partycje usługi Cosmos DB. Aby uzyskać więcej informacji, przeczytaj artykuł Partitioning in Azure Cosmos DB (Partycjonowanie w usłudze Azure Cosmos DB ).

W przeciwieństwie do starszego magazynu usługi Cosmos DB magazyn podzielony na partycje usługi Cosmos DB nie tworzy automatycznie bazy danych na koncie usługi Cosmos DB. Musisz ręcznie utworzyć nową bazę danych, ale pomiń ręcznie tworzenie kontenera, ponieważ usługa CosmosDbPartitionedStorage utworzy kontener.

Poniższy przykładowy kod jest uruchamiany przy użyciu tego samego kodu bota co przykład magazynu pamięci podany powyżej, z wyjątkami wymienionymi tutaj. Poniższe fragmenty kodu pokazują implementację magazynu usługi Cosmos DB dla magazynu "myStorage", który zastępuje lokalny magazyn pamięci.

Najpierw należy zaktualizować plik Startup.cs , aby odwołać się do biblioteki platformy Azure konstruktora botów:

using Microsoft.Bot.Builder.Azure;

Następnie w metodzie ConfigureServices w pliku Startup.cs utwórz CosmosDbPartitionedStorage obiekt . Zostanie to przekazane do konstruktora EchoBot przez wstrzyknięcie zależności.

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

W pliku EchoBot.cs zmień deklarację private static readonly MemoryStorage _myStorage = new MemoryStorage(); zmiennej _myStorage na następującą:

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

Następnie przekaż IStorage obiekt do konstruktora EchoBot :

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

Najpierw dodaj kod do pliku index.js , aby umożliwić dostęp do wartości z wprowadzonego wcześniej pliku env :

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

Następnie należy wprowadzić zmiany w pliku index.js , aby używać magazynu partycjonowanego usługi Cosmos DB zamiast magazynu wewnętrznego Bot Frameworks. Wszystkie zmiany kodu w tej sekcji są wprowadzane w pliku index.js.

Najpierw dodaj odwołanie do botbuilder-azure w pliku index.js. Zapewni to dostęp do CosmosDbPartitionedStorage klasy.

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

Następnie utwórz nowy CosmosDbPartitionedStorage obiekt.

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

Teraz możesz oznaczyć komentarz lub usunąć wcześniej dodaną deklarację myStorage const, ponieważ nie zapisujesz już danych wejściowych użytkownika w wewnętrznym magazynie platformy Bot Framework, ale zamiast tego w usłudze Cosmos DB:

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

Poniższy przykładowy kod jest uruchamiany przy użyciu tego samego kodu bota co przykład magazynu pamięci podany powyżej, z wyjątkami wymienionymi tutaj.

Do CosmosDbPartitionedStorage utworzenia obiektu CosmosDBStorage są wymagane elementy i CosmosDbPartitionedConfig .botbuilder-azure

echo_bot.py

from botbuilder.azure import CosmosDbPartitionedStorage, CosmosDbPartitionedConfig

Aby uzyskać dostęp do ustawień w config.py, zaimportujesz DefaultConfig je, jak pokazano poniżej:

from config import DefaultConfig
CONFIG = DefaultConfig()

Oznacz jako komentarz magazyn pamięci i __init__ zastąp element odwołaniem do usługi Cosmos DB. Użyj identyfikatora URI (punktu końcowego), klucza podstawowego (klucza autoryzacji), identyfikatora bazy danych i użytego powyżej identyfikatora kontenera.

Następnie usuń lub oznacz jako komentarz kod magazynu pamięci w __init__ pliku i dodaj odwołanie do informacji usługi Cosmos DB z config.py.

Poniższy fragment kodu przedstawia implementację usługi Cosmos DB dla magazynu , która zastępuje lokalny magazyn pamięci.

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)

Uruchamianie bota usługi Cosmos DB

Uruchom bota lokalnie.

Testowanie bota usługi Cosmos DB za pomocą emulatora platformy Bot Framework

Teraz uruchom program Bot Framework Emulator i połącz się z botem:

Wybierz link Utwórz nową konfigurację bota na karcie Powitanie emulatora.
Wypełnij pola, aby nawiązać połączenie z botem, biorąc pod uwagę informacje na stronie internetowej wyświetlanej podczas uruchamiania bota.

Interakcja z botem usługi Cosmos DB

Wyślij wiadomość do bota, a bot wyświetli listę odebranych wiadomości.

A conversation with the bot that shows the bot keeping a list of messages from the user.

Wyświetlanie danych usługi Cosmos DB

Po uruchomieniu bota i zapisaniu informacji możesz wyświetlić dane przechowywane w witrynie Azure Portal na karcie Eksplorator danych.

Screenshot of the Data Explorer in the Azure portal.

Korzystanie z usługi Blob Storage

Azure Blob Storage to rozwiązanie do magazynowania obiektów w chmurze firmy Microsoft. Usługa Blob Storage jest zoptymalizowana pod kątem przechowywania olbrzymich ilości danych bez struktury, takich jak dane tekstowe lub binarne. W tej sekcji wyjaśniono, jak utworzyć konto i kontener usługi Azure Blob Storage, a następnie odwołać się do kontenera magazynu obiektów blob z bota.

Aby uzyskać więcej informacji na temat usługi Blob Storage, zobacz Co to jest usługa Azure Blob Storage?

Tworzenie konta usługi Blob Storage

Aby korzystać z usługi Blob Storage w botze, przed przejściem do kodu należy skonfigurować kilka rzeczy.

W witrynie Azure Portal wybierz pozycję Wszystkie usługi.
W sekcji Polecane na stronie Wszystkie usługi wybierz pozycję Konta magazynu.
Na stronie Konta magazynu wybierz pozycję Nowy.
W polu Subskrypcja wybierz subskrypcję, w której chcesz utworzyć konto magazynu.
W polu Grupa zasobów wybierz istniejącą grupę zasobów lub wybierz pozycję Utwórz nową, a następnie wprowadź nazwę nowej grupy zasobów.
W polu Nazwa konta magazynu wprowadź nazwę konta. Zwróć uwagę na następujące wskazówki:
- Nazwa musi być unikatowa na platformie Azure.
- Nazwa musi mieć długość od 3 do 24 znaków.
- Nazwa może zawierać tylko cyfry i małe litery.
W polu Lokalizacja wybierz lokalizację konta magazynu lub użyj lokalizacji domyślnej.
W przypadku pozostałych ustawień skonfiguruj następujące ustawienia:
- Wydajność: Standardowa. Dowiedz się więcej o wydajności.
- Rodzaj konta: BlobStorage. Dowiedz się więcej o kontach magazynu.
- Replikacja: pozostaw ustawienie domyślne. Dowiedz się więcej o nadmiarowości.
W sekcji Szczegóły projektu na stronie Tworzenie konta magazynu wybierz żądane wartości dla subskrypcji i grupy zasobów.
W sekcji Szczegóły wystąpienia na stronie Tworzenie konta magazynu wprowadź nazwę konta magazynu, a następnie wybierz wartości lokalizacji, rodzaju konta i replikacji.
Wybierz pozycję Przejrzyj i utwórz , aby przejrzeć ustawienia konta magazynu.
Po zweryfikowaniu wybierz pozycję Utwórz.

Tworzenie kontenera usługi Blob Storage

Po utworzeniu konta usługi Blob Storage otwórz je, a następnie:

Wybierz pozycję Eksplorator usługi Storage (wersja zapoznawcza).
Następnie kliknij prawym przyciskiem myszy pozycję KONTENERY OBIEKTÓW BLOB
Wybierz pozycję Utwórz kontener obiektów blob z listy rozwijanej.
Wprowadź nazwę w formularzu Nowy kontener . Użyjesz tej nazwy jako wartości "nazwy kontenera obiektów blob", aby zapewnić dostęp do konta usługi Blob Storage. Zwróć uwagę na następujące wskazówki:
- Ta nazwa może zawierać tylko małe litery, cyfry i łączniki.
- Ta nazwa musi zaczynać się literą lub cyfrą.
- Każdy łącznik musi być poprzedzony i poprzedzony prawidłowym znakiem niebędącym łącznikiem.
- Nazwa musi mieć długość od 3 do 63 znaków.

Dodawanie informacji o konfiguracji usługi Blob Storage

Znajdź klucze magazynu obiektów blob, które należy skonfigurować dla bota, jak pokazano powyżej:

W witrynie Azure Portal otwórz konto usługi Blob Storage i wybierz pozycję Klucze dostępu w sekcji Ustawienia.
Aby skonfigurować bota w celu uzyskania dostępu do konta usługi Blob Storage, użyj ciągu Połączenie ion jako wartości parametry połączenia obiektu blob.

Dodaj następujące informacje do pliku konfiguracji.

appsettings.json

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

Dodaj następujące informacje do pliku env .

.Env

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

Dodaj następujące informacje do pliku konfiguracji. Użyj tej samej nazwy kontenera i parametry połączenia używanej podczas tworzenia kontenera magazynu obiektów blob.

config.py

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

Instalowanie pakietów usługi Blob Storage

Jeśli nie zainstalowano wcześniej, zainstaluj następujące pakiety.

Zainstaluj pakiet NuGet Microsoft.Bot.Builder.Azure.Blobs. Aby uzyskać więcej informacji na temat korzystania z pakietu NuGet, zobacz Instalowanie pakietów i zarządzanie nimi w programie Visual Studio przy użyciu Menedżer pakietów NuGet.

Dodaj odwołania do botbuilder-azure-blobs elementu w projekcie za pomocą narzędzia npm.

Uwaga

Ten pakiet npm opiera się na instalacji języka Python istniejącej na komputerze deweloperskim. Jeśli wcześniej nie zainstalowano języka Python, możesz znaleźć zasoby instalacyjne maszyny na Python.org

npm install --save botbuilder-azure-blobs

Jeśli jeszcze nie zainstalowano, pobierz pakiet .NET z narzędzia npm, aby uzyskać dostęp do ustawień pliku env .

npm install --save dotenv

Możesz dodać odwołanie do botbuilder-azure w projekcie za pośrednictwem narzędzia pip.

pip install botbuilder-azure

Implementacja usługi Blob Storage

Magazyn obiektów blob służy do przechowywania stanu bota.

Uwaga

Wersja 4.10 Microsoft.Bot.Builder.Azure.AzureBlobStorage jest przestarzała. Użyj nowego Microsoft.Bot.Builder.Azure.Blobs.BlobsStorage w swoim miejscu.

Poniższy przykładowy kod jest uruchamiany przy użyciu tego samego kodu bota co przykład magazynu pamięci podany powyżej, z wyjątkami wymienionymi tutaj.

Poniższe fragmenty kodu pokazują implementację usługi Blob Storage dla magazynu "myStorage", która zastępuje lokalny magazyn pamięci.

Najpierw należy zaktualizować plik Startup.cs , aby odwołać się do biblioteki obiektów blob platformy Azure konstruktora botów :

Startup.cs

using Microsoft.Bot.Builder.Azure.Blobs;

Następnie w metodzie ConfigureServices w pliku Startup.cs utwórz BlobsStorage obiekt, przekazując wartości z pliku appsettings.json. Zostanie to przekazane do konstruktora EchoBot przez wstrzyknięcie zależności.

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

Teraz musisz zaktualizować plik EchoBot.cs , aby odwołać się do biblioteki obiektów blob platformy Azure konstruktora botów :

EchoBot.cs

using Microsoft.Bot.Builder.Azure.Blobs;

Następnie usuń lub oznacz jako komentarz wiersz kodu, który tworzy zmienną MemoryStorage "private static readonly MemoryStorage _myStorage = new MemoryStorage();" i utwórz nową zmienną, która będzie używana do zapisywania danych wejściowych użytkownika w usłudze Blob Storage.

EchoBot.cs

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

Następnie przekaż IStorage obiekt do konstruktora EchoBot :

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

Gdy magazyn zostanie ustawiony tak, aby wskazywał konto usługi Blob Storage, kod bota będzie teraz przechowywać i pobierać dane z usługi Blob Storage.

Wszystkie zmiany kodu w tej sekcji są wprowadzane w pliku index.js.

Najpierw dodaj kod, aby umożliwić dostęp do wartości z wprowadzonego wcześniej pliku env :

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

Następnie należy wprowadzić zmiany w usłudze Blob Storage zamiast magazynu wewnętrznego Bot Frameworks.

Następnie dodaj odwołanie do botbuilder-azure-blobs. Zapewni to dostęp do interfejsu API usługi Blob Storage:

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

Aby zmodyfikować kod do użycia klasy, zmodyfikuj BlobsStoragemyStorage deklarację w następujący sposób:

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

Gdy magazyn zostanie ustawiony tak, aby wskazywał konto usługi Blob Storage, kod bota będzie teraz przechowywać i pobierać dane z usługi Blob Storage.

Poniższy przykładowy kod jest uruchamiany przy użyciu tego samego kodu bota co przykład magazynu pamięci podany powyżej, z wyjątkami wymienionymi tutaj.

Będzie to wymagało BlobStorage i BlobStorageSettings z botbuilder-azure.

echo_bot.py

from botbuilder.azure import BlobStorage, BlobStorageSettings

Aby uzyskać dostęp do ustawień w config.py, zaimportujesz DefaultConfig je, jak pokazano poniżej:

from config import DefaultConfig
CONFIG = DefaultConfig()

Następnie usuń lub oznacz jako komentarz kod magazynu pamięci w __init__ pliku i dodaj odwołanie do informacji o magazynie obiektów blob z config.py.

Poniższy fragment kodu przedstawia implementację usługi Blob Storage, która zastępuje lokalny magazyn pamięci.

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)

Gdy magazyn zostanie ustawiony tak, aby wskazywał konto usługi Blob Storage, kod bota będzie teraz przechowywać i pobierać dane z usługi Blob Storage.

Uruchamianie bota usługi Blob Storage

Uruchom bota lokalnie.

Uruchom emulator i połącz bota usługi Blob Storage

Następnie uruchom emulator, a następnie połącz się z botem w emulatorze:

Wybierz link Utwórz nową konfigurację bota na karcie Emulator "Witamy".
Wypełnij pola, aby nawiązać połączenie z botem, biorąc pod uwagę informacje na stronie internetowej wyświetlanej podczas uruchamiania bota.

Interakcja z botem usługi Blob Storage

Wyślij wiadomość do bota, a bot wyświetli listę odbieranych komunikatów.

A conversation with the bot that shows the bot keeping a list of messages from the user.

Wyświetlanie danych usługi Blob Storage

Po uruchomieniu bota i zapisaniu informacji możemy wyświetlić je na karcie Eksplorator usługi Storage w witrynie Azure Portal.

Magazyn transkrypcji obiektów blob

Magazyn transkrypcji obiektów blob platformy Azure udostępnia wyspecjalizowaną opcję magazynu, która umożliwia łatwe zapisywanie i pobieranie konwersacji użytkowników w formie zarejestrowanej transkrypcji. Magazyn transkrypcji obiektów blob platformy Azure jest przydatny do automatycznego przechwytywania danych wejściowych użytkownika w celu sprawdzenia podczas debugowania wydajności bota.

Uwaga

Język Python nie obsługuje obecnie magazynu transkrypcji obiektów blob platformy Azure. Chociaż język JavaScript obsługuje magazyn transkrypcji obiektów blob, następujące wskazówki dotyczą tylko języka C#.

Konfigurowanie kontenera magazynu transkrypcji obiektów blob

Magazyn transkrypcji obiektów blob platformy Azure może używać tego samego konta usługi Blob Storage utworzonego zgodnie z instrukcjami opisanymi w sekcjach "Tworzenie konta magazynu obiektów blob" i "Dodawanie informacji o konfiguracji" powyżej. Teraz dodajemy kontener do przechowywania naszych transkrypcji

Screenshot of creating a blob container to use as a transcript store.

Otwórz konto usługi Azure Blob Storage.
Wybierz pozycję Eksplorator usługi Storage.
Kliknij prawym przyciskiem myszy pozycję KONTENERY OBIEKTÓW BLOB i wybierz pozycję Utwórz kontener obiektów blob.
Wprowadź nazwę kontenera transkrypcji, a następnie wybierz przycisk OK. (Wprowadziliśmy skrypty mybottranscripts)

Implementacja magazynu transkrypcji obiektów blob

Poniższy kod łączy wskaźnik _myTranscripts magazynu transkrypcji z nowym kontem magazynu transkrypcji obiektów blob platformy Azure. Aby utworzyć ten link przy użyciu nowej nazwy kontenera, <nazwa-transkrypcji-kontenera-obiektu> blob tworzy nowy kontener w usłudze Blob Storage do przechowywania plików transkrypcji.

Magazyn transkrypcji obiektów blob jest przeznaczony do przechowywania transkrypcji botów.

Uwaga

Wersja 4.10 Microsoft.Bot.Builder.Azure.AzureBlobTranscriptStore jest przestarzała. Użyj nowego Microsoft.Bot.Builder.Azure.Blobs.BlobsTranscriptStore w swoim miejscu.

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

   ...
}

Przechowywanie konwersacji użytkowników w transkrypcjach obiektów blob platformy Azure

Po udostępnieniu kontenera obiektów blob do przechowywania transkrypcji można rozpocząć zachowywanie konwersacji użytkowników z botem. Te konwersacje mogą być później używane jako narzędzie do debugowania, aby zobaczyć, jak użytkownicy wchodzą w interakcję z botem. Każda konwersacja ponownego uruchomienia emulatora inicjuje tworzenie nowej listy konwersacji transkrypcji. Poniższy kod zachowuje dane wejściowe konwersacji użytkownika w przechowywanym pliku transkrypcji.

Bieżąca transkrypcja jest zapisywana przy użyciu polecenia LogActivityAsync.
Zapisane transkrypcje są pobierane przy użyciu polecenia ListTranscriptsAsync. W tym przykładowym kodzie identyfikator każdego przechowywanego transkrypcji jest zapisywany na liście o nazwie "storedTranscripts". Ta lista jest później używana do zarządzania liczbą przechowywanych transkrypcji obiektów blob zachowanych.

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

    ...
}

Zarządzanie przechowywanymi transkrypcjami obiektów blob

Podczas gdy przechowywane transkrypcje mogą być używane jako narzędzie do debugowania, wraz z upływem czasu liczba przechowywanych transkrypcji może być większa niż dbanie o zachowanie. Poniższy dodatkowy kod umożliwia DeleteTranscriptAsync usunięcie wszystkich elementów transkrypcji pobranych z magazynu transkrypcji obiektów blob z ostatnich trzech elementów.

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

Aby uzyskać więcej informacji na temat klasy, zobacz Magazyn transkrypcji obiektów blob platformy Azure.

Dodatkowe informacje

Zarządzanie współbieżnością przy użyciu elementów eTag

W naszym przykładzie kodu bota eTag ustawimy właściwość każdej IStoreItem z nich na *wartość . Element eTag członkowski (tag jednostki) obiektu magazynu jest używany w usłudze Cosmos DB do zarządzania współbieżnością. Polecenie eTag informuje bazę danych o tym, co należy zrobić, jeśli inne wystąpienie bota zmieniło obiekt w tym samym magazynie, do którego pisze bot.

Ostatnie zwycięstwa zapisu — zezwalaj na zastępowanie

eTag Wartość właściwości gwiazdki (*) wskazuje, że ostatni składnik zapisywania wygrywa. Podczas tworzenia nowego magazynu danych można ustawić eTag właściwość, aby * wskazać, że nie zapisano wcześniej zapisanych danych lub chcesz, aby ostatni zapisał dowolną wcześniej zapisaną właściwość. Jeśli współbieżność nie jest problemem dla bota, ustawienie eTag właściwości na * wartość dla wszystkich zapisywanych danych powoduje zastąpienie.

Obsługa współbieżności i zapobieganie zastępowaniu

Podczas przechowywania danych w usłudze Cosmos DB użyj wartości innej niż * dla eTag elementu , jeśli chcesz uniemożliwić współbieżny dostęp do właściwości i uniknąć zastępowania zmian z innego wystąpienia bota. Bot otrzymuje odpowiedź o błędzie z komunikatem etag conflict key= podczas próby zapisania danych stanu, a eTag wartość nie jest taka sama jak eTag w magazynie.

Domyślnie magazyn usługi Cosmos DB sprawdza eTag właściwość obiektu magazynu pod kątem równości za każdym razem, gdy bot zapisuje w tym elemencie, a następnie aktualizuje ją do nowej unikatowej wartości po każdym zapisie. eTag Jeśli właściwość zapisu nie jest zgodna z właściwością eTag w magazynie, oznacza to, że inny bot lub wątek zmienił dane.

Załóżmy na przykład, że chcesz, aby bot edytował zapisaną notatkę, ale nie chcesz, aby bot zastępował zmiany wprowadzone przez inne wystąpienie bota. Jeśli inne wystąpienie bota dokonało edycji, chcesz, aby użytkownik edytował wersję przy użyciu najnowszych aktualizacji.

Najpierw utwórz klasę, która implementuje IStoreItemelement .

EchoBot.cs

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

Następnie utwórz początkową notatkę, tworząc obiekt magazynu i dodając obiekt do magazynu.

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

Następnie uzyskaj dostęp do notatki i zaktualizuj je później, przechowując informacje eTag odczytywane ze sklepu.

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

Jeśli notatka została zaktualizowana w sklepie przed zapisaniem zmian, wywołanie Write metody zgłosi wyjątek.

Dodaj funkcję pomocnika na końcu bota, która napisze przykładową notatkę do magazynu danych. Najpierw utwórz myNoteData obiekt.

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: "*"
    }
}

W funkcji pomocnika zainicjuj createSampleNotechanges obiekt i dodaj do niego notatki , a następnie zapisz go w magazynie.

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

Funkcja pomocnika jest dostępna z poziomu logiki bota, dodając następujące wywołanie:

bot.js

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

Po utworzeniu, aby później pobrać i zaktualizować notatkę, tworzymy inną funkcję pomocnika, do której można uzyskać dostęp, gdy użytkownik wpisze wartość "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}`);
    }
}

Ta funkcja pomocnika jest dostępna z poziomu logiki bota, dodając następujące wywołanie:

bot.js

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

Jeśli notatka została zaktualizowana w magazynie przez innego użytkownika przed podjęciem próby zapisania zmian, eTag wartość nie będzie już zgodna, a wywołanie write metody zgłosi wyjątek.

Najpierw utwórz klasę, która implementuje StoreItemelement .

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

Następnie utwórz początkową notatkę, tworząc obiekt magazynu i dodając obiekt do magazynu.

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)

Następnie uzyskaj dostęp do notatki i zaktualizuj je później, przechowując informacje eTag odczytywane ze sklepu.

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)

Jeśli notatka została zaktualizowana w sklepie przed zapisaniem zmian, wywołanie write metody zgłosi wyjątek.

Aby zachować współbieżność, zawsze odczytaj właściwość z magazynu, a następnie zmodyfikuj odczytaną właściwość, aby eTag ta właściwość jest utrzymywana. Jeśli odczytujesz dane użytkownika z magazynu, odpowiedź będzie zawierać właściwość eTag. Jeśli zmienisz dane i zapiszesz zaktualizowane dane w magazynie, żądanie powinno zawierać właściwość eTag, która określa tę samą wartość, co odczyt wcześniej. Jednak zapisanie obiektu z ustawionym eTag ustawieniem * umożliwi zapisowi zastąpienie wszelkich innych zmian.

Następne kroki

Teraz, gdy wiesz już, jak odczytywać i zapisywać bezpośrednio z magazynu, przyjrzyjmy się temu, jak można to zrobić za pomocą menedżera stanu.

Zapisywanie stanu przy użyciu konwersacji i właściwości użytkownika

Zapisywanie bezpośrednio w magazynie

Wymagania wstępne

Informacje o tym przykładzie

Magazyn pamięci

Tworzenie podstawowego bota

Uruchamianie bota

Uruchom emulator i połącz bota

Interakcja z botem

Korzystanie z usługi Cosmos DB

Konfigurowanie zasobu usługi Cosmos DB

Tworzenie konta bazy danych

Dodawanie bazy danych

Dodawanie informacji o konfiguracji usługi Cosmos DB

Instalowanie pakietów usługi Cosmos DB

Implementacja usługi Cosmos DB

Uruchamianie bota usługi Cosmos DB

Testowanie bota usługi Cosmos DB za pomocą emulatora platformy Bot Framework

Interakcja z botem usługi Cosmos DB

Wyświetlanie danych usługi Cosmos DB

Korzystanie z usługi Blob Storage

Tworzenie konta usługi Blob Storage

Tworzenie kontenera usługi Blob Storage

Dodawanie informacji o konfiguracji usługi Blob Storage

Instalowanie pakietów usługi Blob Storage

Implementacja usługi Blob Storage

Uruchamianie bota usługi Blob Storage

Uruchom emulator i połącz bota usługi Blob Storage

Interakcja z botem usługi Blob Storage

Wyświetlanie danych usługi Blob Storage

Magazyn transkrypcji obiektów blob

Konfigurowanie kontenera magazynu transkrypcji obiektów blob

Implementacja magazynu transkrypcji obiektów blob

Przechowywanie konwersacji użytkowników w transkrypcjach obiektów blob platformy Azure

Zarządzanie przechowywanymi transkrypcjami obiektów blob

Dodatkowe informacje

Zarządzanie współbieżnością przy użyciu elementów eTag

Ostatnie zwycięstwa zapisu — zezwalaj na zastępowanie

Obsługa współbieżności i zapobieganie zastępowaniu

Następne kroki

Dodatkowe zasoby