Определение команд поиска для расширения обмена сообщениямиDefine messaging extension search commands

Важно!

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

Команды поиска для расширения системы обмена сообщениями позволяют пользователям искать внешние системы и вставлять результаты поиска в сообщения в виде карточки.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.

Выбор расположений вызова расширения обмена сообщениямиChoose messaging extension invoke locations

Первое, что необходимо принять, — из чего можно запустить команду поиска (точнее, вызватьее).The first thing you need to decide is where your search command can be triggered (or more specifically, invoked) from. Команда поиска может быть вызвана из одного или обоих следующих расположений:Your search command can be invoked from one or both of the following locations:

  • Кнопки в нижней части области "Создание сообщения"The buttons at the bottom of the compose message area
  • По @mentioning в поле командыBy @mentioning in the command box

При вызове из области "Создание сообщения" пользователь может отправлять результаты в беседу.When invoked from the compose message area, your user will have the option of sending the results to the conversation. При вызове из поля команд пользователь может взаимодействовать с полученной картой или копировать его для использования в другом месте.When invoked from the command box, the user can interact with the resulting card, or copy it for use elsewhere.

Добавление команды в манифест приложенияAdd the command to your app manifest

Теперь, когда вы решили, как пользователи будут взаимодействовать с командой поиска, следует добавить его в манифест приложения.Now that you've decided how users will interact with your search command, it is time to add it to your app manifest. Чтобы сделать это, добавьте новый composeExtension объект на верхний уровень манифеста приложения JSON.To do this you'll add a new composeExtension object to the top level of your app manifest JSON. Это можно сделать с помощью App Studio или вручную.You can either do so with the help of App Studio, or manually.

Создание команды с помощью App StudioCreate a command using App Studio

В следующих действиях предполагается, что вы уже создали расширение системы обмена сообщениями.The following steps assume you've already created a messaging extension.

  1. В клиенте Microsoft Teams откройте app Studio и выберите вкладку редактор манифестов .From the Microsoft Teams client, open App Studio and select the Manifest Editor tab.
  2. Если вы уже создали пакет приложения в App Studio, выберите его из списка.If you've already created your app package in App Studio, chose it from the list. В противном случае вы можете импортировать существующий пакет приложения.If not, you can import an existing app package.
  3. Нажмите кнопку Add (добавить ) в разделе Command (Добавить).Click the Add button in the Command section.
  4. Выберите Разрешить пользователям запрашивать у службы сведения и вставлять их в сообщение.Choose Allow users to query your service for information and insert that into a message.
  5. Добавьте идентификатор команды и название.Add a Command Id and a Title.
  6. Выберите, откуда вы хотите запустить команду поиска.Select where you want your search command to be triggered from. В настоящее время выбор сообщения не изменяет поведение команды поиска.Selecting message does not currently alter the behavior of your search command.
  7. Добавьте параметр поиска.Add your search parameter.
  8. Щелкните Сохранить.Click Save.

Создание команды вручнуюManually create a command

Чтобы вручную добавить команду поиска расширения обмена сообщениями в манифест приложения, необходимо добавить к composeExtension.commands массиву объектов следующие параметры.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.

Имя свойстваProperty name НазначениеPurpose Обязательный?Required? Минимальная версия манифестаMinimum manifest version
id Уникальный идентификатор, назначенный этой команде.Unique ID that you assign to this command. Запрос пользователя будет включать этот идентификатор.The user request will include this ID. ДаYes 1.01.0
title Имя команды.Command name. Это значение отображается в пользовательском интерфейсе.This value appears in the UI. ДаYes 1.01.0
description Текст справки, указывающий, что делает эта команда.Help text indicating what this command does. Это значение отображается в пользовательском интерфейсе.This value appears in the UI. ДаYes 1.01.0
type Необходимое значение — query.Must be query НетNo 1.41.4
initialRun Если задано значение true, то эта команда должна выполняться сразу после того, как пользователь выберет эту команду в пользовательском интерфейсе.If set to true, indicates this command should be executed as soon as the user chooses this command in the UI. НетNo 1.01.0
context Необязательный массив значений, определяющий контекст, в котором действие поиска доступно.Optional array of values that defines the context the search action is available in. Возможные значения: message, compose, или commandBox.Possible values are message, compose, or commandBox. Значение по умолчанию: ["compose", "commandBox"].Default is ["compose", "commandBox"]. НетNo 1.51.5

Кроме того, необходимо добавить сведения о параметре Search, который будет определять текст, видимый для пользователя в клиенте 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.

Имя свойстваProperty name НазначениеPurpose Обязательный?Required? Минимальная версия манифестаMinimum manifest version
parameters Статический список параметров для команды.Static list of parameters for the command. НетNo 1.01.0
parameter.name Имя параметра.The name of the parameter. Он отправляется службе по запросу пользователя.This is sent to your service in the user request. ДаYes 1.01.0
parameter.description Описывает назначение этого параметра или пример значения, которое следует предоставить.Describes this parameter’s purposes or example of the value that should be provided. Это значение отображается в пользовательском интерфейсе.This value appears in the UI. ДаYes 1.01.0
parameter.title Краткий заголовком или меткой с понятным пользователем параметром.Short user-friendly parameter title or label. ДаYes 1.01.0
parameter.inputType Укажите требуемый тип ввода.Set to the type of input required. Возможные значения: text, textarea, number, date, time, toggle.Possible values include text, textarea, number, date, time, toggle. Значение по умолчанию:textDefault is set to text НетNo 1.41.4

Пример манифеста приложенияApp manifest example

Ниже приведен пример composeExtensions объекта, определяющего команду поиска.The below is an example of a composeExtensions object defining a search command. Это не пример полного манифеста для полной схемы манифеста приложения: схема манифеста приложения.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"
          }]
        }
      ]
    }
  ],
...
}

Дальнейшие действияNext steps

Теперь, когда вы добавили команду поиска, вам потребуется обработать запрос поиска.Now that you've added your search command, you'll need to handle the search request.

Дополнительные сведенияLearn more

Попробуйте это в кратком руководстве:Try it out in a quickstart: