TurnContext class
Fournit un contexte pour un tour d’un bot.
Remarques
Le contexte fournit des informations nécessaires pour traiter une activité entrante. L’objet de contexte est créé par un BotAdapter et conserve la longueur du tour.
Constructeurs
Turn |
Crée une instance de la classe TurnContext. |
Turn |
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. |
buffered |
Liste des activités à envoyer quand |
locale | Obtient les paramètres régionaux stockés dans le turnState. Définit les paramètres régionaux stockés dans 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. |
turn |
Obtient les services inscrits sur cet objet de contexte. |
Méthodes
apply |
Met à jour une activité avec les informations de remise à partir d’une référence de conversation existante. |
delete |
Supprime de façon asynchrone une activité précédemment envoyée. |
get |
Copie les informations de référence de conversation d’une activité. |
get |
Obtient toutes les entités de mention incluses dans une activité. |
get |
Copie les informations de référence de conversation à partir d’une réponse de ressource pour une activité envoyée. |
on |
Ajoute un gestionnaire de réponses pour les opérations de suppression d’activité. |
on |
Ajoute un gestionnaire de réponses pour les opérations d’envoi d’activité. |
on |
Ajoute un gestionnaire de réponses pour les opérations d’activité de mise à jour. |
remove |
Supprime les mentions pour un ID donné du texte d’une activité et retourne le texte mis à jour. Utilisez avec précaution ; cette fonction modifie la propriété de texte de l’activité. |
remove |
Supprime les mentions pour le destinataire de l’activité du texte d’une activité et retourne le texte mis à jour. Utilisez avec précaution ; cette fonction modifie la propriété de texte de l’activité. |
send |
Envoie de façon asynchrone un ensemble d’activités à l’expéditeur de l’activité entrante. |
send |
Envoie de façon asynchrone une activité à l’expéditeur de l’activité entrante. |
send |
Envoie de façon asynchrone une activité à l’expéditeur de l’activité entrante. |
update |
Met à jour de façon 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 récupérer les énoncés supprimés des utilisateurs 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é
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 turnState.
string | undefined locale
Valeur de propriété
string | undefined
Paramètres régionaux stockés dans 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é
Services inscrits sur cet objet de contexte.
Remarques
Les intergiciels, autres composants et services utilisent généralement ces informations pour mettre en cache les 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);
Pourboire
Lors de la création d’intergiciels ou d’un composant tiers, utilisez un symbole unique pour votre clé de cache afin d’éviter les collisions d’affectation 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)
Met à 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
Optionnel.
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>
Informations de référence sur l’ID ou la 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 également
getConversationReference(Partial<Activity>)
Copie les informations de référence de conversation 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 également
getMentions(Partial<Activity>)
Obtient toutes les entités de 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
Les entités de l’activité propriété contiennent une liste plate d’objets de métadonnées relatifs à cette activité et peuvent contenir mention entités. 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 également
onDeleteActivity(DeleteActivityHandler)
Ajoute un gestionnaire de réponses pour les opérations de suppression d’activité.
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 enregistrer 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’envoi d’activité.
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 l'sendActivity ou méthode 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 de message
sortantes.
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 d’activité.
context.onUpdateActivity(async (ctx, activity, next) => {
// Replace activity
await next();
// Log update
logUpdate(activity);
});
removeMentionText(Partial<Activity>, string)
Supprime les mentions pour un ID donné du texte d’une activité et retourne le texte mis à jour. Utilisez 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 à partir de mentions.
- id
-
string
ID de l’utilisateur ou du bot à supprimer aux mentions.
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 propriété mise à jour.
Par exemple, lorsque vous supprimez des mentions de 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 mention entité dépend du canal. Toutefois, le texte de la mention propriété doit contenir le texte exact de l’utilisateur tel qu’il apparaît dans le texte de l’activité.
Par exemple, si le canal utilise « nom d’utilisateur» 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 également
removeRecipientMention(Partial<Activity>)
Supprime les mentions pour le destinataire de l’activité du texte d’une activité et retourne le texte mis à jour. Utilisez 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 à partir de mentions.
Retours
string
Texte de l’activité mise à jour.
Remarques
Certains canaux, par exemple Microsoft Teams, ajoutent des détails à mention au texte d’une activité de message.
Utilisez cette méthode d’assistance pour modifier la propriété de texte de l’activité. Elle supprime toutes les mentions du destinataire de l’activité, puis retourne la valeur de propriété mise à jour.
Par exemple:
const updatedText = TurnContext.removeRecipientMention(turnContext.request);
Voir également
sendActivities(Partial<Activity>[])
Envoie de façon 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 ResourceResponse.
Remarques
Si les activités sont correctement envoyées, un tableau de ResourceResponse objets contenant les ID attribués au canal de réception affecté 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 également
sendActivity(string | Partial<Activity>, string, string)
Envoie de façon 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
Optionnel. Texte à prononcer par votre bot sur un canal avec reconnaissance vocale.
- inputHint
-
string
Optionnel. Indique si votre bot accepte, attend ou ignore l’entrée de l’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 ResourceResponse.
Remarques
Si l’activité est correctement envoyée, génère un objet ResourceResponse contenant l’ID affecté au canal de réception affecté à 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 de la voix, de la vitesse, du volume, de la prononciation et du pitch de votre bot, spécifiez parler au format SSML (Speech Synthesis Markup Language).
Par exemple:
await context.sendActivity(`Hello World`);
Voir également
sendTraceActivity(string, any, string, string)
Envoie de façon 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
Optionnel. Texte à prononcer par votre bot sur un canal avec reconnaissance vocale.
- valueType
-
string
Optionnel. Indique si votre bot accepte, attend ou ignore l’utilisateur
- label
-
string
Optionnel. Indique si votre bot accepte, attend ou ignore l’utilisateur
Retours
Promise<ResourceResponse | undefined>
Promesse avec ResourceResponse.
Remarques
Crée et envoie une activité trace. Les activités de suivi sont envoyées uniquement lorsque le canal est l’émulateur.
Par exemple:
await context.sendTraceActivity(`The following exception was thrown ${msg}`);
Voir également
updateActivity(Partial<Activity>)
Met à jour de façon 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 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 également