TurnContext class

Pacchetto:

botbuilder-core

Fornisce il contesto per un turno di un bot.

Commenti

Il contesto fornisce informazioni necessarie per elaborare un'attività in ingresso. L'oggetto contesto viene creato da un BotAdapter e viene mantenuto per la lunghezza del turno.

Costruttori

TurnContext(BotAdapter, Partial<Activity>)	Crea una nuova istanza della classe TurnContext .
TurnContext(TurnContext)	Crea una nuova istanza della classe TurnContext .

Proprietà

activity	Ottiene l'attività associata a questo turno.
adapter	Ottiene l'adattatore bot che ha creato questo oggetto contesto.
bufferedReplyActivities	Elenco di attività da inviare quando context.activity.deliveryMode == 'expectReplies'.
locale	Ottiene le impostazioni locali archiviate in turnState. Imposta le impostazioni locali archiviate in turnState.
responded	Indica se il bot ha risposto all'utente a questo turno. Imposta il flag di risposta nel contesto di turno corrente.
turnState	Ottiene i servizi registrati in questo oggetto contesto.

Metodi

applyConversationReference(Partial<Activity>, Partial<ConversationReference>, boolean)	Aggiorna un'attività con le informazioni di recapito da un riferimento di conversazione esistente.
deleteActivity(string | Partial<ConversationReference>)	Elimina in modo asincrono un'attività inviata in precedenza.
getConversationReference(Partial<Activity>)	Copia le informazioni di riferimento della conversazione da un'attività.
getMentions(Partial<Activity>)	Ottiene tutte le entità di riferimento incluse in un'attività.
getReplyConversationReference(Partial<Activity>, ResourceResponse)	Copia le informazioni di riferimento della conversazione da una risposta di risorsa per un'attività inviata.
onDeleteActivity(DeleteActivityHandler)	Aggiunge un gestore di risposta per le operazioni di eliminazione delle attività.
onSendActivities(SendActivitiesHandler)	Aggiunge un gestore di risposta per le operazioni di invio dell'attività.
onUpdateActivity(UpdateActivityHandler)	Aggiunge un gestore di risposta per le operazioni di aggiornamento dell'attività.
removeMentionText(Partial<Activity>, string)	Rimuove le menzioni per un determinato ID dal testo di un'attività e restituisce il testo aggiornato. Usare con cautela; questa funzione modifica il testo proprietà dell'attività.
removeRecipientMention(Partial<Activity>)	Rimuove le menzioni per il destinatario dell'attività dal testo di un'attività e restituisce il testo aggiornato. Usare con cautela; questa funzione modifica il testo proprietà dell'attività.
sendActivities(Partial<Activity>[])	Invia in modo asincrono un set di attività al mittente dell'attività in ingresso.
sendActivity(string | Partial<Activity>, string, string)	Invia in modo asincrono un'attività al mittente dell'attività in ingresso.
sendTraceActivity(string, any, string, string)	Invia in modo asincrono un'attività al mittente dell'attività in ingresso.
updateActivity(Partial<Activity>)	Aggiorna in modo asincrono un'attività inviata in precedenza.

Dettagli costruttore

TurnContext(BotAdapter, Partial<Activity>)

Crea una nuova istanza della classe TurnContext .

new TurnContext(adapterOrContext: BotAdapter, request: Partial<Activity>)

Parametri

adapterOrContext

BotAdapter

Adattatore che crea il contesto.

request

Partial<Activity>

Attività in ingresso per il turno.

TurnContext(TurnContext)

Crea una nuova istanza della classe TurnContext .

new TurnContext(adapterOrContext: TurnContext)

Parametri

adapterOrContext

TurnContext

Adattatore che crea il contesto.

Dettagli proprietà

activity

Ottiene l'attività associata a questo turno.

Activity activity

Valore della proprietà

Activity

Attività associata a questo turno.

Commenti

Questo esempio illustra come ottenere l'espressione tagliata dagli utenti dall'attività:

const utterance = (context.activity.text || '').trim();

adapter

Ottiene l'adattatore bot che ha creato questo oggetto contesto.

BotAdapter adapter

Valore della proprietà

BotAdapter

Adattatore bot che ha creato questo oggetto contesto.

bufferedReplyActivities

Elenco di attività da inviare quando context.activity.deliveryMode == 'expectReplies'.

bufferedReplyActivities: Partial<Activity>[]

Valore della proprietà

Partial<Activity>[]

locale

Ottiene le impostazioni locali archiviate in turnState. Imposta le impostazioni locali archiviate in turnState.

string | undefined locale

Valore della proprietà

string | undefined

Impostazioni locali archiviate in turnState.

responded

Indica se il bot ha risposto all'utente a questo turno. Imposta il flag di risposta nel contesto di turno corrente.

boolean responded

Valore della proprietà

boolean

True se almeno una risposta è stata inviata per il turno corrente; in caso contrario, false.

Commenti

true se almeno una risposta è stata inviata per il turno corrente; in caso contrario, false. Usare questa opzione per determinare se il bot deve eseguire la logica di fallback dopo altre normali elaborazioni.

Le attività di traccia non impostano questo flag.

Per esempio:

await routeActivity(context);
if (!context.responded) {
   await context.sendActivity(`I'm sorry. I didn't understand.`);
}

turnState

Ottiene i servizi registrati in questo oggetto contesto.

TurnContextStateCollection turnState

Valore della proprietà

TurnContextStateCollection

I servizi registrati in questo oggetto contesto.

Commenti

Il middleware, altri componenti e servizi in genere userà questa funzionalità per memorizzare nella cache le informazioni che potrebbero essere richieste da un bot più volte durante un turno. È possibile usare questa cache per passare informazioni tra i componenti del bot.

Per esempio:

const cartKey = Symbol();
const cart = await loadUsersShoppingCart(context);
context.turnState.set(cartKey, cart);

Mancia

Quando si crea un middleware o un componente di terze parti, usare un simbolo univoco per la chiave della cache per evitare conflitti di denominazione dello stato con il bot o altri componenti o middleware.

Dettagli metodo

applyConversationReference(Partial<Activity>, Partial<ConversationReference>, boolean)

Aggiorna un'attività con le informazioni di recapito da un riferimento di conversazione esistente.

static function applyConversationReference(activity: Partial<Activity>, reference: Partial<ConversationReference>, isIncoming?: boolean): Partial<Activity>

Parametri

activity

Partial<Activity>

Attività da aggiornare.

reference

Partial<ConversationReference>

Riferimento di conversazione da cui copiare le informazioni di recapito.

isIncoming

boolean

Opzionale. true considerare l'attività come un'attività in ingresso, in cui il bot è il destinatario; in caso contrario, false. Il valore predefinito è falsee l'attività mostrerà il bot come mittente.

Restituisce

Partial<Activity>

Questa attività, aggiornata con le informazioni di recapito.

Commenti

Chiamare il metodo getConversationReference su un'attività in ingresso per ottenere un riferimento alla conversazione che è quindi possibile usare per aggiornare un'attività in uscita con le informazioni di recapito corrette.

deleteActivity(string | Partial<ConversationReference>)

Elimina in modo asincrono un'attività inviata in precedenza.

function deleteActivity(idOrReference: string | Partial<ConversationReference>): Promise<void>

Parametri

idOrReference

string | Partial<ConversationReference>

Informazioni di riferimento sull'ID o sulla conversazione per l'attività da eliminare.

Restituisce

Promise<void>

Promessa che rappresenta l'operazione asincrona.

Commenti

Se viene specificato un ID, viene usato il riferimento di conversazione per la richiesta corrente per ottenere il resto delle informazioni necessarie.

Per esempio:

const matched = /approve (.*)/i.exec(context.activity.text);
if (matched) {
   const savedId = await approveExpenseReport(matched[1]);
   await context.deleteActivity(savedId);
}

Vedere anche

• sendActivity
• updateActivity
• getReplyConversationReference

getConversationReference(Partial<Activity>)

Copia le informazioni di riferimento della conversazione da un'attività.

static function getConversationReference(activity: Partial<Activity>): Partial<ConversationReference>

Parametri

activity

Partial<Activity>

Attività da cui ottenere le informazioni.

Restituisce

Partial<ConversationReference>

Riferimento di conversazione per la conversazione che contiene questa attività.

Commenti

È possibile salvare il riferimento alla conversazione come oggetto JSON e usarlo in un secondo momento per inviare un messaggio proattivo all'utente.

Per esempio:

const reference = TurnContext.getConversationReference(context.request);

Vedere anche

• BotAdapter.continueConversation

getMentions(Partial<Activity>)

Ottiene tutte le entità di riferimento incluse in un'attività.

static function getMentions(activity: Partial<Activity>): Mention[]

Parametri

activity

Partial<Activity>

Attività.

Restituisce

Mention[]

Tutte le entità at-mention incluse in un'attività.

Commenti

Le entità dell'attività contengono un elenco semplice di oggetti metadati relativi a questa attività e possono contenere menzionare entità. Questo metodo restituisce tutte queste entità per una determinata attività.

Per esempio:

const mentions = TurnContext.getMentions(turnContext.request);

getReplyConversationReference(Partial<Activity>, ResourceResponse)

Copia le informazioni di riferimento della conversazione da una risposta di risorsa per un'attività inviata.

static function getReplyConversationReference(activity: Partial<Activity>, reply: ResourceResponse): Partial<ConversationReference>

Parametri

activity

Partial<Activity>

Attività inviata.

reply

ResourceResponse

Risposta della risorsa per l'attività, restituita dal metodo sendActivity o sendActiv ities.

Restituisce

Partial<ConversationReference>

ConversationReference che può essere archiviato e usato in un secondo momento per eliminare o aggiornare l'attività.

Commenti

È possibile salvare il riferimento alla conversazione come oggetto JSON e usarlo in un secondo momento per aggiornare o eliminare il messaggio.

Per esempio:

var reply = await context.sendActivity('Hi');
var reference = TurnContext.getReplyConversationReference(context.activity, reply);

Vedere anche

• deleteActivity
• updateActivity

onDeleteActivity(DeleteActivityHandler)

Aggiunge un gestore di risposta per le operazioni di eliminazione delle attività.

function onDeleteActivity(handler: DeleteActivityHandler): this

Parametri

handler

DeleteActivityHandler

Gestore da aggiungere all'oggetto contesto.

Restituisce

this

Oggetto contesto aggiornato.

Commenti

Questo metodo restituisce un riferimento all'oggetto contesto di turno.

Quando viene chiamato il metodo deleteActivity , i gestori registrati vengono chiamati nell'ordine in cui sono stati aggiunti all'oggetto contesto prima dell'eliminazione dell'attività.

In questo esempio viene illustrato come restare in ascolto delle eliminazioni delle attività e del log.

context.onDeleteActivity(async (ctx, reference, next) => {
   // Delete activity
   await next();

   // Log delete
   logDelete(activity);
});

onSendActivities(SendActivitiesHandler)

Aggiunge un gestore di risposta per le operazioni di invio dell'attività.

function onSendActivities(handler: SendActivitiesHandler): this

Parametri

handler

SendActivitiesHandler

Gestore da aggiungere all'oggetto contesto.

Restituisce

this

Oggetto contesto aggiornato.

Commenti

Questo metodo restituisce un riferimento all'oggetto contesto di turno.

Quando viene chiamato il metodo sendActivity o sendActivities, i gestori registrati vengono chiamati nell'ordine in cui sono stati aggiunti all'oggetto contesto prima dell'invio delle attività.

In questo esempio viene illustrato come restare in ascolto e registrare le attività di message in uscita.

context.onSendActivities(async (ctx, activities, next) => {
   // Log activities before sending them.
   activities.filter(a => a.type === 'message').forEach(a => logSend(a));

   // Allow the send process to continue.
   next();
});

onUpdateActivity(UpdateActivityHandler)

Aggiunge un gestore di risposta per le operazioni di aggiornamento dell'attività.

function onUpdateActivity(handler: UpdateActivityHandler): this

Parametri

handler

UpdateActivityHandler

Gestore da aggiungere all'oggetto contesto.

Restituisce

this

Oggetto contesto aggiornato.

Commenti

Questo metodo restituisce un riferimento all'oggetto contesto di turno.

Quando viene chiamato il metodo updateActivity , i gestori registrati vengono chiamati nell'ordine in cui sono stati aggiunti all'oggetto contesto prima dell'aggiornamento dell'attività.

Questo esempio illustra come restare in ascolto e registrare gli aggiornamenti delle attività.

context.onUpdateActivity(async (ctx, activity, next) => {
   // Replace activity
   await next();

   // Log update
   logUpdate(activity);
});

removeMentionText(Partial<Activity>, string)

Rimuove le menzioni per un determinato ID dal testo di un'attività e restituisce il testo aggiornato. Usare con cautela; questa funzione modifica il testo proprietà dell'attività.

static function removeMentionText(activity: Partial<Activity>, id: string): string

Parametri

activity

Partial<Activity>

Attività da cui rimuovere le menzioni.

id

string

ID dell'utente o del bot per cui rimuovere le menzioni.

Restituisce

string

Testo dell'attività aggiornata.

Commenti

Alcuni canali, ad esempio Microsoft Teams, aggiungono menzioni al testo di un'attività di messaggio.

Utilizzare questo metodo helper per modificare la proprietà testo dell'attività. Rimuove tutte le menzioni per il bot o l'ID utente specificato e quindi restituisce il valore della proprietà aggiornato.

Ad esempio, quando si rimuovono menzioni di echoBot da un'attività contenente il testo "@echoBot Hi Bot", il testo dell'attività viene aggiornato e il metodo restituisce "Hi Bot".

Il formato di una menzione 'entità dipende dal canale. Tuttavia, la testo della menzione proprietà deve contenere il testo esatto per l'utente come appare nel testo dell'attività.

Ad esempio, se il canale usa "username" o "@username", questa stringa si trova nel testo dell'attività e questo metodo rimuoverà tutte le occorrenze di tale stringa dal testo.

Per esempio:

const updatedText = TurnContext.removeMentionText(activity, activity.recipient.id);

Vedere anche

• removeRecipientMention

removeRecipientMention(Partial<Activity>)

Rimuove le menzioni per il destinatario dell'attività dal testo di un'attività e restituisce il testo aggiornato. Usare con cautela; questa funzione modifica il testo proprietà dell'attività.

static function removeRecipientMention(activity: Partial<Activity>): string

Parametri

activity

Partial<Activity>

Attività da cui rimuovere le menzioni.

Restituisce

string

Testo dell'attività aggiornata.

Commenti

Alcuni canali, ad esempio Microsoft Teams, aggiungono dettagli di menzione al testo di un'attività di messaggio.

Utilizzare questo metodo helper per modificare la proprietà testo dell'attività. Rimuove tutte le menzioni dell'destinatario dell'attività e quindi restituisce il valore della proprietà aggiornato.

Per esempio:

const updatedText = TurnContext.removeRecipientMention(turnContext.request);

Vedere anche

• removeMentionText

sendActivities(Partial<Activity>[])

Invia in modo asincrono un set di attività al mittente dell'attività in ingresso.

function sendActivities(activities: Partial<Activity>[]): Promise<ResourceResponse[]>

Parametri

activities

Partial<Activity>[]

Attività da inviare.

Restituisce

Promise<ResourceResponse[]>

Promessa con resourceResponse.

Commenti

Se le attività vengono inviate correttamente, genera una matrice di ResourceResponse oggetti contenenti gli ID assegnati al canale ricevente alle attività.

Prima dell'invio, le informazioni di recapito di ogni attività in uscita vengono aggiornate in base alle informazioni di recapito dell'attività in ingresso.

Per esempio:

await context.sendActivities([
   { type: 'typing' },
   { type: 'delay', value: 2000 },
   { type: 'message', text: 'Hello... How are you?' }
]);

Vedere anche

• sendActivity
• updateActivity
• deleteActivity

sendActivity(string | Partial<Activity>, string, string)

Invia in modo asincrono un'attività al mittente dell'attività in ingresso.

function sendActivity(activityOrText: string | Partial<Activity>, speak?: string, inputHint?: string): Promise<ResourceResponse | undefined>

Parametri

activityOrText

string | Partial<Activity>

Attività o testo da inviare.

speak

string

Opzionale. Testo da pronunciare dal bot in un canale abilitato per il riconoscimento vocale.

inputHint

string

Opzionale. Indica se il bot accetta, prevede o ignora l'input dell'utente dopo che il messaggio viene recapitato al client. Uno dei seguenti: 'accettaInput', 'ignoringInput' o 'expectingInput'. Il valore predefinito è "accettaInput".

Restituisce

Promise<ResourceResponse | undefined>

Promessa con resourceResponse.

Commenti

Se l'attività viene inviata correttamente, restituisce un Oggetto ResourceResponse contenente l'ID assegnato al canale ricevente all'attività.

Vedere la documentazione del canale per i limiti imposti al contenuto del parametro activityOrText.

Per controllare varie caratteristiche del parlato del bot, ad esempio voce, frequenza, volume, pronuncia e passo, specificare parlare in formato SSML (Speech Synthesis Markup Language).

Per esempio:

await context.sendActivity(`Hello World`);

Vedere anche

• sendActivities
• updateActivity
• deleteActivity

sendTraceActivity(string, any, string, string)

Invia in modo asincrono un'attività al mittente dell'attività in ingresso.

function sendTraceActivity(name: string, value?: any, valueType?: string, label?: string): Promise<ResourceResponse | undefined>

Parametri

name

string

Attività o testo da inviare.

value

any

Opzionale. Testo da pronunciare dal bot in un canale abilitato per il riconoscimento vocale.

valueType

string

Opzionale. Indica se il bot accetta, prevede o ignora l'utente

label

string

Opzionale. Indica se il bot accetta, prevede o ignora l'utente

Restituisce

Promise<ResourceResponse | undefined>

Promessa con resourceResponse.

Commenti

Crea e invia un'attività di traccia. Le attività di traccia vengono inviate solo quando il canale è l'emulatore.

Per esempio:

await context.sendTraceActivity(`The following exception was thrown ${msg}`);

Vedere anche

• sendActivities

updateActivity(Partial<Activity>)

Aggiorna in modo asincrono un'attività inviata in precedenza.

function updateActivity(activity: Partial<Activity>): Promise<ResourceResponse | void>

Parametri

activity

Partial<Activity>

Sostituzione dell'attività originale.

Restituisce

Promise<ResourceResponse | void>

Promessa con resourceResponse.

Commenti

Il ID dell'attività di sostituzione indica l'attività nella conversazione da sostituire.

Per esempio:

const matched = /approve (.*)/i.exec(context.activity.text);
if (matched) {
   const update = await approveExpenseReport(matched[1]);
   await context.updateActivity(update);
}

Vedere anche

• sendActivity
• deleteActivity
• getReplyConversationReference