TurnContext class

Paket:

botbuilder-core

Stellt Kontext für eine Umdrehung eines Bots bereit.

Hinweise

Kontext stellt Informationen bereit, die zum Verarbeiten einer eingehenden Aktivität erforderlich sind. Das Kontextobjekt wird von einem BotAdapter erstellt und für die Länge des Turns beibehalten.

Konstruktoren

TurnContext(BotAdapter, Partial<Activity>)	Erstellt eine neue Instanz der TurnContext-Klasse .
TurnContext(TurnContext)	Erstellt eine neue Instanz der TurnContext-Klasse .

Eigenschaften

activity	Ruft die aktivität ab, die diesem Turn zugeordnet ist.
adapter	Ruft den Botadapter ab, der dieses Kontextobjekt erstellt hat.
bufferedReplyActivities	Liste der Aktivitäten, die gesendet werden sollen, wenn context.activity.deliveryMode == 'expectReplies'.
locale	Ruft das gebietsschema ab, das im turnState gespeichert ist. Legt das gebietsschema fest, das im turnState gespeichert ist.
responded	Gibt an, ob der Bot dem Benutzer in dieser Runde geantwortet hat. Legt das Antwortflag für den aktuellen Turnkontext fest.
turnState	Ruft die Dienste ab, die für dieses Kontextobjekt registriert sind.

Methoden

applyConversationReference(Partial<Activity>, Partial<ConversationReference>, boolean)	Aktualisierungen eine Aktivität mit den Übermittlungsinformationen aus einem vorhandenen Unterhaltungsverweis.
deleteActivity(string | Partial<ConversationReference>)	Löscht asynchron eine zuvor gesendete Aktivität.
getConversationReference(Partial<Activity>)	Kopiert Unterhaltungsreferenzinformationen aus einer Aktivität.
getMentions(Partial<Activity>)	Ruft alle At-Mention-Entitäten ab, die in einer Aktivität enthalten sind.
getReplyConversationReference(Partial<Activity>, ResourceResponse)	Kopiert Unterhaltungsreferenzinformationen aus einer Ressourcenantwort für eine gesendete Aktivität.
onDeleteActivity(DeleteActivityHandler)	Fügt einen Antworthandler für Löschaktivitätsvorgänge hinzu.
onSendActivities(SendActivitiesHandler)	Fügt einen Antworthandler für Sendeaktivitätsvorgänge hinzu.
onUpdateActivity(UpdateActivityHandler)	Fügt einen Antworthandler für Aktualisierungsaktivitätsvorgänge hinzu.
removeMentionText(Partial<Activity>, string)	Entfernt At-Erwähnungen für eine bestimmte ID aus dem Text einer Aktivität und gibt den aktualisierten Text zurück. Verwenden Sie mit Vorsicht; Diese Funktion ändert die Texteigenschaft der Aktivität.
removeRecipientMention(Partial<Activity>)	Entfernt bei Erwähnungen für den Empfänger der Aktivität aus dem Text einer Aktivität und gibt den aktualisierten Text zurück. Verwenden Sie mit Vorsicht; Diese Funktion ändert die Texteigenschaft der Aktivität.
sendActivities(Partial<Activity>[])	Sendet asynchron eine Reihe von Aktivitäten an den Absender der eingehenden Aktivität.
sendActivity(string | Partial<Activity>, string, string)	Sendet asynchron eine Aktivität an den Absender der eingehenden Aktivität.
sendTraceActivity(string, any, string, string)	Sendet asynchron eine Aktivität an den Absender der eingehenden Aktivität.
updateActivity(Partial<Activity>)	Aktualisiert asynchron eine zuvor gesendete Aktivität.

Details zum Konstruktor

TurnContext(BotAdapter, Partial<Activity>)

Erstellt eine neue Instanz der TurnContext-Klasse .

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

Parameter

adapterOrContext

BotAdapter

Der Adapter, der den Kontext erstellt.

request

Partial<Activity>

Die eingehende Aktivität für die Runde.

TurnContext(TurnContext)

Erstellt eine neue Instanz der TurnContext-Klasse .

new TurnContext(adapterOrContext: TurnContext)

Parameter

adapterOrContext

TurnContext

Der Adapter, der den Kontext erstellt.

Details zur Eigenschaft

activity

Ruft die aktivität ab, die diesem Turn zugeordnet ist.

Activity activity

Eigenschaftswert

Activity

Die aktivität, die dieser Wendung zugeordnet ist.

Hinweise

In diesem Beispiel wird gezeigt, wie Die Benutzer eine gekürzte Äußerung aus der Aktivität erhalten:

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

adapter

Ruft den Botadapter ab, der dieses Kontextobjekt erstellt hat.

BotAdapter adapter

Eigenschaftswert

BotAdapter

Der Botadapter, der dieses Kontextobjekt erstellt hat.

bufferedReplyActivities

Liste der Aktivitäten, die gesendet werden sollen, wenn context.activity.deliveryMode == 'expectReplies'.

bufferedReplyActivities: Partial<Activity>[]

Eigenschaftswert

Partial<Activity>[]

locale

Ruft das gebietsschema ab, das im turnState gespeichert ist. Legt das gebietsschema fest, das im turnState gespeichert ist.

string | undefined locale

Eigenschaftswert

string | undefined

Das gebietsschema, das im turnState gespeichert ist.

responded

Gibt an, ob der Bot dem Benutzer in dieser Runde geantwortet hat. Legt das Antwortflag für den aktuellen Turnkontext fest.

boolean responded

Eigenschaftswert

boolean

True, wenn mindestens eine Antwort für den aktuellen Turn gesendet wurde; Andernfalls false.

Hinweise

TRUE , wenn mindestens eine Antwort für den aktuellen Turn gesendet wurde; Andernfalls false. Verwenden Sie diese Option, um zu ermitteln, ob Ihr Bot nach einer anderen normalen Verarbeitung Eine Fallbacklogik ausführen muss.

Ablaufverfolgungsaktivitäten legen dieses Flag nicht fest.

Beispiel:

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

turnState

Ruft die Dienste ab, die für dieses Kontextobjekt registriert sind.

TurnContextStateCollection turnState

Eigenschaftswert

TurnContextStateCollection

Die für dieses Kontextobjekt registrierten Dienste.

Hinweise

Middleware, andere Komponenten und Dienste verwenden diese in der Regel, um Informationen zwischenzuspeichern, die von einem Bot während eines Turns mehrmals angefordert werden können. Sie können diesen Cache verwenden, um Informationen zwischen Komponenten Ihres Bots zu übergeben.

Beispiel:

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

Tipp

Verwenden Sie beim Erstellen von Middleware oder einer Drittanbieterkomponente ein eindeutiges Symbol für Ihren Cacheschlüssel, um Konflikte mit der Benennung von Zustanden mit dem Bot oder anderen Middleware oder Komponenten zu vermeiden.

Details zur Methode

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

Aktualisierungen eine Aktivität mit den Übermittlungsinformationen aus einem vorhandenen Unterhaltungsverweis.

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

Parameter

activity

Partial<Activity>

Die zu aktualisierende Aktivität.

reference

Partial<ConversationReference>

Der Unterhaltungsverweis zum Kopieren von Übermittlungsinformationen.

isIncoming

boolean

Optional. true die Aktivität als eingehende Aktivität zu behandeln, wobei der Bot der Empfänger ist; falseandernfalls . Der Standardwert ist false, und die Aktivität zeigt den Bot als Absender an.

Gibt zurück

Partial<Activity>

Diese Aktivität wurde mit den Übermittlungsinformationen aktualisiert.

Hinweise

Rufen Sie die getConversationReference-Methode für eine eingehende Aktivität auf, um einen Unterhaltungsverweis abzurufen, den Sie dann verwenden können, um eine ausgehende Aktivität mit den richtigen Übermittlungsinformationen zu aktualisieren.

deleteActivity(string | Partial<ConversationReference>)

Löscht asynchron eine zuvor gesendete Aktivität.

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

Parameter

idOrReference

string | Partial<ConversationReference>

ID oder Unterhaltungsreferenz für die zu löschende Aktivität.

Gibt zurück

Promise<void>

Eine Zusage, die den asynchronen Vorgang darstellt.

Hinweise

Wenn eine ID angegeben wird, wird der Unterhaltungsverweis für die aktuelle Anforderung verwendet, um den Rest der benötigten Informationen abzurufen.

Beispiel:

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

Weitere Informationen

• Sendactivity
• updateActivity
• getReplyConversationReference

getConversationReference(Partial<Activity>)

Kopiert Unterhaltungsreferenzinformationen aus einer Aktivität.

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

Parameter

activity

Partial<Activity>

Die Aktivität, von der die Informationen abgerufen werden sollen.

Gibt zurück

Partial<ConversationReference>

Ein Unterhaltungsverweis für die Unterhaltung, die diese Aktivität enthält.

Hinweise

Sie können den Unterhaltungsverweis als JSON-Objekt speichern und später verwenden, um dem Benutzer proaktiv eine Nachricht zu senden.

Beispiel:

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

Weitere Informationen

• BotAdapter.continueConversation

getMentions(Partial<Activity>)

Ruft alle At-Mention-Entitäten ab, die in einer Aktivität enthalten sind.

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

Parameter

activity

Partial<Activity>

Die Aktivität.

Gibt zurück

Mention[]

Alle at-mention-Entitäten, die in einer Aktivität enthalten sind.

Hinweise

Die Entitätseigenschaft der Aktivität enthält eine flache Liste von Metadatenobjekten, die sich auf diese Aktivität beziehen, und kann Erwähnungsentitäten enthalten. Diese Methode gibt alle solchen Entitäten für eine bestimmte Aktivität zurück.

Beispiel:

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

getReplyConversationReference(Partial<Activity>, ResourceResponse)

Kopiert Unterhaltungsreferenzinformationen aus einer Ressourcenantwort für eine gesendete Aktivität.

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

Parameter

activity

Partial<Activity>

Die gesendete Aktivität.

reply

ResourceResponse

Die Ressourcenantwort für die Aktivität, die von der sendActivity- oder sendActivities-Methode zurückgegeben wird.

Gibt zurück

Partial<ConversationReference>

Eine ConversationReference, die gespeichert und später zum Löschen oder Aktualisieren der Aktivität verwendet werden kann.

Hinweise

Sie können den Unterhaltungsverweis als JSON-Objekt speichern und später verwenden, um die Nachricht zu aktualisieren oder zu löschen.

Beispiel:

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

Weitere Informationen

• deleteActivity
• updateActivity

onDeleteActivity(DeleteActivityHandler)

Fügt einen Antworthandler für Löschaktivitätsvorgänge hinzu.

function onDeleteActivity(handler: DeleteActivityHandler): this

Parameter

handler

DeleteActivityHandler

Der Handler, der dem Kontextobjekt hinzugefügt werden soll.

Gibt zurück

this

Das aktualisierte Kontextobjekt.

Hinweise

Diese Methode gibt einen Verweis auf das Turnkontextobjekt zurück.

Wenn die deleteActivity-Methode aufgerufen wird, werden die registrierten Handler in der Reihenfolge aufgerufen, in der sie dem Kontextobjekt hinzugefügt wurden, bevor die Aktivität gelöscht wird.

In diesem Beispiel wird gezeigt, wie Aktivitätslöschungen überwacht und protokolliert werden.

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

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

onSendActivities(SendActivitiesHandler)

Fügt einen Antworthandler für Sendeaktivitätsvorgänge hinzu.

function onSendActivities(handler: SendActivitiesHandler): this

Parameter

handler

SendActivitiesHandler

Der Handler, der dem Kontextobjekt hinzugefügt werden soll.

Gibt zurück

this

Das aktualisierte Kontextobjekt.

Hinweise

Diese Methode gibt einen Verweis auf das Turnkontextobjekt zurück.

Wenn die sendActivity - oder sendActivities-Methode aufgerufen wird, werden die registrierten Handler in der Reihenfolge aufgerufen, in der sie dem Kontextobjekt hinzugefügt wurden, bevor die Aktivitäten gesendet werden.

In diesem Beispiel wird gezeigt, wie ausgehende message Aktivitäten überwacht und protokolliert werden.

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)

Fügt einen Antworthandler für Aktualisierungsaktivitätsvorgänge hinzu.

function onUpdateActivity(handler: UpdateActivityHandler): this

Parameter

handler

UpdateActivityHandler

Der Handler, der dem Kontextobjekt hinzugefügt werden soll.

Gibt zurück

this

Das aktualisierte Kontextobjekt.

Hinweise

Diese Methode gibt einen Verweis auf das Turnkontextobjekt zurück.

Wenn die updateActivity-Methode aufgerufen wird, werden die registrierten Handler in der Reihenfolge aufgerufen, in der sie dem Kontextobjekt hinzugefügt wurden, bevor die Aktivität aktualisiert wird.

In diesem Beispiel wird gezeigt, wie Aktivitätsupdates überwacht und protokolliert werden.

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

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

removeMentionText(Partial<Activity>, string)

Entfernt At-Erwähnungen für eine bestimmte ID aus dem Text einer Aktivität und gibt den aktualisierten Text zurück. Verwenden Sie mit Vorsicht; Diese Funktion ändert die Texteigenschaft der Aktivität.

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

Parameter

activity

Partial<Activity>

Die Aktivität, aus der bei Erwähnungen entfernt werden soll.

id

string

Die ID des Benutzers oder Bots, der bei Erwähnungen entfernt werden soll.

Gibt zurück

string

Der Text der aktualisierten Aktivität.

Hinweise

Einige Kanäle, z. B. Microsoft Teams, fügen dem Text einer Nachrichtenaktivität At-Erwähnungen hinzu.

Verwenden Sie diese Hilfsmethode, um die Texteigenschaft der Aktivität zu ändern. Es entfernt alle Erwähnungen für die angegebene Bot- oder Benutzer-ID und gibt dann den aktualisierten Eigenschaftswert zurück.

Wenn Sie beispielsweise Erwähnungen von echoBot aus einer Aktivität entfernen, die den Text "@echoBot Hi Bot" enthält, wird der Aktivitätstext aktualisiert, und die Methode gibt "Hi Bot" zurück.

Das Format einer Erwähnungsentität ist kanalabhängig. Die Texteigenschaft der Erwähnung sollte jedoch genau den Text für den Benutzer enthalten, wie er im Aktivitätstext angezeigt wird.

Unabhängig davon, ob der Kanal beispielsweise "benutzername" oder "@username" verwendet, befindet sich diese Zeichenfolge im Text der Aktivität, und diese Methode entfernt alle Vorkommen dieser Zeichenfolge aus dem Text.

Beispiel:

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

Weitere Informationen

• removeRecipientMention

removeRecipientMention(Partial<Activity>)

Entfernt bei Erwähnungen für den Empfänger der Aktivität aus dem Text einer Aktivität und gibt den aktualisierten Text zurück. Verwenden Sie mit Vorsicht; Diese Funktion ändert die Texteigenschaft der Aktivität.

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

Parameter

activity

Partial<Activity>

Die Aktivität, aus der bei Erwähnungen entfernt werden soll.

Gibt zurück

string

Der Text der aktualisierten Aktivität.

Hinweise

Einige Kanäle, z. B. Microsoft Teams, fügen dem Text einer Nachrichtenaktivität Details zur Erwähnung hinzu.

Verwenden Sie diese Hilfsmethode, um die Texteigenschaft der Aktivität zu ändern. Es entfernt alle Erwähnungen des Empfängers der Aktivität und gibt dann den aktualisierten Eigenschaftswert zurück.

Beispiel:

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

Weitere Informationen

• removeMentionText

sendActivities(Partial<Activity>[])

Sendet asynchron eine Reihe von Aktivitäten an den Absender der eingehenden Aktivität.

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

Parameter

activities

Partial<Activity>[]

Die zu sendenden Aktivitäten.

Gibt zurück

Promise<ResourceResponse[]>

Eine Zusage mit einem ResourceResponse.

Hinweise

Wenn die Aktivitäten erfolgreich gesendet wurden, ergibt sich ein Array von ResourceResponse-Objekten , die die IDs enthalten, die der empfangende Kanal den Aktivitäten zugewiesen hat.

Bevor sie gesendet werden, werden die Übermittlungsinformationen jeder ausgehenden Aktivität basierend auf den Übermittlungsinformationen der eingehenden eingehenden Aktivität aktualisiert.

Beispiel:

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

Weitere Informationen

• Sendactivity
• updateActivity
• deleteActivity

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

Sendet asynchron eine Aktivität an den Absender der eingehenden Aktivität.

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

Parameter

activityOrText

string | Partial<Activity>

Die zu sendende Aktivität oder der zu sendende Text.

speak

string

Optional. Der Text, der von Ihrem Bot in einem sprachfähigen Kanal gesprochen werden soll.

inputHint

string

Optional. Gibt an, ob Ihr Bot Benutzereingaben akzeptiert, erwartet oder ignoriert, nachdem die Nachricht an den Client übermittelt wurde. Einer von: "acceptingInput", "ignoringInput" oder "expectingInput". Der Standardwert ist "acceptingInput".

Gibt zurück

Promise<ResourceResponse | undefined>

Eine Zusage mit einem ResourceResponse.

Hinweise

Wenn die Aktivität erfolgreich gesendet wurde, ergibt sich ein ResourceResponse-Objekt , das die ID enthält, die der Empfangende Kanal der Aktivität zugewiesen hat.

In der Dokumentation des Kanals finden Sie Grenzwerte, die dem Inhalt des activityOrText-Parameters auferlegt werden.

Um verschiedene Merkmale der Sprache Ihres Bots wie Stimme, Rate, Lautstärke, Aussprache und Tonhöhe zu steuern, geben Sie die Sprache im SSML-Format (Speech Synthesis Markup Language) an.

Beispiel:

await context.sendActivity(`Hello World`);

Weitere Informationen

• sendActivities
• updateActivity
• deleteActivity

sendTraceActivity(string, any, string, string)

Sendet asynchron eine Aktivität an den Absender der eingehenden Aktivität.

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

Parameter

name

string

Die zu sendende Aktivität oder der zu sendende Text.

value

any

Optional. Der Text, der von Ihrem Bot in einem sprachfähigen Kanal gesprochen werden soll.

valueType

string

Optional. Gibt an, ob Ihr Bot Benutzer akzeptiert, erwartet oder ignoriert.

label

string

Optional. Gibt an, ob Ihr Bot Benutzer akzeptiert, erwartet oder ignoriert.

Gibt zurück

Promise<ResourceResponse | undefined>

Eine Zusage mit einem ResourceResponse.

Hinweise

Erstellt und sendet eine Ablaufverfolgungsaktivität. Ablaufverfolgungsaktivitäten werden nur gesendet, wenn der Kanal der Emulator ist.

Beispiel:

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

Weitere Informationen

• sendActivities

updateActivity(Partial<Activity>)

Aktualisiert asynchron eine zuvor gesendete Aktivität.

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

Parameter

activity

Partial<Activity>

Der Ersatz für die ursprüngliche Aktivität.

Gibt zurück

Promise<ResourceResponse | void>

Eine Zusage mit einem ResourceResponse.

Hinweise

Die ID der Ersetzungsaktivität gibt die zu ersetzende Aktivität in der Konversation an.

Beispiel:

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

Weitere Informationen

• Sendactivity
• deleteActivity
• getReplyConversationReference