Menus de la commande botBot command menus

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 SDK-v3 SDK dans le dossier Resources de la documentation.If you're looking for documentation for earlier versions, see the Bots - v3 SDK section in the Resources folder of the documentation.

Notes

Les menus de bot n’apparaissent pas sur les clients mobiles.Bot menus won't appear on mobile clients.

Add Command menu for your bot vous permet de définir un ensemble de commandes clés auxquelles votre bot peut toujours répondre.Add command menu for your bot allows you to define a set of core commands your bot can always respond to. La liste des commandes est présentée à l’utilisateur au-dessus de la zone de message de composition lorsqu’ils contournent votre robot.The list of commands is presented to the user above the compose message area when they are conversing with your bot. La sélection d’une commande dans la liste entraîne l’insertion de la chaîne de commande dans la boîte de message de composition, puis tous les utilisateurs ont besoin de l’option Envoyer.Selecting a command from the list will insert the command string into the compose message box, then all users need to do is select Send.

Menu de commandes bot

Créer un menu de commandes pour votre robotCreate a command menu for your bot

Les menus de commandes sont définis dans le manifeste de votre application.Command menus are defined in your app manifest. Vous pouvez utiliser app Studio pour vous aider à les créer ou les ajouter manuellement.You can either use App Studio to help you create them, or add them manually.

Création d’un menu de commandes pour votre bot à l’aide d’App StudioCreating a command menu for your bot using App Studio

Les instructions fournies ici supposent que vous modifiez un manifeste d’application existant.The instructions here assume that you'll be editing an existing app manifest. Les étapes d’ajout d’un menu de commandes sont les mêmes, que vous soyez en train de créer un nouveau manifeste ou d’en modifier un existant.The steps for adding a command menu are the same, whether you're creating a new manifest or editing an existing one.

  1. Ouvrez l’application Studio à partir du... menu débordement sur le rail de navigation gauche.Open App Studio from the ... overflow menu on the left navigation rail. Si vous n’avez pas disponible App Studio, vous pouvez le télécharger.If you don't have App Studio available you can download it. Pour plus d’informations sur l’utilisation d’App Studio, voir Installing App Studio .See Installing App Studio for more information on using App Studio.

    App Studio

  2. Une fois dans App Studio, sélectionnez l’onglet éditeur de manifeste .Once in App Studio, select the Manifest editor tab.

  3. Dans la colonne de gauche de la vue de l’éditeur de manifeste dans la section fonctionnalités , sélectionnez bots.In the left column of the manifest editor view in the Capabilities section, select Bots.

  4. Dans la colonne de droite de la vue de l’éditeur de manifeste dans la section commandes , cliquez sur le bouton Ajouter .In the right column of the manifest editor view in the Commands section, select the Add button.

    Bouton Ajouter du menu de commandes d’App Studio

  5. L’écran nouvelle commande s’affiche.The New Command screen appears. Entrez le texte de commande qui doit apparaître en tant que commande de menu, ainsi que le texte d’aide qui doit apparaître directement sous le texte de commande dans le menu.Enter the Command text that you want to have appear as the menu command, and the Help text that you want to have appear directly under the command text in the menu. Cela doit être une brève explication de l’objectif de la commande.This should be a brief explanation of the purpose of the command.

  6. Ensuite, sélectionnez la ou les étendues dans lesquelles vous souhaitez que ce menu de commandes s’affiche, puis cliquez sur le bouton Enregistrer .Next, select the scope(s) where you want this command menu to appear, then select the Save button.

    Bouton Ajouter du menu de commandes d’App Studio

Création d’un menu de commandes pour votre bot en modifiant Manifest. JSONCreating a command menu for your bot by editing Manifest.json

Une autre approche valide pour la création d’un menu de commandes consiste à le créer directement dans le fichier manifeste lors du développement du code source de votre robot.Another valid approach for creating a command menu is to create it directly in the manifest file while developing your bot source code. Voici quelques éléments à garder à l’esprit lors de l’utilisation de cette approche :Here are a few things to keep in mind when using this approach:

  1. Chaque menu prend en charge jusqu’à 10 commandes.Each menu supports up to 10 commands.

  2. Vous pouvez créer un seul menu de commandes qui fonctionne dans toutes les étendues.You can create a single command menu that will work in all scopes.

  3. Vous pouvez créer un autre menu de commandes pour chaque étendueYou can create a different command menu for each scope

Exemple de manifeste-menu unique pour les deux étenduesManifest example - single menu for both scopes

{
  ⋮
  "bots":[
    {
      "botId":"[Microsoft App ID for your bot]",
      "scopes": [
        "personal",
        "team"
      ],
      "commandLists":[
        {
          "scopes":[
            "team",
            "personal"
          ],
          "commands":[
            {
              "title":"Help",
              "description":"Displays this help message"
            },
            {
              "title":"Search Flights",
              "description":"Search flights from Seattle to Phoenix May 2-5 departing after 3pm"
            },
            {
              "title":"Search Hotels",
              "description":"Search hotels in Portland tonight"
            },
            {
              "title":"Best Time to Fly",
              "description":"Best time to fly to London for a 5 day trip this summer"
            }
          ]
        }
      ]
    }
  ],
  ...
}

Exemple de manifeste-menu pour chaque étendueManifest example - menu for each scope

{
  ...
  "bots":[
    {
      "botId":"<Microsoft app ID for your bot>",
      "scopes": [
        "groupChat",
        "team"
      ],
      "commandLists":[
        {
          "scopes":[
            "team"
          ],
          "commands":[
            {
            "title":"help",
            "description":"Displays this help message for channels"
            }
          ]
        },
        {
          "scopes":[
            "groupChat"
          ],
          "commands":[
            {
            "title":"help",
            "description":"Displays this help message for group chat"
            }
          ]
        }
      ]
    }
  ],
  ...
}

Gestion des commandes de menu dans votre code de robotHandling menu commands in your bot code

Les robots d’un groupe ou d’un canal répondent uniquement lorsqu’ils sont mentionnés (« @botname ») dans un message.Bots in a group or channel respond only when they are mentioned ("@botname") in a message. Par conséquent, chaque message reçu par un bot dans une étendue de groupe ou de canal contiendra son propre nom dans le texte du message renvoyé.As a result, every message received by a bot when in a group or channel scope will contain its own name in the message text returned. Vous devez veiller à ce que les handles d’analyse de messages qui précèdent la commande renvoyée soient pris en charge.You need to ensure your message parsing handles that before handling the command being returned.

Vous pouvez analyser la Activity RemoveRecipientMention ** @partie mention** du texte du message à l’aide d’une méthode statique fournie avec Microsoft bot Framework, une méthode de la classe nommée.You can parse out the @Mention portion of the message text using a static method provided with the Microsoft Bot Framework — a method of the Activity class named RemoveRecipientMention.

var modifiedText = turnContext.Activity.RemoveRecipientMention();

Meilleures pratiques du menu de commandesCommand menu best practices

  • Restez simple: le menu robot est conçu pour présenter les fonctionnalités clés de votre bot.Keep it simple: The bot menu is meant to present the key capabilities of your bot.
  • Maintenez-le court: les options de menu ne doivent pas être extrêmement longues et les instructions complexes en langage naturel : elles doivent être des commandes simples.Keep it short: Menu options shouldn’t be extremely long and complex natural language statements — they should be simple commands.
  • Conservez-le invokable: les actions/commandes du menu bot doivent toujours être disponibles, quel que soit l’état de la conversation ou la boîte de dialogue dans laquelle se trouve le robot.Keep it invokable: Bot menu actions/commands should always be available, regardless of the state of the conversation or the dialog the bot is in.