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

  • Статья

Важно!

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

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

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

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

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

Имя свойства Назначение
commandId Имя команды, вызываемой пользователем, соответствующее одной из команд, объявленных в манифесте приложения.
parameters Массив параметров. Каждый объект параметра содержит имя параметра, а также значение параметра, предоставленное пользователем.
queryOptions Параметры разбиения на страницы:
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-ответа на запрос. В течение этого времени служба может выполнить дополнительный поиск или любую другую бизнес-логику, необходимую для обслуживания запроса.

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

Имя свойства Назначение
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.

Ответ конфигурации

Ответ конфигурации — это данные, возвращаемые сервером или приложением для настройки и включения расширения сообщений на платформе обмена сообщениями. Следующий код является примером конфигурации расширения сообщений:

{
    "name": "composeExtension/submitAction",
    "type": "invoke",
    "timestamp": "2024-03-08T14:10:47.575Z",
    "localTimestamp": "2024-03-08T19:40:47.575+05:30",
    "id": "f:7dfe18de-94e3-9f38-5d44-adeb31cd8243",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "29:1PBlnIsEROUYzpFjULDVodMHrnpujmfhBdQAf0pcO1EkaDkhI0_Pj_ql-jZUYOGdSc3_KcqaIIjzbleraVJ2Z3g",
        "name": "MOD Administrator",
        "aadObjectId": "ce9def33-d7fc-444c-8728-be1f95e6b6f2"
    },
    "conversation": {
        "isGroup": true,
        "conversationType": "groupChat",
        "tenantId": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b",
        "id": "19:1dd50ba7-e5bd-46ea-b34e-80a415148de7_ce9def33-d7fc-444c-8728-be1f95e6b6f2@unq.gbl.spaces"
    },
    "recipient": {
        "id": "28:9a2b01fc-88c1-40e1-bf87-5079c8e35626",
        "name": "PSDAzureBot"
    },
    "entities": [
        {
            "locale": "en-GB",
            "country": "GB",
            "platform": "Web",
            "timezone": "Asia/Calcutta",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "tenant": {
            "id": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b"
        },
        "source": {
            "name": "compose"
        }
    },
    "value": {
        "commandId": "razorView",
        "commandContext": "compose",
        "data": {
            "Title": "Welcome to RazorView!",
            "DisplayData": " Today&#x27;s date is 8-3-2024, Friday"
        },
        "context": {
            "theme": "default"
        }
    },
    "locale": "en-GB",
    "localTimezone": "Asia/Calcutta"
}

Следующий ответ — это ответ конфигурации, который появляется при взаимодействии пользователя с расширением compose:

{
    "composeExtension": {
        "type": "config",
        "suggestedActions": {
            "actions": [
                {
                    "type": "openUrl",
                    "value": "https://7a03-2405-201-a00c-7191-b472-ff64-112d-f806.ngrok-free.app"
                }
            ]
        }
    }
}

Снимок экрана: ответ конфигурации для расширения сообщений.

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

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

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

Сведения об использовании типов эскизов и карта главного героя см. в статье Добавление карточек и действий карта.

Дополнительные сведения о карта соединителя для Группы Microsoft 365 см. в статье Использование карт соединителей для Группы Microsoft 365.

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

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

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

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

Для карточек главного элемента и эскизов не требуется указывать свойство предварительного просмотра. Предварительный просмотр создается по умолчанию.

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

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 }
        }
    });
}

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

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

Запрос по умолчанию имеет ту же структуру, что и любой обычный запрос пользователя, при этом 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 В этом примере показано, как создать расширение сообщений на основе Поиск. Он выполняет поиск пакетов nudget и отображает результаты в расширении обмена сообщениями на основе поиска. Просмотр Просмотр Просмотр
Проверка подлинности и конфигурация расширения сообщений Teams В этом примере показано расширение сообщений, которое имеет страницу конфигурации, принимает поисковые запросы и возвращает результаты после входа пользователя. В нем также демонстрируется распаковка ссылки нулевой установки приложения вместе с распаковкой обычной ссылки Просмотр Просмотр Просмотр

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

Добавление сторонней проверки подлинности в расширение сообщений

См. также