TurnContext class

Pacote:

botbuilder-core

Fornece contexto para uma vez de um bot.

Comentários

O contexto fornece informações necessárias para processar uma atividade de entrada. O objeto de contexto é criado por um BotAdapter e persiste para o comprimento do turno.

Construtores

TurnContext(BotAdapter, Partial<Activity>)	Cria uma nova instância da classe TurnContext .
TurnContext(TurnContext)	Cria uma nova instância da classe TurnContext .

Propriedades

activity	Obtém a atividade associada a essa vez.
adapter	Obtém o adaptador de bot que criou esse objeto de contexto.
bufferedReplyActivities	Lista de atividades a serem enviadas quando context.activity.deliveryMode == 'expectReplies'.
locale	Obtém a localidade armazenada no turnState. Define a localidade armazenada no turnState.
responded	Indica se o bot respondeu ao usuário nesta vez. Define o sinalizador de resposta no contexto de turno atual.
turnState	Obtém os serviços registrados neste objeto de contexto.

Métodos

applyConversationReference(Partial<Activity>, Partial<ConversationReference>, boolean)	Atualizações uma atividade com as informações de entrega de uma referência de conversa existente.
deleteActivity(string | Partial<ConversationReference>)	Exclui de forma assíncrona uma atividade enviada anteriormente.
getConversationReference(Partial<Activity>)	Copia informações de referência de conversa de uma atividade.
getMentions(Partial<Activity>)	Obtém todas as entidades de menção incluídas em uma atividade.
getReplyConversationReference(Partial<Activity>, ResourceResponse)	Copia informações de referência de conversa de uma resposta de recurso para uma atividade enviada.
onDeleteActivity(DeleteActivityHandler)	Adiciona um manipulador de resposta para operações de atividade de exclusão.
onSendActivities(SendActivitiesHandler)	Adiciona um manipulador de resposta para operações de atividade de envio.
onUpdateActivity(UpdateActivityHandler)	Adiciona um manipulador de resposta para operações de atividade de atualização.
removeMentionText(Partial<Activity>, string)	Remove em menções para uma determinada ID do texto de uma atividade e retorna o texto atualizado. Use com cuidado; essa função altera a propriedade de texto da atividade.
removeRecipientMention(Partial<Activity>)	Remove em menções para o destinatário da atividade do texto de uma atividade e retorna o texto atualizado. Use com cuidado; essa função altera a propriedade de texto da atividade.
sendActivities(Partial<Activity>[])	Envia de forma assíncrona um conjunto de atividades para o remetente da atividade de entrada.
sendActivity(string | Partial<Activity>, string, string)	Envia de forma assíncrona uma atividade para o remetente da atividade de entrada.
sendTraceActivity(string, any, string, string)	Envia de forma assíncrona uma atividade para o remetente da atividade de entrada.
updateActivity(Partial<Activity>)	Atualiza de forma assíncrona uma atividade enviada anteriormente.

Detalhes do construtor

TurnContext(BotAdapter, Partial<Activity>)

Cria uma nova instância da classe TurnContext .

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

Parâmetros

adapterOrContext

BotAdapter

O adaptador que cria o contexto.

request

Partial<Activity>

A atividade de entrada para o turno.

TurnContext(TurnContext)

Cria uma nova instância da classe TurnContext .

new TurnContext(adapterOrContext: TurnContext)

Parâmetros

adapterOrContext

TurnContext

O adaptador que cria o contexto.

Detalhes da propriedade

activity

Obtém a atividade associada a essa vez.

Activity activity

Valor da propriedade

Activity

A atividade associada a esse turno.

Comentários

Este exemplo mostra como obter o enunciado cortado dos usuários da atividade:

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

adapter

Obtém o adaptador de bot que criou esse objeto de contexto.

BotAdapter adapter

Valor da propriedade

BotAdapter

O adaptador de bot que criou esse objeto de contexto.

bufferedReplyActivities

Lista de atividades a serem enviadas quando context.activity.deliveryMode == 'expectReplies'.

bufferedReplyActivities: Partial<Activity>[]

Valor da propriedade

Partial<Activity>[]

locale

Obtém a localidade armazenada no turnState. Define a localidade armazenada no turnState.

string | undefined locale

Valor da propriedade

string | undefined

A localidade armazenada no turnState.

responded

Indica se o bot respondeu ao usuário nesta vez. Define o sinalizador de resposta no contexto de turno atual.

boolean responded

Valor da propriedade

boolean

True se pelo menos uma resposta foi enviada para a curva atual; caso contrário, false.

Comentários

true se pelo menos uma resposta foi enviada para o turno atual; caso contrário, false. Use isso para determinar se o bot precisa executar a lógica de fallback após outro processamento normal.

As atividades de rastreamento não definem esse sinalizador.

Por exemplo:

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

turnState

Obtém os serviços registrados neste objeto de contexto.

TurnContextStateCollection turnState

Valor da propriedade

TurnContextStateCollection

Os serviços registrados neste objeto de contexto.

Comentários

Middleware, outros componentes e serviços normalmente usarão isso para armazenar em cache as informações que podem ser solicitadas por um bot várias vezes durante um turno. Você pode usar esse cache para passar informações entre os componentes do bot.

Por exemplo:

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

Dica

Ao criar um middleware ou um componente de terceiros, use um símbolo exclusivo para sua chave de cache para evitar colisões de nomenclatura de estado com o bot ou outro middleware ou componentes.

Detalhes do método

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

Atualizações uma atividade com as informações de entrega de uma referência de conversa existente.

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

Parâmetros

activity

Partial<Activity>

A atividade a ser atualizada.

reference

Partial<ConversationReference>

A referência de conversa da qual copiar informações de entrega.

isIncoming

boolean

Opcional. true para tratar a atividade como uma atividade de entrada, em que o bot é o destinatário; caso contrário, false. O padrão é falsee a atividade mostrará o bot como o remetente.

Retornos

Partial<Activity>

Essa atividade, atualizada com as informações de entrega.

Comentários

Chame o método getConversationReference em uma atividade de entrada para obter uma referência de conversa que você pode usar para atualizar uma atividade de saída com as informações de entrega corretas.

deleteActivity(string | Partial<ConversationReference>)

Exclui de forma assíncrona uma atividade enviada anteriormente.

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

Parâmetros

idOrReference

string | Partial<ConversationReference>

ID ou referência de conversa para a atividade a ser excluída.

Retornos

Promise<void>

Uma promessa que representa a operação assíncrona.

Comentários

Se uma ID for especificada, a referência de conversa para a solicitação atual será usada para obter o restante das informações necessárias.

Por exemplo:

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

Consulte também

• Sendactivity
• updateActivity
• getReplyConversationReference

getConversationReference(Partial<Activity>)

Copia informações de referência de conversa de uma atividade.

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

Parâmetros

activity

Partial<Activity>

A atividade da qual obter as informações.

Retornos

Partial<ConversationReference>

Uma referência de conversa para a conversa que contém essa atividade.

Comentários

Você pode salvar a referência de conversa como um objeto JSON e usá-la posteriormente para enviar mensagens proativas ao usuário.

Por exemplo:

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

Consulte também

• BotAdapter.continueConversation

getMentions(Partial<Activity>)

Obtém todas as entidades de menção incluídas em uma atividade.

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

Parâmetros

activity

Partial<Activity>

A atividade.

Retornos

Mention[]

Todas as entidades de menção incluídas em uma atividade.

Comentários

A propriedade de entidades da atividade contém uma lista simples de objetos de metadados pertencentes a essa atividade e pode conter entidades de menção . Esse método retorna todas essas entidades para uma determinada atividade.

Por exemplo:

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

getReplyConversationReference(Partial<Activity>, ResourceResponse)

Copia informações de referência de conversa de uma resposta de recurso para uma atividade enviada.

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

Parâmetros

activity

Partial<Activity>

A atividade enviada.

reply

ResourceResponse

A resposta do recurso para a atividade, retornada pelo método sendActivity ou sendActivities .

Retornos

Partial<ConversationReference>

Uma ConversationReference que pode ser armazenada e usada posteriormente para excluir ou atualizar a atividade.

Comentários

Você pode salvar a referência de conversa como um objeto JSON e usá-la posteriormente para atualizar ou excluir a mensagem.

Por exemplo:

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

Consulte também

• deleteActivity
• updateActivity

onDeleteActivity(DeleteActivityHandler)

Adiciona um manipulador de resposta para operações de atividade de exclusão.

function onDeleteActivity(handler: DeleteActivityHandler): this

Parâmetros

handler

DeleteActivityHandler

O manipulador a ser adicionado ao objeto de contexto.

Retornos

this

O objeto de contexto atualizado.

Comentários

Esse método retorna uma referência ao objeto de contexto de turno.

Quando o método deleteActivity é chamado, os manipuladores registrados são chamados na ordem em que foram adicionados ao objeto de contexto antes que a atividade seja excluída.

Este exemplo mostra como escutar e registrar exclusões de atividades.

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

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

onSendActivities(SendActivitiesHandler)

Adiciona um manipulador de resposta para operações de atividade de envio.

function onSendActivities(handler: SendActivitiesHandler): this

Parâmetros

handler

SendActivitiesHandler

O manipulador a ser adicionado ao objeto de contexto.

Retornos

this

O objeto de contexto atualizado.

Comentários

Esse método retorna uma referência ao objeto de contexto turn.

Quando o método sendActivity ou sendActivities é chamado, os manipuladores registrados são chamados na ordem em que foram adicionados ao objeto de contexto antes que as atividades sejam enviadas.

Este exemplo mostra como escutar e registrar atividades de saída 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)

Adiciona um manipulador de resposta para operações de atividade de atualização.

function onUpdateActivity(handler: UpdateActivityHandler): this

Parâmetros

handler

UpdateActivityHandler

O manipulador a ser adicionado ao objeto de contexto.

Retornos

this

O objeto de contexto atualizado.

Comentários

Esse método retorna uma referência ao objeto de contexto turn.

Quando o método updateActivity é chamado, os manipuladores registrados são chamados na ordem em que foram adicionados ao objeto de contexto antes que a atividade seja atualizada.

Este exemplo mostra como escutar e registrar atualizações de atividades.

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

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

removeMentionText(Partial<Activity>, string)

Remove em menções para uma determinada ID do texto de uma atividade e retorna o texto atualizado. Use com cuidado; essa função altera a propriedade de texto da atividade.

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

Parâmetros

activity

Partial<Activity>

A atividade a ser removida em menções de.

id

string

A ID do usuário ou bot para o qual remover em menções.

Retornos

string

O texto da atividade atualizada.

Comentários

Alguns canais, por exemplo, Microsoft Teams, adicionam menções ao texto de uma atividade de mensagem.

Use esse método auxiliar para modificar a propriedade de texto da atividade. Ele remove todas as menções para o bot ou iD de usuário fornecido e, em seguida, retorna o valor da propriedade atualizada.

Por exemplo, quando você remove menções de echoBot de uma atividade que contém o texto "@echoBot Hi Bot", o texto da atividade é atualizado e o método retorna "Oi Bot".

O formato de uma entidade de menção depende do canal. No entanto, a propriedade de texto da menção deve conter o texto exato para o usuário como ele aparece no texto da atividade.

Por exemplo, se o canal usa "nome de usuário" ou "@username", essa cadeia de caracteres está no texto da atividade e esse método removerá todas as ocorrências dessa cadeia de caracteres do texto.

Por exemplo:

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

Consulte também

• removeRecipientMention

removeRecipientMention(Partial<Activity>)

Remove em menções para o destinatário da atividade do texto de uma atividade e retorna o texto atualizado. Use com cuidado; essa função altera a propriedade de texto da atividade.

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

Parâmetros

activity

Partial<Activity>

A atividade a ser removida em menções de.

Retornos

string

O texto da atividade atualizada.

Comentários

Alguns canais, por exemplo, Microsoft Teams, adicionam detalhes de menção ao texto de uma atividade de mensagem.

Use esse método auxiliar para modificar a propriedade de texto da atividade. Ele remove todas as menções do destinatário da atividade e retorna o valor da propriedade atualizada.

Por exemplo:

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

Consulte também

• removeMentionText

sendActivities(Partial<Activity>[])

Envia de forma assíncrona um conjunto de atividades para o remetente da atividade de entrada.

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

Parâmetros

activities

Partial<Activity>[]

As atividades a serem enviadas.

Retornos

Promise<ResourceResponse[]>

Uma promessa com um ResourceResponse.

Comentários

Se as atividades forem enviadas com êxito, resultará em uma matriz de objetos ResourceResponse contendo as IDs que o canal de recebimento atribuiu às atividades.

Antes de serem enviadas, as informações de entrega de cada atividade de saída são atualizadas com base nas informações de entrega da atividade de entrada.

Por exemplo:

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

Consulte também

• Sendactivity
• updateActivity
• deleteActivity

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

Envia de forma assíncrona uma atividade para o remetente da atividade de entrada.

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

Parâmetros

activityOrText

string | Partial<Activity>

A atividade ou o texto a ser enviado.

speak

string

Opcional. O texto a ser falado pelo bot em um canal habilitado para fala.

inputHint

string

Opcional. Indica se o bot está aceitando, esperando ou ignorando a entrada do usuário depois que a mensagem é entregue ao cliente. Um deles: 'acceptingInput', 'ignoringInput' ou 'expectingInput'. O padrão é 'acceptingInput'.

Retornos

Promise<ResourceResponse | undefined>

Uma promessa com um ResourceResponse.

Comentários

Se a atividade for enviada com êxito, resultará em um objeto ResourceResponse contendo a ID que o canal de recebimento atribuiu à atividade.

Consulte a documentação do canal para obter limites impostos ao conteúdo do parâmetro activityOrText .

Para controlar várias características da fala do bot, como voz, taxa, volume, pronúncia e tom, especifique falar no formato SSML (Speech Synthesis Markup Language).

Por exemplo:

await context.sendActivity(`Hello World`);

Consulte também

• sendActivities
• updateActivity
• deleteActivity

sendTraceActivity(string, any, string, string)

Envia de forma assíncrona uma atividade para o remetente da atividade de entrada.

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

Parâmetros

name

string

A atividade ou o texto a ser enviado.

value

any

Opcional. O texto a ser falado pelo bot em um canal habilitado para fala.

valueType

string

Opcional. Indica se o bot está aceitando, esperando ou ignorando o usuário

label

string

Opcional. Indica se o bot está aceitando, esperando ou ignorando o usuário

Retornos

Promise<ResourceResponse | undefined>

Uma promessa com um ResourceResponse.

Comentários

Cria e envia uma atividade trace. As atividades de rastreamento só são enviadas quando o canal é o emulador.

Por exemplo:

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

Consulte também

• sendActivities

updateActivity(Partial<Activity>)

Atualiza de forma assíncrona uma atividade enviada anteriormente.

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

Parâmetros

activity

Partial<Activity>

A substituição da atividade original.

Retornos

Promise<ResourceResponse | void>

Uma promessa com um ResourceResponse.

Comentários

A ID da atividade de substituição indica a atividade na conversa a ser substituída.

Por exemplo:

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

Consulte também

• Sendactivity
• deleteActivity
• getReplyConversationReference