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)	Удаляет упоминания для заданного идентификатора из текста действия и возвращает обновленный текст. Использовать с осторожностью; Эта функция изменяет текстовое свойство действия.
removeRecipientMention(Partial<Activity>)	Удаляет упоминания получателя действия из текста действия и возвращает обновленный текст. Использовать с осторожностью; Эта функция изменяет текстовое свойство действия.
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>

Идентификатор или ссылка на беседу для удаляемого действия.

Возвращаемое значение

Promise<void>

Обещание, представляющее асинхронную операцию.

Комментарии

Если указан идентификатор, ссылка на беседу для текущего запроса используется для получения остальных необходимых сведений.

Например:

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[]

Все упоминаемые сущности, включенные в действие.

Комментарии

Свойство сущностей действия содержит плоский список объектов метаданных, относящихся к этому действию, и может содержать сущности упоминания . Этот метод возвращает все такие сущности для заданного действия.

Например:

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)

Удаляет упоминания для заданного идентификатора из текста действия и возвращает обновленный текст. Использовать с осторожностью; Эта функция изменяет текстовое свойство действия.

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

Параметры

activity

Partial<Activity>

Действие, удаляемого при упоминаниях.

id

string

Идентификатор пользователя или бота для удаления при упоминании.

Возвращаемое значение

string

Текст обновленного действия.

Комментарии

Некоторые каналы, например Microsoft Teams, добавляют упоминания в текст действия сообщения.

Используйте этот вспомогательный метод для изменения текстового свойства действия. Он удаляет все упоминания для заданного бота или идентификатора пользователя, а затем возвращает обновленное значение свойства.

Например, при удалении упоминаний echoBot из действия, содержащего текст "@echoBot Hi Bot", текст действия обновляется, а метод возвращает "Hi Bot".

Формат сущности упоминания зависит от канала. Однако свойство text упоминания должно содержать точный текст для пользователя, который отображается в тексте действия.

Например, независимо от того, использует ли канал "имя пользователя" или "@username", эта строка находится в тексте действия, и этот метод удалит все вхождения этой строки из текста.

Например:

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

См. также:

• removeRecipientMention

removeRecipientMention(Partial<Activity>)

Удаляет упоминания получателя действия из текста действия и возвращает обновленный текст. Использовать с осторожностью; Эта функция изменяет текстовое свойство действия.

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

Параметры

activity

Partial<Activity>

Действие, удаляемого при упоминаниях.

Возвращаемое значение

string

Текст обновленного действия.

Комментарии

Некоторые каналы, например Microsoft Teams, добавляют сведения об упоминании в текст действия сообщения.

Используйте этот вспомогательный метод для изменения текстового свойства действия. Он удаляет все при упоминаниях получателя действия, а затем возвращает обновленное значение свойства.

Например:

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

См. также:

• removeMentionText

sendActivities(Partial<Activity>[])

Асинхронно отправляет набор действий отправителю входящего действия.

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

Параметры

activities

Partial<Activity>[]

Отправляемые действия.

Возвращаемое значение

Promise<ResourceResponse[]>

Обещание с ResourceResponse.

Комментарии

Если действия успешно отправлены, получается массив объектов ResourceResponse , содержащий идентификаторы, назначенные получающим каналом действиям.

Перед отправкой сведения о доставке каждого исходящего действия обновляются на основе сведений о доставке входящего действия.

Например:

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.

Комментарии

Если действие успешно отправлено, в результате получается объект 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.

Комментарии

Идентификатор действия замены указывает действие в беседе, которое нужно заменить.

Например:

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

См. также:

• sendActivity
• deleteActivity
• getReplyConversationReference