Définir les commandes de recherche d’extension de messagerie

Important

Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du SDK Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section Extensions de messagerie - V3 SDK dans le dossier Ressources de la documentation.

Les commandes de recherche d’extension de messagerie permettent aux utilisateurs de rechercher des systèmes externes et d’insérer les résultats de cette recherche dans un message sous la forme d’une carte. Ce document vous guide sur la sélection des emplacements d’appel de commande de recherche et ajoute la commande de recherche au manifeste de votre application.

Notes

La limite de taille de carte de résultat est de 28 Ko. La carte n’est pas envoyée si sa taille dépasse 28 Ko.

Sélectionner des emplacements d’appel de commande de recherche

La commande de recherche est invoquée à partir de l’un des emplacements suivants ou des deux :

  • Zone de composition de message : boutons situés en bas de la zone composer un message.

  • Zone de commande : en @mentioning dans la zone de commande.

    Lorsque la commande de recherche est invoquée à partir de la zone composer un message, l’utilisateur envoie les résultats à la conversation. Lorsqu’il est appelé à partir de la zone de commande, l’utilisateur interagit avec la carte résultante ou la copie pour l’utiliser ailleurs.

L’image suivante affiche les emplacements d’appel de la commande de recherche :

emplacements d’appel de commande de recherche

Ajouter la commande de recherche au manifeste de votre application

Pour ajouter la commande de recherche au manifeste de votre application, vous devez ajouter un nouvel objet au niveau supérieur du manifeste JSON de composeExtension votre application. Vous pouvez ajouter la commande de recherche à l’aide d’App Studio ou manuellement.

Créer une commande de recherche à l’aide d’App Studio

La condition préalable à la création d’une commande de recherche est que vous devez déjà avoir créé une extension de messagerie. Pour plus d’informations sur la création d’une extension de messagerie, voir créer une extension de messagerie.

Pour créer une commande de recherche

  1. Ouvrez App Studio à partir Microsoft Teams client, puis sélectionnez l’onglet Éditeur de manifeste.

  2. Si vous avez déjà créé votre package d’application dans App Studio, sélectionnez-le dans la liste. Si vous n’avez pas créé de package d’application, importez-en un existant.

  3. Après avoir importé le package d’application, sélectionnez les extensions de messagerie sous Fonctionnalités. Vous obtenez une fenêtre instantanée pour configurer l’extension de messagerie.

  4. Sélectionnez Configurer dans la fenêtre pour inclure l’extension de messagerie dans l’expérience de votre application. L’image suivante affiche la page de mise en place de l’extension de messagerie :

    messaging extension set up
  5. Pour créer l’extension de messagerie, vous avez besoin d’un bot inscrit par Microsoft. Vous pouvez utiliser un bot existant ou en créer un nouveau. Sélectionnez Créer une option de bot, donnez un nom au nouveau bot, puis sélectionnez Créer. L’image suivante affiche la création d’un bot pour l’extension de messagerie :

    create bot for messaging extension
  6. Sélectionnez Ajouter dans la section Commande de la page Extensions de messagerie pour inclure les commandes qui déterminent le comportement de l’extension de messagerie.
    L’image suivante affiche l’ajout de commande pour l’extension de messagerie :

    include command
  7. Sélectionnez Autoriser les utilisateurs à interroger votre service pour obtenir des informations et à les insérer dans un message. L’image suivante affiche la sélection du paramètre de commande de recherche :

    search command parameter selection
  8. Ajoutez un ID de commande et un titre.

  9. Sélectionnez l’emplacement à partir de lequel votre commande de recherche doit être invoquée. La sélection d’un message ne modifie pas actuellement le comportement de votre commande de recherche. L’image suivante affiche l’emplacement d’appel de commande de recherche :

    search command invoke location selection]
  10. Ajoutez votre paramètre de recherche et sélectionnez Enregistrer.

Créer une commande de recherche manuellement

Pour ajouter manuellement votre commande de recherche d’extension de messagerie au manifeste de votre application, vous devez ajouter les paramètres suivants à votre composeExtension.commands tableau d’objets :

Nom de la propriété Objectif Obligatoire ? Version minimale du manifeste
id Cette propriété est un ID unique que vous affectez à la commande de recherche. La demande de l’utilisateur inclut cet ID. Oui 1.0
title Cette propriété est un nom de commande. Cette valeur apparaît dans l’interface utilisateur. Oui 1.0
description Cette propriété est un texte d’aide indiquant ce que fait cette commande. Cette valeur apparaît dans l’interface utilisateur. Oui 1.0
type Cette propriété doit être une query . Non 1.4
initialRun Si cette propriété est définie sur true, elle indique que cette commande doit être exécutée dès que l’utilisateur sélectionne cette commande dans l’interface utilisateur. Non 1.0
context Cette propriété est un tableau facultatif de valeurs qui définit le contexte dans lequel l’action de recherche est disponible. Les valeurs possibles sont message, compose ou commandBox. La valeur par défaut est ["compose", "commandBox"]. Non 1,5

Vous devez ajouter les détails du paramètre de recherche, qui définit le texte visible pour votre utilisateur dans le client Teams recherche.

Nom de la propriété Objectif Est-ce obligatoire ? Version minimale du manifeste
parameters Cette propriété définit une liste statique de paramètres pour la commande. Non 1.0
parameter.name Cette propriété décrit le nom du paramètre. Cette information est envoyée à votre service dans la demande de l’utilisateur. Oui 1.0
parameter.description Cette propriété décrit les objectifs du paramètre ou un exemple de la valeur à fournir. Cette valeur apparaît dans l’interface utilisateur. Oui 1.0
parameter.title Cette propriété est un titre ou une étiquette de paramètre convivial court. Oui 1.0
parameter.inputType Cette propriété est définie sur le type d’entrée requis. Les valeurs text possibles sont , , , , textarea number date time toggle . La valeur par défaut est définie sur text . Non 1.4

Exemple

La section suivante est un exemple du manifeste d’application simple de composeExtensions l’objet définissant une commande de recherche :

{
...
  "composeExtensions": [
    {
      "botId": "57a3c29f-1fc5-4d97-a142-35bb662b7b23",
      "canUpdateConfiguration": true,
      "commands": [{
          "id": "searchCmd",
          "description": "Search Bing for information on the web",
          "title": "Search",
          "initialRun": true,
          "parameters": [{
            "name": "searchKeyword",
            "description": "Enter your search keywords",
            "title": "Keywords"
          }]
        }
      ]
    }
  ],
...
}

Pour obtenir le manifeste complet de l’application, voir schéma de manifeste d’application.

Exemple de code

Exemple de nom Description .NET Node.js
Teams d’extension de messagerie Décrit comment définir des commandes d’action, créer un module de tâche et répondre à l’action d’soumission du module de tâche. View View
Teams d’extension de messagerie Décrit comment définir des commandes de recherche et répondre aux recherches. View View

Étape suivante