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

Важно!

Примеры кода в этом разделе основаны на версии 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.
}

Пример справочника по коду

class TeamsMessagingExtensionsSearch extends TeamsActivityHandler {
    async handleTeamsMessagingExtensionQuery(context, query) {
  // Code to handle the query.
    }
}

Следующий код JSON сокращается, чтобы выделить наиболее важные разделы.

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "searchKeywords",
        "value": "Toronto"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
...
}

Реагирование на запросы пользователей

Когда пользователь выполняет запрос, Microsoft Teams отправляет к вашей службе синхронный HTTP-запрос. На этом этапе у кода есть пять секунд, чтобы предоставить 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`.

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

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

В следующем фрагменте config кода показан ответ, который появляется при взаимодействии пользователя с расширением сообщения:

{
    "composeExtension": {
        "suggestedActions": {
            "actions": [
                {
                    "type": "openUrl",
                    "title": "Open url",
                    "value": "https://<your-tunnel-url>/searchSettings.html?settings="
                }
            ]
        },
        "type": "config"
    },
    "responseType": "composeExtension"
}

Ответ включает в себя следующее config :

Свойство value , содержащее URL-адрес для открытия страницы конфигурации в диалоговом окне Teams, которое позволяет пользователям вводить необходимые сведения и отправлять конфигурацию. Вот несколько примеров value свойства:
- https://<your-subdomain>.ngrok-free.app/searchSettings.html
- https://<your-subdomain>.devtunnels.ms/searchSettings.html.
Поле type в параметре composeExtensionconfig, указывающее характер этого ответа в качестве конфигурации.
Объект responseType , определяющий этот ответ, предназначен для composeExtension приложения.

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

Инициализируйте пакет SDK Для Teams на странице конфигурации и используйте authentication.notifySuccess() для отправки собранных данных конфигурации обратно в Teams. submitConfig() функция демонстрирует структурирование и возврат значений конфигурации после завершения процесса настройки пользователем.

Чтобы завершить процесс настройки расширения сообщений, выполните следующие действия.

В URL-адресе, указанном в свойстве value , должна размещаться веб-страница, которая открывает URL-адрес в виде диалогового окна Teams при активации конфигурации расширения сообщений.
Если требуется проверка подлинности, страница должна использовать проверку подлинности Teams и вызывать authentication.notifySuccess() ее при успешном входе.
После сбора введенных пользователем данных страница должна уведомить Teams об успешной настройке путем вызова notifySuccess(configData) , который отправляет значения конфигурации обратно в Teams:
```
  microsoftTeams.app.initialize();

  function submitConfig() {
      const configData = {
          setting1: "User-selected value",
          setting2: "Another value"
      };

      microsoftTeams.authentication.notifySuccess(configData);
  }
```
После notifySuccess() выполнения окно конфигурации автоматически закрывается, а расширение сообщений настроено успешно.

`auth` Тип ответа

Если служба требует проверки подлинности пользователя, пользователи должны войти в систему, прежде чем использовать расширение для сообщений. Дополнительные сведения см. в разделе Проверка подлинности.

`message` Тип ответа

Ответ message используется, когда расширение должно отображать текстовое сообщение. Тип message ответа не поддерживает форматирование.

Следующий фрагмент кода является примером ответа, возвращаемого message приложением:


return new MessagingExtensionResponse
    {
        ComposeExtension = new MessagingExtensionResult
            {
                Type = "message",
                Text = "Here is the message you want to show!"
            }
    };

Снимок экрана: тип ответа на сообщение.

`result` Тип ответа

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

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

Примечание.

Результаты поиска расширения сообщений не поддерживают заполнение.

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

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

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

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

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

Пример справочника по коду

class TeamsMessagingExtensionsSearchBot extends TeamsActivityHandler {
    async handleTeamsMessagingExtensionQuery(context, query) {
        const searchQuery = query.parameters[0].value;
        const response = await axios.get(`http://registry.npmjs.com/-/v1/search?${ querystring.stringify({ text: searchQuery, size: 8 }) }`);

        const attachments = [];
        response.data.objects.forEach(obj => {
            const heroCard = CardFactory.heroCard(obj.package.name);
            const preview = CardFactory.heroCard(obj.package.name);
            const attachment = { ...heroCard, preview };
            attachments.push(attachment);
        });

        return {
            composeExtension: {
                type: 'result',
                attachmentLayout: 'list',
                attachments: attachments
            }
        };
    }
}

{
  "composeExtension": {
    "type": "result",
    "attachmentLayout": "list",
    "attachments": [
      {
        "contentType": "application/vnd.microsoft.teams.card.o365connector",
        "content": {
          "sections": [
            {
              "activityTitle": "[85069]: Create a cool app",
              "activityImage": "https://placekitten.com/200/200"
            },
            {
              "title": "Details",
              "facts": [
                {
                  "name": "Assigned to:",
                  "value": "[Larry Brown](mailto:larryb@example.com)"
                },
                {
                  "name": "State:",
                  "value": "Active"
                }
              ]
            }
          ]
        },
        "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "85069: Create a cool app",
            "images": [
              {
                "url": "https://placekitten.com/200/200"
              }
            ]
          }
        }
      },
      {
        "contentType": "application/vnd.microsoft.card.adaptive",
        "content": {
          "type": "AdaptiveCard",
          "body": [
            {
              "type": "Container",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Microsoft Corp (NASDAQ: MSFT)",
                  "size": "medium",
                  "isSubtle": true
                },
                {
                  "type": "TextBlock",
                  "text": "September 19, 4:00 PM EST",
                  "isSubtle": true
                }
              ]
            },
            {
              "type": "Container",
              "spacing": "none",
              "items": [
                {
                  "type": "ColumnSet",
                  "columns": [
                    {
                      "type": "Column",
                      "width": "stretch",
                      "items": [
                        {
                          "type": "TextBlock",
                          "text": "75.30",
                          "size": "extraLarge"
                        },
                        {
                          "type": "TextBlock",
                          "text": "▼ 0.20 (0.32%)",
                          "size": "small",
                          "color": "attention",
                          "spacing": "none"
                        }
                      ]
                    },
                    {
                      "type": "Column",
                      "width": "auto",
                      "items": [
                        {
                          "type": "FactSet",
                          "facts": [
                            {
                              "title": "Open",
                              "value": "62.24"
                            },
                            {
                              "title": "High",
                              "value": "62.98"
                            },
                            {
                              "title": "Low",
                              "value": "62.20"
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ],
          "version": "1.0"
        },
        "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "Microsoft Corp (NASDAQ: MSFT)",
            "text": "75.30 ▼ 0.20 (0.32%)"
          }
        }
      }
    ]
  }
}

async def on_teams_messaging_extension_query(self, context, query):
   """
   Handles a Messaging Extension query for searching NPM packages.
 
    This method takes a search query from Teams, fetches matching NPM packages using 
    the NPM registry API, and returns a list of thumbnail cards displaying package 
    details with action buttons.
    """
    search_query = query.parameters[0].value

    response = requests.get(
        "http://registry.npmjs.com/-/v1/search",
        params={"text": search_query, "size": 8},  # Limit results to top 8
    )
    response.raise_for_status()  # Raise an error if the API call fails
    data = response.json()  # Parse the JSON response from the API

    attachments = []
    for obj in data["objects"][:8]:  # Iterate through the first 5 search results
        package = obj.get("package", {})
        package_name = package.get("name", "Unknown Package")  # Fallback if name is missing
        description = package.get("description", "No description available")  # Fallback for missing description
        homepage = package.get("links", {}).get("homepage", "https://www.npmjs.com")  # Default link

        thumbnail_card = ThumbnailCard(
            title = package_name,  # Package name as card title
            text = description,  # Package description
            buttons=[
                # Button to view the package on NPM
                CardAction(
                    type="openUrl",
                    title="View on NPM",
                    value=f"https://www.npmjs.com/package/{package_name}",
                ),
                # Button to visit the package's homepage
                CardAction(
                    type="openUrl",
                    title="Homepage",
                    value=homepage,
                ),
            ],
        )

        preview_card = ThumbnailCard(
            title=package_name,
            text = description,
        )
        preview_attachment = CardFactory.thumbnail_card(preview_card)

        preview_attachment.content.tap = CardAction(
            type="invoke",  # Invoke action triggers a bot command
            value={"title": package_name, "description": description},
        )

        attachment = MessagingExtensionAttachment(
            content=thumbnail_card,
            content_type=CardFactory.content_types.thumbnail_card,
            preview=preview_attachment,
        )

        attachments.append(attachment)

    return MessagingExtensionResponse(
        compose_extension=MessagingExtensionResult(
            type="result",  # Indicates this is a list of results
            attachment_layout="list",  # Layout style for results
            attachments=attachments,
        )
    )

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

Когда пользователь выбирает результат из поискового запроса расширения сообщений, в предварительной версии карта отображается описание и определенные действия Tap. Действию Tap должно быть присвоено необходимое свойство значения, которое отображается в виде кнопки Касание в карта отправленного.

Пример справочника по коду

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

Пример справочника по коду

async handleTeamsMessagingExtensionSelectItem(context, obj) {
        return {
            composeExtension: {
                  type: 'result',
                  attachmentLayout: 'list',
                  attachments: [CardFactory.thumbnailCard(obj.Item3)]
            }
        };
    }

{
    "name": "composeExtension/selectItem",
    "type": "invoke",
    "value": {
        "Item1": "Package_Name",
        "Item2": "Version",
        "Item3": "Package Description"
    },
    .
    .
    .
}

async def on_teams_messaging_extension_select_item(
    self, turn_context: TurnContext, query
) -> MessagingExtensionResponse:
    
    thumbnail_card = ThumbnailCard(
        title = query.get("title") # Extract title from the query
        text = query.get("description"),  # Extract description from the query
    )

    attachment = MessagingExtensionAttachment(
        content_type=CardFactory.content_types.thumbnail_card,
        content=thumbnail_card,
    )

    return MessagingExtensionResponse(
        compose_extension=MessagingExtensionResult(
            type="result",  # Indicates this is a single result
            attachment_layout="list",  # Use list layout
            attachments=[attachment],  # Include the single attachment
        )
    )

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

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

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

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

Пример кода

Название примера	Описание	.NET	Node.js	Манифест
Поиск в расширении для сообщений Teams	В этом примере показано, как создать расширение сообщений в Teams, которое позволяет пользователям выполнять поиск пакетов NuGet и получать результаты в виде карта.	Просмотр	Просмотр	Просмотр
Проверка подлинности и конфигурация расширения сообщений Teams	В этом примере показано, как реализовать проверку подлинности в расширении сообщений для Teams, обеспечивая безопасный доступ и взаимодействие с пользователем.	Просмотр	Просмотр	Просмотр

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

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

См. также

Обратная связь

Была ли эта страница полезна?

Last updated on 2025-05-12