Condividi tramite

Gestione dello stato

si applica a: SDK v4

Lo stato all'interno di un bot segue gli stessi paradigmi delle moderne applicazioni Web e Bot Framework SDK fornisce alcune astrazioni per semplificare la gestione dello stato.

Come con le app Web, un bot è intrinsecamente senza stato. Una istanza diversa del bot può gestire un determinato turno della conversazione. Per alcuni bot, questa semplicità è preferibile: il bot può operare senza informazioni aggiuntive oppure è garantito che le informazioni necessarie siano all'interno del messaggio in arrivo. Per altri utenti, lo stato ,ad esempio dove la conversazione è stata interrotta o i dati ricevuti in precedenza sull'utente, è necessario per consentire al bot di avere una conversazione utile.

Perché è necessario lo stato?

La gestione dello stato consente al bot di avere conversazioni più significative ricordando alcuni aspetti relativi a un utente o a una conversazione. Ad esempio, se in precedenza si è parlato con un utente, è possibile salvare le informazioni precedenti su di esse, in modo che non sia necessario richiederlo di nuovo. Lo stato mantiene anche i dati per più tempo rispetto al turno corrente, in modo che il bot mantenga le informazioni nel corso di una conversazione a più turni.

In quanto riguarda i bot, esistono alcuni livelli per usare lo stato: il livello di archiviazione, la gestione dello stato (contenuta nello stato del bot nel diagramma seguente) e le funzioni di accesso alle proprietà di stato. Questo diagramma illustra parti della sequenza di interazione tra questi livelli, con le frecce a tinta unita che rappresentano una chiamata al metodo e le frecce tratteggiate che rappresentano la risposta (con o senza un valore restituito).

Diagramma di sequenza che illustra come lo stato viene caricato, memorizzato nella cache e archiviato a ogni turno.

Il flusso di questo diagramma è illustrato nelle sezioni seguenti con i dettagli di ognuno di questi livelli.

Livello di archiviazione

A partire dal back-end, in cui vengono effettivamente archiviate le informazioni sullo stato, è il livello di archiviazione. Questo può essere considerato come l'archiviazione fisica, ad esempio in memoria, Azure o un server di terze parti.

Bot Framework SDK include alcune implementazioni per il livello di archiviazione:

  • L'archiviazione di memoria implementa lo storage in memoria per scopi di test. L'archiviazione dei dati in memoria è destinata solo ai test locali perché questa risorsa di archiviazione è volatile e temporanea. I dati vengono cancellati ogni volta che il bot viene riavviato.
  • Archiviazione BLOB di Azure si connette a un database di oggetti di Archiviazione BLOB di Azure.
  • L'archiviazione partizionata di Azure Cosmos DB si connette a un database NoSQL di Cosmos DB partizionato.

Importante

La classe CosmosDbStorage è stata deprecata. I contenitori creati in origine con CosmosDbStorage non avevano un set di chiavi di partizione e avevano la chiave di partizione predefinita "/_partitionKey".

I contenitori creati con l'archiviazione cosmos DB possono essere usati con l'archiviazione partizionata di Cosmos DB. Per altre informazioni, vedere Partizionamento in Azure Cosmos DB.

Si noti anche che, a differenza dell'archiviazione di Cosmos DB legacy, l'archiviazione partizionata di Cosmos DB non crea automaticamente un database all'interno dell'account Cosmos DB. È necessario creare manualmente un nuovo database, ma ignorare la creazione manuale di un contenitore perché CosmosDbPartitionedStorage creerà automaticamente il contenitore.

Per istruzioni su come connettersi ad altre opzioni di archiviazione, vedere Scrivere direttamente nell'archiviazione.

Gestione dello stato

La gestione dello stato automatizza la lettura e la scrittura dello stato del bot nel livello di archiviazione sottostante. Lo stato viene archiviato come proprietà di stato, ovvero coppie chiave-valore che il bot può leggere e scrivere tramite l'oggetto di gestione dello stato senza doversi preoccupare dell'implementazione sottostante specifica. Tali proprietà di stato definiscono la modalità di archiviazione delle informazioni. Ad esempio, quando si recupera una proprietà definita come classe o oggetto specifico, si sa come verranno strutturati i dati.

Queste proprietà di stato sono raggruppate in "insiemi con ambito limitato", che sono semplici raccolte per facilitare l'organizzazione di tali proprietà. L'SDK include tre di questi "bucket":

  • Stato utente
  • Stato della conversazione
  • Stato della conversazione privata

Tutti questi bucket sono sottoclassi della classe di stato del bot , che possono essere derivate per definire altri tipi di bucket con ambiti diversi.

Questi contenitori predefiniti hanno una visibilità specifica, che varia a seconda del contenitore.

  • Lo stato utente è disponibile in qualsiasi turno in cui il bot sta conversando con l'utente su tale canale, indipendentemente dalla conversazione
  • Lo stato della conversazione è disponibile in qualsiasi turno in una conversazione specifica, indipendentemente dall'utente, ad esempio nelle conversazioni di gruppo
  • Lo stato della conversazione privata è limitato sia alla conversazione specifica che a tale utente specifico

Suggerimento

Sia lo stato utente che quello della conversazione hanno come ambito il canale. La stessa persona che usa canali diversi per accedere al bot viene visualizzata come utenti diversi, uno per ogni canale e ognuno con uno stato utente distinto.

Le chiavi usate per ognuno di questi bucket predefiniti sono specifiche per l'utente e la conversazione o entrambe. Quando si imposta il valore della proprietà di stato, la chiave viene definita internamente, con informazioni contenute nel contesto di turno per assicurarsi che ogni utente o conversazione venga inserito nel bucket e nella proprietà corretti. In particolare, le chiavi vengono definite come segue:

  • Lo stato utente crea una chiave usando l'ID canale e l'ID origine. Ad esempio, {Activity.ChannelId}/users/{Activity.From.Id}#YourPropertyName
  • Lo stato della conversazione crea una chiave usando l'ID canale e l'ID conversazione. Ad esempio, {Activity.ChannelId}/conversations/{Activity.Conversation.Id}#YourPropertyName
  • Lo stato della conversazione privata crea una chiave usando l'ID del canale, l'ID di origine e l'ID della conversazione. Ad esempio, {Activity.ChannelId}/conversations/{Activity.Conversation.Id}/users/{Activity.From.Id}#YourPropertyName

Quando usare ogni tipo di stato

Lo stato della conversazione è adatto per tenere traccia del contesto della conversazione, ad esempio:

  • Indica se il bot ha chiesto all'utente una domanda e quale domanda
  • Qual è l'argomento corrente della conversazione o qual è l'ultimo

Lo stato utente è utile per tenere traccia delle informazioni sull'utente, ad esempio:

  • Informazioni utente non critiche, ad esempio nome e preferenze, impostazione di allarme o preferenza di avviso
  • Informazioni sull'ultima conversazione che hanno avuto con il bot
    • Ad esempio, un bot del supporto tecnico del prodotto potrebbe tenere traccia dei prodotti che l'utente ha chiesto.

Lo stato della conversazione privata è adatto per i canali che supportano le conversazioni di gruppo, ma dove si vogliono tenere traccia delle informazioni specifiche dell'utente e della conversazione. Ad esempio, se avevi un bot clicker per la classe:

  • Il bot può aggregare e visualizzare le risposte degli studenti per una determinata domanda.
  • Il bot potrebbe aggregare le prestazioni di ogni studente e trasmetterle a ciascuno privatamente alla fine della sessione.

Per informazioni dettagliate sull'uso di questi bucket predefiniti, vedere l'articolo di istruzioni sullo stato.

Connessione a più database

Se il bot deve connettersi a più database, creare un livello di archiviazione per ogni database. È possibile scegliere di usare più database se il bot raccoglie informazioni con diverse esigenze di sicurezza, concorrenza o posizione dei dati.

Per ogni livello di archiviazione, creare gli oggetti di gestione dello stato necessari per supportare le proprietà di stato.

Accessori delle proprietà di stato

Le funzioni di accesso alle proprietà di stato vengono usate per leggere o scrivere una delle proprietà di stato e fornire metodi get, set ed delete per accedere alle proprietà di stato dall'interno di un turno. Per creare un accessor, è necessario specificare il nome della proprietà, che in genere avviene durante l'inizializzazione del bot. È quindi possibile usare tale funzione di accesso per ottenere e modificare tale proprietà dello stato del bot.

Le funzioni di accesso consentono all'SDK di ottenere lo stato dalla risorsa di archiviazione sottostante e aggiornare automaticamente la cache di stato del bot. La cache di stato è una cache locale gestita dal bot che archivia automaticamente l'oggetto stato, consentendo operazioni di lettura e scrittura senza accedere all'archiviazione sottostante. Se non è già presente nella cache, la chiamata al metodo get della funzione di accesso recupera lo stato e la inserisce anche nella cache. Una volta recuperata, la proprietà di stato può essere modificata esattamente come una variabile locale.

Il metodo delete della funzione di accesso rimuove la proprietà dalla cache e la elimina anche dalla risorsa di archiviazione sottostante.

Importante

Per la prima chiamata al metodo get di una funzione di accesso, è necessario fornire un metodo di creazione per creare l'oggetto se non è già presente nel tuo stato. Se non viene specificato alcun metodo factory, si otterrà un'eccezione. Per informazioni dettagliate su come usare un metodo factory, vedere l'articolo procedure sullo stato.

Per rendere persistenti le modifiche apportate alla proprietà di stato ottenuta dalla funzione di accesso, è necessario aggiornare la proprietà nella cache di stato. È possibile farlo tramite una chiamata al metodo set delle funzioni di accesso, che imposta il valore della proprietà nella cache ed è disponibile se deve essere letto o aggiornato in un secondo momento. Per rendere effettivamente persistenti i dati nella risorsa di archiviazione sottostante (e quindi renderli disponibili dopo il turno corrente), è quindi necessario salvare lo stato.

Funzionamento dei metodi di accesso alle proprietà dello stato

I metodi di accesso sono il modo principale per consentire al bot di interagire con lo stato. Le modalità di interazione di ogni livello e il modo in cui interagiscono i livelli sottostanti sono le seguenti:

  • Metodo get dell'accessore:
    • La funzione di accesso richiede la proprietà dalla cache di stato.
    • Se la proprietà si trova nella cache, restituiscila. In caso contrario, recuperalo dall'oggetto di gestione dello stato. Se non è ancora in stato, usare il metodo factory fornito nella chiamata get delle funzioni di accesso.
  • Metodo set dell'accessor:
    • Aggiornare la cache di stato con il nuovo valore della proprietà.
  • Metodo save changes dell'oggetto di gestione dello stato:
    • Controllare le modifiche apportate alla proprietà nella cache di stato.
    • Scrivere la proprietà nella memoria.

Stato nei dialoghi

La libreria dialogs usa una funzione di accesso alle proprietà dello stato del dialogo, definita nello stato della conversazione del bot, per mantenere la posizione di un dialogo nella conversazione. La proprietà dello stato del dialogo consente anche a ogni finestra di dialogo di archiviare informazioni temporanee tra turni.

I dialoghi adattivi hanno una struttura di ambito di memoria più elaborata, che semplifica l'accesso ai risultati della configurazione e del riconoscimento, tra le altre cose. Il gestore dei dialoghi utilizza gli oggetti di gestione dello stato dell'utente e della conversazione per fornire questi ambiti di memoria.

Per informazioni sulla libreria di dialoghi, vedere l'articolo della dialogs library.

Salvataggio dello stato

Quando si chiama il metodo set della funzione di accesso per registrare lo stato aggiornato, tale proprietà di stato non è ancora stata salvata nella risorsa di archiviazione persistente e viene invece salvata solo nella cache di stato del bot. Per salvare le modifiche nella cache di stato nello stato persistente, è necessario chiamare il metodo save changes dell'oggetto di gestione dello stato, disponibile nell'implementazione della classe di stato del bot menzionata in precedenza, ad esempio lo stato utente o lo stato della conversazione.

La chiamata al metodo save changes per un oggetto di gestione dello stato ,ad esempio i bucket indicati in precedenza, salva tutte le proprietà nella cache di stato configurate fino a quel punto per tale bucket, ma non per gli altri bucket presenti nello stato del bot.

Suggerimento

Lo stato del bot implementa un comportamento di "ultima scrittura prevale", in cui l'ultima scrittura sovrascrive lo stato scritto in precedenza. Questo può funzionare per molte applicazioni, ma ha implicazioni, in particolare in scenari con scalabilità orizzontale, in cui potrebbe esserci un certo livello di concorrenza o latenza in gioco.

Se si dispone di un middleware personalizzato che potrebbe aggiornare lo stato al termine del gestore dei turni, prendere in considerazione la gestione dello stato nel middleware.

Risorse aggiuntive