Définir les commandes de recherche d’extension de messagerieDefine messaging extension search commands

Important

Les exemples de code de cette section sont basés sur 4,6 et les versions ultérieures du kit de développement logiciel (SDK) de l’infrastructure bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Si vous recherchez de la documentation pour les versions antérieures, reportez-vous à la section extensions de messagerie-v3 SDK dans le dossier Resources de la documentation.If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

Les commandes de recherche d’extension de messagerie permettent à vos utilisateurs d’effectuer des recherches dans des systèmes externes et d’insérer les résultats de cette recherche dans un message sous la forme d’une carte.Messaging extension search commands allow your users to search external systems and insert the results of that search into a message in the form of a card.

Choisir les emplacements d’appel d’extension de messagerieChoose messaging extension invoke locations

La première chose que vous devez décider est l’emplacement où votre commande de recherche peut être déclenchée (ou plus spécifiquement appelée).The first thing you need to decide is where your search command can be triggered (or more specifically, invoked) from. Votre commande de recherche peut être appelée à partir de l’un des emplacements suivants (ou les deux) :Your search command can be invoked from one or both of the following locations:

  • Les boutons situés en bas de la zone de message de compositionThe buttons at the bottom of the compose message area
  • Par @mentioning dans la zone de commandeBy @mentioning in the command box

Lorsqu’il est appelé à partir de la zone de message de composition, votre utilisateur a la possibilité d’envoyer les résultats à la conversation.When invoked from the compose message area, your user will have the option of sending the results to the conversation. Lorsqu’il est appelé à partir de la zone de commande, l’utilisateur peut interagir avec la carte résultante ou la copier pour une utilisation ailleurs.When invoked from the command box, the user can interact with the resulting card, or copy it for use elsewhere.

Ajouter la commande à votre manifeste d’applicationAdd the command to your app manifest

Maintenant que vous avez décidé de la façon dont les utilisateurs vont interagir avec votre commande de recherche, il est temps de l’ajouter à votre manifeste d’application.Now that you've decided how users will interact with your search command, it is time to add it to your app manifest. Pour ce faire, vous allez ajouter un composeExtension nouvel objet au niveau supérieur de votre fichier JSON de manifeste d’application.To do this you'll add a new composeExtension object to the top level of your app manifest JSON. Vous pouvez le faire à l’aide de l’aide d’App Studio ou manuellement.You can either do so with the help of App Studio, or manually.

Créer une commande à l’aide d’App StudioCreate a command using App Studio

Les étapes suivantes supposent que vous avez déjà créé une extension de messagerie.The following steps assume you've already created a messaging extension.

  1. À partir du client Microsoft Teams, ouvrez l' application Studio et sélectionnez l’onglet éditeur de manifeste .From the Microsoft Teams client, open App Studio and select the Manifest Editor tab.
  2. Si vous avez déjà créé votre package d’application dans l’application Studio, sélectionnez-le dans la liste.If you've already created your app package in App Studio, chose it from the list. Si ce n’est pas le cas, vous pouvez importer un package d’application existant.If not, you can import an existing app package.
  3. Cliquez sur le bouton Ajouter dans la section commande.Click the Add button in the Command section.
  4. Choisissez autoriser les utilisateurs à interroger votre service pour obtenir des informations et les insérer dans un message.Choose Allow users to query your service for information and insert that into a message.
  5. Ajoutez un ID de commande et un titre.Add a Command Id and a Title.
  6. Sélectionnez l’emplacement à partir duquel vous souhaitez déclencher la commande de recherche.Select where you want your search command to be triggered from. La sélection de message ne modifie actuellement pas le comportement de votre commande de recherche.Selecting message does not currently alter the behavior of your search command.
  7. Ajoutez votre paramètre de recherche.Add your search parameter.
  8. Cliquez sur Enregistrer.Click Save.

Créer manuellement une commandeManually create a command

Pour ajouter manuellement votre commande de recherche d’extension de messagerie à votre manifeste d’application, vous devez ajouter les paramètres follow composeExtension.commands à votre tableau d’objets.To manually add your messaging extension search command to your app manifest, you'll need to add the follow parameters to your composeExtension.commands array of objects.

Nom de la propriétéProperty name ObjectifPurpose Obligatoire ?Required? Version de manifeste minimaleMinimum manifest version
id ID unique que vous affectez à cette commande.Unique ID that you assign to this command. La demande de l’utilisateur contiendra cet ID.The user request will include this ID. OuiYes 1.01.0
title Nom de la commande.Command name. Cette valeur apparaît dans l’interface utilisateur.This value appears in the UI. OuiYes 1.01.0
description Texte d’aide indiquant la signification de cette commande.Help text indicating what this command does. Cette valeur apparaît dans l’interface utilisateur.This value appears in the UI. OuiYes 1.01.0
type Doivent êtrequeryMust be query NonNo 1.41.4
initialRun Si la valeur est définie sur true, cette commande doit être exécutée dès que l’utilisateur choisit cette commande dans l’interface utilisateur.If set to true, indicates this command should be executed as soon as the user chooses this command in the UI. NonNo 1.01.0
context Tableau facultatif de valeurs qui définit le contexte dans lequel l’action de recherche est disponible.Optional array of values that defines the context the search action is available in. Les valeurs possibles messagesont compose, ou commandBox.Possible values are message, compose, or commandBox. La valeur par défaut est ["compose", "commandBox"].Default is ["compose", "commandBox"]. NonNo 1,51.5

Vous devrez également ajouter les détails du paramètre de recherche, qui définira le texte visible par votre utilisateur dans le client Teams.You'll also need to add the details of the search parameter, which will define the text visible to your user in the Teams client.

Nom de la propriétéProperty name ObjectifPurpose Obligatoire ?Required? Version de manifeste minimaleMinimum manifest version
parameters Liste statique des paramètres de la commande.Static list of parameters for the command. NonNo 1.01.0
parameter.name Le nom du paramètre.The name of the parameter. Cette adresse est envoyée à votre service dans la demande de l’utilisateur.This is sent to your service in the user request. OuiYes 1.01.0
parameter.description Décrit ce paramètre ou un exemple de la valeur qui doit être fournie.Describes this parameter’s purposes or example of the value that should be provided. Cette valeur apparaît dans l’interface utilisateur.This value appears in the UI. OuiYes 1.01.0
parameter.title Titre de paramètre court convivial ou étiquette.Short user-friendly parameter title or label. OuiYes 1.01.0
parameter.inputType Défini sur le type d’entrée requis.Set to the type of input required. Les valeurs possibles textsont textarea, number, date, time, toggleet.Possible values include text, textarea, number, date, time, toggle. La valeur par défaut est définie surtextDefault is set to text NonNo 1.41.4

Exemple de manifeste d’applicationApp manifest example

Voici un exemple d’un composeExtensions objet qui définit une commande de recherche.The below is an example of a composeExtensions object defining a search command. Il ne s’agit pas d’un exemple du manifeste complet, pour le schéma de manifeste d’application complet, voir : schéma de manifeste d’application.It is not an example of the complete manifest, for the full app manifest schema see: App manifest schema.

{
...
  "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"
          }]
        }
      ]
    }
  ],
...
}

Étapes suivantesNext steps

À présent que vous avez ajouté votre commande de recherche, vous devez gérer la demande de recherche.Now that you've added your search command, you'll need to handle the search request.

En savoir plusLearn more

Essayez-le dans un démarrage rapide :Try it out in a quickstart: