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".

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

Например, используется ли канал "имя пользователя" или "@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.

Комментарии

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

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

Например:

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.

Комментарии

Создает и отправляет действие Trace. Действия трассировки отправляются только в том случае, если канал является эмулятором.

Например:

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