TurnContext class

Paquete:

botbuilder-core

Proporciona contexto para un turno de un bot.

Comentarios

El contexto proporciona información necesaria para procesar una actividad entrante. BotAdapter crea el objeto de contexto y persiste durante la longitud del turno.

Constructores

TurnContext(BotAdapter, Partial<Activity>)	Crea una nueva instancia de la clase TurnContext .
TurnContext(TurnContext)	Crea una nueva instancia de la clase TurnContext .

Propiedades

activity	Obtiene la actividad asociada a este turno.
adapter	Obtiene el adaptador de bot que creó este objeto de contexto.
bufferedReplyActivities	Lista de actividades que se van a enviar cuando context.activity.deliveryMode == 'expectReplies'.
locale	Obtiene la configuración regional almacenada en turnState. Establece la configuración regional almacenada en turnState.
responded	Indica si el bot ha respondido al usuario este turno. Establece la marca de respuesta en el contexto de turno actual.
turnState	Obtiene los servicios registrados en este objeto de contexto.

Métodos

applyConversationReference(Partial<Activity>, Partial<ConversationReference>, boolean)	Novedades una actividad con la información de entrega de una referencia de conversación existente.
deleteActivity(string | Partial<ConversationReference>)	Elimina de forma asincrónica una actividad enviada previamente.
getConversationReference(Partial<Activity>)	Copia la información de referencia de conversación de una actividad.
getMentions(Partial<Activity>)	Obtiene todas las entidades de mención incluidas en una actividad.
getReplyConversationReference(Partial<Activity>, ResourceResponse)	Copia la información de referencia de conversación de una respuesta de recursos para una actividad enviada.
onDeleteActivity(DeleteActivityHandler)	Agrega un controlador de respuesta para las operaciones de actividad de eliminación.
onSendActivities(SendActivitiesHandler)	Agrega un controlador de respuesta para las operaciones de actividad de envío.
onUpdateActivity(UpdateActivityHandler)	Agrega un controlador de respuesta para las operaciones de actividad de actualización.
removeMentionText(Partial<Activity>, string)	Quita en menciones para un identificador determinado del texto de una actividad y devuelve el texto actualizado. Use con precaución; esta función modifica la propiedad de texto de la actividad.
removeRecipientMention(Partial<Activity>)	Quita en menciones para el destinatario de la actividad del texto de una actividad y devuelve el texto actualizado. Use con precaución; esta función modifica la propiedad de texto de la actividad.
sendActivities(Partial<Activity>[])	Envía de forma asincrónica un conjunto de actividades al remitente de la actividad entrante.
sendActivity(string | Partial<Activity>, string, string)	Envía de forma asincrónica una actividad al remitente de la actividad entrante.
sendTraceActivity(string, any, string, string)	Envía de forma asincrónica una actividad al remitente de la actividad entrante.
updateActivity(Partial<Activity>)	Actualiza de forma asincrónica una actividad enviada previamente.

Detalles del constructor

TurnContext(BotAdapter, Partial<Activity>)

Crea una nueva instancia de la clase TurnContext .

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

Parámetros

adapterOrContext

BotAdapter

Adaptador que crea el contexto.

request

Partial<Activity>

Actividad entrante del turno.

TurnContext(TurnContext)

Crea una nueva instancia de la clase TurnContext .

new TurnContext(adapterOrContext: TurnContext)

Parámetros

adapterOrContext

TurnContext

Adaptador que crea el contexto.

Detalles de las propiedades

activity

Obtiene la actividad asociada a este turno.

Activity activity

Valor de propiedad

Activity

Actividad asociada a este turno.

Comentarios

En este ejemplo se muestra cómo obtener la expresión recortada de los usuarios de la actividad:

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

adapter

Obtiene el adaptador de bot que creó este objeto de contexto.

BotAdapter adapter

Valor de propiedad

BotAdapter

Adaptador de bot que creó este objeto de contexto.

bufferedReplyActivities

Lista de actividades que se van a enviar cuando context.activity.deliveryMode == 'expectReplies'.

bufferedReplyActivities: Partial<Activity>[]

Valor de propiedad

Partial<Activity>[]

locale

Obtiene la configuración regional almacenada en turnState. Establece la configuración regional almacenada en turnState.

string | undefined locale

Valor de propiedad

string | undefined

Configuración regional almacenada en turnState.

responded

Indica si el bot ha respondido al usuario este turno. Establece la marca de respuesta en el contexto de turno actual.

boolean responded

Valor de propiedad

boolean

True si se envió al menos una respuesta para el turno actual; de lo contrario, false.

Comentarios

true si se envió al menos una respuesta para el turno actual; de lo contrario, false. Úselo para determinar si el bot necesita ejecutar la lógica de reserva después de otro procesamiento normal.

Las actividades de seguimiento no establecen esta marca.

Por ejemplo:

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

turnState

Obtiene los servicios registrados en este objeto de contexto.

TurnContextStateCollection turnState

Valor de propiedad

TurnContextStateCollection

Los servicios registrados en este objeto de contexto.

Comentarios

El middleware, otros componentes y servicios normalmente lo usarán para almacenar en caché la información que un bot podría solicitar varias veces durante un turno. Puede usar esta memoria caché para pasar información entre los componentes del bot.

Por ejemplo:

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

Sugerencia

Al crear middleware o un componente de terceros, use un símbolo único para la clave de caché para evitar colisiones de nomenclatura de estado con el bot u otros middleware o componentes.

Detalles del método

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

Novedades una actividad con la información de entrega de una referencia de conversación existente.

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

Parámetros

activity

Partial<Activity>

Actividad que se va a actualizar.

reference

Partial<ConversationReference>

Referencia de conversación desde la que se copia la información de entrega.

isIncoming

boolean

Opcional. true para tratar la actividad como una actividad entrante, donde el bot es el destinatario; de lo contrario, false. El valor predeterminado es falsey la actividad mostrará el bot como remitente.

Devoluciones

Partial<Activity>

Esta actividad, actualizada con la información de entrega.

Comentarios

Llame al método getConversationReference en una actividad entrante para obtener una referencia de conversación que puede usar para actualizar una actividad saliente con la información de entrega correcta.

deleteActivity(string | Partial<ConversationReference>)

Elimina de forma asincrónica una actividad enviada previamente.

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

Parámetros

idOrReference

string | Partial<ConversationReference>

Referencia de identificador o conversación para la actividad que se va a eliminar.

Devoluciones

Promise<void>

Promesa que representa la operación asincrónica.

Comentarios

Si se especifica un identificador, la referencia de conversación para la solicitud actual se usa para obtener el resto de la información necesaria.

por ejemplo:

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

Consulte también

• sendActivity
• updateActivity
• getReplyConversationReference

getConversationReference(Partial<Activity>)

Copia la información de referencia de conversación de una actividad.

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

Parámetros

activity

Partial<Activity>

Actividad de la que se va a obtener la información.

Devoluciones

Partial<ConversationReference>

Referencia de conversación para la conversación que contiene esta actividad.

Comentarios

Puede guardar la referencia de conversación como un objeto JSON y usarla más adelante para enviar mensajes de forma proactiva al usuario.

por ejemplo:

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

Consulte también

• BotAdapter.continueConversation

getMentions(Partial<Activity>)

Obtiene todas las entidades de mención incluidas en una actividad.

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

Parámetros

activity

Partial<Activity>

La actividad.

Devoluciones

Mention[]

Todas las entidades de mención incluidas en una actividad.

Comentarios

La propiedad entities de la actividad contiene una lista plana de objetos de metadatos pertenecientes a esta actividad y puede contener entidades de mención . Este método devuelve todas estas entidades para una actividad determinada.

por ejemplo:

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

getReplyConversationReference(Partial<Activity>, ResourceResponse)

Copia la información de referencia de conversación de una respuesta de recursos para una actividad enviada.

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

Parámetros

activity

Partial<Activity>

Actividad enviada.

reply

ResourceResponse

Respuesta de recursos para la actividad, devuelta por el método sendActivity o sendActivities .

Devoluciones

Partial<ConversationReference>

ConversationReference que se puede almacenar y usar más adelante para eliminar o actualizar la actividad.

Comentarios

Puede guardar la referencia de conversación como un objeto JSON y usarla más adelante para actualizar o eliminar el mensaje.

por ejemplo:

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

Consulte también

• deleteActivity
• updateActivity

onDeleteActivity(DeleteActivityHandler)

Agrega un controlador de respuesta para las operaciones de actividad de eliminación.

function onDeleteActivity(handler: DeleteActivityHandler): this

Parámetros

handler

DeleteActivityHandler

Controlador que se va a agregar al objeto de contexto.

Devoluciones

this

Objeto de contexto actualizado.

Comentarios

Este método devuelve una referencia al objeto de contexto de turno.

Cuando se llama al método deleteActivity , se llama a los controladores registrados en el orden en que se agregaron al objeto de contexto antes de eliminar la actividad.

En este ejemplo se muestra cómo escuchar y registrar eliminaciones de actividad.

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

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

onSendActivities(SendActivitiesHandler)

Agrega un controlador de respuesta para las operaciones de actividad de envío.

function onSendActivities(handler: SendActivitiesHandler): this

Parámetros

handler

SendActivitiesHandler

Controlador que se va a agregar al objeto de contexto.

Devoluciones

this

Objeto de contexto actualizado.

Comentarios

Este método devuelve una referencia al objeto de contexto de turno.

Cuando se llama al método sendActivity o sendActivities , se llama a los controladores registrados en el orden en que se agregaron al objeto de contexto antes de enviar las actividades.

En este ejemplo se muestra cómo escuchar y registrar actividades salientes 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)

Agrega un controlador de respuesta para las operaciones de actividad de actualización.

function onUpdateActivity(handler: UpdateActivityHandler): this

Parámetros

handler

UpdateActivityHandler

Controlador que se va a agregar al objeto de contexto.

Devoluciones

this

Objeto de contexto actualizado.

Comentarios

Este método devuelve una referencia al objeto de contexto de turno.

Cuando se llama al método updateActivity , se llama a los controladores registrados en el orden en que se agregaron al objeto de contexto antes de actualizar la actividad.

En este ejemplo se muestra cómo escuchar y registrar actualizaciones de actividad.

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

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

removeMentionText(Partial<Activity>, string)

Quita en menciones para un identificador determinado del texto de una actividad y devuelve el texto actualizado. Use con precaución; esta función modifica la propiedad de texto de la actividad.

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

Parámetros

activity

Partial<Activity>

Actividad de la que se va a quitar en menciones.

id

string

Identificador del usuario o bot para el que se va a quitar en menciones.

Devoluciones

string

Texto de la actividad actualizada.

Comentarios

Algunos canales, por ejemplo, Microsoft Teams, agregan menciones al texto de una actividad de mensaje.

Use este método auxiliar para modificar la propiedad de texto de la actividad. Quita todas las menciones del bot o el identificador de usuario especificados y, a continuación, devuelve el valor de propiedad actualizado.

Por ejemplo, cuando se quitan menciones de echoBot de una actividad que contiene el texto "@echoBot Hi Bot", se actualiza el texto de la actividad y el método devuelve "Hi Bot".

El formato de una entidad de mención depende del canal. Sin embargo, la propiedad text de la mención debe contener el texto exacto para el usuario tal y como aparece en el texto de la actividad.

Por ejemplo, si el canal usa "username" o "@username", esta cadena se encuentra en el texto de la actividad y este método quitará todas las apariciones de esa cadena del texto.

por ejemplo:

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

Consulte también

• removeRecipientMention

removeRecipientMention(Partial<Activity>)

Quita en menciones para el destinatario de la actividad del texto de una actividad y devuelve el texto actualizado. Use con precaución; esta función modifica la propiedad de texto de la actividad.

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

Parámetros

activity

Partial<Activity>

Actividad de la que se va a quitar en menciones.

Devoluciones

string

Texto de la actividad actualizada.

Comentarios

Algunos canales, por ejemplo, Microsoft Teams, agregan detalles de mención al texto de una actividad de mensaje.

Use este método auxiliar para modificar la propiedad de texto de la actividad. Quita todas las menciones del destinatario de la actividad y, a continuación, devuelve el valor de propiedad actualizado.

por ejemplo:

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

Consulte también

• removeMentionText

sendActivities(Partial<Activity>[])

Envía de forma asincrónica un conjunto de actividades al remitente de la actividad entrante.

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

Parámetros

activities

Partial<Activity>[]

Las actividades que se van a enviar.

Devoluciones

Promise<ResourceResponse[]>

Una promesa con resourceResponse.

Comentarios

Si las actividades se envían correctamente, da como resultado una matriz de objetos ResourceResponse que contienen los identificadores asignados al canal receptor asignado a las actividades.

Antes de enviarlos, la información de entrega de cada actividad de salida se actualiza en función de la información de entrega de la actividad entrante entrante.

por ejemplo:

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

Consulte también

• sendActivity
• updateActivity
• deleteActivity

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

Envía de forma asincrónica una actividad al remitente de la actividad entrante.

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

Parámetros

activityOrText

string | Partial<Activity>

Actividad o texto que se va a enviar.

speak

string

Opcional. Texto que va a hablar el bot en un canal habilitado para voz.

inputHint

string

Opcional. Indica si el bot acepta, espera o omite la entrada del usuario después de que el mensaje se entregue al cliente. Uno de: "acceptingInput", "ignoreingInput" o "expectingInput". El valor predeterminado es "acceptingInput".

Devoluciones

Promise<ResourceResponse | undefined>

Una promesa con resourceResponse.

Comentarios

Si la actividad se envía correctamente, da como resultado un objeto ResourceResponse que contiene el identificador asignado al canal receptor asignado a la actividad.

Consulte la documentación del canal para conocer los límites impuestos sobre el contenido del parámetro activityOrText .

Para controlar varias características de la voz del bot, como voz, velocidad, volumen, pronunciación y tono, especifique hablar en formato lenguaje de marcado de síntesis de voz (SSML).

por ejemplo:

await context.sendActivity(`Hello World`);

Consulte también

• sendActivities
• updateActivity
• deleteActivity

sendTraceActivity(string, any, string, string)

Envía de forma asincrónica una actividad al remitente de la actividad entrante.

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

Parámetros

name

string

Actividad o texto que se va a enviar.

value

any

Opcional. Texto que va a hablar el bot en un canal habilitado para voz.

valueType

string

Opcional. Indica si el bot acepta, espera o omite el usuario.

label

string

Opcional. Indica si el bot acepta, espera o omite el usuario.

Devoluciones

Promise<ResourceResponse | undefined>

Una promesa con resourceResponse.

Comentarios

Crea y envía una actividad trace. Las actividades de seguimiento solo se envían cuando el canal es el emulador.

por ejemplo:

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

Consulte también

• sendActivities

updateActivity(Partial<Activity>)

Actualiza de forma asincrónica una actividad enviada previamente.

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

Parámetros

activity

Partial<Activity>

Reemplazo de la actividad original.

Devoluciones

Promise<ResourceResponse | void>

Una promesa con resourceResponse.

Comentarios

El identificador de la actividad de reemplazo indica la actividad de la conversación que se va a reemplazar.

por ejemplo:

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

Consulte también

• sendActivity
• deleteActivity
• getReplyConversationReference