TurnContext class

Paquet:

botbuilder-core

Fournit le contexte d’un tour de bot.

Remarques

Le contexte fournit les informations nécessaires pour traiter une activité entrante. L’objet de contexte est créé par un BotAdapter et persiste pendant la longueur du tour.

Constructeurs

TurnContext(BotAdapter, Partial<Activity>)	Crée une instance de la classe TurnContext .
TurnContext(TurnContext)	Crée une instance de la classe TurnContext .

Propriétés

activity	Obtient l’activité associée à ce tour.
adapter	Obtient l’adaptateur de bot qui a créé cet objet de contexte.
bufferedReplyActivities	Liste des activités à envoyer quand context.activity.deliveryMode == 'expectReplies'.
locale	Obtient les paramètres régionaux stockés dans le turnState. Définit les paramètres régionaux stockés dans le turnState.
responded	Indique si le bot a répondu à l’utilisateur ce tour. Définit l’indicateur de réponse sur le contexte de tour actuel.
turnState	Obtient les services inscrits sur cet objet de contexte.

Méthodes

applyConversationReference(Partial<Activity>, Partial<ConversationReference>, boolean)	Mises à jour une activité avec les informations de remise à partir d’une référence de conversation existante.
deleteActivity(string | Partial<ConversationReference>)	Supprime de façon asynchrone une activité précédemment envoyée.
getConversationReference(Partial<Activity>)	Copie les informations de référence de conversation à partir d’une activité.
getMentions(Partial<Activity>)	Obtient toutes les entités à mention incluses dans une activité.
getReplyConversationReference(Partial<Activity>, ResourceResponse)	Copie les informations de référence de conversation à partir d’une réponse de ressource pour une activité envoyée.
onDeleteActivity(DeleteActivityHandler)	Ajoute un gestionnaire de réponses pour les opérations d’activité de suppression.
onSendActivities(SendActivitiesHandler)	Ajoute un gestionnaire de réponses pour les opérations d’activité d’envoi.
onUpdateActivity(UpdateActivityHandler)	Ajoute un gestionnaire de réponses pour les opérations d’activité de mise à jour.
removeMentionText(Partial<Activity>, string)	Supprime au niveau des mentions pour un ID donné du texte d’une activité et retourne le texte mis à jour. À utiliser avec précaution; cette fonction modifie la propriété de texte de l’activité.
removeRecipientMention(Partial<Activity>)	Supprime aux mentions du destinataire de l’activité du texte d’une activité et retourne le texte mis à jour. À utiliser avec précaution; cette fonction modifie la propriété de texte de l’activité.
sendActivities(Partial<Activity>[])	Envoie de manière asynchrone un ensemble d’activités à l’expéditeur de l’activité entrante.
sendActivity(string | Partial<Activity>, string, string)	Envoie de manière asynchrone une activité à l’expéditeur de l’activité entrante.
sendTraceActivity(string, any, string, string)	Envoie de manière asynchrone une activité à l’expéditeur de l’activité entrante.
updateActivity(Partial<Activity>)	Met à jour de manière asynchrone une activité précédemment envoyée.

Détails du constructeur

TurnContext(BotAdapter, Partial<Activity>)

Crée une instance de la classe TurnContext .

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

Paramètres

adapterOrContext

BotAdapter

Adaptateur créant le contexte.

request

Partial<Activity>

Activité entrante pour le tour.

TurnContext(TurnContext)

Crée une instance de la classe TurnContext .

new TurnContext(adapterOrContext: TurnContext)

Paramètres

adapterOrContext

TurnContext

Adaptateur créant le contexte.

Détails de la propriété

activity

Obtient l’activité associée à ce tour.

Activity activity

Valeur de propriété

Activity

Activité associée à ce tour.

Remarques

Cet exemple montre comment obtenir les utilisateurs supprimés l’énoncé de l’activité :

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

adapter

Obtient l’adaptateur de bot qui a créé cet objet de contexte.

BotAdapter adapter

Valeur de propriété

BotAdapter

Adaptateur de bot qui a créé cet objet de contexte.

bufferedReplyActivities

Liste des activités à envoyer quand context.activity.deliveryMode == 'expectReplies'.

bufferedReplyActivities: Partial<Activity>[]

Valeur de propriété

Partial<Activity>[]

locale

Obtient les paramètres régionaux stockés dans le turnState. Définit les paramètres régionaux stockés dans le turnState.

string | undefined locale

Valeur de propriété

string | undefined

Paramètres régionaux stockés dans le turnState.

responded

Indique si le bot a répondu à l’utilisateur ce tour. Définit l’indicateur de réponse sur le contexte de tour actuel.

boolean responded

Valeur de propriété

boolean

True si au moins une réponse a été envoyée pour le tour actuel ; sinon, false.

Remarques

true si au moins une réponse a été envoyée pour le tour actuel ; sinon, false. Utilisez cette option pour déterminer si votre bot doit exécuter la logique de secours après un autre traitement normal.

Les activités de suivi ne définissent pas cet indicateur.

Par exemple :

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

turnState

Obtient les services inscrits sur cet objet de contexte.

TurnContextStateCollection turnState

Valeur de propriété

TurnContextStateCollection

Services inscrits sur cet objet de contexte.

Remarques

Le middleware, d’autres composants et services l’utilisent généralement pour mettre en cache des informations qui peuvent être demandées par un bot plusieurs fois au cours d’un tour. Vous pouvez utiliser ce cache pour transmettre des informations entre les composants de votre bot.

Par exemple :

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

Conseil

Lors de la création d’un middleware ou d’un composant tiers, utilisez un symbole unique pour votre clé de cache afin d’éviter les collisions de noms d’état avec le bot ou d’autres middlewares ou composants.

Détails de la méthode

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

Mises à jour une activité avec les informations de remise à partir d’une référence de conversation existante.

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

Paramètres

activity

Partial<Activity>

Activité à mettre à jour.

reference

Partial<ConversationReference>

Référence de conversation à partir de laquelle copier les informations de remise.

isIncoming

boolean

facultatif. true pour traiter l’activité comme une activité entrante, où le bot est le destinataire ; sinon, false. La valeur par défaut est false, et l’activité affiche le bot en tant qu’expéditeur.

Retours

Partial<Activity>

Cette activité, mise à jour avec les informations de remise.

Remarques

Appelez la méthode getConversationReference sur une activité entrante pour obtenir une référence de conversation que vous pouvez ensuite utiliser pour mettre à jour une activité sortante avec les informations de remise correctes.

deleteActivity(string | Partial<ConversationReference>)

Supprime de façon asynchrone une activité précédemment envoyée.

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

Paramètres

idOrReference

string | Partial<ConversationReference>

ID ou référence de conversation pour l’activité à supprimer.

Retours

Promise<void>

Promesse représentant l’opération asynchrone.

Remarques

Si un ID est spécifié, la référence de conversation pour la requête actuelle est utilisée pour obtenir le reste des informations nécessaires.

Par exemple :

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

Voir aussi

• sendActivity
• updateActivity
• getReplyConversationReference

getConversationReference(Partial<Activity>)

Copie les informations de référence de conversation à partir d’une activité.

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

Paramètres

activity

Partial<Activity>

Activité à partir de laquelle obtenir les informations.

Retours

Partial<ConversationReference>

Référence de conversation pour la conversation qui contient cette activité.

Remarques

Vous pouvez enregistrer la référence de conversation en tant qu’objet JSON et l’utiliser ultérieurement pour envoyer un message proactif à l’utilisateur.

Par exemple :

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

Voir aussi

• BotAdapter.continueConversation

getMentions(Partial<Activity>)

Obtient toutes les entités à mention incluses dans une activité.

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

Paramètres

activity

Partial<Activity>

Activité.

Retours

Mention[]

Toutes les entités à mention incluses dans une activité.

Remarques

La propriété entities de l’activité contient une liste plate d’objets de métadonnées relatifs à cette activité et peut contenir des entités de mention . Cette méthode retourne toutes ces entités pour une activité donnée.

Par exemple :

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

getReplyConversationReference(Partial<Activity>, ResourceResponse)

Copie les informations de référence de conversation à partir d’une réponse de ressource pour une activité envoyée.

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

Paramètres

activity

Partial<Activity>

Activité envoyée.

reply

ResourceResponse

Réponse de ressource pour l’activité, retournée par la méthode sendActivity ou sendActivities .

Retours

Partial<ConversationReference>

ConversationReference qui peut être stockée et utilisée ultérieurement pour supprimer ou mettre à jour l’activité.

Remarques

Vous pouvez enregistrer la référence de conversation en tant qu’objet JSON et l’utiliser ultérieurement pour mettre à jour ou supprimer le message.

Par exemple :

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

Voir aussi

• deleteActivity
• updateActivity

onDeleteActivity(DeleteActivityHandler)

Ajoute un gestionnaire de réponses pour les opérations d’activité de suppression.

function onDeleteActivity(handler: DeleteActivityHandler): this

Paramètres

handler

DeleteActivityHandler

Gestionnaire à ajouter à l’objet de contexte.

Retours

this

Objet de contexte mis à jour.

Remarques

Cette méthode retourne une référence à l’objet de contexte de tour.

Lorsque la méthode deleteActivity est appelée, les gestionnaires inscrits sont appelés dans l’ordre dans lequel ils ont été ajoutés à l’objet de contexte avant la suppression de l’activité.

Cet exemple montre comment écouter et consigner les suppressions d’activité.

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

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

onSendActivities(SendActivitiesHandler)

Ajoute un gestionnaire de réponses pour les opérations d’activité d’envoi.

function onSendActivities(handler: SendActivitiesHandler): this

Paramètres

handler

SendActivitiesHandler

Gestionnaire à ajouter à l’objet de contexte.

Retours

this

Objet de contexte mis à jour.

Remarques

Cette méthode retourne une référence à l’objet de contexte de tour.

Lorsque la méthode sendActivity ou sendActivities est appelée, les gestionnaires inscrits sont appelés dans l’ordre dans lequel ils ont été ajoutés à l’objet de contexte avant l’envoi des activités.

Cet exemple montre comment écouter et journaliser les activités sortantes 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)

Ajoute un gestionnaire de réponses pour les opérations d’activité de mise à jour.

function onUpdateActivity(handler: UpdateActivityHandler): this

Paramètres

handler

UpdateActivityHandler

Gestionnaire à ajouter à l’objet de contexte.

Retours

this

Objet de contexte mis à jour.

Remarques

Cette méthode retourne une référence à l’objet de contexte de tour.

Lorsque la méthode updateActivity est appelée, les gestionnaires inscrits sont appelés dans l’ordre dans lequel ils ont été ajoutés à l’objet de contexte avant la mise à jour de l’activité.

Cet exemple montre comment écouter et journaliser les mises à jour de l’activité.

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

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

removeMentionText(Partial<Activity>, string)

Supprime au niveau des mentions pour un ID donné du texte d’une activité et retourne le texte mis à jour. À utiliser avec précaution; cette fonction modifie la propriété de texte de l’activité.

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

Paramètres

activity

Partial<Activity>

Activité à supprimer lors des mentions.

id

string

ID de l’utilisateur ou du bot à supprimer aux mentions pour.

Retours

string

Texte de l’activité mise à jour.

Remarques

Certains canaux, par exemple Microsoft Teams, ajoutent des mentions au texte d’une activité de message.

Utilisez cette méthode d’assistance pour modifier la propriété de texte de l’activité. Il supprime toutes les mentions pour le bot ou l’ID utilisateur donné, puis retourne la valeur de la propriété mise à jour.

Par exemple, lorsque vous supprimez les mentions d’echoBot d’une activité contenant le texte « @echoBot Hi Bot », le texte de l’activité est mis à jour et la méthode retourne « Hi Bot ».

Le format d’une entité de mention dépend du canal. Toutefois, la propriété de texte de la mention doit contenir le texte exact de l’utilisateur tel qu’il apparaît dans le texte d’activité.

Par exemple, si le canal utilise « username » ou « @username », cette chaîne se trouve dans le texte de l’activité, et cette méthode supprime toutes les occurrences de cette chaîne du texte.

Par exemple :

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

Voir aussi

• removeRecipientMention

removeRecipientMention(Partial<Activity>)

Supprime aux mentions du destinataire de l’activité du texte d’une activité et retourne le texte mis à jour. À utiliser avec précaution; cette fonction modifie la propriété de texte de l’activité.

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

Paramètres

activity

Partial<Activity>

Activité à supprimer lors des mentions.

Retours

string

Texte de l’activité mise à jour.

Remarques

Certains canaux, par exemple Microsoft Teams, ajoutent des détails à la mention au texte d’une activité de message.

Utilisez cette méthode d’assistance pour modifier la propriété de texte de l’activité. Il supprime tout aux mentions du destinataire de l’activité, puis retourne la valeur de la propriété mise à jour.

Par exemple :

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

Voir aussi

• removeMentionText

sendActivities(Partial<Activity>[])

Envoie de manière asynchrone un ensemble d’activités à l’expéditeur de l’activité entrante.

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

Paramètres

activities

Partial<Activity>[]

Activités à envoyer.

Retours

Promise<ResourceResponse[]>

Promesse avec un ResourceResponse.

Remarques

Si les activités sont correctement envoyées, il en résulte un tableau d’objets ResourceResponse contenant les ID que le canal de réception a attribués aux activités.

Avant d’être envoyées, les informations de remise de chaque activité sortante sont mises à jour en fonction des informations de remise de l’activité entrante.

Par exemple :

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

Voir aussi

• sendActivity
• updateActivity
• deleteActivity

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

Envoie de manière asynchrone une activité à l’expéditeur de l’activité entrante.

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

Paramètres

activityOrText

string | Partial<Activity>

Activité ou texte à envoyer.

speak

string

facultatif. Texte à prononcer par votre bot sur un canal à commande vocale.

inputHint

string

facultatif. Indique si votre bot accepte, attend ou ignore l’entrée utilisateur une fois le message remis au client. L’un des éléments suivants : « acceptInput », « ignoringInput » ou « expectingInput ». La valeur par défaut est « acceptInput ».

Retours

Promise<ResourceResponse | undefined>

Promesse avec un ResourceResponse.

Remarques

Si l’activité est correctement envoyée, il en résulte un objet ResourceResponse contenant l’ID que le canal de réception a attribué à l’activité.

Consultez la documentation du canal pour connaître les limites imposées au contenu du paramètre activityOrText .

Pour contrôler différentes caractéristiques du discours de votre bot, telles que la voix, la fréquence, le volume, la prononciation et la hauteur, spécifiez la parole au format SSML (Speech Synthesis Markup Language).

Par exemple :

await context.sendActivity(`Hello World`);

Voir aussi

• sendActivities
• updateActivity
• deleteActivity

sendTraceActivity(string, any, string, string)

Envoie de manière asynchrone une activité à l’expéditeur de l’activité entrante.

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

Paramètres

name

string

Activité ou texte à envoyer.

value

any

facultatif. Texte à prononcer par votre bot sur un canal à commande vocale.

valueType

string

facultatif. Indique si votre bot accepte, attend ou ignore l’utilisateur

label

string

facultatif. Indique si votre bot accepte, attend ou ignore l’utilisateur

Retours

Promise<ResourceResponse | undefined>

Promesse avec un ResourceResponse.

Remarques

Crée et envoie une activité Trace. Les activités de trace sont envoyées uniquement lorsque le canal est l’émulateur.

Par exemple :

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

Voir aussi

• sendActivities

updateActivity(Partial<Activity>)

Met à jour de manière asynchrone une activité précédemment envoyée.

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

Paramètres

activity

Partial<Activity>

Remplacement de l’activité d’origine.

Retours

Promise<ResourceResponse | void>

Promesse avec un ResourceResponse.

Remarques

L’ID de l’activité de remplacement indique l’activité dans la conversation à remplacer.

Par exemple :

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

Voir aussi

• sendActivity
• deleteActivity
• getReplyConversationReference