Direktes Schreiben in den Speicher

Artikel
12/27/2023

GILT FÜR: SDK v4

Sie können ohne Verwendung eines Middleware- oder Kontextobjekts direkt aus Ihrem Speicherobjekt lesen und in das Speicherobjekt schreiben. Dies eignet sich möglicherweise für Daten, die Ihr Bot zum Aufrechterhalten einer Konversation verwendet, oder für Daten, die aus einer Quelle außerhalb des Konversationsflusses Ihres Bots stammen. Bei diesem Datenspeichermodell werden Daten direkt aus dem Speicher gelesen, anstatt einen Zustands-Manager zu verwenden. Die Codebeispiele in diesem Artikel zeigen, wie Sie mithilfe von Speicher, Cosmos DB, Azure Blob und Azure-Blob-Transkripts-Speicher Daten aus dem Speicher lesen und in den Speicher schreiben.

Hinweis

Die JavaScript-, C#- und Python-SDKs für Bot Framework werden weiterhin unterstützt, das Java-SDK wird jedoch eingestellt und der langfristige Support endet im November 2023.

Bestehende Bots, die mit dem Java SDK erstellt wurden, werden weiterhin funktionieren.

Für das erstellen eines neuen Bots sollten Sie Microsoft Copilot Studio verwenden und lesen, wie Sie die richtige Copilot-Lösung auswählen.

Weitere Informationen finden Sie unter Die Zukunft des Bot-Design.

Voraussetzungen

Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.
Vertrautheit mit der lokalen Erstellung eines Bots.
Vorlagen für das Bot Framework SDK v4 für Visual Studio (C#), Node.js oder Yeoman.

Hinweis

Sie können die Vorlagen aus Visual Studio installieren.

Wählen Sie im Menü Erweiterungen die Option Erweiterungen verwalten aus.
Suchen Sie im Dialogfeld Erweiterungen verwalten nach Bot Framework v4 SDK-Vorlagen für Visual Studio und installieren Sie sie.

Informationen zum Bereitstellen von .NET-Bots in Azure finden Sie unter Bereitstellen und Veröffentlichen eines Bots.

Informationen zu diesem Beispiel

Der Beispielcode in diesem Artikel beginnt mit der Struktur eines einfachen Echobots und erweitert die Funktionalität des Bots anschließend durch Hinzufügen von zusätzlichem Code (siehe unten). Dieser erweiterte Code erstellt eine Liste, um empfangene Benutzereingaben beizubehalten. Bei jedem Zug wird die vollständige Liste der Benutzereingaben, die im Speicher abgelegt ist, an den Benutzer zurückgesendet. Die Datenstruktur, die diese Liste von Eingaben enthält, wird dann geändert, um sie im Speicher abzulegen. Beim Hinzufügen zusätzlicher Funktionen zum Beispielcode werden verschiedene Speichertypen vorgestellt.

Arbeitsspeicher

Mit dem Bot Framework SDK können Sie Benutzereingaben in In-Memory-Speicher speichern. Da der Speicher im Arbeitsspeicher jedes Mal gelöscht wird, wenn der Bot neu gestartet wird, eignet er sich am besten für Testzwecke und ist nicht für die Produktionsverwendung vorgesehen. Für Bots in Produktionsumgebungen sollten permanente Speichertypen wie etwa Datenbankspeicher verwendet werden.

Erstellen eines einfachen Bots

Die restlichen Abschnitte dieses Themas basieren auf einem Echobot. Der Echo-Bot-Beispielcode kann lokal erstellt werden, indem sie die Schnellstartanweisungen zum Erstellen eines Bots befolgen.

Ersetzen Sie den Code in EchoBot.cs durch den folgenden Code:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Zur Verwendung der .env-Konfigurationsdatei muss Ihrem Bot ein zusätzliches Paket hinzugefügt werden. Sofern es noch nicht installiert ist, können Sie das NET-Paket über npm abrufen:

npm install --save dotenv

Ändern Sie den Code in index.js, der den Hauptdialog erstellt. Die bestehende Codezeile zur Erstellung des Hauptdialogs ist const myBot = new EchoBot();, sie muss aktualisiert werden, um die Übergabe eines Speicherobjekts an den EchoBot-Konstruktor zu ermöglichen, damit die Eingaben des Benutzers im internen Speicher des Bots gespeichert werden können:

Zuerst müssen Sie einen Verweis auf MemoryStorage in botbuilder hinzufügen:

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

Erstellen Sie dann das Speicherobjekt und übergeben Sie es an den EchoBot-Konstruktor:

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

Damit wird ein MemoryStorage-Objekt an den EchoBot-Konstruktor übergeben. Sie ändern dies später, um ein Cosmos DB- oder Blob Storage-Objekt zu übergeben.

Ersetzen Sie dann den Code in bot.js durch den folgenden Code:

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;

Ersetzen Sie den Code in echo_bot.py durch den folgenden Code:

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

Starten Ihres Bots

Führen Sie Ihren Bot lokal aus.

Starten des Emulators und Herstellen einer Verbindung mit Ihrem Bot

Installieren Sie Bot Framework Emulator. Starten Sie dann den Emulator und stellen Sie dann im Emulator eine Verbindung mit Ihrem Bot her:

Wählen Sie den Link Neue Bot-Konfiguration erstellen auf der Registerkarte Emulator Willkommen.
Füllen Sie die Felder zur Verbindung mit Ihrem Bot mit den Daten aus, die beim Starten des Bots auf der Webseite angezeigt wurden.

Interagieren mit Ihrem Bot

Senden Sie eine Nachricht an den Bot. Der Bot listet die empfangenen Nachrichten auf.

Eine Unterhaltung mit dem Bot, die zeigt, dass der Bot eine Liste von Nachrichten vom Benutzer hält.

Im weiteren Verlauf dieses Artikels wird gezeigt, wie man im beständigen Speicher statt im internen Speicher des Bots speichert.

Verwenden von Cosmos DB

Wichtig

Die Klasse Cosmos DB-Speicher wurde als veraltet gekennzeichnet. Bei Containern, die ursprünglich mit CosmosDbStorage erstellt wurden, war kein Partitionsschlüssel festgelegt und sie erhielten den Standardpartitionsschlüssel _/partitionKey.

Mit Cosmos DB-Speicher erstellte Container können mit partitioniertem Cosmos DB-Speicher verwendet werden. Weitere Informationen finden Sie unter Partitionierung in Azure Cosmos DB.

Beachten Sie außerdem, dass der partitionierte Cosmos-DB-Speicher im Gegensatz zum älteren Cosmos-DB-Speicher nicht automatisch eine Datenbank in Ihrem Cosmos-DB-Konto erstellt. Sie müssen eine neue Datenbank manuell erstellen, aber überspringen Sie die manuelle Erstellung eines Containers, da CosmosDbPartitionedStorage den Container für Sie erstellt.

Nachdem Sie den Arbeitsspeicher verwendet haben, aktualisieren Sie nun den Code, um Azure Cosmos DB zu verwenden. Cosmos DB ist eine global verteilte Datenbank von Microsoft mit mehreren Modellen. Azure Cosmos DB ermöglicht es Ihnen, Durchsatz und Speicher elastisch und unabhängig voneinander über eine beliebige Anzahl von geografischen Azure-Regionen hinweg zu skalieren. Azure Cosmos DB bietet Ihnen mit umfassenden Vereinbarungen zum Servicelevel (Service Level Agreements, SLAs) Durchsatz-, Wartezeit-, Verfügbarkeits- und Konsistenzgarantien.

Einrichten einer Cosmos DB-Ressource

Zum Verwenden von Cosmos DB in Ihrem Bot müssen Sie eine Datenbankressource erstellen, bevor Sie in den Code einsteigen. Eine ausführliche Beschreibung der Cosmos-DB-Datenbank und der App-Erstellung finden Sie in der Schnellstartanleitung für .NET, Node.js oder Python.

Erstellen Ihres Datenbankkontos

Wechseln Sie zum Azure-Portal, um ein Azure Cosmos DB-Konto zu erstellen. Suchen Sie nachAzure Cosmos DB.
Wählen Sie auf der Seite Azure Cosmos DB die Option Neu aus, um die Seite Azure-Cosmos-DB-Konto erstellen anzuzeigen.
Stellen Sie Werte für die folgenden Felder bereit:
1. Abonnement: Wählen Sie das Azure-Abonnement aus, das Sie für dieses Azure Cosmos-Konto verwenden möchten.
2. Ressourcengruppe. Wählen Sie eine vorhandene Ressourcengruppe aus oder wählen Sie Neu erstellen aus, und geben Sie einen Namen für eine neue Ressourcengruppe ein.
3. Kontoname. Geben Sie einen Namen ein, der Ihr Azure Cosmos-Konto identifiziert. Da documents.azure.com an den Namen angefügt wird, die Sie für die URI-Erstellung angeben, muss der Name eindeutig sein. Beachten Sie die folgenden Richtlinien:
  - Der Name muss innerhalb von Azure eindeutig sein.
  - Der Name muss zwischen 3 und 31 Zeichen lang sein.
  - Der Name darf nur aus Kleinbuchstaben, Zahlen und Bindestrichen (-) bestehen.
4. API. Wählen Sie Core (SQL) aus
5. Standort. Wählen Sie einen Standort, der Ihren Benutzern am nächsten ist, damit sie möglichst schnell auf die Daten zugreifen können.
Klicken Sie auf Überprüfen + erstellen.
Klicken Sie nach der Validierung auf Erstellen.

Die Kontoerstellung dauert einige Minuten. Warten Sie, bis das Portal die Seite Herzlichen Glückwunsch! Ihr Azure Cosmos DB-Konto wurde erstellt anzeigt.

Hinzufügen einer Datenbank

Hinweis

Erstellen Sie den Container nicht selbst. Dies übernimmt Ihr Bot beim Erstellen des internen Cosmos DB-Clients. Hierbei wird auch sichergestellt, dass der Container zum Speichern des Botzustands richtig konfiguriert ist.

Navigieren Sie unter Ihrem neu erstellten Cosmos DB-Konto zur Seite Daten-Explorer, und wählen Sie dann im Dropdownfeld Neuer Container die Option Neue Datenbank aus. Im rechten Teil des Fensters wird dann ein Bereich geöffnet, in dem Sie die Details für die neue Datenbank eingeben können.
Geben Sie eine ID für Ihre neue Datenbank ein, und legen Sie optional den Durchsatz fest (kann später geändert werden). Klicken Sie abschließend auf OK, um Ihre Datenbank zu erstellen. Notieren Sie sich diese Datenbank-ID, da Sie sie später beim Konfigurieren Ihres Bots benötigen.
Nachdem Sie nun ein Cosmos DB-Konto und eine Datenbank erstellt haben, müssen Sie einige Werte für die Integration Ihrer neuen Datenbank in Ihren Bot kopieren. Navigieren Sie zum Abrufen der Werte in Ihrem Cosmos DB-Konto im Abschnitt mit den Datenbankeinstellungen zur Registerkarte Schlüssel. Auf dieser Seite benötigen Sie Ihre URI (Cosmos-DB-Endpunkt) und Ihren PRIMÄRSCHLÜSSEL (Autorisierungsschlüssel).

Sie sollten jetzt über ein Cosmos-DB-Konto mit einer Datenbank und den folgenden Werten verfügen, die in Ihren Bot-Einstellungen verwendet werden können.

URI
Primärschlüssel
Datenbank-ID

Hinzufügen von Cosmos-DB-Konfigurationsinformationen

Verwenden Sie die Angaben, die Sie sich im vorherigen Teil dieses Artikels notiert haben, um Ihren Endpunkt, den Autorisierungsschlüssel und die Datenbank-ID festzulegen. Abschließend sollten Sie einen geeigneten Namen für den Container auswählen, der in Ihrer Datenbank zum Speichern des Botzustands erstellt werden soll. Im folgenden Beispiel wird der erstellte Cosmos-DB-Container "bot-storage" genannt.

Fügen Sie Ihrer Konfigurationsdatei die folgenden Informationen hinzu:

appsettings.json

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

Fügen Sie Ihrer .env-Datei die folgenden Informationen hinzu.

.env

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

Fügen Sie Ihrer Konfigurationsdatei die folgenden Informationen hinzu:

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"

Installieren von Cosmos-DB-Paketen

Stellen Sie sicher, dass Sie über die erforderlichen Pakete für Cosmos DB verfügen.

Installieren Sie das NuGet-Paket Microsoft.Bot.Builder.Azure. Weitere Informationen zur Verwendung von NuGet finden Sie unter Installieren und Verwalten von Paketen in Visual Studio mit dem NuGet-Paket-Manager.

Fügen Sie mithilfe von npm einen Verweis auf botbuilder-azure hinzu.

npm install --save botbuilder-azure

Sofern noch nicht installiert, rufen Sie das .NET-Paket über npm ab, um auf Ihre .env-Dateieinstellungen zuzugreifen.

npm install --save dotenv

Sie können in Ihrem Projekt Verweise auf „botbuilder-azure“ über PIP hinzufügen.

pip install botbuilder-azure

Implementierung von Cosmos DB

Hinweis

In Version 4.6 wurde ein neuer Cosmos DB-Speicheranbieter eingeführt: die Klasse für partitionierten Cosmos DB-Speicher. Die Klasse für den ursprünglichen Cosmos DB-Speicher wurde als veraltet gekennzeichnet. Mit Cosmos DB-Speicher erstellte Container können mit partitioniertem Cosmos DB-Speicher verwendet werden. Weitere Informationen finden Sie unter Partitionierung in Azure Cosmos DB.

Der partitionierte Cosmos-DB-Speicher erstellt im Gegensatz zum älteren Cosmos-DB-Speicher nicht automatisch eine Datenbank in Ihrem Cosmos-DB-Konto. Sie müssen eine neue Datenbank manuell erstellen, aber überspringen Sie die manuelle Erstellung eines Containers, da CosmosDbPartitionedStorage den Container für Sie erstellt.

Der folgende Beispielcode wird mit dem gleichen Botcode ausgeführt wie das obige Beispiel für den Arbeitsspeicher, allerdings mit den hier aufgeführten Ausnahmen. Der unten stehende Codeausschnitt zeigt eine Implementierung von Cosmos-DB-Speicher für myStorage, die den lokalen Arbeitsspeicher ersetzt.

Sie müssen Startup.cs zuerst aktualisieren, um auf die Bot-Builder-Azure-Bibliothek zu verweisen:

using Microsoft.Bot.Builder.Azure;

Erstellen Sie als Nächstes in der ConfigureServices-Methode in Startup.cs das CosmosDbPartitionedStorage-Objekt. Dies wird über die Abhängigkeitsinjektion an den EchoBot-Konstruktor übergeben.

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

Ändern Sie in EchoBot.cs die _myStorage-Variabledeklaration private static readonly MemoryStorage _myStorage = new MemoryStorage(); wie folgt:

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

Geben Sie dann das IStorage-Objekt an den EchoBot-Konstruktor weiter:

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

Fügen Sie zunächst der Datei index.js Code hinzu, damit Sie auf die Werte aus Ihrer .env-Datei zugreifen können, die Sie zuvor eingegeben haben:

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

Als Nächstes müssen Sie Änderungen an index.js vornehmen, um den partitionierten Cosmos-DB-Speicher anstelle des internen Bot-Frameworks-Speichers zu verwenden. Alle Codeänderungen in diesem Abschnitt werden in index.js vorgenommen.

Fügen Sie zunächst einen Verweis auf botbuilder-azure in index.js hinzu. Dadurch erhalten Sie Zugriff auf die CosmosDbPartitionedStorage-Klasse.

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

Erstellen Sie als Nächstes ein neues CosmosDbPartitionedStorage-Objekt.

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

Sie können nun die zuvor hinzugefügte myStorage-Const-Deklaration auskommentieren oder entfernen, da die Benutzereingaben nicht mehr im internen Speicher des Bot Frameworks, sondern in der Cosmos DB gespeichert werden:

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

Der folgende Beispielcode wird mit dem gleichen Botcode ausgeführt wie das obige Beispiel für den Arbeitsspeicher, allerdings mit den hier aufgeführten Ausnahmen.

Sowohl CosmosDbPartitionedStorage als auch CosmosDbPartitionedConfig von botbuilder-azure sind erforderlich, um das CosmosDBStorage-Objekt zu erstellen.

echo_bot.py

from botbuilder.azure import CosmosDbPartitionedStorage, CosmosDbPartitionedConfig

Um auf die Einstellungen in config.py zuzugreifen, müssen Sie DefaultConfig wie unten gezeigt importieren:

from config import DefaultConfig
CONFIG = DefaultConfig()

Kommentieren Sie in __init__ den Arbeitsspeicher aus, und ersetzen Sie diese Angabe durch einen Verweis auf Cosmos DB. Verwenden Sie den URI (Endpunkt), den Primärschlüssel (Autorisierungsschlüssel), die Datenbank-ID und die Container-ID, die oben verwendet wurden.

Entfernen oder kommentieren Sie als Nächstes den Speichercode in __init__ aus und fügen Sie einen Verweis auf Ihre Cosmos-DB-Informationen aus config.py hinzu.

Der unten stehende Codeschnipsel zeigt eine Implementierung von Cosmos DB für „Speicher“, der den lokalen Arbeitsspeicher ersetzt.

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)

Starten Ihres Cosmos-DB-Bots

Führen Sie Ihren Bot lokal aus.

Testen des Cosmos-DB-Bots mit Bot Framework Emulator

Starten Sie nun den Bot Framework Emulator und verbinden Sie sich mit Ihrem Bot:

Wählen Sie den Link Neue Bot-Konfiguration erstellen auf der Registerkarte Emulator Willkommen.
Füllen Sie die Felder zur Verbindung mit Ihrem Bot mit den Daten aus, die beim Starten des Bots auf der Webseite angezeigt wurden.

Interagieren mit Ihrem Cosmos-DB-Bot

Senden Sie eine Nachricht an den Bot. Der Bot listet daraufhin die von ihm empfangenen Nachrichten auf.

Eine Unterhaltung mit dem Bot, die zeigt, dass der Bot eine Liste von Nachrichten vom Benutzer hält.

Anzeigen Ihrer Cosmos-DB-Daten

Nachdem Sie den Bot ausgeführt und Ihre Informationen gespeichert haben, können Sie die im Azure-Portal gespeicherten Daten auf der Registerkarte Daten-Explorer anzeigen.

Screenshot des Daten-Explorers im Azure-Portal.

Verwenden von Blob Storage

Azure Blob Storage ist die Objektspeicherlösung von Microsoft für die Cloud. Blobspeicher ist für die Speicherung großer Mengen von unstrukturierten Daten, z.B. Text oder Binärdaten, optimiert. In diesem Abschnitt wird erläutert, wie Sie ein Azure-Blob-Storage-Konto und einen Container erstellen und dann auf Ihren Blob-Storage-Container von Ihrem Bot verweisen.

Weitere Informationen zu Blob Storage finden Sie unter Was ist Azure Blob Storage?

Erstellen Ihres Blob Storage-Kontos

Um Blob Storage in Ihrem Bot verwenden zu können, müssen Sie einige Einrichtungsschritte durchführen, bevor wir uns mit dem Code befassen.

Wählen Sie im Azure-Portal die Option Alle Dienste.
Wählen Sie auf der Seite Alle Dienste im Abschnitt Empfohlen die Option Speicherkonten.
Klicken Sie auf der Seite Speicherkonten auf Neu.
Wählen Sie im Feld Abonnement das Abonnement aus, in dem das Speicherkonto erstellt werden soll.
Wählen Sie im Feld Ressourcengruppe eine vorhandene Ressourcengruppe aus, oder wählen Sie Neu erstellen aus, und geben Sie einen Namen für die neue Ressourcengruppe ein.
Geben Sie im Feld Speicherkontoname einen Namen für das Konto ein. Beachten Sie die folgenden Richtlinien:
- Der Name muss innerhalb von Azure eindeutig sein.
- Der Name muss zwischen 3 und 24 Zeichen lang sein.
- Der Name darf nur Ziffern und Kleinbuchstaben enthalten.
Wählen Sie im Feld Standort einen Standort für das Speicherkonto aus, oder verwenden Sie den Standardstandort.
Konfigurieren Sie für die übrigen Einstellungen die folgenden Werte:
- Leistung: Standard. Erfahren Sie mehr über Leistung.
- Art des Kontos: BlobStorage. Weitere Informationen zu Speicherkonten.
- Replikation: Behalten Sie die Standardeinstellung bei. Informieren Sie sich über Redundanz.
Wählen Sie im Abschnitt Projektdetails auf der Seite Speicherkonto erstellen die gewünschten Werte für Subscription und Ressourcengruppe aus.
Geben Sie im Abschnitt Instancedetails auf der Seite Speicherkonto erstellen den Namen des Speicherkontos ein und wählen Sie dann Werte für Standort, Kontotyp und Replikation aus.
Wählen Sie Überprüfen + erstellen aus, um die Speicherkontoeinstellungen zu überprüfen.
Klicken Sie nach der Validierung auf Erstellen.

Erstellen eines Blob Storage-Containers

Nachdem Ihr Blob Storage-Konto erstellt wurde, öffnen Sie es wie folgt:

Wählen Sie Speicher-Explorer (Vorschau) aus.
Klicken Sie dann mit der rechten Maustaste auf BLOB-CONTAINER
Wählen Sie Blobcontainer erstellen aus der Einblendliste.
Geben Sie einen Namen in das Formular Neuer Container ein. Sie verwenden diesen Namen als Wert für Ihren „Blob-Containernamen“, um den Zugriff auf Ihr Blob-Speicherkonto zu ermöglichen. Beachten Sie die folgenden Richtlinien:
- Dieser Name darf nur Kleinbuchstaben, Zahlen und Bindestriche enthalten.
- Dieser Name muss mit einem Buchstaben oder einer Zahl beginnen.
- Vor und nach jedem Bindestrich muss ein gültiges Zeichen stehen, das kein Bindestrich ist.
- Der Name muss zwischen 3 und 63 Zeichen lang sein.

Hinzufügen von Blob-Storage-Konfigurationsinformationen

Suchen Sie wie oben dargestellt nach den Blob-Storage-Schlüsseln, die Sie zum Konfigurieren von Blob Storage für Ihren Bot benötigen:

Öffnen Sie im Azure-Portal Ihr Blob-Storage-Konto und wählen Sie im Abschnitt Einstellungen die Option Zugriffsschlüssel.
Um Ihren Bot für den Zugriff auf Ihr Blob-Speicherkonto zu konfigurieren, verwenden Sie Verbindungszeichenfolge als Wert für die Blob-Verbindungszeichenfolge.

Fügen Sie Ihrer Konfigurationsdatei die folgenden Informationen hinzu:

appsettings.json

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

Fügen Sie Ihrer .env-Datei die folgenden Informationen hinzu.

.env

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

Fügen Sie Ihrer Konfigurationsdatei die folgenden Informationen hinzu: Verwenden Sie denselben Containernamen und dieselbe Verbindungszeichenfolge wie bei der Erstellung Ihres Blob-Storage-Containers.

config.py

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

Installieren von Blob-Storage-Paketen

Falls noch nicht installiert, installieren Sie die folgenden Pakete.

Installieren Sie das NuGet-Paket Microsoft.Bot.Builder.Azure.Blobs. Weitere Informationen zur Verwendung von NuGet finden Sie unter Installieren und Verwalten von Paketen in Visual Studio mit dem NuGet-Paket-Manager.

Fügen Sie Referenzen auf botbuilder-azure-blobs in Ihrem Projekt über npm hinzu.

Hinweis

Dieses npm-Paket erfordert, dass Python auf dem Entwicklungscomputer installiert ist. Falls Sie Python noch nicht installiert haben, finden Sie unter Python.org die Installationsressourcen für Ihren Computer

npm install --save botbuilder-azure-blobs

Sofern noch nicht installiert, rufen Sie das .NET-Paket über npm ab, um auf Ihre .env-Dateieinstellungen zuzugreifen.

npm install --save dotenv

Sie können in Ihrem Projekt Verweise auf „botbuilder-azure“ über PIP hinzufügen.

pip install botbuilder-azure

Implementierung eines Blob Storage

Blob Storage wird verwendet, um Bot State zu speichern.

Hinweis

Ab der Version 4.10 ist Microsoft.Bot.Builder.Azure.AzureBlobStorage veraltet. Verwenden Sie das neue Microsoft.Bot.Builder.Azure.Blobs.BlobsStorage an seiner Stelle.

Der folgende Beispielcode wird mit dem gleichen Botcode ausgeführt wie das obige Beispiel für den Arbeitsspeicher, allerdings mit den hier aufgeführten Ausnahmen.

Die unten stehenden Codeschnipsel zeigen eine Implementierung von Blob Storage für myStorage, die den lokalen Arbeitsspeicher ersetzen.

Sie müssen Startup.cs zuerst aktualisieren, um auf die Bot-Builder-Azure-Blob-Bibliothek zu verweisen:

Startup.cs

using Microsoft.Bot.Builder.Azure.Blobs;

Erstellen Sie als Nächstes in der ConfigureServices-Methode in Startup.cs das BlobsStorage-Objekt und übergeben Sie die Werte aus appsettings.json. Dies wird über die Abhängigkeitsinjektion an den EchoBot-Konstruktor übergeben.

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

Sie müssen jetzt EchoBot.cs zuerst aktualisieren, um auf die Bot-Builder-Azure-Blob-Bibliothek zu verweisen:

EchoBot.cs

using Microsoft.Bot.Builder.Azure.Blobs;

Als Nächstes entfernen oder kommentieren Sie die Codezeile aus, die die MemoryStorage-Variable „private static readonly MemoryStorage _myStorage = new MemoryStorage();“ erstellt und erstellen Sie eine neue Variable, die zum Speichern von Benutzereingaben im Blob Storage verwendet wird.

EchoBot.cs

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

Geben Sie dann das IStorage-Objekt an den EchoBot-Konstruktor weiter:

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

Sobald „storage“ auf Ihr Blob Storage-Konto verweist, verwendet der Botcode zum Speichern und Abrufen von Daten Blob Storage.

Alle Codeänderungen in diesem Abschnitt werden in index.js vorgenommen.

Fügen Sie zunächst Code hinzu, damit Sie auf die Werte aus Ihrer .env-Datei zugreifen können, die Sie zuvor eingegeben haben:

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

Als Nächstes müssen Sie Änderungen am Blob Storage anstelle des internen Speichers von Bot Frameworks vornehmen.

Fügen Sie dann einen Verweis auf botbuilder-azure-blobs hinzu. Dadurch erhalten Sie Zugriff auf die Blob-Storage-API:

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

Um den Code für die Verwendung der BlobsStorage-Klasse zu ändern, ändern Sie die myStorage-Deklaration wie folgt:

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

Sobald „storage“ auf Ihr Blob Storage-Konto verweist, verwendet der Botcode zum Speichern und Abrufen von Daten Blob Storage.

Der folgende Beispielcode wird mit dem gleichen Botcode ausgeführt wie das obige Beispiel für den Arbeitsspeicher, allerdings mit den hier aufgeführten Ausnahmen.

Dies erfordert BlobStorage und BlobStorageSettings aus botbuilder-azure.

echo_bot.py

from botbuilder.azure import BlobStorage, BlobStorageSettings

Um auf die Einstellungen in config.py zuzugreifen, müssen Sie DefaultConfig wie unten gezeigt importieren:

from config import DefaultConfig
CONFIG = DefaultConfig()

Entfernen oder kommentieren Sie als Nächstes den Speichercode in __init__ aus und fügen Sie einen Verweis auf Ihre Blob-Storage-Informationen aus config.py hinzu.

Der unten stehende Codeschnipsel zeigt eine Implementierung von Blob Storage, der den lokalen Arbeitsspeicher ersetzt.

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)

Sobald „storage“ auf Ihr Blob Storage-Konto verweist, verwendet der Botcode zum Speichern und Abrufen von Daten Blob Storage.

Starten des Blob-Storage-Bots

Führen Sie Ihren Bot lokal aus.

Starten des Emulators und Herstellen einer Verbindung mit Ihrem Blob-Storage-Bot

Starten Sie im nächste Schritt den Emulator und stellen Sie dann im Emulator eine Verbindung mit Ihrem Bot her:

Wählen Sie den Link Neue Bot-Konfiguration erstellen auf der Registerkarte Emulator „Willkommen“.
Füllen Sie die Felder zur Verbindung mit Ihrem Bot mit den Daten aus, die beim Starten des Bots auf der Webseite angezeigt wurden.

Interagieren mit Ihrem Blob-Storage-Bot

Senden Sie eine Nachricht an den Bot. Der Bot listet daraufhin die von ihm empfangenen Nachrichten auf.

Eine Unterhaltung mit dem Bot, die zeigt, dass der Bot eine Liste von Nachrichten vom Benutzer hält.

Anzeigen ihrer Blob-Storage-Daten

Nachdem Sie den Bot ausgeführt und Ihre Informationen gespeichert haben, können Sie sie im Azure-Portal auf der Registerkarte Speicher-Explorer anzeigen.

Blob-Transkriptspeicher

Azure-Blob-Transkriptspeicher ist eine spezielle Speicheroption, die Ihnen auf einfache Weise das Speichern und Abrufen von Benutzerkonversationen in Form eines aufgezeichneten Transkripts ermöglicht. Azure-Blob-Transkriptspeicher eignet sich für die automatische Erfassung von Benutzereingaben, die dann beim Debuggen zum Untersuchen der Leistung des Bots verwendet werden können.

Hinweis

Python unterstützt derzeit keinen Azure-Blob-Transkriptspeicher. Während JavaScript Blob-Transkriptspeicher unterstützt, gelten die folgenden Anweisungen nur für C#.

Einrichten eines Blob-Transkriptspeichercontainers

Für Azure-Blob-Transkriptspeicher kann das Blob Storage-Konto verwendet werden, das Sie in den obigen Abschnitten Erstellen Ihres Blob Storage-Kontos und Hinzufügen der Konfigurationsinformationen erstellt haben. Jetzt fügen Sie einen Container zum Speichern der Transkripte hinzu.

Screenshot des Erstellens eines BLOB-Containers, der als Transkriptspeicher verwendet werden soll.

Öffnen Sie Ihr Azure Blob Storage-Konto.
Auswählen des Speicher-Explorers.
Klicken Sie mit der rechten Maustaste auf BLOB-CONTAINER, und wählen Sie BLOB-Container erstellen aus.
Geben Sie einen Namen für den Transkriptcontainer ein und wählen Sie dann OK aus. (In diesem Beispiel wurde der Name mybottranscripts eingegeben.)

Implementierung des Blob-Transkriptspeichers

Der folgende Code verbindet den Zeiger für den Transkriptspeicher _myTranscripts mit Ihrem neuen Azure-Blob-Transkriptspeicherkonto. Um diesen Link mit einem neuen Containernamen, <your-blob-transcript-container-name>, zu erstellen, wird in Blob Storage ein neuer Container zum Speichern der Transkriptdateien erstellt.

Blob-Transkriptspeicher dient zum Speichern von Bot-Transkripten.

Hinweis

Ab der Version 4.10 ist Microsoft.Bot.Builder.Azure.AzureBlobTranscriptStore veraltet. Verwenden Sie das neue Microsoft.Bot.Builder.Azure.Blobs.BlobsTranscriptStore an seiner Stelle.

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

   ...
}

Speichern von Benutzerkonversationen in Azure-Blob-Transkripts

Sobald ein Blobcontainer zum Speichern von Transkripts verfügbar ist, können Sie beginnen, die Konversationen Ihrer Benutzer mit dem Bot zu speichern. Diese Konversationen können später zum Debuggen verwendet werden, um festzustellen, wie Benutzer mit Ihrem Bot interagieren. Jeder Neustart der Konversation im Emulator initiiert die Erstellung einer neuen Liste mit dem Konversationstranskript. Der folgende Code speichert Benutzereingaben im Rahmen der Konversation in einer gespeicherten Transkriptdatei.

Das aktuelle Transkript wird mithilfe von LogActivityAsync gespeichert.
Gespeicherte Transkripte werden mithilfe von ListTranscriptsAsync abgerufen. In diesem Beispiel wird die ID jedes gespeicherten Transkripts in einer Liste mit dem Namen „storedTranscripts“ gespeichert. Mithilfe dieser Liste wird später die Anzahl gespeicherter Blob-Transkripte verwaltet, die beibehalten werden.

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

    ...
}

Verwalten der gespeicherten Blob-Transkripte

Gespeicherte Transkripte sind zwar hilfreich beim Debuggen, im Laufe der Zeit kann die Anzahl gespeicherter Transkripte jedoch Ihre Speicherkapazität übersteigen. Im folgenden zusätzlichen Code wird DeleteTranscriptAsync verwendet, um bis auf die drei zuletzt abgerufenen Transkriptelemente alle Transkripte aus dem Blob-Transkriptspeicher zu löschen.

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

Weitere Informationen zur Klasse finden Sie unter Blob-Transkriptspeicher von Azure.

Weitere Informationen

Verwalten von Parallelität mit eTags

In unserem Botcodebeispiel legen Sie die eTag-Eigenschaft jedes IStoreItem auf * fest. Der eTag-Member (Entitätstag) Ihres Speicherobjekts wird in Cosmos DB zum Verwalten der Parallelität verwendet. Das eTag teilt Ihrer Datenbank mit, wie vorzugehen ist, wenn eine andere Instanz des Bots das Objekt in demselben Speicher geändert hat, in den der Bot schreibt.

Der letzte Schreibzugriff gewinnt: Überschreiben zulassen

Wenn der Eigenschaftenwert von eTag das Sternchen (*) ist, zeigt dies an, dass der letzte Schreibvorgang gewinnt. Wenn Sie einen neuen Datenspeicher erstellen, können Sie das eTag einer Eigenschaft auf * festlegen, um anzugeben, dass Sie die Daten, die Sie schreiben, noch nicht gespeichert haben, oder dass der letzte Schreibvorgang eine zuvor gespeicherte Eigenschaft überschreiben soll. Wenn die Parallelität für Ihren Bot kein Problem darstellt, erlaubt das Festlegen der eTag-Eigenschaft auf * für alle Daten, die Sie schreiben, das Überschreiben.

Verwalten von Parallelität und Verhindern von Überschreibungen

Verwenden Sie beim Speichern Ihrer Daten in Cosmos DB einen anderen Wert als * für das eTag, wenn Sie den gleichzeitigen Zugriff auf eine Eigenschaft und das Überschreiben von Änderungen von einer anderen Instanz des Bots verhindern möchten. Der Bot erhält eine Fehlerantwort mit der Meldung etag conflict key=, wenn er versucht, Zustandsdaten zu speichern und das eTag weist nicht denselben Wert auf wie das eTag im Speicher.

Die eTag-Eigenschaft eines Speicherobjekts wird von Cosmos DB standardmäßig jedes Mal auf Gleichheit überprüft, wenn ein Bot in dieses Element schreibt, und nach jedem Schreibvorgang auf einen neuen eindeutigen Wert aktualisiert. Wenn die eTag-Eigenschaft beim Schreiben nicht mit der Eigenschaft eTag im Speicher übereinstimmt, bedeutet dies, dass ein anderer Bot oder Thread die Daten geändert hat.

Angenommen, Sie möchten, dass Ihr Bot eine gespeicherte Notiz bearbeitet, aber Sie möchten nicht, dass Ihr Bot Änderungen überschreibt, die eine andere Instanz des Bots vorgenommen hat. Wenn eine andere Instanz des Bots Bearbeitungen vorgenommen hat, möchten Sie, dass der Benutzer die Version mit den neuesten Aktualisierungen bearbeitet.

Erstellen Sie zunächst eine Klasse, die IStoreItem implementiert.

EchoBot.cs

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

Erstellen Sie anschließend eine erste Notiz, indem Sie ein Speicherobjekt erstellen, und fügen Sie das Objekt Ihrem Speicher hinzu.

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

Greifen Sie dann später auf die Notiz zu, und aktualisieren Sie sie, indem Sie ihr eTag, das Sie aus dem Speicher gelesen haben, beibehalten.

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

Wenn die Notiz im Speicher aktualisiert wurde, bevor Sie Ihre Änderungen schreiben, löst der Aufruf von Write eine Ausnahme aus.

Fügen Sie eine Hilfsfunktion am Ende des Bots hinzu, die eine Beispielnotiz in einen Datenspeicher schreibt. Erstellen Sie zunächst ein 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: "*"
    }
}

Initialisieren Sie innerhalb der createSampleNote-Hilfsfunktion ein changes-Objekt, fügen Sie ihm Ihre Notizen hinzu und schreiben Sie es dann in den Speicher.

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

Der Zugriff auf die Hilfsfunktion erfolgt innerhalb der Logik des Bots durch Hinzufügen des folgenden Aufrufs:

bot.js

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

Um später auf die Notiz zuzugreifen und sie zu abzurufen, erstellen Sie eine weitere Hilfsfunktion, auf die zugegriffen werden kann, wenn der Benutzer „update note“ (Notiz aktualisieren) eingibt.

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

Der Zugriff auf diese Hilfsfunktion erfolgt innerhalb der Logik des Bots durch Hinzufügen des folgenden Aufrufs:

bot.js

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

Wenn die Notiz im Speicher von einem anderen Benutzer aktualisiert wurde, bevor Sie versucht haben, Ihre Änderungen zurückzuschreiben, stimmt der eTag-Wert nicht mehr überein, und der Aufruf von write löst eine Ausnahme aus.

Erstellen Sie zunächst eine Klasse, die StoreItem implementiert.

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

Erstellen Sie anschließend eine erste Notiz, indem Sie ein Speicherobjekt erstellen, und fügen Sie das Objekt Ihrem Speicher hinzu.

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)

Greifen Sie dann später auf die Notiz zu, und aktualisieren Sie sie, indem Sie ihr eTag, das Sie aus dem Speicher gelesen haben, beibehalten.

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)

Wenn die Notiz im Speicher aktualisiert wurde, bevor Sie Ihre Änderungen schreiben, löst der Aufruf von write eine Ausnahme aus.

Um die Parallelität zu verwalten, lesen Sie immer eine Eigenschaft aus dem Speicher, und ändern Sie die Eigenschaft dann, die Sie gelesen haben, sodass das eTag beibehalten wird. Wenn Sie Benutzerdaten aus dem Speicher lesen, enthält die Antwort die eTag-Eigenschaft. Wenn Sie die Daten ändern und aktualisierte Daten in den Speicher schreiben, sollte Ihre Anforderung die eTag-Eigenschaft enthalten, die den gleichen Wert angibt, den Sie zuvor gelesen haben. Das Schreiben eines Objekts, dessen eTag auf * festgelegt ist, erlaubt es dem Schreibvorgang jedoch, alle anderen Änderungen zu überschreiben.

Nächste Schritte

Da Sie nun wissen, wie Sie direkt aus dem Speicher lesen und in ihn schreiben können, schauen wir uns an, wie der Zustands-Manager diese Aufgabe für Sie übernehmen kann.

Speichern des Zustands mithilfe der Unterhaltungs- und Benutzereigenschaften

Freigeben über

Direktes Schreiben in den Speicher

Voraussetzungen

Informationen zu diesem Beispiel

Arbeitsspeicher

Erstellen eines einfachen Bots

Starten Ihres Bots

Starten des Emulators und Herstellen einer Verbindung mit Ihrem Bot

Interagieren mit Ihrem Bot

Verwenden von Cosmos DB

Einrichten einer Cosmos DB-Ressource

Erstellen Ihres Datenbankkontos

Hinzufügen einer Datenbank

Hinzufügen von Cosmos-DB-Konfigurationsinformationen

Installieren von Cosmos-DB-Paketen

Implementierung von Cosmos DB

Starten Ihres Cosmos-DB-Bots

Testen des Cosmos-DB-Bots mit Bot Framework Emulator

Interagieren mit Ihrem Cosmos-DB-Bot

Anzeigen Ihrer Cosmos-DB-Daten

Verwenden von Blob Storage

Erstellen Ihres Blob Storage-Kontos

Erstellen eines Blob Storage-Containers

Hinzufügen von Blob-Storage-Konfigurationsinformationen

Installieren von Blob-Storage-Paketen

Implementierung eines Blob Storage

Starten des Blob-Storage-Bots

Starten des Emulators und Herstellen einer Verbindung mit Ihrem Blob-Storage-Bot

Interagieren mit Ihrem Blob-Storage-Bot

Anzeigen ihrer Blob-Storage-Daten

Blob-Transkriptspeicher

Einrichten eines Blob-Transkriptspeichercontainers

Implementierung des Blob-Transkriptspeichers

Speichern von Benutzerkonversationen in Azure-Blob-Transkripts

Verwalten der gespeicherten Blob-Transkripte

Weitere Informationen

Verwalten von Parallelität mit eTags

Der letzte Schreibzugriff gewinnt: Überschreiben zulassen

Verwalten von Parallelität und Verhindern von Überschreibungen

Nächste Schritte

Zusätzliche Ressourcen