TurnContext class

包:

botbuilder-core

为机器人的轮次提供上下文。

注解

上下文提供处理传入活动所需的信息。 上下文对象由 BotAdapter 创建，并保留轮次长度。

构造函数

TurnContext(BotAdapter, Partial<Activity>)	创建 TurnContext 类的新实例。
TurnContext(TurnContext)	创建 TurnContext 类的新实例。

属性

activity	获取与此轮次关联的活动。
adapter	获取创建此上下文对象的机器人适配器。
bufferedReplyActivities	在 时 context.activity.deliveryMode == 'expectReplies'要发送的活动列表。
locale	获取存储在 turnState 中的区域设置。 设置存储在 turnState 中的区域设置。
responded	指示机器人是否已在此轮次回复用户。 设置当前轮次上下文上的响应标志。
turnState	获取在此上下文对象上注册的服务。

方法

applyConversationReference(Partial<Activity>, Partial<ConversationReference>, boolean)	使用现有对话引用中的传递信息汇报活动。
deleteActivity(string | Partial<ConversationReference>)	异步删除以前发送的活动。
getConversationReference(Partial<Activity>)	从活动复制会话引用信息。
getMentions(Partial<Activity>)	获取活动中包含的所有提及实体。
getReplyConversationReference(Partial<Activity>, ResourceResponse)	从已发送活动的资源响应中复制会话引用信息。
onDeleteActivity(DeleteActivityHandler)	为删除活动操作添加响应处理程序。
onSendActivities(SendActivitiesHandler)	为发送活动操作添加响应处理程序。
onUpdateActivity(UpdateActivityHandler)	为更新活动操作添加响应处理程序。
removeMentionText(Partial<Activity>, string)	从活动的文本中删除给定 ID 的提及，并返回更新的文本。 请谨慎使用;此函数更改活动的 text 属性。
removeRecipientMention(Partial<Activity>)	从活动的文本中删除活动 收件人 的提及，并返回更新的文本。 请谨慎使用;此函数更改活动的 text 属性。
sendActivities(Partial<Activity>[])	以异步方式将一组活动发送到传入活动的发送方。
sendActivity(string | Partial<Activity>, string, string)	以异步方式将活动发送到传入活动的发送方。
sendTraceActivity(string, any, string, string)	以异步方式将活动发送到传入活动的发送方。
updateActivity(Partial<Activity>)	异步更新以前发送的活动。

构造函数详细信息

TurnContext(BotAdapter, Partial<Activity>)

创建 TurnContext 类的新实例。

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

参数

adapterOrContext

BotAdapter

创建上下文的适配器。

request

Partial<Activity>

轮次的传入活动。

TurnContext(TurnContext)

创建 TurnContext 类的新实例。

new TurnContext(adapterOrContext: TurnContext)

参数

adapterOrContext

TurnContext

创建上下文的适配器。

属性详细信息

activity

获取与此轮次关联的活动。

Activity activity

属性值

Activity

与此轮次关联的活动。

注解

此示例演示如何从活动获取用户已剪裁的话语：

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

adapter

获取创建此上下文对象的机器人适配器。

BotAdapter adapter

属性值

BotAdapter

创建此上下文对象的机器人适配器。

bufferedReplyActivities

在 时 context.activity.deliveryMode == 'expectReplies'要发送的活动列表。

bufferedReplyActivities: Partial<Activity>[]

属性值

Partial<Activity>[]

locale

获取存储在 turnState 中的区域设置。 设置存储在 turnState 中的区域设置。

string | undefined locale

属性值

string | undefined

存储在 turnState 中的区域设置。

responded

指示机器人是否已在此轮次回复用户。 设置当前轮次上下文上的响应标志。

boolean responded

属性值

boolean

如果为当前轮次发送了至少一个响应，则为 True;否则为 false。

注解

如果为当前轮次发送了至少一个响应，则为 true;否则为 false。 使用它来确定机器人是否需要在其他正常处理后运行回退逻辑。

跟踪活动不设置此标志。

例如：

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

turnState

获取在此上下文对象上注册的服务。

TurnContextStateCollection turnState

属性值

TurnContextStateCollection

在此上下文对象上注册的服务。

注解

中间件、其他组件和服务通常会使用它来缓存机器人在轮次期间可能多次请求的信息。 可以使用此缓存在机器人的组件之间传递信息。

例如：

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

提示

创建中间件或第三方组件时，请为缓存密钥使用唯一符号，以避免状态命名与机器人或其他中间件或组件发生冲突。

方法详细信息

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

使用现有对话引用中的传递信息汇报活动。

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

参数

activity

Partial<Activity>

要更新的活动。

reference

Partial<ConversationReference>

从中复制传递信息的对话引用。

isIncoming

boolean

可选。 true 将活动视为传入活动，其中机器人是接收者;否则为 false。 默认值为 false，活动会将机器人显示为发送方。

返回

Partial<Activity>

此活动，使用传递信息进行了更新。

注解

对传入活动调用 getConversationReference 方法以获取会话引用，然后使用该引用使用正确的传递信息更新传出活动。

deleteActivity(string | Partial<ConversationReference>)

异步删除以前发送的活动。

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

参数

idOrReference

string | Partial<ConversationReference>

要删除的活动的 ID 或对话引用。

返回

Promise<void>

表示异步操作的承诺。

注解

如果指定了 ID，则使用当前请求的会话引用来获取所需的其余信息。

例如：

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

另请参阅

• sendActivity
• updateActivity
• getReplyConversationReference

getConversationReference(Partial<Activity>)

从活动复制会话引用信息。

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

参数

activity

Partial<Activity>

要从中获取信息的活动。

返回

Partial<ConversationReference>

包含此活动的会话的会话引用。

注解

可以将会话引用保存为 JSON 对象，并在以后使用它主动向用户发送消息。

例如：

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

另请参阅

• BotAdapter.continueConversation

getMentions(Partial<Activity>)

获取活动中包含的所有提及实体。

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

参数

activity

Partial<Activity>

活动。

返回

Mention[]

活动中包含的所有提及实体。

注解

活动的 entities 属性包含与此活动相关的元数据对象的平面列表，并且可以包含 提及 实体。 此方法返回给定活动的所有此类实体。

例如：

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

getReplyConversationReference(Partial<Activity>, ResourceResponse)

从已发送活动的资源响应中复制会话引用信息。

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

参数

activity

Partial<Activity>

发送的活动。

reply

ResourceResponse

活动的资源响应，由 sendActivity 或 sendActivities 方法返回。

返回

Partial<ConversationReference>

可存储并稍后用于删除或更新活动的 ConversationReference。

注解

可以将会话引用保存为 JSON 对象，稍后再使用它来更新或删除消息。

例如：

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

另请参阅

• deleteActivity
• updateActivity

onDeleteActivity(DeleteActivityHandler)

为删除活动操作添加响应处理程序。

function onDeleteActivity(handler: DeleteActivityHandler): this

参数

handler

DeleteActivityHandler

要添加到上下文对象的处理程序。

返回

this

更新的上下文对象。

注解

此方法返回对轮次上下文对象的引用。

调用 deleteActivity 方法时，将按照在删除活动之前将其添加到上下文对象的顺序调用已注册的处理程序。

此示例演示如何侦听和记录活动删除。

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

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

onSendActivities(SendActivitiesHandler)

为发送活动操作添加响应处理程序。

function onSendActivities(handler: SendActivitiesHandler): this

参数

handler

SendActivitiesHandler

要添加到上下文对象的处理程序。

返回

this

更新的上下文对象。

注解

此方法返回对轮次上下文对象的引用。

调用 sendActivity 或 sendActivities 方法时，将按照在发送活动之前将其添加到上下文对象的顺序调用已注册的处理程序。

此示例演示如何侦听和记录传出 message 活动。

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)

为更新活动操作添加响应处理程序。

function onUpdateActivity(handler: UpdateActivityHandler): this

参数

handler

UpdateActivityHandler

要添加到上下文对象的处理程序。

返回

this

更新的上下文对象。

注解

此方法返回对轮次上下文对象的引用。

调用 updateActivity 方法时，将按照在更新活动之前将其添加到上下文对象的顺序调用已注册的处理程序。

此示例演示如何侦听和记录活动更新。

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

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

removeMentionText(Partial<Activity>, string)

从活动的文本中删除给定 ID 的提及，并返回更新的文本。 请谨慎使用;此函数更改活动的 text 属性。

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

参数

activity

Partial<Activity>

要从中删除的活动。

id

string

提及时要删除的用户或机器人的 ID。

返回

string

更新的活动的文本。

注解

某些频道（例如 Microsoft Teams）将提及添加到消息活动的文本。

使用此帮助程序方法修改活动的 text 属性。 它删除给定机器人或用户 ID 的所有提及项，然后返回更新的属性值。

例如，从包含文本“@echoBot Hi Bot”的活动中删除 提及 echoBot 时，活动文本将更新，并且该方法返回“Hi Bot”。

提及 实体 的格式依赖于通道。 但是，提及的 text 属性应包含用户显示在活动文本中的确切文本。

例如，无论通道使用“username”还是“@username”，此字符串都在活动的文本中，此方法将从文本中删除该字符串的所有匹配项。

例如：

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

另请参阅

• removeRecipientMention

removeRecipientMention(Partial<Activity>)

从活动的文本中删除活动 收件人 的提及，并返回更新的文本。 请谨慎使用;此函数更改活动的 text 属性。

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

参数

activity

Partial<Activity>

要从中删除的活动。

返回

string

更新的活动的文本。

注解

某些频道（例如 Microsoft Teams）将提及详细信息添加到消息活动的文本中。

使用此帮助程序方法修改活动的 text 属性。 它删除活动 收件人 的所有提及，然后返回更新的属性值。

例如：

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

另请参阅

• removeMentionText

sendActivities(Partial<Activity>[])

以异步方式将一组活动发送到传入活动的发送方。

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

参数

activities

Partial<Activity>[]

要发送的活动。

返回

Promise<ResourceResponse[]>

具有 ResourceResponse 的承诺。

注解

如果活动成功发送，则生成 ResourceResponse 对象的数组，其中包含接收通道分配给活动的 ID。

在发送它们之前，会根据入站入站活动的传递信息更新每个出站活动的传递信息。

例如：

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

另请参阅

• sendActivity
• updateActivity
• deleteActivity

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

以异步方式将活动发送到传入活动的发送方。

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

参数

activityOrText

string | Partial<Activity>

要发送的活动或文本。

speak

string

可选。 机器人在支持语音的通道上朗读的文本。

inputHint

string

可选。 指示在消息传递到客户端后，机器人是接受、期待还是忽略用户输入。 之一：“acceptingInput”、“ignoringInput”或“expectingInput”。 默认值为“acceptingInput”。

返回

Promise<ResourceResponse | undefined>

具有 ResourceResponse 的承诺。

注解

如果成功发送活动，则生成包含接收通道分配给活动的 ID 的 ResourceResponse 对象。

有关 对 activityOrText 参数的内容施加的限制，请参阅通道的文档。

若要控制机器人语音的各种特征（如语音、速率、音量、发音和音调），请在语音合成标记语言 (SSML) 格式中指定 语音 。

例如：

await context.sendActivity(`Hello World`);

另请参阅

• sendActivities
• updateActivity
• deleteActivity

sendTraceActivity(string, any, string, string)

以异步方式将活动发送到传入活动的发送方。

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

参数

name

string

要发送的活动或文本。

value

any

可选。 机器人在支持语音的通道上朗读的文本。

valueType

string

可选。 指示机器人是接受、期待还是忽略用户

label

string

可选。 指示机器人是接受、期待还是忽略用户

返回

Promise<ResourceResponse | undefined>

具有 ResourceResponse 的承诺。

注解

创建并发送跟踪活动。 仅当通道是模拟器时，才会发送跟踪活动。

例如：

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

另请参阅

• sendActivities

updateActivity(Partial<Activity>)

异步更新以前发送的活动。

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

参数

activity

Partial<Activity>

原始活动的替换。

返回

Promise<ResourceResponse | void>

具有 ResourceResponse 的承诺。

注解

替换活动的 ID 指示要替换的会话中的活动。

例如：

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

另请参阅

• sendActivity
• deleteActivity
• getReplyConversationReference