Меню команд BotBot command menus

Важно!

Примеры кода, приведенные в этом разделе, основаны на 4,6 и более поздних версиях пакета SDK Bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Если вы ищете документацию по более ранним версиям, ознакомьтесь с разделом Боты – v3 SDK в папке resources этой документации.If you're looking for documentation for earlier versions, see the Bots - v3 SDK section in the Resources folder of the documentation.

Примечание

Меню ленты не отображаются на мобильных клиентах.Bot menus won't appear on mobile clients.

Команда добавить меню для ленты позволяет определить набор основных команд, на которые пользователь Bot всегда может отвечать.Add command menu for your bot allows you to define a set of core commands your bot can always respond to. Список команд предоставляется пользователю, расположенному над областью создание сообщения, при их взаимосравнении с Bot.The list of commands is presented to the user above the compose message area when they are conversing with your bot. При выборе команды из списка в поле создать сообщение будет вставлена Командная строка, тогда все пользователи должны выполнить команду Отправить.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.

Меню команд Bot

Создание командного меню для лентыCreate a command menu for your bot

Меню команд определяются в манифесте приложения.Command menus are defined in your app manifest. Вы можете использовать приложение App Studio, чтобы создать их или добавить вручную.You can either use App Studio to help you create them, or add them manually.

Создание командного меню для ленты с помощью App StudioCreating a command menu for your bot using App Studio

В этих инструкциях предполагается, что вы будете редактировать существующий манифест приложения.The instructions here assume that you'll be editing an existing app manifest. Действия для добавления командного меню одинаковы, независимо от того, создаете ли вы новый манифест или редактируете существующий.The steps for adding a command menu are the same, whether you're creating a new manifest or editing an existing one.

  1. Откройте приложение App Studio из... меню переполнения на левой панели навигации.Open App Studio from the ... overflow menu on the left navigation rail. Если у вас нет доступной App Studio, вы можете скачать его.If you don't have App Studio available you can download it. Более подробную информацию об использовании App Studio можно узнать в статье Установка App Studio .See Installing App Studio for more information on using App Studio.

    App Studio

  2. В App Studio перейдите на вкладку редактор манифестов .Once in App Studio, select the Manifest editor tab.

  3. В левом столбце представления редактор манифестов в разделе возможности выберите Боты.In the left column of the manifest editor view in the Capabilities section, select Bots.

  4. В правой колонке представления "редактор манифестов" в разделе команды нажмите кнопку Добавить .In the right column of the manifest editor view in the Commands section, select the Add button.

    Кнопка "Добавить" меню "команд" в App Studio

  5. Откроется экран Новая команда .The New Command screen appears. Введите текст команды , который должен отображаться в качестве команды меню, и текст справки , который должен отображаться непосредственно под текстом команды в меню.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. Это должно быть краткое описание назначения команды.This should be a brief explanation of the purpose of the command.

  6. Затем выберите области, в которых должно отображаться меню команд, а затем нажмите кнопку сохранить .Next, select the scope(s) where you want this command menu to appear, then select the Save button.

    Кнопка "Добавить" меню "команд" в App Studio

Создание командного меню для ленты с помощью Manifest.js редактированияCreating a command menu for your bot by editing Manifest.json

Другой допустимый подход к созданию командного меню состоит в том, чтобы создать его непосредственно в файле манифеста во время разработки исходного кода для ленты.Another valid approach for creating a command menu is to create it directly in the manifest file while developing your bot source code. Ниже приведены некоторые моменты, которые необходимо учитывать при использовании такого подхода.Here are a few things to keep in mind when using this approach:

  1. Каждое меню поддерживает до 10 команд.Each menu supports up to 10 commands.

  2. Вы можете создать одно командное меню, которое будет работать во всех областях.You can create a single command menu that will work in all scopes.

  3. Вы можете создать другое меню команд для каждой области.You can create a different command menu for each scope

Пример манифеста — одно меню для обеих областейManifest 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"
            }
          ]
        }
      ]
    }
  ],
  ...
}

Пример манифеста для каждой областиManifest 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"
            }
          ]
        }
      ]
    }
  ],
  ...
}

Обработка команд меню в коде BotHandling menu commands in your bot code

Боты в группе или канале отвечают только на то время, когда они упоминаются ("@botname") в сообщении.Bots in a group or channel respond only when they are mentioned ("@botname") in a message. В результате каждое сообщение, полученное с помощью Bot в области группы или канала, будет содержать собственное имя в возвращенном тексте сообщения.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. Прежде чем обрабатывать возвращаемую команду, необходимо убедиться в том, что дескрипторы синтаксического анализа сообщений.You need to ensure your message parsing handles that before handling the command being returned.

Note (Примечание ) Для обработки команд в коде они отправляются в программу Bot как обычное сообщение.Note For handling the commands in code, they are sent to your bot as a regular message. Поэтому их необходимо обработать так же, как и для любого другого сообщения от пользователей.So you need to handle them as you would do for any other message from your users. Они представляют собой только обработку пользовательского интерфейса, которая вставляет предварительно настроенный текст в текстовое поле.They are purely a UI treatment that inserts pre-configured text into the text box. После этого пользователь должен отправить этот текст так же, как и для любого другого сообщения.The user must then send that text as they would do for any other message.

Вы можете анализировать @ упоминание текста сообщения с помощью статического метода, поставляемого с Microsoft Bot Framework — метод Activity класса с именем RemoveRecipientMention .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();

Рекомендации по использованию меню командCommand menu best practices

  • Для простоты сделайте следующее: меню Bot предназначено для представления ключевых возможностей робота.Keep it simple: The bot menu is meant to present the key capabilities of your bot.
  • Не забудьте: параметры меню не должны быть чрезвычайно длинными и сложными естественными языками — они должны быть простыми командами.Keep it short: Menu options shouldn’t be extremely long and complex natural language statements — they should be simple commands.
  • Поддерживать возможность вызова: действия и команды меню "bot" всегда должны быть доступны, независимо от состояния беседы или диалогового окна, в котором находится почтовый робот.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.

Note (Примечание ) Если вы удалите какие бы то ни были команды из манифеста, необходимо повторно развернуть приложение, чтобы изменения вступили в силу.Note If you remove any commands from your manifest, you will need to redeploy your app for the changes to take effect. В общем случае все изменения в манифесте требуют этого.In general, any changes to the manifest require this.