Ответ на команду поиска

Важно!

Примеры кода в этом разделе основаны на 4.6 и более поздних версиях SDK Bot Framework. Если вы ищете документацию для более ранних версий, см. раздел Расширения обмена сообщениями — раздел v3 SDK в папке Ресурсы документации.

После отправки команды поиска веб-служба получает сообщение об вызове, содержащем объект composeExtension/query value с параметрами поиска. Этот вызов запускается при следующих условиях:

  • Как символы вписались в поле поиска.
  • initialRun установлено, что в манифесте приложения вы получите сообщение вызова, как только будет вызвана команда поиска. Дополнительные сведения см. в запросе по умолчанию.

В этом документе вы можете узнать, как реагировать на запросы пользователей в виде карт и предварительных просмотров, а также условия, при которых Microsoft Teams выдает запрос по умолчанию.

Параметры запроса находятся в объекте в запросе, который включает value следующие свойства:

Имя свойства Назначение
commandId Имя команды, вызываемой пользователем, совпадает с одной из команд, объявленных в манифесте приложения.
parameters Массив параметров. Каждый объект параметра содержит имя параметра, а также значение параметра, предоставленное пользователем.
queryOptions Параметры pagination:
skip: Пропустить количество для этого запроса
count: Количество возвращаемого элемента.
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
  //code to handle the query
}

Ответы на запросы пользователей

Когда пользователь выполняет запрос, Microsoft Teams выдает синхронный http-запрос в службу. В этот момент у кода есть 5 секунды, чтобы предоставить http-ответ на запрос. За это время служба может выполнять дополнительный просмотр или любую другую бизнес-логику, необходимую для обслуживания запроса.

Служба должна отвечать результатами, совпадающие с запросом пользователя. Ответ должен указывать код состояния HTTP и допустимый объект приложения или JSON со 200 OK следующими свойствами:

Имя свойства Назначение
composeExtension Конверт ответа верхнего уровня.
composeExtension.type Тип ответа. Поддерживаются следующие типы:
result: Отображает список результатов поиска
auth: Просит пользователя проверить подлинность
config: Просит пользователя настроить расширение обмена сообщениями
message: Отображает простое текстовое сообщение
composeExtension.attachmentLayout Указывает макет вложений. Используется для ответов типа result .
В настоящее время поддерживаются следующие типы:
list: Список объектов карт, содержащих эскизы, заголовки и текстовые поля
grid: Сетка изображений эскизов
composeExtension.attachments Массив допустимых объектов вложений. Используется для ответов типа result .
В настоящее время поддерживаются следующие типы:
application/vnd.microsoft.card.thumbnail
application/vnd.microsoft.card.hero
application/vnd.microsoft.teams.card.o365connector
application/vnd.microsoft.card.adaptive
composeExtension.suggestedActions Предлагаемые действия. Используется для ответов типа auth или config .
composeExtension.text Отображение сообщения. Используется для ответов типа message .

Типы и предварительные просмотры карт отклика

Teams поддерживает следующие типы карт:

Чтобы лучше понимать карты и их обзор, см. в этом обзоре.

Чтобы узнать, как использовать эскизы и типы карт героев, см. в добавлении карт и действий карт.

Дополнительные сведения о карточке Office 365 соединители см. в Office 365 connector cards.

Список результатов отображается в пользовательском Microsoft Teams с предварительным просмотром каждого элемента. Предварительный просмотр создается одним из двух способов:

  • Использование preview свойства в attachment объекте. Вложение preview может быть только карточкой Hero или Thumbnail.
  • Извлечение из основных title text и свойств image attachment объекта. Основные свойства используются только в том случае, если свойство preview не указано.

Для карты Hero или Thumbnail, за исключением действия вызова, другие действия, такие как кнопка и касание, не поддерживаются в карточке предварительного просмотра.

Чтобы отправить адаптивную карту или соединительные карты Ofiice 365, необходимо включить предварительный просмотр. Свойство preview должно быть карточкой Hero или Thumbnail. Если не указать свойство предварительного просмотра в объекте, предварительный просмотр attachment не создается.

Для карт Hero и Thumbnail не требуется указывать свойство предварительного просмотра, предварительный просмотр создается по умолчанию. В следующем примере отображается функция разгрузки ссылки при вклеии ссылки в расширении обмена сообщениями:
разгрузка ссылки

Пример ответа

protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken) 
{
  var text = query?.Parameters?[0]?.Value as string ?? string.Empty;

  //searches NuGet for a package
  var obj = JObject.Parse(await (new HttpClient()).GetStringAsync($"https://azuresearch-usnc.nuget.org/query?q=id:{text}&prerelease=true"));
  var packages = obj["data"].Select(item => (item["id"].ToString(), item["version"].ToString(), item["description"].ToString()));

  // We take every row of the results and wrap them in cards wrapped in in MessagingExtensionAttachment objects.
  // The Preview is optional, if it includes a Tap, that will trigger the OnTeamsMessagingExtensionSelectItemAsync event back on this bot.
  var attachments = packages.Select(package => new MessagingExtensionAttachment
      {
          ContentType = HeroCard.ContentType,
          Content = new HeroCard { Title = package.Item1 },
          Preview = new HeroCard { Title = package.Item1, Tap = new CardAction { Type = "invoke", Value = package } }.ToAttachment()
      })
      .ToList();

  // The list of MessagingExtensionAttachments must we wrapped in a MessagingExtensionResult wrapped in a MessagingExtensionResponse.
  return new MessagingExtensionResponse
  {
      ComposeExtension = new MessagingExtensionResult
      {
          Type = "result",
          AttachmentLayout = "list",
          Attachments = attachments
      }
  };
}

Включить и обрабатывать действия касания

protected override Task<MessagingExtensionResponse> OnTeamsMessagingExtensionSelectItemAsync(ITurnContext<IInvokeActivity> turnContext, JObject query, CancellationToken cancellationToken)
{
    // The Preview card's Tap should have a Value property assigned, this will be returned to the bot in this event. 
    var (packageId, version, description, projectUrl, iconUrl) = query.ToObject<(string, string, string, string, string)>();

    var card = new ThumbnailCard
    {
        Title = "Card Select Item",
        Subtitle = description
    };

    var attachment = new MessagingExtensionAttachment
    {
        ContentType = ThumbnailCard.ContentType,
        Content = card,
    };

    return Task.FromResult(new MessagingExtensionResponse
    {
        ComposeExtension = new MessagingExtensionResult
        {
            Type = "result",
            AttachmentLayout = "list",
            Attachments = new List<MessagingExtensionAttachment> { attachment }
        }
    });
}

Примечание

OnTeamsMessagingExtensionSelectItemAsync не запускается в приложении мобильных групп.

Запрос по умолчанию

Если вы заданы в манифесте, Microsoft Teams запрос по умолчанию при первом открываемом пользователем initialRun true расширении обмена сообщениями. Служба может отвечать на этот запрос набором предварительно заполненных результатов. Это полезно, когда команда поиска требует проверки подлинности или конфигурации, отображая недавно просмотримые элементы, избранное или любую другую информацию, которая не зависит от ввода пользователя.

Запрос по умолчанию имеет ту же структуру, что и любой обычный запрос пользователя, при этом поле заказано и заказано, как показано name initialRun в следующем value true объекте:

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "initialRun",
        "value": "true"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
  ⋮
}

Пример кода

Имя образца Описание .NET Node.js
Teams расширения обмена сообщениями Описывает, как определить команды действий, создать модуль задач и реагировать на отправку действия модуля задач. View View
Teams расширения обмена сообщениями Описывает, как определить команды поиска и реагировать на поиски. View View

Следующий этап

См. также

Добавление конфигурации в расширение обмена сообщениями