Utiliser des modules de tâches à partir de bots

Les modules de tâche peuvent être appelés à partir de bots Microsoft Teams à l’aide de boutons sur les cartes adaptatives et les cartes Bot Framework qui sont hero, thumbnail et Office 365 Connector. Les modules de tâche sont souvent une meilleure expérience utilisateur que plusieurs étapes de conversation. Suivez l’état du bot et autorisez l’utilisateur à interrompre ou annuler la séquence.

Il existe deux façons d’invoquer des modules de tâche :

  • Un nouveau type de message d’appel : l’utilisation de l’action de carte pour les cartes Bot Framework ou de l’action de carte pour les cartes adaptatives, avec un module de tâche, une URL ou une carte adaptative, est récupérée dynamiquement à partir de votre task/fetch invoke Action.Submit task/fetch bot.
  • URL de lien profond : à l’aide de la syntaxe de lien profond pour les modulesde tâche, vous pouvez utiliser l’action de carte pour les cartes Bot Framework ou l’action de carte pour les cartes adaptatives, openUrl Action.OpenUrl respectivement. Avec les URL de lien profond, l’URL du module de tâche ou le corps de la carte adaptative est déjà connu pour éviter un aller-retour serveur par rapport à task/fetch .

Important

Chacun url fallbackUrl d’eux doit implémenter le protocole de chiffrement HTTPS.

La section suivante fournit des détails sur l’appel d’un module de tâche à task/fetch l’aide.

Appeler un module de tâche à l’aide de la tâche/extraction

Lorsque value l’objet de l’action de carte ou est initialisé et lorsqu’un utilisateur sélectionne le bouton, un message est invoke Action.Submit envoyé au invoke bot. Dans la réponse HTTP au message, il existe un objet TaskInfo incorporé dans un objet wrapper, que Teams utilise pour afficher invoke le module de tâche.

demande ou réponse de tâche/extraction

Les étapes suivantes fournissent le module d’appel de tâche à l’aide de la tâche/extraction :

  1. Cette image montre une carte Hero Bot Framework avec une action acheter invoke une carte. La valeur de type la propriété est et le reste de task/fetch l’objet value peut être de votre choix.

  2. Le bot reçoit le invoke message HTTP POST.

  3. Le bot crée un objet de réponse et le renvoie dans le corps de la réponse POST avec un code de réponse HTTP 200. Pour plus d’informations sur le schéma des réponses, voir la discussion sur la tâche/envoyer. Le code suivant fournit un exemple de corps de la réponse HTTP qui contient un objet TaskInfo incorporé dans un objet wrapper :

    {
      "task": {
        "type": "continue",
        "value": {
          "title": "Task module title",
          "height": 500,
          "width": "medium",
          "url": "https://contoso.com/msteams/taskmodules/newcustomer",
          "fallbackUrl": "https://contoso.com/msteams/taskmodules/newcustomer"
        }
      }
    }
    

    task/fetchL’événement et sa réponse pour les bots sont similaires à la fonction dans le microsoftTeams.tasks.startTask() SDK client.

  4. Microsoft Teams affiche le module de tâche.

La section suivante fournit des détails sur l’envoi du résultat d’un module de tâche.

Envoyer le résultat d’un module de tâche

Lorsque l’utilisateur a terminé le module de tâche, la soumission du résultat au bot est similaire à la façon dont il fonctionne avec les onglets. Pour plus d’informations, voir l’exemple d’envoi du résultat d’un module de tâche. Il existe quelques différences comme suit :

  • HTML ou JavaScript c’est-à-dire : une fois que vous avez validé ce que l’utilisateur a entré, vous appelez la fonction SDK appelée ci-après comme à des fins de TaskInfo.url microsoftTeams.tasks.submitTask() submitTask() lisibilité. Vous pouvez appeler sans paramètre si vous souhaitez Teams le module de tâche, mais vous devez transmettre un objet ou une submitTask() chaîne à votre submitHandler . Passez-le en tant que premier paramètre, result . Teams appelle , submitHandler err est null et est result l’objet ou la chaîne que vous avez transmis à submitTask() . Si vous submitTask() appelez avec result un paramètre, vous devez transmettre un ou appId plusieurs tableaux de appId chaînes. Cela permet Teams vérifier que l’application qui envoie le résultat est la même que celle qui a appelé le module de tâche. Votre bot reçoit un task/submit message incluant result . Pour plus d’informations, voir la charge utile des task/fetch task/submit messages.
  • Carte adaptative : le corps de la carte adaptative tel qu’il est rempli par l’utilisateur est envoyé au bot par le biais d’un message lorsque l’utilisateur TaskInfo.card task/submit sélectionne un Action.Submit bouton.

La section suivante fournit des détails sur la flexibilité de task/submit .

Flexibilité de la tâche/de l’soumission

Lorsque l’utilisateur termine avec un module de tâche appelé à partir d’un bot, le bot reçoit toujours un task/submit invoke message. Plusieurs options s’offrent à vous pour répondre task/submit au message comme suit :

Réponse du corps HTTP Scénario
Aucun ne ignore le task/submit message La réponse la plus simple n’est pas du tout une réponse. Votre bot n’est pas tenu de répondre lorsque l’utilisateur a terminé avec le module de tâche.
{
"task": {
"type": "message",
"value": "Message text"
}
}
Teams affiche la valeur d’un message dans value une boîte de message.
{
"task": {
"type": "continue",
"value": <TaskInfo object>
}
}
Vous permet de chaîner des séquences de cartes adaptatives ensemble dans un Assistant ou une expérience en plusieurs étapes.

Notes

Le chaînage de cartes adaptatives dans une séquence est un scénario avancé. L'Node.js exemple d’application le prend en charge. Pour plus d’informations, voir Microsoft Teams module de tâche Node.js.

La section suivante fournit des détails sur la charge utile task/fetch et les task/submit messages.

Charge utile des messages de tâche/d’extraction et de tâche/d’soumission

Cette section définit le schéma de ce que votre bot reçoit lorsqu’il reçoit un task/fetch objet task/submit Bot Activity Framework. Le tableau suivant fournit les propriétés de la charge utile task/fetch et des task/submit messages :

Propriété Description
type Est toujours invoke .
name Est soit task/fetch task/submit ou .
value Est la charge utile définie par le développeur. La structure de value l’objet est la même que ce qui est envoyé à partir Teams. Dans ce cas, toutefois, il est différent. Elle nécessite la prise en charge de l’extraction dynamique à partir de Bot Framework, c’est-à-dire les actions de carte task/fetch value Action.Submit adaptative, autrement dit. data Un moyen de communiquer Teams au bot est nécessaire en plus de ce context qui est inclus dans ou value data .

Combinez « value » et « data » dans un objet parent :

{
"context": {
"theme": "default" | "dark" | "contrast",
},
"data": [value field from Bot Framework card] | [data field from Adaptive Card]
}

La section suivante fournit un exemple de réception et de réponse à des messages dans task/fetch task/submit Node.js.

Exemple de messages d’appel de tâche/extraction et de tâche/d'Node.js et C

handleTeamsTaskModuleFetch(context, taskModuleRequest) {
    // Called when the user selects an options from the displayed HeroCard or
    // AdaptiveCard.  The result is the action to perform.

    const cardTaskFetchValue = taskModuleRequest.data.data;
    var taskInfo = {}; // TaskModuleTaskInfo

    if (cardTaskFetchValue === TaskModuleIds.YouTube) {
        // Display the YouTube.html page
        taskInfo.url = taskInfo.fallbackUrl = this.baseUrl + '/' + TaskModuleIds.YouTube + '.html';
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.YouTube);
    } else if (cardTaskFetchValue === TaskModuleIds.CustomForm) {
        // Display the CustomForm.html page, and post the form data back via
        // handleTeamsTaskModuleSubmit.
        taskInfo.url = taskInfo.fallbackUrl = this.baseUrl + '/' + TaskModuleIds.CustomForm + '.html';
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.CustomForm);
    } else if (cardTaskFetchValue === TaskModuleIds.AdaptiveCard) {
        // Display an AdaptiveCard to prompt user for text, and post it back via
        // handleTeamsTaskModuleSubmit.
        taskInfo.card = this.createAdaptiveCardAttachment();
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.AdaptiveCard);
    }

    return TaskModuleResponseFactory.toTaskModuleResponse(taskInfo);
}

async handleTeamsTaskModuleSubmit(context, taskModuleRequest) {
    // Called when data is being returned from the selected option (see `handleTeamsTaskModuleFetch').

    // Echo the users input back.  In a production bot, this is where you'd add behavior in
    // response to the input.
    await context.sendActivity(MessageFactory.text('handleTeamsTaskModuleSubmit: ' + JSON.stringify(taskModuleRequest.data)));

    // Return TaskModuleResponse
    return {
        // TaskModuleMessageResponse
        task: {
            type: 'message',
            value: 'Thanks!'
        }
    };
}

setTaskInfo(taskInfo, uiSettings) {
    taskInfo.height = uiSettings.height;
    taskInfo.width = uiSettings.width;
    taskInfo.title = uiSettings.title;
}

Actions de carte Bot Framework et actions Action de carte adaptative.Submit

Le schéma des actions de carte Bot Framework est différent des actions de carte adaptative et la façon d’appeler des modules de Action.Submit tâche est également différente. dataL’objet dans contient un objet afin Action.Submit msteams qu’il n’interfère pas avec les autres propriétés de la carte. Le tableau suivant présente un exemple de chaque action de carte :

Action de carte Bot Framework Action Action.Submit de carte adaptative
{
"type": "invoke",
"title": "Buy",
"value": {
"type": "task/fetch",
<...>
}
}
{
"type": "Action.Submit",
"id": "btnBuy",
"title": "Buy",
"data": {
<...>,
"msteams": {
"type": "task/fetch"
}
}
}

Exemple de code

Exemple de nom Description .NET Node.js
Exemples de module de tâche bots-V4 Exemples de création de modules de tâche. View View

Voir aussi