TurnContext class

Paket:

botbuilder-core

Stellt Kontext für eine Drehung eines Bots bereit.

Hinweise

Der 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 Drehs 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 dieser 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 auf den Benutzer geantwortet hat. Legt das Antwortkennzeichnung für den aktuellen Turnkontext fest.
turnState	Ruft die für dieses Kontextobjekt registrierten Dienste ab.

Methoden

applyConversationReference(Partial<Activity>, Partial<ConversationReference>, boolean)	Aktualisiert 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 in einer Aktivität enthaltenen At-Mention-Entitäten ab.
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 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 den Text der Aktivität Eigenschaft.
removeRecipientMention(Partial<Activity>)	Entfernt 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 den Text der Aktivität Eigenschaft.
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 Drehung.

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 dieser Turn zugeordnet ist.

Activity activity

Eigenschaftswert

Activity

Die aktivität, die dieser Drehung zugeordnet ist.

Hinweise

In diesem Beispiel wird gezeigt, wie sie die Benutzer aus der Aktivität gekürzt haben:

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 auf den Benutzer geantwortet hat. Legt das Antwortkennzeichnung für den aktuellen Turnkontext fest.

boolean responded

Eigenschaftswert

boolean

True, wenn mindestens eine Antwort für die aktuelle Drehung gesendet wurde; andernfalls "false".

Hinweise

"true", wenn mindestens eine Antwort für die aktuelle Drehung gesendet wurde; andernfalls "false". Verwenden Sie diese Methode, um zu ermitteln, ob Ihr Bot fallbacklogik nach einer anderen normalen Verarbeitung ausführen muss.

Ablaufverfolgungsaktivitäten legen dieses Kennzeichen nicht fest.

Zum Beispiel:

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

turnState

Ruft die für dieses Kontextobjekt registrierten Dienste ab.

TurnContextStateCollection turnState

Eigenschaftswert

TurnContextStateCollection

Die in diesem Kontextobjekt registrierten Dienste.

Hinweise

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

Zum Beispiel:

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

Trinkgeld

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

Details zur Methode

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

Aktualisiert 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 aus.

isIncoming

boolean

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

Gibt zurück

Partial<Activity>

Diese Aktivität, aktualisiert mit den Übermittlungsinformationen.

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 ist, wird der Unterhaltungsverweis für die aktuelle Anforderung verwendet, um die restlichen erforderlichen Informationen abzurufen.

Zum Beispiel:

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

Siehe auch

• 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, aus 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 den Benutzer proaktiv zu benachrichtigen.

Zum Beispiel:

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

Siehe auch

• BotAdapter.continueConversation

getMentions(Partial<Activity>)

Ruft alle in einer Aktivität enthaltenen At-Mention-Entitäten ab.

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

Parameter

activity

Partial<Activity>

Die Aktivität.

Gibt zurück

Mention[]

Alle in einer Aktivität enthaltenen At-Mention-Entitäten.

Hinweise

Die Entitäten der Aktivität Eigenschaft enthält eine flache Liste von Metadatenobjekten, die zu dieser Aktivität gehören, und kann Erwähnung Entitäten enthalten. Diese Methode gibt alle solchen Entitäten für eine bestimmte Aktivität zurück.

Zum 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 methode sendActivity oder sendActivities zurückgegeben wird.

Gibt zurück

Partial<ConversationReference>

Eine ConversationReference, die gespeichert und später verwendet werden kann, um die Aktivität zu löschen oder zu aktualisieren.

Hinweise

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

Zum Beispiel:

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

Siehe auch

• 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 Sie auf Löschungen von Aktivitäten lauschen und diese protokollieren.

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 Sie auf Aktivitätsupdates lauschen und diese protokollieren.

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

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

removeMentionText(Partial<Activity>, string)

Entfernt 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 den Text der Aktivität Eigenschaft.

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

Parameter

activity

Partial<Activity>

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

id

string

Die ID des Benutzers oder Bots, für den Erwähnungen entfernt werden sollen.

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 den Text der Aktivität Eigenschaft zu ändern. Es entfernt alle Erwähnungen für den angegebenen Bot oder die 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ähnung Entität ist kanalabhängig. Der Text der Erwähnung Eigenschaft sollte jedoch den genauen Text für den Benutzer enthalten, wie er im Aktivitätstext angezeigt wird.

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.

Zum Beispiel:

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

Siehe auch

• removeRecipientMention

removeRecipientMention(Partial<Activity>)

Entfernt 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 den Text der Aktivität Eigenschaft.

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

Parameter

activity

Partial<Activity>

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

Gibt zurück

string

Der Text der aktualisierten Aktivität.

Hinweise

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

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

Zum Beispiel:

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

Siehe auch

• 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 einer ResourceResponse.

Hinweise

Wenn die Aktivitäten erfolgreich gesendet werden, führt dies zu einem Array von ResourceResponse- Objekten, die die IDs enthalten, die dem empfangenden Kanal den Aktivitäten zugewiesen wurden.

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

Zum Beispiel:

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

Siehe auch

• 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

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

inputHint

string

Wahlfrei. 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 einer ResourceResponse.

Hinweise

Wenn die Aktivität erfolgreich gesendet wurde, führt dies zu einem ResourceResponse- Objekt, das die ID enthält, die der Empfangenden Kanal der Aktivität zugewiesen wurde.

In der Dokumentation des Kanals finden Sie Grenzwerte für den Inhalt des activityOrText- Parameters.

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

Zum Beispiel:

await context.sendActivity(`Hello World`);

Siehe auch

• 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

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

valueType

string

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

label

string

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

Gibt zurück

Promise<ResourceResponse | undefined>

Eine Zusage mit einer ResourceResponse.

Hinweise

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

Zum Beispiel:

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

Siehe auch

• 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 einer ResourceResponse.

Hinweise

Die -ID der Ersetzungsaktivität gibt die Aktivität in der Unterhaltung an, die ersetzt werden soll.

Zum Beispiel:

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

Siehe auch

• sendActivity-
• deleteActivity-
• getReplyConversationReference-